HdsNavDestination (导航子页面容器)

导入模块

6.0.1(21)及之前版本：

import { HdsNavDestination, HdsNavDestinationAttribute } from '@kit.UIDesignKit';

6.0.2(22)及之后版本：

import { HdsNavDestination } from '@kit.UIDesignKit';

子组件

• 子组件类型：系统组件和自定义组件，支持渲染控制类型（if/else、ForEach和LazyForEach）。

• 子组件个数：多个。

接口

HdsNavDestination()

创建HdsNavigation (导航根视图容器)子页面的根容器。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 5.1.0(18)

属性

支持通用属性。

不推荐设置位置、大小等布局相关属性，可能会造成页面显示异常。

titleBar

titleBar(options?: HdsNavigationTitleBarOptions)

设置HdsNavDestination组件titleBar区域（包括返回图标区域、标题区域、菜单区域、背景板）样式以及内容。

标题字符串超长时，如果不设置副标题，先缩小再换行（2行）最后以"..."截断。如果设置副标题，先缩小后以"..."截断。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 5.1.0(18)

参数：

hideTitleBar

hideTitleBar(hide: boolean, animated?: boolean)

设置是否隐藏标题栏，并且可设置在标题栏显示隐藏的状态变化中是否使用动画。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 5.1.0(18)

参数：

hideBackButton

hideBackButton(value: boolean)

设置是否隐藏标题栏中的返回键。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 5.1.0(18)

参数：

mode

mode(value: NavDestinationMode)

设置HdsNavDestination类型，不支持动态修改。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 5.1.0(18)

参数：

toolbarConfiguration

toolbarConfiguration(toolbarParam: Array<ToolbarItem> | CustomBuilder, options?: NavigationToolbarOptions)

设置工具栏内容。未调用本接口时不显示工具栏。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 5.1.0(18)

参数：

hideToolBar

hideToolBar(hide: boolean, animated?: boolean)

设置是否隐藏工具栏，并且可设置在工具栏显示隐藏的状态变化中是否使用动画。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 5.1.0(18)

参数：

ignoreLayoutSafeArea

ignoreLayoutSafeArea(types?: Array<LayoutSafeAreaType>, edges?: Array<LayoutSafeAreaEdge>)

控制组件的布局，使其扩展到非安全区域。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 5.1.0(18)

参数：

systemBarStyle

systemBarStyle(originalStyle: Optional<SystemBarStyle>, scrollEffectStyle: Optional<SystemBarStyle>)

当HdsNavigation中显示当前HdsNavDestination时，设置对应系统状态栏的样式。若未与HdsNavigation配合使用，systemBarStyle属性可能不会生效，建议开发者在使用前确保已正确配置HdsNavigation组件。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 5.1.0(18)

参数：

说明：

1. 必须配合HdsNavigation使用，作为其HdsNavigation目的页面的根节点时才能生效。

2. 其他使用限制请参考HdsNavigation对应的systemBarStyle属性说明。

recoverable

recoverable(recoverable: Optional<boolean>)

配置HdsNavDestination是否可恢复。如配置为可恢复，当应用进程异常退出并重新冷启动时，可自动创建该HdsNavDestination。该功能需HdsNavDestination对应的HdsNavigation也配置了可恢复属性使用。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 5.1.0(18)

参数：

dynamicHideTitleBar

dynamicHideTitleBar(value: DynamicHideParams)

设置标题栏跟随内容区动态显隐配置，推荐搭配bindToScrollable/bindToNestedScrollable体验更佳的滑动效果。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 6.0.0(20)

参数：

bindToScrollable

bindToScrollable(scrollers: Array<Scroller>)

绑定导航组件和可滚动容器组件，动态显隐标题区域，状态栏及底部自定义区域，使能动态显隐更优体验。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 6.0.0(20)

参数：

bindToNestedScrollable

bindToNestedScrollable(scrollers: Array<NestedScrollInfo>)

绑定导航组件和嵌套的可滚动容器组件，动态显隐标题区域，状态栏及底部自定义区域，使能动态显隐更优体验。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 6.0.0(20)

参数：

systemTransition

systemTransition(type: NavigationSystemTransitionType)

设置HdsNavDestination系统转场动画，支持分别设置系统标题栏动画和内容动画。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 6.0.0(20)

参数：

customTransition

customTransition(delegate: NavDestinationTransitionDelegate)

设置HdsNavDestination自定义转场动画。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 6.0.0(20)

参数：

titleMode

titleMode(value: HdsNavDestinationTitleMode)

设置页面标题栏显示模式。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 6.0.0(20)

参数：

withTheme

withTheme(value: WithThemeOptions)

设置HdsNavDestination的WithTheme能力。使用本功能时，需确保HdsNavDestination组件与对应的HdsNavigation (导航根视图容器)组件配置的WithTheme属性保持一致。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 6.1.0(23)

事件

onShown

onShown(callback: Callback<void>)

当显示HdsNavDestination页面时，触发onShown回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 5.1.0(18)

onShown

onShown(callback: Callback<VisibilityChangeReason>)

当显示HdsNavDestination页面时，触发onShown回调。通过VisibilityChangeReason说明触发的原因。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 6.1.0(23)

onHidden

onHidden(callback: Callback<void>)

当隐藏HdsNavDestination页面时，触发onHidden回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 5.1.0(18)

onHidden

onHidden(callback: Callback<VisibilityChangeReason>)

当隐藏HdsNavDestination页面时，触发onHidden回调。通过VisibilityChangeReason说明触发的原因。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 6.1.0(23)

onReady

onReady(callback: Callback<NavDestinationContext>)

当HdsNavDestination即将构建子组件之前会触发此回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 5.1.0(18)

onWillAppear

onWillAppear(callback: Callback<void>)

当该HdsNavDestination挂载之前触发此回调。在该回调中允许修改页面栈，当前帧生效。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 5.1.0(18)

onWillDisappear

onWillDisappear(callback: Callback<void>)

当该HdsNavDestination卸载之前触发的生命周期（有转场动画时，在转场动画开始之前触发）。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 5.1.0(18)

onWillShow

onWillShow(callback: Callback<void>)

当该HdsNavDestination显示之前触发此回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 5.1.0(18)

onWillHide

onWillHide(callback: Callback<void>)

当该HdsNavDestination隐藏之前触发此回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 5.1.0(18)

onBackPressed

onBackPressed(callback: Callback<void, boolean>)

当与HdsNavigation绑定的页面栈中存在内容时，此回调生效。当点击返回键时，触发该回调。

返回值为true时，表示重写返回键逻辑，返回值为false时，表示回退到上一个页面。不推荐同时设置返回键自定义事件与onBackPressed回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 6.0.0(20)

onActive

onActive(callback: Optional<Callback<NavDestinationActiveReason>>)

HdsNavDestination处于激活态（处于栈顶可操作，且上层无特殊组件遮挡）时，触发该回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 6.0.1(21)

onInactive

onInactive(callback: Optional<Callback<NavDestinationActiveReason>>)

HdsNavDestination处于非激活态（处于非栈顶不可操作，或处于栈顶时上层有特殊组件遮挡）时，触发该回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 6.0.1(21)

onResult

onResult(callback: Optional<Callback<ESObject>>)

HdsNavDestination返回时触发该回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 26.0.0

参数：

onNewParam

onNewParam(callback: Optional<Callback<ESObject>>)

当之前存在于栈中的HdsNavDestination页面通过launchMode.MOVE_TO_TOP_SINGLETON或launchMode.POP_TO_SINGLETON移动到栈顶时，触发该回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 26.0.0

参数：

HdsNavDestinationTitleMode

标题栏显示模式枚举。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.UIDesign.HDSComponent.Core

起始版本： 6.0.0(20)

示例

通过titleBar属性，自定义设置标题栏随内容区滚动的动态模糊样式。

import { HdsNavDestination, HdsNavDestinationAttribute, ScrollEffectType } from '@kit.UIDesignKit';
import { LengthMetrics } from '@kit.ArkUI';

const TITLE_BAR_HEIGHT_MINI: number = 56;

@Entry
@Component
struct PageOne {
  scroller: Scroller = new Scroller();

  build() {
    HdsNavDestination() {
      Scroll(this.scroller) {
        Column() {
          Blank().height(TITLE_BAR_HEIGHT_MINI)
          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: 'PageOne',
        },
        menu: {
          value: [{
            content: {
              label: 'menu1',
              icon: 'resources/base/media/startIcon.png',
              isEnabled: true,
              action: () => {
                console.info('HdsNavDestination menu1');
              }
            }
          }, {
            content: {
              label: 'menu2',
              icon: 'resources/base/media/startIcon.png',
              isEnabled: true,
              action: () => {
                console.info('HdsNavDestination menu2');
              }
            }
          }]
        }
      }
    })
    .bindToScrollable([this.scroller])
    .systemBarStyle({ statusBarContentColor: '#0A59F7' }, { statusBarContentColor: '#C7C7CD' })
    .hideBackButton(false)
  }
}

HdsNavDestination更多示例可以参考HdsNavigation示例。