文章总结： 本文介绍了HarmonyOS开发中的标题栏组件HdsNavigation，详细解析了其作用、配置方法和代码实现。通过完整示例展示了titleBar属性的padding、style和content等关键参数的用法，包括滚动效果、样式设置和菜单配置，为开发者提供了实用的组件使用指南。 综合评分： 75 文章分类： 其他
harmonyOS开发基础之标题栏（HdsNavigation）
原创
书中自有代码来 书中自有代码来
书中自有代码来
2026年4月3日 21:48 四川
一、标题栏的作用
在移动应用和桌面应用的使用中，标题栏一直发挥着不可或缺的重要作用，从早期的显示简单信息，例如：软件logo、软件名称、软件介绍等，到现今包含菜单按钮，将大量复杂的入口以图标或菜单的形式显示在标题栏，方便用户进入，标题栏一直是应用的重要组成部分，而在鸿蒙应用开发中，华为已经为我们提供了多种多样的标题栏组件方便开发者使用，让开发更加简洁高效。
二、几种标题栏组件
1.HdsNavigation的titlebar
示例代码（参考官方文档）：
import { HdsNavigation, ScrollEffectType, HdsNavigationTitleMode } from'@kit.UIDesignKit';
import { LengthMetrics } from'@kit.ArkUI';
constTITLE_BAR_HEIGHT_FREE: number = 138;
@Entry
@Component
struct Index {
@Provide('pageInfos') pageInfos: NavPathStack = newNavPathStack();
scroller: Scroller = newScroller();
@StateblankHeight: number = TITLE_BAR_HEIGHT_FREE;
@StateisHideBackButton: boolean = false;
@StatetitleMode: HdsNavigationTitleMode = HdsNavigationTitleMode.FREE;
@StatesubTitle: 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)
}
}
界面演示：
- 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显示隐藏的菜单项，如下：
- systemBarStyle属性
代码部分：
.systemBarStyle({ statusBarContentColor: '#fff70a84' }, { statusBarContentColor: '#ff0000ff' })
其中，
statusBarContentColor用于设置不同状态下系统状态栏的主题色，例如这里初始化颜色设为红色，如下：
而改变后设置为蓝色，如下：
- titleMode属性
代码部分：
@State titleMode: HdsNavigationTitleMode = HdsNavigationTitleMode.FREE;
……
.titleMode(this.titleMode)
该项有多种选择，对应关系如下：
| 名称 | 值 | 说明 | | — | — | — | | FREE | 0 | 标题随内容滚动而动态缩放。向上滚动时缩小，向下滚动回顶部时恢复。 | | FULL | 1 | 固定为大标题模式。 | | MINI | 2 | 固定为小标题模式。 | | MODAL | 3 | 固定为半模态模式。 |
- hideBackButton属性
示例代码：
.hideBackButton(false)
仅在MINI状态下生效，例如设置为false，即显示返回按钮：
点击按钮即返回上一页，这里因为是第一页，所以直接退出应用。
如果设置为true，即隐藏返回按钮：
- hideTitleBar属性
示例代码：
.hideTitleBar(false)
设置是否显示标题栏，设置为false即显示标题栏，设置为true即隐藏标题栏。
免责声明：
本文所载程序、技术方法仅面向合法合规的安全研究与教学场景，旨在提升网络安全防护能力，具有明确的技术研究属性。
任何单位或个人未经授权，将本文内容用于攻击、破坏等非法用途的，由此引发的全部法律责任、民事赔偿及连带责任，均由行为人独立承担，本站不承担任何连带责任。
本站内容均为技术交流与知识分享目的发布，若存在版权侵权或其他异议，请通过邮件联系处理，具体联系方式可点击页面上方的联系我。
本文转载自：书中自有代码来 书中自有代码来 书中自有代码来《harmonyOS开发基础之标题栏（HdsNavigation）》
版权声明
本站仅做备份收录，仅供研究与教学参考之用。
读者将信息用于其他用途的，全部法律及连带责任由读者自行承担，本站不承担任何责任。
评论