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

代码飞天2026-04-05 21:31

一、标题栏的作用

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

二、几种标题栏组件

1.HdsNavigation的titlebar

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

ts 复制代码 
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)
  }
}

界面演示：

  1. titlebar属性

代码部分：

ts 复制代码 
.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显示隐藏的菜单项，如下：

  1. systemBarStyle属性

代码部分：

ts 复制代码 
.systemBarStyle({ statusBarContentColor: '#fff70a84' }, { statusBarContentColor: '#ff0000ff' })

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

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

  1. titleMode属性

代码部分：

ts 复制代码 
@State titleMode: HdsNavigationTitleMode = HdsNavigationTitleMode.FREE;
......

.titleMode(this.titleMode)

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

名称 值 说明
FREE 0 标题随内容滚动而动态缩放。向上滚动时缩小，向下滚动回顶部时恢复。
FULL 1 固定为大标题模式。
MINI 2 固定为小标题模式。
MODAL 3 固定为半模态模式。
  1. hideBackButton属性

示例代码：

ts 复制代码 
.hideBackButton(false)

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

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

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

  1. hideTitleBar属性

示例代码：

ts 复制代码 
.hideTitleBar(false)

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

相关推荐
nashane7 小时前
HarmonyOS 6学习：AI攻略长截图“防抖”与像素级拼接术
学习·华为·harmonyos
想你依然心痛9 小时前
HarmonyOS 6（API 23）实战：基于悬浮导航、沉浸光感与HMAF的“代码哨兵“——AI智能体代码安全审计平台
人工智能·安全·harmonyos·智能体
轻口味10 小时前
HarmonyOS 6.1 全栈实战录 - 09 极光底座：ArkWeb 6.1 性能、安全与视觉插帧全特性深度实战
pytorch·安全·harmonyos
Ww.xh11 小时前
鸿蒙Web组件中Hash路由传登录态方案
前端·哈希算法·harmonyos
nashane11 小时前
HarmonyOS 6学习：Canvas性能优化与长截图流畅实现实战
学习·性能优化·harmonyos
轻口味11 小时前
HarmonyOS 6.1 全栈实战录 - 13 流量增长新引擎：全场景归因与 App Linking 链接深度开发实战
pytorch·深度学习·harmonyos
轻口味14 小时前
HarmonyOS 6.1 全栈实战录 - 12 性能底座与包管理演进深度开发实战
华为·harmonyos
云水一下15 小时前
华为防火墙安全区域与NAT实战：基于eNSP的企业边界网完整部署
安全·华为·nat·下一代防火墙
小雨青年16 小时前
鸿蒙 HarmonyOS 6 | Pura X Max 鸿蒙原生适配 06：GridRow 做卡片自适应布局
华为·harmonyos
前端不太难17 小时前
一套鸿蒙 App，如何跑在手机 / 平板 / TV？
智能手机·电脑·harmonyos
热门推荐
01GitHub 镜像站点02Codex 接入 DeepSeek API 完整配置文档03【AI】2026 年具身智能模型和世界模型总结04CC-Switch & Claude 基于 Linux 服务器安装使用指南05Codex 手机端连接教程：三分钟搞定，附完整步骤06Gemini大升级、AI眼镜首发、Android XR亮相，13天后见分晓07人工智能最新动态 AI 日报 · 2026年5月10日08AI科技热点日报 | 2026年5月11日09头歌软件工程导论UML画图题(基于starUML)10裂开！ChatGPT 居然开始要手机号验证，附详细解决方法