HarmonyOS 6 新特性 UIDesignKit 之 HdsNavigation
前言
大家好，我是若城。HarmonyOS 6 已正式发布，本文聚焦 UIDesignKit 中的导航组件 HdsNavigation，带你快速上手“滚动联动高斯模糊”的标题栏与系统状态栏效果，帮助你在新版本中实现更现代、更沉浸的交互体验。
功能概览
-
顶部标题栏与系统状态栏样式联动
-
常用滚动模糊效果
ScrollEffectType.COMMON_BLUR -
标题栏模式切换（FREE/SMALL/LARGE）
-
以 vp 为单位的长度度量，适配不同屏幕密度
场景与效果图
如下图所示，滚动过程中标题栏与系统状态栏产生高斯模糊与样式切换：
代码解读（结构与要点）
本项目以 HdsNavigation 作为“导航壳”，统一承载以下能力：
-
HdsNavigation：提供标题栏/系统状态栏/滚动联动的统一容器 -
ScrollEffectType.COMMON_BLUR：常用滚动模糊效果 -
HdsNavigationTitleMode：标题栏模式（FREE/SMALL/LARGE） -
LengthMetrics.vp(...)：以 vp 作为长度单位，适配不同屏幕密度
引入与常量
import { HdsNavigation, HdsNavigationAttribute, ScrollEffectType, HdsNavigationTitleMode } from '@kit.UIDesignKit';
import { LengthMetrics } from '@kit.ArkUI';
const TITLE_BAR_HEIGHT_FREE: number = 138; // 与 FREE 模式标题栏高度保持一致，用于内容区预留空白（Blank）避免被覆盖
从 UIDesignKit 引入导航相关能力与枚举，同时使用 ArkUI 的 LengthMetrics 以 vp 为单位传递长度。通过 TITLE_BAR_HEIGHT_FREE 在 FREE 模式下预留内容区头部空白，避免首屏内容被标题栏遮挡。
组件与状态
@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 = '副标题';
@State hideTitleBar: boolean = false;
@State blurEndVp: number = 20;
...
}
-
@Entry：页面入口；@Component：定义 UI 组件。 -
@Provide('pageInfos')：向子树提供导航栈，供HdsNavigation与页面跳转使用。 -
scroller：用于控制Scroll（回到顶部、定点）。 -
blankHeight：预留顶部占位，避免内容被标题栏覆盖。 -
isHideBackButton：控制返回键显隐（可结合导航栈或显式backIcon配置）。 -
titleMode：标题栏模式选择（此处为FREE）。 -
subTitle：可动态更新的副标题文案。 -
hideTitleBar：整体隐藏标题栏（适合沉浸式场景）。 -
blurEndVp：滚动模糊生效终点（vp），值越小越早模糊。
核心实现
HdsNavigation(this.pageInfos) {
Column() {
Stack() {
Scroll(this.scroller) {
Column() {
Blank().height(this.blankHeight)
Image($r('app.media.scenery')).width('100%')
}
}.edgeEffect(EdgeEffect.Spring).scrollBar(BarState.Off)
}
}
}
-
最外层为
HdsNavigation，传入导航栈pageInfos。 -
建议采用
Column -> Stack -> Scroll -> Column的层次结构，清晰承载滚动内容。 -
Blank().height(this.blankHeight)：在滚动内容顶部预留与标题栏等高的空间，确保视觉从标题栏下方开始露出。 -
Image(...).width('100%')：展示占位图（建议替换为本地品牌资源）。 Scroll配置：-
edgeEffect(EdgeEffect.Spring)：弹性边缘效果，提升滚动体验。 -
scrollBar(BarState.Off)：隐藏滚动条，强化沉浸视觉。
-
系统状态栏与标题模式
.systemBarStyle({ statusBarContentColor: '#0A59F7' }, { statusBarContentColor: '#C7C7CD' })
.titleMode(this.titleMode)
.hideBackButton(this.isHideBackButton)
.hideTitleBar(this.hideTitleBar)
-
.systemBarStyle(original, scrolled)：分别指定原始状态与滚动状态的系统状态栏前景色，与标题栏形成统一联动。 .titleMode(this.titleMode)：-
FREE：自由布局，适配自定义内容与高度（本文示例）。 -
SMALL/LARGE：标准模式，具备固定高度与样式规范。
-
-
.hideBackButton(this.isHideBackButton)：控制返回键显隐（与导航栈或backIcon配合）。 -
.hideTitleBar(this.hideTitleBar)：是否隐藏整个标题栏，适用于全屏媒体、沉浸式场景。
完整示例
/**
* 关键点：
* - HdsNavigation：导航壳组件，承载标题栏、系统栏样式与内容滚动联动效果
* - ScrollEffectType.COMMON_BLUR：常用滚动模糊效果
* - HdsNavigationTitleMode：标题栏模式（FREE/SMALL/LARGE等）
*/
import { HdsNavigation, HdsNavigationAttribute, ScrollEffectType, HdsNavigationTitleMode } from '@kit.UIDesignKit';
import { LengthMetrics } from '@kit.ArkUI';
const TITLE_BAR_HEIGHT_FREE: number = 138; // 与 FREE 模式标题栏高度保持一致，用于内容区预留空白（Blank）避免被覆盖
@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; // 返回键显隐（需要结合导航栈或显式配置 backIcon 一起使用）
@State titleMode: HdsNavigationTitleMode = HdsNavigationTitleMode.FREE; // 标题栏模式：演示使用 FREE（自由布局）
@State subTitle: string = '副标题' // 副标题：演示动态文本（如状态/计数）时可修改该值
@State hideTitleBar: boolean = false; // 整体隐藏标题栏（适合全屏内容场景）
@State blurEndVp: number = 20; // 模糊效果触发终点（vp）。越小越早模糊，越大滚动更远才模糊
build() {
// 导航与内容容器：标题栏样式、系统栏与滚动效果在此统一配置
HdsNavigation(this.pageInfos) {
Column() {
Stack() {
Scroll(this.scroller) {
Column() {
Blank().height(this.blankHeight)
Image($r('app.media.scenery')).width('100%') // 占位图：请替换为本地资源（确保品牌一致与清晰度）
}
}.edgeEffect(EdgeEffect.Spring).scrollBar(BarState.Off)
}
}
}
.titleBar({
padding: {
start: LengthMetrics.vp(2),
end: LengthMetrics.vp(2)
},
style: { // 标题栏样式（原始状态/滚动模糊状态）、滚动联动配置
// 滚动联动配置：启用 COMMON_BLUR，并通过 blurEndVp 控制模糊触发距离
scrollEffectOpts: {
enableScrollEffect: true,
scrollEffectType: ScrollEffectType.COMMON_BLUR,
blurEffectiveStartOffset: LengthMetrics.vp(0),
blurEffectiveEndOffset: LengthMetrics.vp(this.blurEndVp)
},
// 原始样式：未滚动/未达到模糊阈值时的背景与内容色彩
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') }
}
},
// 滚动样式：达到模糊阈值后的背景与内容色彩（注意与 originalStyle 保持对比度可读性）
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: this.subTitle
},
menu: { // 右侧菜单项：可绑定 action 用于快速入口/调试打印
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: { // 返回键外观配置：与 hideBackButton 状态、导航栈行为相互配合
label: 'backButton',
icon: $r('sys.symbol.trunk'),
isEnabled: true,
}
}
})
.systemBarStyle({ statusBarContentColor: '#0A59F7' }, { statusBarContentColor: '#C7C7CD' }) // 系统状态栏前景色：原始/滚动态分别指定
.titleMode(this.titleMode) // 标题栏模式（FREE/SMALL/LARGE），影响布局与高度
.hideBackButton(this.isHideBackButton) // 是否隐藏返回键：演示时可切换该状态观察变化
.hideTitleBar(this.hideTitleBar) // 是否隐藏整个标题栏：适合沉浸/全屏媒体场景
}
}
知识点讲解
-
使用 vp 作为长度单位，保证不同屏幕密度下的视觉一致性。
-
根据页面内容与滚动距离调整
blurEndVp，建议从 12–24 vp 之间微调以取得更自然的模糊过渡。 -
保证
originalStyle与scrollEffectStyle之间的对比度与可读性，尤其是标题与图标的前景色。 -
返回键显隐与导航栈行为需一致，避免出现“可见但不可用”的交互问题。
-
在大图/视频等沉浸式场景，可启用
hideTitleBar，并在首屏通过blankHeight处理内容起始位置。
总结
借助 HdsNavigation 与 COMMON_BLUR 滚动效果，可轻松实现 HarmonyOS 6 中现代、沉浸的导航体验。本文从结构、状态与样式联动入手，给出完整示例与最佳实践，便于你在真实业务中快速落地。
讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。
更多推荐
0
0- 0
已为社区贡献1条内容
所有评论(0)