本模块提供导航组件的能力,默认支持标题栏随内容区滚动的动态模糊样式。6.0.0(20)及以上版本,推荐使用bindToScrollable、bindToNestedScrollable属性绑定导航组件和可滚动容器组件后,再使用导航组件滚动相关的功能,从而获得更优的体验。如滚动生效动态模糊样式,标题栏随内容区滚动动态显隐功能等。
HdsNavigation组件是路由导航的根视图容器,一般作为Page页面的根容器使用,其内部默认包含了标题栏、内容区和工具栏。其中内容区默认首页显示导航内容(HdsNavigation的子组件)或非首页显示(HdsNavDestination (导航子页面容器)的子组件),首页和非首页通过路由进行切换。
起始版本: 5.1.0(18)
6.0.1(21)及之前版本:
import { HdsNavigation, HdsNavigationAttribute } from '@kit.UIDesignKit'; 6.0.2(22)及之后版本:
import { HdsNavigation } from '@kit.UIDesignKit'; HdsNavigation(pathInfos?: NavPathStack, homeDestination?: HomePathInfo)
绑定路由栈到HdsNavigation组件。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 5.1.0(18)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pathInfos | NavPathStack | 否 | 路由栈信息。 |
| homeDestination | HomePathInfo | 否 | 首页对应的NavDestination配置信息。 起始版本: 26.0.1 |
titleBar(options?: HdsNavigationTitleBarOptions)
设置HdsNavigation组件titleBar区域(包含返回图标区域、标题区域、菜单区域、背景板)样式以及内容。
标题字符串超长时,如果不设置副标题,先缩小再换行(2行)最后以"..."截断。如果设置副标题,先缩小后以"..."截断。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 5.1.0(18)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| options | HdsNavigationTitleBarOptions | 否 | 标题栏配置信息。 |
titleMode(value: HdsNavigationTitleMode)
设置页面标题栏显示模式。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 5.1.0(18)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | HdsNavigationTitleMode | 是 | 页面标题栏显示模式。 默认值:HdsNavigationTitleMode.FREE。 |
toolbarConfiguration(value: Array<ToolbarItem> | CustomBuilder, options?: NavigationToolbarOptions)
不支持通过SymbolGlyphModifier对象的fontSize属性修改图标大小、effectStrategy属性修改动效、symbolEffect属性修改动效类型。
设置工具栏内容。不设置时不显示工具栏。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 5.1.0(18)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | Array<ToolbarItem> | CustomBuilder | 是 | 工具栏内容。 使用Array<ToolbarItem>写法设置的工具栏有如下特性: - 如果为Stack模式,不推荐使用该写法。推荐使用CustomBuilder配合ToolBar组件写法,避免布局显示问题。 - 工具栏所有选项均分底部工具栏,在每个均分内容区布局文本和图标。 - 最多支持显示5个图标,多余的图标会被放入自动生成的更多图标。 使用CustomBuilder写法为用户自定义工具栏选项,除均分底部工具栏外不具备以上功能。 |
| options | NavigationToolbarOptions | 否 | 工具栏选项。 |
hideToolBar(hide: boolean, animated?: boolean)
设置是否隐藏工具栏,并且可设置在工具栏显示隐藏的状态变化中是否使用动画。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 5.1.0(18)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| hide | boolean | 是 | 是否隐藏工具栏。 默认值:false。 - true: 隐藏工具栏。 - false:显示工具栏。 |
| animated | boolean | 否 | 设置是否使用动画显隐工具栏。 默认值:false。 - true:使用动画显示隐藏工具栏。 - false:不使用动画显示隐藏工具栏。 |
hideTitleBar(hide: boolean, animated?: boolean)
设置是否隐藏标题栏,并且可设置在标题栏显示隐藏的状态变化中是否使用动画。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 5.1.0(18)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| hide | boolean | 是 | 是否隐藏标题栏。 默认值:false。 - true:隐藏标题栏。 - false:显示标题栏。 |
| animated | boolean | 否 | 设置是否使用动画显隐标题栏。 默认值:false。 - true:使用动画显示隐藏标题栏。 - false:不使用动画显示隐藏标题栏。 |
hideBackButton(value: boolean)
设置是否隐藏标题栏中的返回键。返回键仅针对titleMode为HdsNavigationTitleMode.MINI时才生效。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 5.1.0(18)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | boolean | 是 | 是否隐藏标题栏中的返回键。 默认值:false。 - true:隐藏返回键。 - false:显示返回键。 |
mode(value: NavigationMode)
设置导航栏的显示模式。支持Stack、Split与Auto模式。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 5.1.0(18)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | NavigationMode | 是 | 导航栏的显示模式。 默认值:NavigationMode.Auto。 自适应:基于组件宽度自适应单栏和双栏。 |
divider(style: NavigationDividerStyle | null)
设置HdsNavigation双栏模式下的分割线样式。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.1.0(23)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| style | NavigationDividerStyle | null | 是 | 设置双栏分割线样式。 配置为null时:隐藏分割线。 |
minContentWidth(value: Dimension)
设置导航栏内容区最小宽度(双栏模式下生效)。
规则: 优先级规则详见说明。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 5.1.0(18)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | Dimension | 是 | 导航栏内容区最小宽度。 默认值:360。单位:vp。 undefined:行为不做处理,导航栏内容区最小宽度与默认值保持一致。 |
仅设置navBarWidth时,不支持HdsNavigation分割线拖拽。
navBarWidthRange指定分割线可以拖拽范围。如果不设置值,则按照默认值处理。拖拽范围需要满足navBarWidthRange设置的范围和minContentWidth限制。
HdsNavigation显示范围缩小顺序:a. 缩小内容区大小。如果不设置minContentWidth属性,则可以缩小内容区至0, 否则最小缩小至minContentWidth。b. 缩小导航栏大小,缩小时需要满足导航栏宽度大于navBarRange的下限。c. 对显示内容进行裁切。
ignoreLayoutSafeArea(types?: Array<LayoutSafeAreaType>, edges?: Array<LayoutSafeAreaEdge>)
控制组件的布局,使其扩展到非安全区域。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 5.1.0(18)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| types | Array <LayoutSafeAreaType> | 否 | 配置扩展安全区域的类型。 默认值:[LayoutSafeAreaType.SYSTEM]。 |
| edges | Array <LayoutSafeAreaEdge> | 否 | 配置扩展安全区域的方向。 默认值:[LayoutSafeAreaEdge.TOP, LayoutSafeAreaEdge.BOTTOM]。 |
组件设置LayoutSafeArea之后生效的条件为:
设置LayoutSafeAreaType.SYSTEM时,组件的边界与非安全区域重合时组件能够延伸到非安全区域下。例如:设备顶部状态栏高度100,组件在屏幕中纵向方位的绝对偏移需要在0到100之间。
若组件延伸到非安全区域内,此时在非安全区域里触发的事件(例如:点击事件)等可能会被系统拦截,优先响应状态栏等系统组件。
systemBarStyle(originalStyle: Optional<SystemBarStyle>, scrollEffectStyle: Optional<SystemBarStyle>)
当HdsNavigation中显示HdsNavigation首页时,设置对应系统状态栏的样式。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 5.1.0(18)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| originalStyle | Optional<SystemBarStyle> | 是 | 系统状态栏初始样式。未设置systemBarStyle属性时,颜色默认值同主标题栏字体颜色。 |
| scrollEffectStyle | Optional<SystemBarStyle> | 是 | HdsNavigation动态样式生效后,系统状态栏对应的动态样式。未设置systemBarStyle属性时,颜色默认值同主标题栏字体颜色。 |
不建议混合使用systemBarStyle属性和window设置状态栏样式的相关接口,例如:setWindowSystemBarProperties。
Split模式下的HdsNavigation,如果内容区没有HdsNavDestination,则遵从HdsNavigation首页的设置,反之则遵从栈顶HdsNavDestination的设置。
仅支持在主窗口的主页面中使用systemBarStyle设置状态栏样式。
当页面设置不同样式时,在页面转场开始时生效。
非全屏窗口下,HdsNavigation/HdsNavDestination设置的状态栏不生效。
recoverable(recoverable: Optional<boolean>)
配置HdsNavigation是否可恢复。如配置为可恢复,当应用进程异常退出并重新冷启动时,可自动创建该HdsNavigation,并恢复至异常退出时的页面栈。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 5.1.0(18)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| recoverable | Optional<boolean> | 是 | HdsNavigation是否可恢复,默认为不可恢复。 默认值:false。 - true:页面栈可恢复。 - false:页面栈不可恢复。 |
使用该接口需要先设置HdsNavigation的id属性,否则该接口无效。
该接口需要配合HdsNavDestination的recoverable接口使用。
恢复的过程中不可序列化的信息,例如不可序列化的参数与用户设置的onPop等,会被丢弃,无法恢复。
当应用退到后台,因系统资源不足等原因被系统终止后,如果某页面已配置为可恢复,当应用再次被唤醒至前台时,系统将自动恢复该页面。详细说明请参考UIAbility备份恢复。
dynamicHideTitleBar(value: DynamicHideParams)
设置标题栏跟随内容区动态显隐配置,推荐搭配bindToScrollable/bindToNestedScrollable体验更佳的滑动效果。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.0.0(20)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | DynamicHideParams | 是 | 标题栏跟随内容区滚动动态显隐配置。 当标题栏模式为HdsNavigationTitleMode.MODAL时该接口设置无效。 不支持在显隐过程中动态切换属性。 |
bindToScrollable(scrollers: Array<Scroller>)
绑定导航组件和可滚动容器组件,动态显隐标题区域,状态栏及底部自定义区域,使能动态显隐更优体验。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.0.0(20)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| scrollers | Array<Scroller> | 是 | 可滚动容器组件的控制器。 |
bindToNestedScrollable(scrollers: Array<NestedScrollInfo>)
绑定导航组件和嵌套的可滚动容器组件,动态显隐标题区域、状态栏及底部自定义区域,使能动态显隐更优体验。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.0.0(20)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| scrollers | Array<NestedScrollInfo> | 是 | 嵌套的可滚动容器组件的控制器。 |
当多个可滚动容器组件绑定了同一个导航组件时,滚动任何一个容器都会触发标题栏显示或隐藏效果。且当任何一个可滚动容器组件滑动到底部或顶部位
置时,会立即触发标题栏显示动效。因此,为了获得最佳用户体验,不建议同时触发多个可滚动容器组件的滚动事件。
enableDragBar(isEnabled: Optional<boolean>)
控制分栏场景下是否显示拖拽条。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.0.0(20)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| isEnabled | Optional<boolean> | 是 | 是否开启拖拽条,默认为无拖拽条样式。 默认值:false。 - true:有拖拽条样式。 - false:无拖拽条样式。 |
enableModeChangeAnimation(isEnabled: Optional<boolean>)
控制是否开启NavigationMode单双栏切换时的动效。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.0.0(20)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| isEnabled | Optional<boolean> | 是 | 是否开启单双栏切换动效。 默认值:true。 - true:开启单双栏切换动效。 - false:关闭单双栏切换动效。 |
withTheme(value: WithThemeOptions)
设置HdsNavigation的WithTheme能力。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.1.0(23)
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | WithThemeOptions | 是 | WithTheme能力配置信息。 |
splitPlaceholder(placeholder: ComponentContent)
HdsNavigation双栏模式下,支持设置右侧页面显示默认占位页,占位页仅作为UI展示页,不可获焦和响应事件。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.1.0(23)
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| placeholder | ComponentContent | 是 | 设置Navigation双栏模式下右侧的默认占位页。 |
enableVisibilityLifecycleWithContentCover(isEnabled: Optional<boolean>)
设置是否启用HdsNavDestination页面的onHidden、onShown生命周期与全模态的联动触发。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.1.0(23)
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| isEnabled | Optional<boolean> | 是 | 是否启用HdsNavDestination页面onShown、onHidden生命周期与全模态的联动触发。 默认值:true。 - true:全模态拉起时,会触发当前HdsNavDestination页面的onHidden生命周期;全模态关闭时,会触发当前HdsNavDestination页面的onShown生命周期。 - false:HdsNavDestination页面onHidden、onShown生命周期不会因为全模态的拉起、关闭而触发。 |
onTitleModeChange(callback: Callback<HdsNavigationTitleMode>)
当titleMode为HdsNavigationTitleMode.FREE时,随着可滚动组件的滑动标题栏模式发生变化时触发此回调。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.0.0(20)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| callback | Callback<HdsNavigationTitleMode> | 是 | 回调函数,返回当前标题栏显示模式。 |
标题栏模糊样式枚举。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 5.1.0(18)
| 名称 | 值 | 说明 |
|---|---|---|
| COMMON_BLUR | 0 | 标题栏的模糊样式类型:通用模糊。 对组件背景进行均匀的模糊处理,模糊强度一致,边界清晰,用于强调控件与内容的层级分隔。 滑动内容进入/离开标题栏区域过程中,模糊背板和分割线透明渐变出现/消失。此方式适用于非沉浸式场景。 |
| GRADUAL_BLUR | 1 | 标题栏的模糊样式类型:过渡模糊。 对组件背景进行均匀的模糊处理,模糊强度一致,边界清晰,用于强调控件与内容的层级分隔。 滑动前后标题栏内容发生颜色/状态变化,滑动过程中,线性跟手变化。此样式适用于沉浸式图文类的场景。 起始版本: 6.0.0(20) |
| GRADIENT_BLUR | 2 | 标题栏的模糊样式类型:渐变模糊。 模糊效果在空间维度上呈现渐强/渐弱的变化,模糊边界柔和,用于增强页面沉浸感。 - 当ScrollEffectOptions.enableScrollEffect属性配置为true时,标题栏样式从originalStyle到scrollEffectStyle线性过渡。 - 当ScrollEffectOptions.enableScrollEffect属性配置为false时,直接生效模糊。此方式适用于列表型非沉浸式场景。 起始版本: 6.0.0(20) |
| IMMERSIVE_GRADIENT_BLUR | 3 | 标题栏的模糊样式类型:沉浸式渐变模糊。 模糊效果在空间维度上呈现渐强/渐弱的变化,模糊边界柔和,用于增强页面沉浸感。 - 当ScrollEffectOptions.enableScrollEffect属性配置为true时,标题栏样式从originalStyle到scrollEffectStyle线性过渡。 - 当ScrollEffectOptions.enableScrollEffect属性配置为false时,直接生效模糊。此样式适用于沉浸式图文类的场景。 起始版本: 6.1.0(23) |
分割线显示类型枚举。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.0.0(20)
| 名称 | 值 | 说明 |
|---|---|---|
| OFF | 0 | 分割线始终不显示。 |
| ON | 1 | 分割线始终显示。 |
| AUTO | 2 | 分割线随内容区滚动跟手显示。 |
文字型图标模式枚举。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.0.0(20)
| 名称 | 值 | 说明 |
|---|---|---|
| NORMAL | 200 | 普通文本模式。 胶囊按钮,圆角为sys.float.corner_radius_level10。 |
| SINGLE_CHARACTER | 201 | 单字文本模式。 圆形按钮。 |
bottomBuilder显示类型枚举。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.0.0(20)
| 名称 | 值 | 说明 |
|---|---|---|
| DIRECTLY_SHOW | 0 | 直接显示bottomBuilder。 |
| OVERDRAG_SHOW | 1 | 过度拖拽场景下,显示bottomBuilder。 |
标题栏动态显隐模式枚举。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.0.0(20)
| 名称 | 值 | 说明 |
|---|---|---|
| SCROLL_UP_TO | 0 | 上滑到固定位置隐藏,下滑到固定位置显示。 |
| SCROLL_UP | 1 | 任意位置上滑隐藏,下滑显示。仅针对连续滑动场景生效,使用滚动组件接口触发的滚动不生效该隐藏模式。 |
| SCROLL_DOWN | 2 | 任意位置上滑显示,下滑隐藏。仅标题栏模式为HdsNavigationTitleMode.MINI或者HdsNavDestinationTitleMode.MINI时该配置生效。仅针对连续滑动场景生效,使用滚动组件接口触发的滚动不生效该隐藏模式。 |
| SCROLL_UP_TO_BLEND_SCROLL_UP | 3 | 混合隐藏模式,bottomBuilder使用SCROLL_UP_TO隐藏模式,标题栏使用SCROLL_UP隐藏模式。 |
图片型图标模式枚举。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.0.0(20)
| 名称 | 值 | 说明 |
|---|---|---|
| SMALL | 100 | 小图标模式,图标默认大小为18vp * 18vp。 |
| NORMAL | 101 | 普通图标模式,图标默认大小为24vp * 24vp。 |
| LARGE | 102 | 大图标模式,图标默认大小为40vp * 40vp。 |
模糊效果生效策略枚举。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.0.0(20)
| 名称 | 值 | 说明 |
|---|---|---|
| ENABLE | 0 | 使能模糊效果。 |
| DISABLE | 1 | 不使能模糊效果。 |
| ADAPTIVE | 2 | 模糊效果生效策略将根据系统策略进行调整。共设置三档系统策略:精美、轻柔、流畅,只有精美档位配置能够生效模糊效果。 系统策略由设备厂商根据设备性能配置,未配置时默认执行精美策略。 |
标题字号大小。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.1.0(23)
| 名称 | 值 | 说明 |
|---|---|---|
| TITLE_S | 0 | 小号标题。 |
| TITLE_ML | 1 | 中等偏大号标题。 |
type CustomTransitionDelegate = (from: NavContentInfo, to: NavContentInfo, operation: NavigationOperation) => NavigationAnimatedTransition | undefined
自定义转场动画回调方法。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.0.0(20)
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| from | NavContentInfo | 是 | 退场Destination的页面。 |
| to | NavContentInfo | 是 | 进场Destination的页面。 |
| operation | NavigationOperation | 是 | 转场类型。 |
返回值:
| 类型 | 说明 |
|---|---|
| NavigationAnimatedTransition | undefined | 自定义转场动画协议。 undefined:返回未定义,执行默认转场动效。 |
type IconType = ResourceStr | SymbolGlyphModifier | PixelMap
HdsNavigation标题栏上单个图标型菜单项支持的图片资源类型。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 5.1.0(18)
| 类型 | 说明 |
|---|---|
| ResourceStr | 字符串类型。 |
| SymbolGlyphModifier | symbol资源类型。 |
| PixelMap | 图像像素类型。 起始版本: 6.0.0(20) |
type BuilderType = ComponentContent | BuilderOptions
自定义节点类型。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Full
起始版本: 26.0.0
| 类型 | 说明 |
|---|---|
| ComponentContent | 组件内容封装类型。 |
| BuilderOptions | 自定义构建函数类型。 |
HdsNavigation标题栏的内容区样式。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 5.1.0(18)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| titleStyle | HdsNavigationTitleStyle | 否 | 是 | 标题栏内容区标题样式。 |
| menuStyle | HdsNavigationIconItemStyle | 否 | 是 | 标题栏内容区菜单栏样式。 |
| backIconStyle | HdsNavigationIconItemStyle | 否 | 是 | 标题栏内容区返回图标样式。 |
| subIconStyle | HdsNavigationIconItemStyle | 否 | 是 | 标题栏内容区子图标样式。 起始版本: 6.0.0(20) |
| dividerStyle | HdsNavigationDividerStyle | 否 | 是 | 标题栏内容区分割线样式。 起始版本: 6.0.0(20) |
HdsNavigation标题栏的动态样式参数配置。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 5.1.0(18)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| enableScrollEffect | boolean | 否 | 是 | 配置标题栏是否随内容区滚动的总偏移量动态生效标题栏样式。 默认值:true。 - true:内容区滚动的总偏移量从blurEffectiveStartOffset到blurEffectiveEndOffset,标题栏样式从originalStyle到scrollEffectStyle线性过渡。 - false:不随内容区滚动动态生效标题栏样式,仅生效originalStyle。 |
| scrollEffectType | ScrollEffectType | 否 | 是 | 标题栏模糊样式类型。 默认值:ScrollEffectType.COMMON_BLUR。 |
| enableRefreshOffsetChange | boolean | 否 | 是 | 是否响应内容区Refresh组件的滚动。 默认值:true。 - true:随内容区Refresh组件的滚动变化生效对应的标题栏样式。 - false:不随内容区Refresh组件的滚动变化生效对应的标题栏样式。 起始版本: 6.1.0(23) |
| blurEffectiveStartOffset | LengthMetrics | 否 | 是 | 动态样式线性过渡的起始位置。当内容区滚动的总偏移量超过该值时,标题栏开始从originalStyle到scrollEffectStyle线性过渡。 取值范围[0,+∞)。 默认值:LengthMetric.vp(0)。 超出取值范围时,按默认值处理。 |
| blurEffectiveEndOffset | LengthMetrics | 否 | 是 | 动态样式线性过渡的终点位置。当内容区滚动的总偏移量超过该值时,标题栏的动态样式过渡结束,固定为scrollEffectStyle。 取值范围[0,+∞)。 若设置数值小于blurEffectiveStartOffset,按默认值处理。 默认值: - 标题栏模糊样式类型设置为ScrollEffectType.COMMON_BLUR时,默认值为LengthMetric.vp(8)。 - 标题栏模糊样式类型设置为ScrollEffectType.GRADIENT_BLUR时,默认值为LengthMetric.vp(8)。起始版本: 6.0.0(20) - 标题栏模糊样式类型设置为ScrollEffectType.GRADUAL_BLUR,默认值为LengthMetric.vp(56)。起始版本: 6.0.0(20) -标题栏模糊样式类型设置为ScrollEffectType.IMMERSIVE_GRADIENT_BLUR,默认值为LengthMetric.vp(56)。起始版本: 6.1.0(23) |
HdsNavigation标题栏的样式配置。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 5.1.0(18)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| scrollEffectOpts | ScrollEffectOptions | 否 | 是 | 标题栏的动态样式参数配置。 |
| originalStyle | HdsNavigationTitleBarStyle | 否 | 是 | 设置标题栏的初始样式。 |
| scrollEffectStyle | HdsNavigationTitleBarStyle | 否 | 是 | 设置标题栏随内容区滚动生效的终点样式。 如果设置的模糊参数与模糊样式类型不匹配时,按照模糊样式类型对应的默认样式生效。 |
| blurStrategy | BlurStrategy | 否 | 是 | 设置标题栏的模糊生效策略。 默认值:BlurStrategy.ADAPTIVE。 起始版本: 6.0.0(20) |
| thermoCtrl | boolean | 否 | 是 | 设置组件样式的生效策略是否跟随热管理档位ThermalLevel信息管理。 默认值:false。 - true:跟随热管理档位信息生效组件样式,组件创建时,若ThermalLevel > OVERHEATED,关闭组件模糊效果。 - false:不跟随热管理档位信息生效组件样式。 起始版本: 6.1.0(23) |
| systemMaterialEffect | SystemMaterialParams | 否 | 是 | 设置标题栏沉浸光感样式。 起始版本: 6.1.0(23) |
HdsNavigation标题栏底部自定义区域配置。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.0.0(20)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| builder | CustomBuilder | 否 | 否 | 设置标题底部自定义区域内容。 |
| builderComponent | ComponentContent | 否 | 是 | 设置标题底部自定义区域内容。 当同时配置了builder属性与builderComponent属性时,生效builderComponent属性。 起始版本: 6.0.1(21) |
| builderContent | BuilderType | 否 | 是 | 设置标题底部自定义区域内容。 当同时配置了builder与builderContent属性时,生效builderContent属性;当配置了builderComponent与builderContent属性时,生效builderComponent属性。 起始版本: 26.0.0 |
| height | Length | 否 | 是 | 设置标题栏底部自定义区域高度。不支持设置百分比单位。 默认值:56vp。 |
| showType | BottomBuilderShowType | 否 | 是 | 设置标题栏底部自定义区域显示类型。仅在HideMode配置为HideMode.SCROLL_UP_TO时,该配置生效。 默认值:BottomBuilderShowType.DIRECTLY_SHOW。 |
HdsNavigation标题栏的内容区配置信息。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 5.1.0(18)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| title | HdsNavigationTitle | 否 | 是 | 设置标题栏标题内容。 |
| menu | HdsNavigationMenuContentOptions | 否 | 是 | 设置标题栏菜单栏内容。 |
| backIcon | HdsNavigationBackButtonItemOptions | 否 | 是 | 设置标题栏的返回按钮内容。 |
| stackBuilder | CustomBuilder | 否 | 是 | 设置标题栏顶部自定义区域。 起始版本: 6.0.0(20) |
| stackBuilderComponent | ComponentContent | 否 | 是 | 设置标题栏顶部自定义区域。 当同时配置了stackBuilder属性与stackBuilderComponent属性时,生效stackBuilderComponent属性。 起始版本: 6.0.1(21) |
| stackBuilderContent | BuilderType | 否 | 是 | 设置标题栏顶部自定义区域。 当同时配置了stackBuilder与stackBuilderContent属性时,生效stackBuilderContent属性;当同时配置了stackBuilderComponent与stackBuilderContent属性时,生效stackBuilderComponent属性。 起始版本: 26.0.0 |
| bottomBuilder | BottomBuilderParams | 否 | 是 | 设置标题栏底部自定义区域。 起始版本: 6.0.0(20) |
| divider | HdsNavigationDividerParams | 否 | 是 | 设置标题栏分割线内容。 起始版本: 6.0.0(20) |
| subIcon | HdsNavigationBadgeIconOptions | 否 | 是 | 设置标题栏子图标内容。 起始版本: 6.0.0(20) |
标题栏的内间距配置。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 5.1.0(18)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| start | LengthMetrics | 否 | 是 | 标题栏起始端内间距。 默认值:页面宽度小于600vp时,默认值为16vp,页面宽度大于等于840vp时,默认值为32vp,其他场景默认值为24vp。 |
| end | LengthMetrics | 否 | 是 | 标题栏结束端内间距。 默认值:页面宽度小于600vp时,默认值为16vp,页面宽度大于等于800vp时,默认值为32vp,其他场景默认值为24vp。 |
HdsNavigation标题栏动态显隐配置信息。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.0.0(20)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| hideTitleArea | boolean | 否 | 是 | 是否隐藏标题区域。 默认值:false。 - true:隐藏标题区域。 - false:不隐藏标题区域。 |
| hideBottomBuilder | boolean | 否 | 是 | 是否隐藏标题栏底部自定义区域。 默认值:false。 - true:隐藏标题栏底部自定义区域。 - false:不隐藏标题栏底部自定义区域。 |
| hideStatusBar | boolean | 否 | 是 | 是否隐藏状态栏区域。只有在配置隐藏标题区域时,配置隐藏状态栏才能生效 默认值:false。 - true:隐藏状态栏区域。 - false:不隐藏状态栏区域。 |
| mode | HideMode | 否 | 是 | 标题栏动态隐藏模式。 默认值:HideMode.SCROLL_UP_TO。 |
| hideOffset | number | 否 | 是 | 设置标题栏开始隐藏的滚动距离。只在HideMode.SCROLL_UP_TO隐藏模式下生效。 默认值:0。单位:vp。 |
| hideRatio | number | 否 | 是 | 设置内容区滚动距离与标题栏隐藏的比例,取值范围[1.0,3.0]。 当内容区每滚动1vp,标题栏隐藏1/hideRatio vp。 超出取值范围,按默认值处理。 默认值:2.0。 |
嵌套可滚动容器组件信息。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.0.0(20)
标题栏WithTheme能力配置信息。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 6.1.0(23)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| enableThemeColorMode | boolean | 否 | 是 | 是否支持WithTheme作用域内组件自定义深浅色配置。 默认值:false。 - true:支持WithTheme作用域内自定义深浅色配置。 - false:不支持WithTheme作用域内自定义深浅色配置。 |
材质效果参数。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
设备行为差异: 该接口在Phone、Tablet中可正常调用,在PC/2in1设备调用时需先调用getSystemMaterialTypes()接口查询当前设备支持的材质能力。
起始版本: 6.1.0(23)
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| materialType | hdsMaterial.MaterialType | 否 | 是 | 设置材质类型。 默认值:hdsMaterial.MaterialType.NONE。 |
| materialLevel | hdsMaterial.MaterialLevel | 否 | 是 | 设置材质等级。 默认值:hdsMaterial.MaterialLevel.ADAPTIVE 说明: 推荐使用默认值ADAPTIVE档位: 该模式下,系统会根据当前设备的算力动态调整组件的材质效果,实现性能与显示效果的最佳平衡体验。 若未采用系统自适应能力: 请先调用getSystemMaterialTypes()接口查询当前设备支持的材质能力,再根据查询结果选用相应的材质效果枚举: 1. 如果查询结果显示当前设备支持IMMERSIVE材质类型,可选用EXQUISITE或GENTLE效果。 2. 如果查询结果显示当前设备不支持IMMERSIVE材质类型,则建议使用SMOOTH效果,以降低卡顿和发热风险,保障用户体验。 详细使用指导: 请参见HDS组件使用沉浸光感材质指南。 |
构建导航标题栏中的自定义组件配置信息。
模型约束: 此接口仅可在Stage模型下使用。
系统能力: SystemCapability.UIDesign.HDSComponent.Core
起始版本: 26.0.0
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| builder | CustomBuilder | 否 | 是 | 用户自定义组件。 |
| updated | boolean | 否 | 是 | 设置是否需要更新自定义组件节点。 默认值:true。 - true:需要更新自定义组件节点。 - false:不更新自定义组件节点,保持原节点,不重新挂载新节点。 |
通过titleBar属性,自定义设置标题栏随内容区滚动的动态模糊样式。
// 从6.0.2(22)版本开始,无需手动导入HdsNavigationAttribute。具体请参考HdsNavigation的导入模块说明。
import { HdsNavigation, HdsNavigationAttribute, 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.scenery')).width('100%') // scenery为自定义资源,开发者需替换本地资源
}
}.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: 'Main',
subTitle: this.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: '#0A59F7' }, { statusBarContentColor: '#C7C7CD' })
.titleMode(this.titleMode)
.hideBackButton(this.isHideBackButton)
.hideTitleBar(false)
}
} 
通过设置标题栏上菜单配置中的badge属性,使用信息提醒能力,在菜单项右上角附加消息提醒。
// 从6.0.2(22)版本开始,无需手动导入HdsNavigationAttribute。具体请参考HdsNavigation的导入模块说明。
import { HdsNavigation, HdsNavigationAttribute } from '@kit.UIDesignKit';
const TITLE_BAR_HEIGHT_FREE: number = 138;
@Entry
@Component
struct Index {
@Provide('pageInfos') pageInfos: NavPathStack = new NavPathStack();
@State blankHeight: number = TITLE_BAR_HEIGHT_FREE;
@State subTitle: string = 'Sub';
build() {
HdsNavigation(this.pageInfos) {
Column() {
Stack() {
Column() {
Blank().height(this.blankHeight)
Image($r('app.media.background1')) // background1为自定义资源,开发者需替换本地资源
.width('100%')
}
}
}
}
.titleBar({
content: {
title: {
mainTitle: 'Main',
subTitle: this.subTitle
},
menu: {
value: [{
content: {
label: 'menu1',
icon: $r('sys.symbol.plus'),
isEnabled: true
},
badge: {
count: 1
}
}, {
content: {
label: 'menu2',
icon: $r('sys.symbol.trunk'),
isEnabled: true
},
badge: {
count: 100
}
}]
}
}
})
}
} 
通过设置titleBar属性中的stackBuilder,bottomBuilder属性,可以使用标题栏的自定义区域设置能力。
// 从6.0.2(22)版本开始,无需手动导入HdsNavigationAttribute。具体请参考HdsNavigation的导入模块说明。
import { HdsNavigation, HdsNavigationAttribute, ScrollEffectType } from '@kit.UIDesignKit';
import { LengthMetrics } from '@kit.ArkUI';
const TITLE_BAR_HEIGHT_FREE: number = 138;
const BOTTOM_BUILDER_HEIGHT: number = 56;
@Entry
@Component
struct Index {
scroller: Scroller = new Scroller();
@State blankHeight: number = TITLE_BAR_HEIGHT_FREE + BOTTOM_BUILDER_HEIGHT;
@Builder
stackBuilder() {
Column() {
Button('HdsNavigation')
}
.height(56)
.justifyContent(FlexAlign.Center)
}
@Builder
bottomBuilder() {
Column() {
Search()
}
.width('100%')
.height(56)
}
build() {
Column() {
HdsNavigation() {
Scroll(this.scroller) {
Column() {
Blank().height(this.blankHeight).width('100%')
Image($r('app.media.scenery')).width('100%') // scenery为自定义资源,开发者需替换本地资源
}
}.edgeEffect(EdgeEffect.Spring).scrollBar(BarState.Off)
}
.titleBar({
style: {
scrollEffectOpts: {
enableScrollEffect: true,
scrollEffectType: ScrollEffectType.GRADIENT_BLUR,
blurEffectiveStartOffset: LengthMetrics.vp(0),
blurEffectiveEndOffset: LengthMetrics.vp(20)
},
scrollEffectStyle: {
backgroundStyle: { maskExtraHeight: 56.0 }
}
},
content: {
title: {
mainTitle: 'MainTitle',
subTitle: 'SubTitle'
},
stackBuilder: (): void => this.stackBuilder(),
bottomBuilder: { builder: (): void => this.bottomBuilder() },
menu: {
value: [{
content: {
label: 'menu1',
icon: $r('sys.symbol.plus')
},
}, {
content: {
label: 'menu2',
icon: $r('sys.symbol.lock')
}
}]
}
}
})
.bindToScrollable([this.scroller])
}
}
} 
通过设置dynamicHideTitleBar属性,可以使用标题栏随内容区动态显隐能力。
// 从6.0.2(22)版本开始,无需手动导入HdsNavigationAttribute。具体请参考HdsNavigation的导入模块说明。
import { HdsNavigation, HdsNavigationAttribute, HideMode } from '@kit.UIDesignKit';
const TITLE_BAR_HEIGHT_FREE: number = 138;
const BOTTOM_BUILDER_HEIGHT: number = 56;
@Entry
@Component
struct Index {
scroller: Scroller = new Scroller();
@State blankHeight: number = TITLE_BAR_HEIGHT_FREE + BOTTOM_BUILDER_HEIGHT;
@Builder
bottomBuilder() {
Column() {
Search()
}
.width('100%')
.height(56)
}
build() {
Column() {
HdsNavigation() {
Scroll(this.scroller) {
Column() {
Blank().height(this.blankHeight).width('100%')
Image($r('app.media.scenery')).width('100%') // scenery为自定义资源,开发者需替换本地资源
}
}.edgeEffect(EdgeEffect.Spring).scrollBar(BarState.Off)
}
.titleBar({
content: {
title: {
mainTitle: 'MainTitle',
subTitle: 'SubTitle'
},
bottomBuilder: { builder: (): void => this.bottomBuilder() },
menu: {
value: [{
content: {
label: 'menu1',
icon: $r('sys.symbol.plus')
}
}]
}
}
})
.bindToScrollable([this.scroller])
.dynamicHideTitleBar({
hideTitleArea: true,
hideBottomBuilder: true,
hideStatusBar: false,
mode: HideMode.SCROLL_UP_TO
})
}
}
} 
通过设置HdsNavigationIconOptions属性中的type属性,可以设置图标为文字型或者图片型图标。
// 从6.0.2(22)版本开始,无需手动导入HdsNavigationAttribute。具体请参考HdsNavigation的导入模块说明。
import {
HdsNavigation,
HdsNavigationAttribute,
HdsNavigationTitleMode,
IconStyleMode,
TextStyleMode,
DividerShowType
} from '@kit.UIDesignKit';
const TITLE_BAR_HEIGHT_MINI: number = 56;
@Entry
@Component
struct Index {
scroller: Scroller = new Scroller();
@State blankHeight: number = TITLE_BAR_HEIGHT_MINI;
build() {
Column() {
HdsNavigation() {
Scroll(this.scroller) {
Column() {
Blank().height(this.blankHeight).width('100%')
Image($r('app.media.background1')).width('100%')
}
}.edgeEffect(EdgeEffect.Spring).scrollBar(BarState.Off)
}
.titleMode(HdsNavigationTitleMode.MINI)
.titleBar({
content: {
title: {
mainTitle: 'Main',
subTitle: 'Sub'
},
menu: {
value: [{
content: {
label: 'CAPSULE',
type: TextStyleMode.NORMAL
}
}, {
content: {
label: '5',
type: TextStyleMode.SINGLE_CHARACTER
}
}, {
content: {
label: 'smallIcon',
icon: $r('sys.symbol.plus'),
type: IconStyleMode.LARGE
}
}]
},
subIcon: {
content: {
label: 'headIcon',
icon: $r('sys.symbol.lock'),
type: IconStyleMode.SMALL
}
},
divider: { showType: DividerShowType.ON }
}
})
}
}
} 
通过titleMode设置半模态标题栏显示模式,半模态模式下,可以在subTitle右侧区域设置用户自定义的subTitleBuilder。半模态样式下,设置图标类型为IconStyleMode.SMALL,同时不设置图标资源时,默认显示关闭按钮。
// 从6.0.2(22)版本开始,无需手动导入HdsNavigationAttribute。具体请参考HdsNavigation的导入模块说明。
import { HdsNavigation, HdsNavigationAttribute, HdsNavigationTitleMode, IconStyleMode } from '@kit.UIDesignKit';
const TITLE_BAR_HEIGHT_MODAL: number = 80;
@Entry
@Component
struct SheetTransitionExample {
@State isShow: boolean = false;
@State blankHeight: number = TITLE_BAR_HEIGHT_MODAL;
scroller: Scroller = new Scroller();
@Builder
subTitleBuilder() {
Text('click to share')
.fontColor(Color.Blue)
.maxFontScale(1)
.lineHeight(`${14 * 1.49}vp`)
.fontSize(14)
.onClick(() => {
console.info('click to share');
})
}
// 创建半模态页面显示内容
@Builder
myBuilder() {
Column() {
HdsNavigation() {
Scroll(this.scroller) {
Column() {
Blank().height(this.blankHeight).width('100%')
Image($r('app.media.background1')) // background1为自定义资源,开发者需替换本地资源
.width('100%')
}
}.edgeEffect(EdgeEffect.Spring).scrollBar(BarState.Off)
}
.titleMode(HdsNavigationTitleMode.MODAL) // 设置显示的HdsNavigation为半模态样式
.titleBar({
content: {
title: {
mainTitle: 'MainTitle',
subTitle: 'SubTitle',
subTitleBuilder: (): void => this.subTitleBuilder() // 自定义副标题区域
},
menu: {
value: [{
content: {
label: 'modal_cancel',
isEnabled: true,
type: IconStyleMode.SMALL,
action: () => {
console.info('model cancel');
}
}
}]
},
subIcon: {
content: {
label: 'leftIcon',
icon: $r('sys.symbol.ohos_wifi'),
isEnabled: true
}
}
}
})
}
}
build() {
Column() {
Button('transition modal')
.onClick(() => {
this.isShow = true;
})
.fontSize(20)
.margin(10)
.bindSheet($$this.isShow, this.myBuilder(), { showClose: false }) // 绑定半模态页面
}
.justifyContent(FlexAlign.Center)
.width('100%')
.height('100%')
}
} 
创建一级导航组件,通过配置titleBar中的menu上的multiWindowEntryInAPPMenu属性,实现应用内多窗图标设置。
// 从6.0.2(22)版本开始,无需手动导入HdsNavigationAttribute。具体请参考HdsNavigation的导入模块说明。
import { HdsNavigation, HdsNavigationAttribute, HdsNavigationMenuContentOptions } from '@kit.UIDesignKit';
import { Want } from '@kit.AbilityKit';
@Entry
@Component
struct MultiWindowEntryInAPPTest {
private want: Want = {
// 修改为当前应用的bundleName、moduleName、abilityName,启动应用内的UIAbility
bundleName: "com.example.myapplication",
moduleName: "entry",
abilityName: "FuncAbility",
}
@State menuContent: HdsNavigationMenuContentOptions = {
multiWindowEntryInAPPMenu: {
want: this.want,
},
maxCount: 3,
value: [
{ content: { label: 'menu1', icon: $r('sys.symbol.search_things'), } },
{ content: { label: 'menu2', icon: $r('sys.symbol.plus'), } }
]
}
build() {
HdsNavigation() {
Stack() {
Text("Page1")
}.alignContent(Alignment.Center)
.width("100%")
.height("100%")
}
.hideToolBar(false)
.navBarWidth('100%')
.titleBar({
content: {
title: {
mainTitle: "Index"
},
menu: this.menuContent
}
})
}
} 
该示例主要展示HdsNavigation配置沉浸式模糊和材质的各类型效果。
示例:
// 从6.0.2(22)版本开始,无需手动导入HdsNavigationAttribute。具体请参考HdsNavigation的导入模块说明。
import {
hdsMaterial,
HdsNavigation,
HdsNavigationAttribute,
HdsNavigationTitleMode,
ScrollEffectType
} from '@kit.UIDesignKit';
import { promptAction } from '@kit.ArkUI';
@Entry
@Component
struct Index {
private scrollerForScroll: Scroller = new Scroller();
@State materialLevel: hdsMaterial.MaterialLevel = hdsMaterial.MaterialLevel.ADAPTIVE;
@State materialType: hdsMaterial.MaterialType = hdsMaterial.MaterialType.IMMERSIVE;
aboutToAppear(): void {
// 该示例以系统支持的材质类型为hdsMaterial.MaterialType.IMMERSIVE为例
try {
let materialTypes: Array<hdsMaterial.MaterialType> = hdsMaterial.getSystemMaterialTypes();
console.info(`getSystemMaterialTypes successed, types: ${materialTypes}`);
} catch (err) {
let message = (err as BusinessError).message;
let code = (err as BusinessError).code;
console.error(`getSystemMaterialTypes failed, code: ${code}, message: ${message}`);
}
}
build() {
HdsNavigation() {
Scroll(this.scrollerForScroll) {
Column() {
// 'app.media.demo_img'需要替换为开发者所需的资源文件
Image($r('app.media.demo_img'))
.width('100%')
Text(`当前材质Level为: ${this.materialLevel}`).fontSize(20).fontWeight(FontWeight.Bold)
Text(`当前材质Type为: ${this.materialType}`).fontSize(20).fontWeight(FontWeight.Bold)
Button('切换材质Type为None').onClick(() => {
// 无材质效果
this.materialType = hdsMaterial.MaterialType.NONE;
}).margin({ top: 2 })
}.height('100%')
}.edgeEffect(EdgeEffect.Spring).height('100%')
}
.titleBar({
content: {
title: {
mainTitle: '主标题'
},
menu: {
value: [{
content: {
icon: $r('sys.symbol.search_things'),
label: 'search',
action: () => {
try {
promptAction.openToast({ message: 'on click' })
.then(() => {
console.info('openToast success');
})
.catch((err: BusinessError) => {
console.error(`openToast error code is ${err.code}, message is ${err.message}`);
})
} catch (error) {
let message = (error as BusinessError).message;
let code = (error as BusinessError).code;
console.error(`openToast args error code is ${code}, message is ${message}`);
}
}
}
}]
}
},
style: {
scrollEffectOpts: {
// 从6.1.0(23)开始, 新增IMMERSIVE_GRADIENT_BLUR类型,标题文字和图标样式从白色到黑色线性过渡。
scrollEffectType: ScrollEffectType.IMMERSIVE_GRADIENT_BLUR
},
// 从6.1.0(23)开始,支持材质相关属性。
// 推荐与ScrollEffectType.IMMERSIVE_GRADIENT_BLUR(推荐沉浸式图文类的场景使用) 或 ScrollEffectType.GRADIENT_BLUR(推荐非沉浸式列表类的场景使用)搭配使用。
systemMaterialEffect: {
materialType: this.materialType,
materialLevel: this.materialLevel
}
}
})
.bindToScrollable([this.scrollerForScroll])
.hideBackButton(true)
.titleMode(HdsNavigationTitleMode.MINI)
.ignoreLayoutSafeArea([LayoutSafeAreaType.SYSTEM], [LayoutSafeAreaEdge.TOP, LayoutSafeAreaEdge.BOTTOM])
}
} 效果展示:
执行上述代码展示的效果如下。

该示例主要演示如下两点功能:
NavPathStack无需声明为状态变量,也可以实现路由栈操作功能。
HdsNavDestination (导航子页面容器)通过onReady事件能够拿到对应的NavPathInfo和所属的NavPathStack。
示例:
import {
HdsNavDestination,
HdsNavigation,
HdsNavigationAttribute,
HdsNavDestinationAttribute,
HdsNavigationTitleMode
} from '@kit.UIDesignKit';
class PageParam {
constructor(num_: number) {
this.num = num_;
}
num: number = 0;
}
@Builder
export function PageOneBuilder(name: string, param: Object) {
PageOne();
}
@Component
struct PageOne {
private stack: NavPathStack | null = null;
private name: string = '';
private paramNum: number = 0;
build() {
HdsNavDestination() {
Column() {
Text('NavPathInfo: name: ' + this.name + ', paramNum: ' + this.paramNum)
Button('pushPath', { stateEffect: true, type: ButtonType.Capsule })
.width('80%')
.height(40)
.margin(20)
.onClick(() => {
if (this.stack) {
let p = new PageParam(this.paramNum + 1);
this.stack.pushPath({ name: 'pageOne', param: p });
}
})
Button('pop', { stateEffect: true, type: ButtonType.Capsule })
.width('80%')
.height(40)
.margin(20)
.onClick(() => {
this.stack?.pop();
})
}
.width('100%')
.height('100%')
}
.titleBar({
enableComponentSafeArea: true,
content: {
title: {
mainTitle: 'PageOne'
}
}
})
.onReady((ctx: NavDestinationContext) => {
// 在NavDestination中能够拿到传来的NavPathInfo和当前所处的NavPathStack
try {
this.name = ctx?.pathInfo?.name;
this.paramNum = (ctx?.pathInfo?.param as PageParam)?.num;
this.stack = ctx.pathStack;
} catch (e) {
console.error(`testTag onReady catch exception: ${JSON.stringify(e)}`);
}
})
}
}
@Entry
@Component
struct NavigationExample2 {
private stack: NavPathStack = new NavPathStack();
build() {
HdsNavigation(this.stack) {
Stack({ alignContent: Alignment.Center }) {
Button('pushPath', { stateEffect: true, type: ButtonType.Capsule })
.width('80%')
.height(40)
.margin(20)
.onClick(() => {
let p = new PageParam(1);
this.stack.pushPath({ name: 'pageOne', param: p });
})
}
.width('100%')
.height('100%')
}
.width('100%')
.height('100%')
.titleBar({
content: {
title: {
mainTitle: '主标题'
}
}
})
.titleMode(HdsNavigationTitleMode.MINI)
.hideBackButton(true)
}
} 在src/main目录下的module.json5配置文件中的module字段里配置"routerMap": "$profile:router_map",并在src/main/resources/base/profile目录下新增router_map.json。router_map.json示例如下。
{
"routerMap": [
{
"name": "pageOne",
"pageSourceFile": "src/main/ets/pages/Index.ets",
"buildFunction": "PageOneBuilder",
"data": {
"description": "this is pageOne"
}
}
]
} 效果展示:
执行上述代码,效果展示如下。
