harmonyOS开发基础之标题栏（HdsNavigation）

代码飞一会儿
0 阅读3分钟

一、标题栏的作用

在移动应用和桌面应用的使用中，标题栏一直发挥着不可或缺的重要作用，从早期的显示简单信息，例如：软件logo、软件名称、软件介绍等，到现今包含菜单按钮，将大量复杂的入口以图标或菜单的形式显示在标题栏，方便用户进入，标题栏一直是应用的重要组成部分，而在鸿蒙应用开发中，华为已经为我们提供了多种多样的标题栏组件方便开发者使用，让开发更加简洁高效。

二、几种标题栏组件

1.HdsNavigation的titlebar

示例代码（参考官方文档）：

import { HdsNavigation,  ScrollEffectType, HdsNavigationTitleMode } from '@kit.UIDesignKit';
import { LengthMetrics } from '@kit.ArkUI';

const  TITLE_BAR_HEIGHT_FREE: number = 138;
@Entry
@Component
struct Index {
  @Provide('pageInfos') pageInfos: NavPathStack = new NavPathStack();
  scroller: Scroller = new Scroller();
  @State blankHeight: number = TITLE_BAR_HEIGHT_FREE;
  @State isHideBackButton: boolean = false;
  @State titleMode: HdsNavigationTitleMode = HdsNavigationTitleMode.FREE;
  @State subTitle: string = 'Sub'

  build() {
    HdsNavigation(this.pageInfos) {
      Column() {
        Stack() {
          Scroll(this.scroller) {
            Column() {
              Blank().height(this.blankHeight)
              Image($r('app.media.scene')).width('100%')
              Text('1')
              Image($r('app.media.scene')).width('100%')
              Text('1')
              Image($r('app.media.scene')).width('100%')
              Text('1')
              Image($r('app.media.scene')).width('100%')
              Text('1')
              Image($r('app.media.scene')).width('100%')
              Text('1')
              Image($r('app.media.scene')).width('100%')
              Text('1')
              Image($r('app.media.scene')).width('100%')
              Text('1')
              Image($r('app.media.scene')).width('100%')
            }
          }.edgeEffect(EdgeEffect.Spring).scrollBar(BarState.Off)
        }
      }
    }
    .titleBar({
      padding: {
        start: LengthMetrics.vp(2),
        end: LengthMetrics.vp(2)
      },
      style: {
        scrollEffectOpts: {
          enableScrollEffect: true,
          scrollEffectType: ScrollEffectType.COMMON_BLUR,
          blurEffectiveStartOffset: LengthMetrics.vp(0),
          blurEffectiveEndOffset: LengthMetrics.vp(20)
        },
        originalStyle: {
          backgroundStyle: {
            backgroundColor: $r('sys.color.ohos_id_color_background'),
          },
          contentStyle: {
            titleStyle: { mainTitleColor: $r('sys.color.font_primary'), subTitleColor: $r('sys.color.font_secondary') },
            menuStyle: { backgroundColor: $r('sys.color.comp_background_tertiary'), iconColor: $r('sys.color.icon_primary') },
            backIconStyle: { backgroundColor: $r('sys.color.comp_background_tertiary'), iconColor: $r('sys.color.icon_primary') }
          }
        },
        scrollEffectStyle: {
          backgroundStyle: {
            backgroundColor: $r('sys.color.ohos_id_color_background_transparent'),
          },
          contentStyle: {
            titleStyle: { mainTitleColor: $r('sys.color.font_primary'), subTitleColor: $r('sys.color.font_secondary') },
            menuStyle: { backgroundColor: $r('sys.color.comp_background_tertiary'), iconColor: $r('sys.color.icon_primary') },
            backIconStyle: { backgroundColor: $r('sys.color.comp_background_tertiary'), iconColor: $r('sys.color.icon_primary') }
          }
        }
      },
      content: {
        title: {
          mainTitle: '主标题',
          subTitle: '副标题'
        },
        menu: {
          value: [{
            content: {
              label: 'menu1',
              icon: $r('sys.symbol.ohos_wifi'),
              isEnabled: true,
              action: () => {
                console.info("HdsNavigation menu1");
              }
            }
          }, {
            content: {
              label: 'menu2',
              icon: $r('sys.symbol.plus'),
              isEnabled: true,
            }
          }, {
            content: {
              label: 'menu3',
              icon: $r('sys.symbol.lock'),
            }
          }, {
            content: {
              label: 'menu4',
              icon: $r('sys.symbol.trunk'),
            }
          }]
        },
        backIcon: {
          label: 'backButton',
          icon: $r('sys.symbol.trunk'),
          isEnabled: true,
        }
      }
    })
    .systemBarStyle({ statusBarContentColor: '#ffff0000' }, { statusBarContentColor: '#ff02025b' })
    .titleMode(this.titleMode)
    .hideBackButton(this.isHideBackButton)
    .hideTitleBar(false)
  }
}

界面演示：

2026-04-03-14-31-20-20260403-0631-09.4894078.gif

  1. titlebar属性

代码部分：

.titleBar({
      padding: {
        start: LengthMetrics.vp(2),
        end: LengthMetrics.vp(2)
      },
      style: {
        scrollEffectOpts: {
          enableScrollEffect: true,
          scrollEffectType: ScrollEffectType.COMMON_BLUR,
          blurEffectiveStartOffset: LengthMetrics.vp(0),
          blurEffectiveEndOffset: LengthMetrics.vp(20)
        },
        originalStyle: {
          backgroundStyle: {
            backgroundColor: $r('sys.color.ohos_id_color_background'),
          },
          contentStyle: {
            titleStyle: { mainTitleColor: $r('sys.color.font_primary'), subTitleColor: $r('sys.color.font_secondary') },
            menuStyle: { backgroundColor: $r('sys.color.comp_background_tertiary'), iconColor: $r('sys.color.icon_primary') },
            backIconStyle: { backgroundColor: $r('sys.color.comp_background_tertiary'), iconColor: $r('sys.color.icon_primary') }
          }
        },
        scrollEffectStyle: {
          backgroundStyle: {
            backgroundColor: $r('sys.color.ohos_id_color_background_transparent'),
          },
          contentStyle: {
            titleStyle: { mainTitleColor: $r('sys.color.font_primary'), subTitleColor: $r('sys.color.font_secondary') },
            menuStyle: { backgroundColor: $r('sys.color.comp_background_tertiary'), iconColor: $r('sys.color.icon_primary') },
            backIconStyle: { backgroundColor: $r('sys.color.comp_background_tertiary'), iconColor: $r('sys.color.icon_primary') }
          }
        }
      },
      content: {
        title: {
          mainTitle: '主标题',
          subTitle: '副标题'
        },
        menu: {
          value: [{
            content: {
              label: 'menu1',
              icon: $r('sys.symbol.ohos_wifi'),
              isEnabled: true,
              action: () => {
                console.info("HdsNavigation menu1");
              }
            }
          }, {
            content: {
              label: 'menu2',
              icon: $r('sys.symbol.plus'),
              isEnabled: true,
            }
          }, {
            content: {
              label: 'menu3',
              icon: $r('sys.symbol.lock'),
            }
          }, {
            content: {
              label: 'menu4',
              icon: $r('sys.symbol.trunk'),
            }
          }]
        },
        backIcon: {
          label: 'backButton',
          icon: $r('sys.symbol.trunk'),
          isEnabled: true,
        }
      }
    })

参数：

名称可选说明
padding是标题栏内间距设置。
style是标题栏样式设置。
content是标题栏内容区设置。
enableHoverMode是是否响应悬停态。
avoidLayoutSafeArea是是否需要标题栏主动避让安全区。
enableComponentSafeArea是是否将标题栏设置为组件级安全区。

content设置：

名称可选说明
title是设置标题栏标题内容。
menu是设置标题栏菜单栏内容。
backIcon是设置标题栏的返回按钮内容。
stackBuilder是设置标题栏顶部自定义区域。
stackBuilderComponent是设置标题栏顶部自定义区域。
bottomBuilder是设置标题栏底部自定义区域。
divider是设置标题栏分割线内容。
subIcon是设置标题栏子图标内容。

title中使用mainTitle设置主标题的内容，使用subTitle设置副标题内容。

menu中使用value数组配置菜单相关信息,参考下面配置项:

名称可选说明
icon是图标型菜单项支持的图片资源类型。不配置时，显示空白。
label是图标型菜单项的文本。默认值：""。
isEnabled是是否使能。默认值：true。true：使能。false：未使能。
action是当前选项被选中的事件回调。
type是标题栏图标类型。

如果图标数量过多时，系统会使用更多的图标隐藏菜单图标，点击后以文字的label显示隐藏的菜单项，如下：

2026-04-03-15-12-47-image.png

2. systemBarStyle属性

代码部分：

.systemBarStyle({ statusBarContentColor: '#fff70a84' }, { statusBarContentColor: '#ff0000ff' })

其中，statusBarContentColor用于设置不同状态下系统状态栏的主题色，例如这里初始化颜色设为红色，如下：

2026-04-03-14-36-49-image.png

而改变后设置为蓝色，如下：

2026-04-03-14-38-45-image.png

  1. titleMode属性

代码部分：

@State titleMode: HdsNavigationTitleMode = HdsNavigationTitleMode.FREE;
……

.titleMode(this.titleMode)

该项有多种选择，对应关系如下：

名称值说明
FREE0标题随内容滚动而动态缩放。向上滚动时缩小，向下滚动回顶部时恢复。
FULL1固定为大标题模式。
MINI2固定为小标题模式。
MODAL3固定为半模态模式。
  1. hideBackButton属性

示例代码：

.hideBackButton(false)

仅在MINI状态下生效，例如设置为false，即显示返回按钮：

2026-04-03-14-51-07-image.png

点击按钮即返回上一页，这里因为是第一页，所以直接退出应用。

如果设置为true，即隐藏返回按钮：

2026-04-03-14-53-14-image.png

  1. hideTitleBar属性

示例代码：

.hideTitleBar(false)

设置是否显示标题栏，设置为false即显示标题栏，设置为true即隐藏标题栏。

avatar
文章
阅读
粉丝