文档管理中心

NavDestination

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

作为子页面的根容器,用于显示Navigation的内容区。

说明
  • 该组件从API version 9开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。

  • 该组件从API version 11开始默认支持安全区避让特性(默认值为:expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM])),开发者可以重写该属性覆盖默认行为,API version 11之前的版本需配合expandSafeArea属性实现安全区避让。

  • NavDestination组件必须配合Navigation使用,作为Navigation目的页面的根节点,单独使用只能作为普通容器组件,不具备路由相关属性能力。

  • 如果路由栈中间页面的生命周期发生变化,跳转之前的栈顶NavDestination的生命周期(onWillShow, onShown, onHidden, onWillDisappear)与跳转之后的栈顶NavDestination的生命周期(onWillShow, onShown, onHidden, onWillDisappear)均在最后触发。

  • NavDestination未设置主副标题并且没有返回键时,不显示标题栏。

  • 不建议设置位置、大小等布局相关属性,可能会造成页面显示异常。例如在NavDestination上添加zIndex属性时,会覆盖掉系统设置的层级,可能导致出现显示异常。

子组件

说明
  • 子组件类型:系统组件和自定义组件,支持渲染控制类型(if/elseForEachLazyForEach)。
  • 子组件个数:多个。

接口

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

NavDestination()

创建Navigation子页面的根容器。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

属性

支持通用属性

title

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

title(value: string | CustomBuilder | NavDestinationCommonTitle | NavDestinationCustomTitle | Resource, options?: NavigationTitleOptions)

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

说明

从API version 12开始,该接口支持在attributeModifier中调用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
value string | CustomBuilder | NavDestinationCommonTitle | NavDestinationCustomTitle | Resource14+ 页面标题。
options12+ NavigationTitleOptions

标题栏选项。

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

hideTitleBar

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

hideTitleBar(value: boolean)

设置是否隐藏标题栏。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
value boolean

是否隐藏标题栏。

默认值:false

true:隐藏标题栏。

false:显示标题栏。

hideTitleBar13+

Phone13+PC/2in113+Tablet13+TV19+Wearable18+

hideTitleBar(hide: boolean, animated: boolean)

设置是否隐藏标题栏。与hideTitleBar相比,新增标题栏显隐时是否使用动画。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
hide boolean

是否隐藏标题栏。

默认值:false

true:隐藏标题栏。

false:显示标题栏。

animated boolean

设置是否使用动画显隐标题栏。

默认值:false

true:使用动画显示隐藏标题栏。

false:不使用动画显示隐藏标题栏。

fullScreenOverlay

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

fullScreenOverlay(fullScreenOverlay: Optional<boolean>)

设置NavDestination是否以全屏覆盖模式显示。

当参数设置为true时,在Navigation分栏模式下,当前页面会覆盖整个Navigation容器,包括NavBar和内容区。该配置作用于当前NavDestination的所有实例;当路由栈中已有页面以全屏覆盖模式显示时,其后入栈的DIALOG页面与未设置fullScreenOverlay为false的STANDARD页面也会继承为全屏覆盖显示。未通过该接口设置时,NavDestination默认是普通显示模式,遵循Navigation分栏显示规则。

起始版本: 26.0.0

元服务API: 从API版本26.0.0开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
fullScreenOverlay Optional<boolean>

是否以全屏覆盖模式显示。

true:全屏覆盖模式,覆盖整个Navigation容器。

false:普通显示模式,遵循Navigation分栏显示规则。指定为false的STANDARD类型页面不会继承全屏显示。

undefined:普通显示模式,遵循Navigation分栏显示规则。指定为undefined的页面会继承全屏显示。

toolbarConfiguration13+

Phone13+PC/2in113+Tablet13+TV19+Wearable18+

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

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

说明
  • 从API version 20开始,该接口支持在attributeModifier中调用。

  • 不支持通过SymbolGlyphModifier对象的fontSize属性修改图标大小、effectStrategy属性修改动效、symbolEffect属性修改动效类型。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
toolbarParam Array<ToolbarItem> | CustomBuilder

工具栏内容。

使用Array<ToolbarItem>写法设置的工具栏有如下特性:

-工具栏所有选项均分底部工具栏,在每个均分内容区布局文本和图标。

-竖屏模式最多支持显示5个图标,多余的图标会被放入自动生成的更多图标中,点击更多图标,可以展示剩余内容。横屏模式时,如果为Split模式,仍按照竖屏模式显示,如果为Stack模式需配合menus属性的Array<NavigationMenuItem>使用,底部工具栏会自动隐藏,同时底部工具栏所有选项移动至页面右上角菜单。

使用CustomBuilder写法为用户自定义工具栏选项,不具备以上功能。

options NavigationToolbarOptions 工具栏选项。包含工具栏背景颜色、工具栏背景模糊样式及模糊选项、工具栏背景属性、工具栏布局方式、是否隐藏工具栏的文本、工具栏更多图标的菜单选项。

hideToolBar13+

Phone13+PC/2in113+Tablet13+TV19+Wearable18+

hideToolBar(hide: boolean, animated?: boolean)

设置是否隐藏工具栏。

元服务API: 从API version 13开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
hide boolean

是否隐藏工具栏。

默认值:false

true:隐藏工具栏。

false:显示工具栏。

animated boolean

设置是否使用动画显隐工具栏。

默认值:false

true:使用动画显示隐藏工具栏。

false:不使用动画显示隐藏工具栏。

mode11+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

mode(value: NavDestinationMode)

设置NavDestination类型,不支持动态修改。

说明

从API version 12开始,该接口支持在attributeModifier中调用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
value NavDestinationMode

NavDestination类型。

默认值:NavDestinationMode.STANDARD

backButtonIcon11+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

backButtonIcon(value: ResourceStr | PixelMap | SymbolGlyphModifier)

设置标题栏返回键图标。

说明
  • 从API version 12开始,该接口支持在attributeModifier中调用。

  • 不支持通过SymbolGlyphModifier对象的fontSize属性修改图标大小、effectStrategy属性修改动效、symbolEffect属性修改动效类型。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
value ResourceStr | PixelMap | SymbolGlyphModifier12+ 标题栏返回键图标。

backButtonIcon19+

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

backButtonIcon(icon: ResourceStr | PixelMap | SymbolGlyphModifier, accessibilityText?: ResourceStr)

设置标题栏返回键图标和无障碍播报内容。

说明
  • 该接口不支持在attributeModifier中调用。

  • 不支持通过SymbolGlyphModifier对象的fontSize属性修改图标大小、effectStrategy属性修改动效、symbolEffect属性修改动效类型。

元服务API: 从API version 19开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
icon ResourceStr | PixelMap | SymbolGlyphModifier 标题栏返回键图标。
accessibilityText ResourceStr

返回键无障碍播报内容。

默认值:系统语言是中文时为“返回”,系统语言是英文时为“back”。

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

menus(value: Array<NavigationMenuItem> | CustomBuilder)

设置页面右上角菜单。不设置时不显示菜单项。使用Array<NavigationMenuItem> 写法时,竖屏最多支持显示3个图标,横屏最多支持显示5个图标,多余的图标会被放入自动生成的更多图标。

说明
  • 从API version 14开始,该接口支持在attributeModifier中调用。

  • 不支持通过SymbolGlyphModifier对象的fontSize属性修改图标大小、effectStrategy属性修改动效、symbolEffect属性修改动效类型。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
value Array<NavigationMenuItem> | CustomBuilder 页面右上角菜单。
Phone19+PC/2in119+Tablet19+TV19+Wearable19+

menus(items: Array<NavigationMenuItem> | CustomBuilder, options?: NavigationMenuOptions)

设置页面右上角菜单。不设置时不显示菜单项。与menus相比,新增菜单选项。使用Array<NavigationMenuItem> 写法时,竖屏最多支持显示3个图标,横屏最多支持显示5个图标,多余的图标会被放入自动生成的更多图标。

说明
  • 该接口不支持在attributeModifier中调用。

  • 不支持通过SymbolGlyphModifier对象的fontSize属性修改图标大小、effectStrategy属性修改动效、symbolEffect属性修改动效类型。

元服务API: 从API version 19开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
items Array<NavigationMenuItem> | CustomBuilder 页面右上角菜单。
options NavigationMenuOptions 页面右上角菜单选项。

ignoreLayoutSafeArea12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

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

说明
  • 组件设置ignoreLayoutSafeArea之后生效的条件为:

    设置LayoutSafeAreaType.SYSTEM时,组件的边界与非安全区域重合时组件能够延伸到非安全区域下。

  • 若组件扩展到非安全区域内,此时在非安全区域里触发的事件(例如:点击事件)等可能会被系统拦截,优先响应状态栏等系统组件。

  • 组件想要扩展到非安全区域内,需隐藏或者设置标题栏和工具栏为STACK模式。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
types Array <LayoutSafeAreaType>

配置扩展安全区域的类型。

默认值:

[LayoutSafeAreaType.SYSTEM]

edges Array <LayoutSafeAreaEdge>

配置扩展安全区域的方向。

默认值:

[LayoutSafeAreaEdge.TOP, LayoutSafeAreaEdge.BOTTOM]。

systemBarStyle12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

systemBarStyle(style: Optional<SystemBarStyle>)

当Navigation中显示当前NavDestination时,设置对应系统状态栏的样式。

说明
  • 必须配合Navigation使用,作为其Navigation目的页面的根节点时才能生效。

  • 其他使用限制请参考Navigation对应的systemBarStyle属性说明。

  • 从API version 20开始,该接口支持在attributeModifier中调用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
style Optional<SystemBarStyle> 系统状态栏样式。

systemTransition14+

Phone14+PC/2in114+Tablet14+TV19+Wearable18+

systemTransition(type: NavigationSystemTransitionType)

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

元服务API: 从API version 14开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
type NavigationSystemTransitionType

系统转场动画类型。

默认值:NavigationSystemTransitionType.DEFAULT

recoverable14+

Phone14+PC/2in114+Tablet14+TV19+Wearable18+

recoverable(recoverable: Optional<boolean>)

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

说明

该接口需要配合Navigation的recoverable接口使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
recoverable Optional<boolean>

NavDestination是否可恢复,默认为可恢复。

默认值:true

true:NavDestination可恢复。

false:NavDestination不可恢复。

bindToScrollable14+

Phone14+PC/2in114+Tablet14+TV19+Wearable18+

bindToScrollable(scrollers: Array<Scroller>)

绑定NavDestination组件和可滚动容器组件(支持ListScrollGridWaterFlow),当滑动可滚动容器组件时,会触发所有与其绑定的NavDestination组件的标题栏和工具栏的显示和隐藏动效,上滑隐藏,下滑显示。一个NavDestination可与多个可滚动容器组件绑定,一个可滚动容器组件也可与多个NavDestination绑定。使用示例参见示例1

说明
  • 只有NavDestination的标题栏或工具栏设置为可见时,联动效果才会生效。

  • 当多个可滚动容器组件绑定了同一个NavDestination组件时,滚动任何一个容器都会触发标题栏和工具栏的显示或隐藏效果。且当任何一个可滚动容器组件滑动到底部或顶部位置时,会立即触发标题栏和工具栏的显示动效。因此,为了获得最佳用户体验,不建议同时触发多个可滚动容器组件的滚动事件。

  • 从API version 22开始,该接口支持在attributeModifier中调用。

元服务API: 从API version 14开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
scrollers Array<Scroller> 可滚动容器组件的控制器。

bindToNestedScrollable14+

Phone14+PC/2in114+Tablet14+TV19+Wearable18+

bindToNestedScrollable(scrollInfos: Array<NestedScrollInfo>)

绑定NavDestination组件和嵌套的可滚动容器组件(支持ListScrollGridWaterFlow),当滑动父组件或子组件时,会触发所有与其绑定的NavDestination组件的标题栏和工具栏的显示和隐藏动效,上滑隐藏,下滑显示。一个NavDestination可与多个嵌套的可滚动容器组件绑定,嵌套的可滚动容器组件也可与多个NavDestination绑定。使用示例参见示例1

说明
  • 只有NavDestination的标题栏或工具栏设置为可见时,联动效果才会生效。

  • 当多个可滚动容器组件绑定了同一个NavDestination组件时,滚动任何一个容器都会触发标题栏和工具栏的显示或隐藏效果。且当任何一个可滚动容器组件滑动到底部或顶部位置时,会立即触发标题栏和工具栏的显示动效。因此,为了获得最佳用户体验,不建议同时触发多个可滚动容器组件的滚动事件。

  • 从API version 22开始,该接口支持在attributeModifier中调用。

元服务API: 从API version 14开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
scrollInfos Array<NestedScrollInfo> 嵌套的可滚动容器组件的控制器。

hideBackButton15+

Phone15+PC/2in115+Tablet15+TV19+Wearable18+

hideBackButton(hide: Optional<boolean>)

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

元服务API: 从API version 15开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
hide Optional<boolean>

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

默认值:false

true:隐藏返回键。

false:显示返回键。

customTransition15+

Phone15+PC/2in115+Tablet15+TV19+Wearable18+

customTransition(delegate: NavDestinationTransitionDelegate)

设置NavDestination自定义转场动画。

说明

元服务API: 从API version 15开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
delegate NavDestinationTransitionDelegate NavDestination自定义动画的代理函数。

preferredOrientation19+

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

preferredOrientation(orientation: Optional<Orientation>)

设置NavDestination对应的显示方向。转场到该NavDestination后,系统也会将应用主窗口切到该显示方向。

说明
  • 该属性满足如下全部条件时才有效:

    1. NavDestination属于应用主窗口页面,并且主窗口为全屏窗口;
    2. NavDestination所属的Navigation的大小占满整个应用页面;
    3. NavDestination类型为NavDestinationMode.STANDARD。
  • 设置显示方向的实际效果依赖于具体的设备支持情况,具体参考窗口的setPreferredOrientation接口。

元服务API: 从API version 19开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
orientation Optional<Orientation> NavDestination页面对应的Orientation。

enableStatusBar19+

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

enableStatusBar(enabled: Optional<boolean>, animated?: boolean)

设置进入该NavDestination后,显示或者隐藏系统的状态栏。

说明
  • 该属性满足如下全部条件时才生效:

    1. NavDestination属于应用主窗口页面,并且主窗口为全屏窗口;
    2. NavDestination所属的Navigation的大小占满整个页面;
    3. NavDestination的大小占满整个Navigation组件;
    4. NavDestination类型为NavDestinationMode.STANDARD。
  • 设置系统状态栏的实际效果依赖于具体的设备支持情况,具体参考窗口的setSpecificSystemBarEnabled接口。

元服务API: 从API version 19开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
enabled Optional<boolean>

进入该NavDestination后,系统状态栏的显示/隐藏状态。

true:显示状态栏。

false:隐藏状态栏。

animated boolean

是否使用动画的方式显示/隐藏系统状态栏。

默认值:false

true:使用动画的方式显示/隐藏系统状态栏。

false:不使用动画的方式显示/隐藏系统状态栏。

enableNavigationIndicator19+

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

enableNavigationIndicator(enabled: Optional<boolean>)

设置进入该NavDestination后,显示或者隐藏系统的导航条。

说明

该属性满足如下全部条件时才生效:

  1. NavDestination属于应用主窗口页面,并且主窗口为全屏窗口;
  2. NavDestination所属的Navigation的大小占满整个页面;
  3. NavDestination的大小占满整个Navigation组件;
  4. NavDestination类型为NavDestinationMode.STANDARD。

设置系统导航条的实际效果依赖于具体的设备支持情况,具体参考窗口的setSpecificSystemBarEnabled接口。

元服务API: 从API version 19开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
enabled Optional<boolean>

进入该NavDestination后,系统导航条的显示/隐藏状态。

true:显示导航条。

false:隐藏导航条。

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

NavDestination类型。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

展开
名称 说明
STANDARD 0 标准模式的NavDestination。
DIALOG 1

默认透明,进出路由栈不影响下层NavDestination的可见性(onShown、onHidden等生命周期),只会触发onActive、onInactive这两个生命周期。

API version 13之前,默认无系统转场动画。从API version 13开始,支持系统转场动画。

Phone14+PC/2in114+Tablet14+TV19+Wearable18+

系统转场动画类型。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

展开
名称 说明
DEFAULT 0

默认系统转场动画。

元服务API: 从API version 14开始,该接口支持在元服务中使用。

NONE 1

无系统转场动画。

元服务API: 从API version 14开始,该接口支持在元服务中使用。

TITLE 2

标题栏系统转场动画。

元服务API: 从API version 14开始,该接口支持在元服务中使用。

CONTENT 3

内容区系统转场动画。

元服务API: 从API version 14开始,该接口支持在元服务中使用。

FADE15+ 4

渐变类型的系统转场动画。

元服务API: 从API version 15开始,该接口支持在元服务中使用。

EXPLODE15+ 5

中心缩放类型的系统转场动画。

元服务API: 从API version 15开始,该接口支持在元服务中使用。

SLIDE_RIGHT15+ 6

右侧平移类型的系统转场动画。

元服务API: 从API version 15开始,该接口支持在元服务中使用。

SLIDE_BOTTOM15+ 7

底部平移类型的系统转场动画。

元服务API: 从API version 15开始,该接口支持在元服务中使用。

说明

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

系统默认转场动画中只有STANDARD页面的push和pop动画有单独的标题栏动画,存在如下限制:

  1. 设置NavigationSystemTransitionType为TITLE时,系统转场只有标题栏动画。
  2. 设置NavigationSystemTransitionType为CONTENT时,系统转场只有内容区动画。

设置NONE时没有系统转场动画,设置TITLE时只有标题栏系统转场动画,设置CONTENT和DEFAULT时默认系统转场动画。

事件

除支持通用事件外,还支持如下事件:

onShown10+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onShown(callback: Callback<VisibilityChangeReason>)

当该NavDestination页面显示时触发此回调。从API version 21开始,支持通过VisibilityChangeReason说明onShown触发的原因。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
callback Callback<VisibilityChangeReason>21+

当该NavDestination页面显示时触发此回调。

在API version 21之前,当NavDestination页面显示时触发回调。

从API version 21开始,回调会提供入参VisibilityChangeReason以说明onShown触发的原因。

onHidden10+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onHidden(callback: Callback<VisibilityChangeReason>)

当该NavDestination页面隐藏时触发此回调。从API version 21开始,支持通过VisibilityChangeReason说明onHidden触发的原因。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
callback Callback<VisibilityChangeReason>21+

当该NavDestination页面隐藏时触发此回调。

在API version 21之前,当NavDestination页面隐藏时触发回调。

从API version 21开始,该回调会提供入参VisibilityChangeReason以说明onHidden触发的原因。

onWillAppear12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onWillAppear(callback: Callback<void>)

当该NavDestination挂载之前触发此回调。在该回调中允许修改路由栈,当前帧生效。

说明

从API version 20开始,该接口支持在attributeModifier中调用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
callback Callback<void> 当该NavDestination挂载之前触发此回调。在该回调中允许修改路由栈,当前帧生效。

onWillShow12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onWillShow(callback: Callback<void>)

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

说明

从API version 20开始,该接口支持在attributeModifier中调用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
callback Callback<void> 当该NavDestination显示之前触发此回调。

onWillHide12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onWillHide(callback: Callback<void>)

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

说明

从API version 20开始,该接口支持在attributeModifier中调用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
callback Callback<void> 当该NavDestination隐藏之前触发此回调。

onWillDisappear12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onWillDisappear(callback: Callback<void>)

当该NavDestination卸载之前触发的生命周期(有转场动画时,在转场动画开始之前触发)。

说明

从API version 20开始,该接口支持在attributeModifier中调用。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
callback Callback<void> 当该NavDestination卸载之前触发的生命周期(有转场动画时,在转场动画开始之前触发)。

onBackPressed10+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onBackPressed(callback: () => boolean)

当与Navigation绑定的导航控制器中存在内容时,此回调生效。当点击返回键时,触发该回调。

返回值为true时,表示重写返回键逻辑,返回值为false时,表示回退到上一个页面。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
callback () => boolean 当与Navigation绑定的导航控制器中存在内容时,此回调生效。当点击返回键时,触发该回调。

onReady11+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onReady(callback: import('../api/@ohos.base').Callback<NavDestinationContext>)

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

说明

从API version 20开始,该接口支持在attributeModifier中调用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
callback import('../api/@ohos.base').Callback<NavDestinationContext> 当NavDestination即将构建子组件之前会触发此回调。

onSaveState

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

onSaveState(callback: Optional<SaveStateCallback>)

设置自定义页面状态保存回调。在NavDestination页面的onHidden生命周期后触发该回调,用于保存当前页面的自定义状态,以便页面后续重建时恢复。

该回调配合Navigation的configuration接口使用。页面创建时传入的初始参数由Navigation单独保留,开发者只需在该回调中返回自定义页面状态。返回的状态对象必须可序列化;页面重建时,保存的状态会通过onRestoreState回调传入。

起始版本: 26.0.0

元服务API: 从API版本26.0.0开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
callback Optional<SaveStateCallback> 页面状态保存回调。

onRestoreState

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

onRestoreState(callback: Optional<RestoreStateCallback>)

设置自定义页面状态恢复回调。当NavDestination页面被重建时触发该回调,用于恢复页面自定义状态。

该回调配合Navigation的configuration接口使用。页面重建时,系统会将onSaveState返回并保存的状态作为入参传入该回调;如果没有保存自定义状态,则入参为null。

起始版本: 26.0.0

元服务API: 从API版本26.0.0开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
callback Optional<RestoreStateCallback> 页面状态恢复回调。

onResult15+

Phone15+PC/2in115+Tablet15+TV19+Wearable18+

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

NavDestination返回时触发该回调。

说明

从API version 22开始,该接口支持在attributeModifier中调用。

元服务API: 从API version 15开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
callback Optional<Callback<ESObject>> 页面返回回调,入参为poppopToNamepopToIndex接口传入的result参数。如果不传该参数,入参为undefined。

onActive17+

Phone17+PC/2in117+Tablet17+TV19+Wearable18+

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

NavDestination处于激活态(处于栈顶可操作,且上层无特殊组件遮挡)时,触发该回调。使用示例参见示例5

说明

从API version 22开始,该接口支持在attributeModifier中调用。

元服务API: 从API version 17开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
callback Optional<Callback<NavDestinationActiveReason>> NavDestination由非激活态变为激活态的原因。

onInactive17+

Phone17+PC/2in117+Tablet17+TV19+Wearable18+

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

NavDestination处于非激活态(处于非栈顶不可操作,或处于栈顶时上层有特殊组件遮挡)时,触发该回调。使用示例参见示例5

说明

从API version 22开始,该接口支持在attributeModifier中调用。

元服务API: 从API version 17开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
callback Optional<Callback<NavDestinationActiveReason>> NavDestination由激活态变为非激活态的原因。

onNewParam19+

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

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

当之前存在于栈中的NavDestination页面通过launchMode.MOVE_TO_TOP_SINGLETONlaunchMode.POP_TO_SINGLETON移动到栈顶时,触发该回调。

说明

元服务API: 从API version 19开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
callback Optional<Callback<ESObject>> onNewParam触发时的回调函数,入参为路由跳转时传递到目标页面的数据。

SaveStateCallback

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

type SaveStateCallback = () => Record<string, Object> | null

页面状态保存回调。

起始版本: 26.0.0

元服务API: 从API版本26.0.0开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

返回值:

展开
类型 说明
Record<string, Object> | null 自定义页面状态。状态对象必须可序列化,否则不会被保存;返回null表示不保存页面状态。

RestoreStateCallback

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

type RestoreStateCallback = (savedState: Record<string, Object> | null) => void

页面状态恢复回调。

起始版本: 26.0.0

元服务API: 从API版本26.0.0开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
savedState Record<string, Object> | null onSaveState保存的自定义页面状态。没有保存自定义状态时为null。
Phone12+PC/2in113+Tablet12+TV19+Wearable18+

NavDestination通用标题。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

展开
名称 类型 只读 可选 说明
main string | Resource14+ 设置主标题。
sub string | Resource14+ 设置副标题。
Phone12+PC/2in113+Tablet12+TV19+Wearable18+

NavDestination自定义标题。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

展开
名称 类型 只读 可选 说明
builder CustomBuilder 设置标题栏内容。
height TitleHeight | Length

设置标题栏高度。

取值范围:[0, +∞)

单位参考Length类型的说明。

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

NavDestination上下文信息。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

展开
名称 类型 只读 可选 说明
pathInfo NavPathInfo

跳转NavDestination时指定的参数。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

pathStack NavPathStack

当前NavDestination所处的导航控制器。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

navDestinationId12+ string

当前NavDestination的唯一ID,由系统自动生成,和组件通用属性id无关。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

mode22+ NavDestinationMode

当前NavDestination的类型。

元服务API: 从API version 22开始,该接口支持在元服务中使用。

getConfigInRouteMap12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

getConfigInRouteMap(): RouteMapConfig | undefined

获取当前NavDestination的路由配置信息。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

返回值:

展开
类型 说明
RouteMapConfig | undefined

当前页面路由配置信息。

当该页面不是通过路由表配置时返回undefined。

RouteMapConfig12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

路由配置信息。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

展开
名称 类型 只读 可选 说明
name string 页面名称。
pageSourceFile string 页面在当前包中的路径。
data Object 页面自定义字段信息。

NestedScrollInfo14+

Phone14+PC/2in114+Tablet14+TV19+Wearable18+

嵌套可滚动容器组件信息

元服务API: 从API version 14开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

展开
名称 类型 只读 可选 说明
parent Scroller 可滚动容器组件的控制器。
child Scroller 可滚动容器组件的控制器,child对应的组件需要是parent对应组件的子组件,且组件间存在嵌套滚动关系。
Phone17+PC/2in117+Tablet17+TV19+Wearable18+

NavDestination激活态或者非激活态变化的原因。

元服务API: 从API version 17开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

展开
名称 说明
TRANSITION 0 通过页面跳转的方式使NavDestination激活态发生变化。
CONTENT_COVER 1 通过全模态的开启和关闭使NavDestination激活态发生变化。
SHEET 2 通过半模态的开启或关闭使NavDestination激活态发生变化。
DIALOG 3 通过自定义Dialog开启或关闭使NavDestination激活态发生变化。
OVERLAY 4 通过OverlayManager开启或者关闭Overlay使NavDestination激活态发生变化。
APP_STATE 5 通过前后台切换使NavDestination激活态发生变化。

VisibilityChangeReason21+

Phone21+PC/2in121+Tablet21+TV21+Wearable21+

NavDestination可见性发生变化的原因。

元服务API: 从API version 21开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

展开
名称 说明
TRANSITION 0 通过页面跳转的方式使NavDestination可见性发生变化。
CONTENT_COVER 1 通过全模态的开启和关闭使NavDestination可见性发生变化。
APP_STATE 2 通过前后台切换使NavDestination可见性发生变化。
Phone15+PC/2in115+Tablet15+TV19+Wearable18+

NavDestination自定义动画接口。

元服务API: 从API version 15开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

展开
名称 类型 只读 可选 说明
onTransitionEnd Callback<void> 转场动画结束时的回调函数。
duration number

转场动画的持续时间。

默认值:1000(毫秒)

单位:ms

curve Curve 动画的曲线类型,默认值为Curve.EaseInOut
delay number

转场动画的延迟。

默认值:0(毫秒)

单位:ms

event Callback<void> 指定转场动效的闭包函数,系统会根据闭包中对组件UI状态的修改,生成对应的过渡动画。参见animateTo中的event。
Phone15+PC/2in115+Tablet15+TV19+Wearable18+

type NavDestinationTransitionDelegate = (operation: NavigationOperation, isEnter: boolean) => Array<NavDestinationTransition> | undefined

NavDestination自定义转场动画的代理函数。

元服务API: 从API version 15开始,该接口支持在元服务中使用。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
operation NavigationOperation 当前页面转场的操作类型。
isEnter boolean

当前页面是否为入场页面。

true:当前页面是入场页面;false:当前页面不是入场页面。

返回值:

展开
类型 说明
Array<NavDestinationTransition> | undefined NavDestination页面的自定义动画集合。如果返回undefined则做系统默认动画。

Orientation19+

Phone19+PC/2in119+Tablet19+TV19+Wearable19+

type Orientation = import('../api/@ohos.window').default.Orientation

Orientation实例对象。

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

系统能力: SystemCapability.ArkUI.ArkUI.Full

元服务API: 从API version 19开始,该接口支持在元服务中使用。

展开
类型 说明
import('../api/@ohos.window').default.Orientation 返回Orientation实例对象。

示例

示例1(标题栏工具栏与可滚动类组件联动)

以下示例主要演示NavDestination绑定可滚动容器组件来实现滚动内容时触发标题栏和工具栏显示隐藏的效果。

收起
自动换行
深色代码主题
复制
  1. import { SymbolGlyphModifier } from '@kit.ArkUI';
  2. @Component
  3. struct MyPageOne {
  4. private listScroller: Scroller = new Scroller();
  5. private scrollScroller: Scroller = new Scroller();
  6. private arr: number[] = [];
  7. aboutToAppear(): void {
  8. for (let i = 0; i < 30; i++) {
  9. this.arr.push(i);
  10. }
  11. }
  12. build() {
  13. NavDestination() {
  14. Scroll(this.scrollScroller) {
  15. Column() {
  16. List({ space: 0, initialIndex: 0, scroller: this.listScroller }) {
  17. ForEach(this.arr, (item: number, index: number) => {
  18. ListItem() {
  19. Text('' + item)
  20. .height(100)
  21. .fontSize(16)
  22. .textAlign(TextAlign.Center)
  23. .width('90%')
  24. .margin({ left: '5%' })
  25. .borderRadius(10)
  26. .backgroundColor(Color.Gray)
  27. }
  28. }, (item: number) => item.toString());
  29. }.width('100%').height('80%').scrollBar(BarState.Off)
  30. .nestedScroll({ scrollForward: NestedScrollMode.SELF_FIRST, scrollBackward: NestedScrollMode.SELF_FIRST })
  31. ForEach(this.arr, (item: number, index: number) => {
  32. ListItem() {
  33. Text('' + item)
  34. .height(100)
  35. .fontSize(16)
  36. .textAlign(TextAlign.Center)
  37. .width('90%')
  38. .margin({ top: '5%' })
  39. .borderRadius(10)
  40. .backgroundColor(Color.Pink)
  41. }
  42. }, (item: number) => item.toString());
  43. }
  44. }
  45. .width('100%')
  46. .scrollBar(BarState.Off)
  47. .scrollable(ScrollDirection.Vertical)
  48. .edgeEffect(EdgeEffect.Spring)
  49. }
  50. .title('PageOne', { backgroundColor: Color.Yellow, barStyle: BarStyle.STACK })
  51. .toolbarConfiguration([
  52. {
  53. // $r('sys.symbol.phone_badge_star')需要替换为开发者所需的资源文件
  54. value: 'item1',
  55. symbolIcon: new SymbolGlyphModifier($r('sys.symbol.phone_badge_star'))
  56. }
  57. ], { backgroundColor: Color.Orange, barStyle: BarStyle.STACK })
  58. // 绑定有父子关系的可滚动容器组件
  59. .bindToNestedScrollable([{ parent: this.scrollScroller, child: this.listScroller }])
  60. }
  61. }
  62. @Component
  63. struct MyPageTwo {
  64. private listScroller: Scroller = new Scroller();
  65. private arr: number[] = [];
  66. aboutToAppear(): void {
  67. for (let i = 0; i < 30; i++) {
  68. this.arr.push(i);
  69. }
  70. }
  71. build() {
  72. NavDestination() {
  73. List({ scroller: this.listScroller }) {
  74. ForEach(this.arr, (item: number, index: number) => {
  75. ListItem() {
  76. Text('' + item)
  77. .height(100)
  78. .fontSize(16)
  79. .textAlign(TextAlign.Center)
  80. .width('90%')
  81. .margin({ left: '5%' })
  82. .borderRadius(10)
  83. .backgroundColor(Color.Gray)
  84. }
  85. }, (item: number) => item.toString());
  86. }.width('100%')
  87. }
  88. .title('PageTwo', { backgroundColor: Color.Yellow, barStyle: BarStyle.STACK })
  89. .toolbarConfiguration([
  90. {
  91. // $r('sys.symbol.phone_badge_star')需要替换为开发者所需的资源文件
  92. value: 'item1',
  93. symbolIcon: new SymbolGlyphModifier($r('sys.symbol.phone_badge_star'))
  94. }
  95. ], { backgroundColor: Color.Orange, barStyle: BarStyle.STACK })
  96. // 绑定可滚动容器组件
  97. .bindToScrollable([this.listScroller])
  98. }
  99. }
  100. @Entry
  101. @Component
  102. struct Index {
  103. private stack: NavPathStack = new NavPathStack();
  104. @Builder
  105. MyPageMap(name: string) {
  106. if (name === 'myPageOne') {
  107. MyPageOne();
  108. } else {
  109. MyPageTwo();
  110. }
  111. }
  112. build() {
  113. Navigation(this.stack) {
  114. Column() {
  115. Button('push PageOne').onClick(() => {
  116. this.stack.pushPath({ name: 'myPageOne' });
  117. })
  118. Button('push PageTwo').onClick(() => {
  119. this.stack.pushPath({ name: 'myPageTwo' });
  120. })
  121. }.height('40%').justifyContent(FlexAlign.SpaceAround)
  122. }.width('100%')
  123. .height('100%')
  124. .title({ main: 'MainTitle', sub: 'subTitle' })
  125. .navDestination(this.MyPageMap)
  126. }
  127. }

示例2(设置NavDestination自定义转场)

以下示例主要演示NavDestination设置自定义转场动画属性customTransition的效果。

收起
自动换行
深色代码主题
复制
  1. @Entry
  2. @Component
  3. struct NavDestinationCustomTransition {
  4. stack: NavPathStack = new NavPathStack();
  5. @Builder
  6. pageMap(name: string) {
  7. if (name) {
  8. NavDest();
  9. }
  10. }
  11. aboutToAppear(): void {
  12. this.stack.pushPath({name: 'dest0'});
  13. }
  14. build() {
  15. Navigation(this.stack) {
  16. // empty
  17. }
  18. .navDestination(this.pageMap)
  19. .hideNavBar(true)
  20. .title('Main Page')
  21. .titleMode(NavigationTitleMode.Mini)
  22. }
  23. }
  24. declare type voidFunc = () => void;
  25. @Component
  26. struct NavDest {
  27. @State name: string = 'NA';
  28. stack: NavPathStack = new NavPathStack();
  29. @State translateY: string = '0';
  30. @Builder
  31. titleBuilder() {
  32. Text(this.name)
  33. .fontSize(20)
  34. .height(55)
  35. .fontWeight(FontWeight.Bold)
  36. .width('100%')
  37. .padding({ left: 16, right: 16 })
  38. }
  39. build() {
  40. NavDestination() {
  41. Column() {
  42. Button('push next page', { stateEffect: true, type: ButtonType.Capsule })
  43. .width('80%')
  44. .height(40)
  45. .margin(20)
  46. .onClick(() => {
  47. this.stack.pushPath({ name: this.name == 'PageOne' ? "PageTwo" : "PageOne" });
  48. })
  49. }
  50. .size({ width: '100%', height: '100%' })
  51. }
  52. .title(this.titleBuilder)
  53. .translate({ y: this.translateY })
  54. .onReady((context) => {
  55. this.name = context.pathInfo.name;
  56. this.stack = context.pathStack;
  57. })
  58. .backgroundColor(this.name == 'PageOne' ? '#F1F3F5' : '#ff11dee5')
  59. .customTransition(
  60. (op: NavigationOperation, isEnter: boolean)
  61. : Array<NavDestinationTransition> | undefined => {
  62. console.info('[NavDestinationTransition]', 'reached delegate in frontend, op: ' + op + ', isEnter: ' + isEnter);
  63. let transitionOneEvent: voidFunc = () => { console.info('[NavDestinationTransition]', 'reached transitionOne, empty now!'); }
  64. let transitionOneFinishEvent: voidFunc = () => { console.info('[NavDestinationTransition]', 'reached transitionOneFinish, empty now!'); }
  65. let transitionOneDuration: number = 500;
  66. if (op === NavigationOperation.PUSH) {
  67. if (isEnter) {
  68. // ENTER_PUSH
  69. this.translateY = '100%';
  70. transitionOneEvent = () => {
  71. console.info('[NavDestinationTransition]', 'transitionOne, push & isEnter');
  72. this.translateY = '0';
  73. }
  74. } else {
  75. // EXIT_PUSH
  76. this.translateY = '0';
  77. transitionOneEvent = () => {
  78. console.info('[NavDestinationTransition]', 'transitionOne, push & !isEnter');
  79. this.translateY = '0';
  80. }
  81. transitionOneDuration = 450;
  82. }
  83. } else if (op === NavigationOperation.POP) {
  84. if (isEnter) {
  85. // ENTER_POP
  86. this.translateY = '0';
  87. transitionOneEvent = () => {
  88. console.info('[NavDestinationTransition]', 'transitionOne, pop & isEnter');
  89. this.translateY = '0';
  90. }
  91. } else {
  92. // EXIT_POP
  93. this.translateY = '0';
  94. transitionOneEvent = () => {
  95. console.info('[NavDestinationTransition]', 'transitionOne, pop & !isEnter');
  96. this.translateY = '100%';
  97. }
  98. }
  99. }
  100. let transitionOne: NavDestinationTransition = {
  101. duration: transitionOneDuration,
  102. delay: 0,
  103. curve: Curve.Friction,
  104. event: transitionOneEvent,
  105. onTransitionEnd: transitionOneFinishEvent
  106. };
  107. let transitionTwoEvent: voidFunc = () => { console.info('[NavDestinationTransition]', 'reached transitionTwo, empty now!'); }
  108. let transitionTwo: NavDestinationTransition = {
  109. duration: 1000,
  110. delay: 0,
  111. curve: Curve.EaseInOut,
  112. event: transitionTwoEvent,
  113. onTransitionEnd: () => { console.info('[NavDestinationTransition]', 'reached Two\'s finish'); }
  114. };
  115. return [
  116. transitionOne,
  117. transitionTwo,
  118. ];
  119. })
  120. }
  121. }

示例3(设置指定的NavDestination系统转场)

以下示例主要演示NavDestination设置系统转场动画systemTransition为Fade、Explode、SlideBottom与SlideRight时的转场效果。

收起
自动换行
深色代码主题
复制
  1. @Entry
  2. @Component
  3. struct NavDestinationSystemTransition {
  4. @Provide stack: NavPathStack = new NavPathStack()
  5. @Provide homePageTransitionType: NavigationSystemTransitionType = NavigationSystemTransitionType.DEFAULT;
  6. @Builder
  7. pageMap(name: string) {
  8. if (name === 'Fade') {
  9. Fade();
  10. } else if (name === 'Explode') {
  11. Explode();
  12. } else if (name === 'SlideRight') {
  13. SlideRight();
  14. } else if (name === 'SlideBottom') {
  15. SlideBottom();
  16. } else {
  17. Dest();
  18. }
  19. }
  20. aboutToAppear(): void {
  21. this.stack.pushPath({name: 'Dest'});
  22. }
  23. build() {
  24. Navigation(this.stack) {
  25. // empty
  26. }
  27. .navDestination(this.pageMap)
  28. .hideNavBar(true)
  29. }
  30. }
  31. @Component
  32. struct Dest {
  33. @Consume stack: NavPathStack;
  34. @Consume homePageTransitionType: NavigationSystemTransitionType;
  35. @State name: string = 'NA';
  36. build() {
  37. NavDestination() {
  38. HomeBody();
  39. }
  40. .title('Navigation System Animation')
  41. .onReady((context) => {
  42. this.name = context.pathInfo.name;
  43. })
  44. .systemTransition(this.homePageTransitionType)
  45. }
  46. }
  47. @Component
  48. struct Fade {
  49. @Consume stack: NavPathStack;
  50. @State name: string = 'NA';
  51. build() {
  52. NavDestination() {
  53. DestBody({
  54. name: this.name
  55. })
  56. }
  57. .title(this.name)
  58. .onReady((context) => {
  59. this.name = context.pathInfo.name;
  60. })
  61. .systemTransition(NavigationSystemTransitionType.FADE)
  62. }
  63. }
  64. @Component
  65. struct Explode {
  66. @Consume stack: NavPathStack;
  67. @State name: string = 'NA';
  68. build() {
  69. NavDestination() {
  70. DestBody({
  71. name: this.name
  72. })
  73. }
  74. .title(this.name)
  75. .onReady((context) => {
  76. this.name = context.pathInfo.name;
  77. })
  78. .systemTransition(NavigationSystemTransitionType.EXPLODE)
  79. }
  80. }
  81. @Component
  82. struct SlideRight {
  83. @Consume stack: NavPathStack;
  84. @State name: string = 'NA';
  85. build() {
  86. NavDestination() {
  87. DestBody({
  88. name: this.name
  89. })
  90. }
  91. .title(this.name)
  92. .onReady((context) => {
  93. this.name = context.pathInfo.name;
  94. })
  95. .systemTransition(NavigationSystemTransitionType.SLIDE_RIGHT)
  96. }
  97. }
  98. @Component
  99. struct SlideBottom {
  100. @Consume stack: NavPathStack;
  101. @State name: string = 'NA';
  102. build() {
  103. NavDestination() {
  104. DestBody({
  105. name: this.name
  106. })
  107. }
  108. .title(this.name)
  109. .onReady((context) => {
  110. this.name = context.pathInfo.name;
  111. })
  112. .systemTransition(NavigationSystemTransitionType.SLIDE_BOTTOM)
  113. }
  114. }
  115. @Component
  116. struct DestBody {
  117. name: string = 'NA';
  118. columnTextSize: number = 22;
  119. columnTextFontWeight: FontWeight = FontWeight.Bolder;
  120. columnWidth: string = '65%';
  121. columnPadding: number = 22;
  122. columnMargin: number = 10;
  123. columnBorderRadius: number = 10;
  124. build() {
  125. Column() {
  126. Column()
  127. .width('85')
  128. .height(50)
  129. .backgroundColor(Color.White)
  130. Column() {
  131. Text(this.name)
  132. .fontSize(this.columnTextSize)
  133. .fontWeight(this.columnTextFontWeight)
  134. }
  135. .width(this.columnWidth)
  136. .padding(this.columnPadding)
  137. .margin(this.columnMargin)
  138. .borderRadius(this.columnBorderRadius)
  139. .shadow(ShadowStyle.OUTER_DEFAULT_LG)
  140. }
  141. }
  142. }
  143. @Component
  144. struct HomeBody {
  145. @Consume stack: NavPathStack;
  146. @Consume homePageTransitionType: NavigationSystemTransitionType;
  147. columnTextSize: number = 22;
  148. columnTextFontWeight: FontWeight = FontWeight.Bolder;
  149. columnWidth: string = '85%';
  150. columnPadding: number = 22;
  151. columnMargin: number = 10;
  152. columnBorderRadius: number = 10;
  153. columnShadow: ShadowStyle = ShadowStyle.OUTER_DEFAULT_MD;
  154. build() {
  155. Column() {
  156. Search({ value: 'Search' })
  157. .width(this.columnWidth)
  158. Column() {
  159. Text('fade')
  160. .fontSize(this.columnTextSize)
  161. .fontWeight(this.columnTextFontWeight)
  162. }
  163. .width(this.columnWidth)
  164. .padding(this.columnPadding)
  165. .margin(this.columnMargin)
  166. .borderRadius(this.columnBorderRadius)
  167. .shadow(this.columnShadow)
  168. .onClick(() => {
  169. this.homePageTransitionType = NavigationSystemTransitionType.FADE;
  170. this.stack.pushPath({name: 'Fade'});
  171. })
  172. Column() {
  173. Text('explode')
  174. .fontSize(this.columnTextSize)
  175. .fontWeight(this.columnTextFontWeight)
  176. }
  177. .width(this.columnWidth)
  178. .padding(this.columnPadding)
  179. .margin(this.columnMargin)
  180. .borderRadius(this.columnBorderRadius)
  181. .shadow(this.columnShadow)
  182. .onClick(() => {
  183. this.homePageTransitionType = NavigationSystemTransitionType.EXPLODE;
  184. this.stack.pushPath({name: 'Explode'});
  185. })
  186. Column() {
  187. Text('slide right')
  188. .fontSize(this.columnTextSize)
  189. .fontWeight(this.columnTextFontWeight)
  190. }
  191. .width(this.columnWidth)
  192. .padding(this.columnPadding)
  193. .margin(this.columnMargin)
  194. .borderRadius(this.columnBorderRadius)
  195. .shadow(this.columnShadow)
  196. .onClick(() => {
  197. this.homePageTransitionType = NavigationSystemTransitionType.SLIDE_RIGHT;
  198. this.stack.pushPath({name: 'SlideRight'});
  199. })
  200. Column() {
  201. Text('slide bottom')
  202. .fontSize(this.columnTextSize)
  203. .fontWeight(this.columnTextFontWeight)
  204. }
  205. .width(this.columnWidth)
  206. .padding(this.columnPadding)
  207. .margin(this.columnMargin)
  208. .borderRadius(this.columnBorderRadius)
  209. .shadow(this.columnShadow)
  210. .onClick(() => {
  211. this.homePageTransitionType = NavigationSystemTransitionType.SLIDE_BOTTOM;
  212. this.stack.pushPath({name: 'SlideBottom'});
  213. })
  214. }
  215. }
  216. }

示例4(NavDestination配置页面方向和对应状态栏、导航条显隐)

以下示例主要演示每个NavDestination可以配置preferredOrientation指定的页面方向和状态栏,导航条显隐状态。

从API version 19开始,新增了preferredOrientation属性。

收起
自动换行
深色代码主题
复制
  1. import { window } from '@kit.ArkUI';
  2. @Component
  3. struct PortraitPage {
  4. @State info: string = '';
  5. private stack: NavPathStack | undefined = undefined;
  6. build() {
  7. NavDestination() {
  8. Stack({alignContent: Alignment.Center}) {
  9. Button('push LANDSCAPE page').onClick(() => {
  10. this.stack?.pushPath({name: 'landscape'});
  11. })
  12. }.width('100%').height('100%')
  13. }
  14. .width('100%').height('100%')
  15. .title('PortraitPage')
  16. .preferredOrientation(window.Orientation.PORTRAIT) // 竖屏方向
  17. .enableStatusBar(true) // 显示状态栏
  18. .enableNavigationIndicator(true) // 显示导航条
  19. .backgroundColor('#ffbaece9')
  20. .onResult((result: ESObject)=>{
  21. this.info = result as string;
  22. })
  23. .onReady((ctx: NavDestinationContext) => {
  24. this.stack = ctx.pathStack;
  25. })
  26. }
  27. }
  28. @Component
  29. struct LandscapePage {
  30. private stack: NavPathStack | undefined = undefined;
  31. build() {
  32. NavDestination() {
  33. Stack({alignContent: Alignment.Center}) {
  34. Button('push PORTRAIT page').onClick(() => {
  35. this.stack?.pushPath({name: 'portrait'});
  36. })
  37. }.width('100%').height('100%')
  38. }
  39. .width('100%').height('100%')
  40. .title('LandscapePage')
  41. .preferredOrientation(window.Orientation.LANDSCAPE) // 横屏方向
  42. .enableStatusBar(false) // 隐藏状态栏
  43. .enableNavigationIndicator(false) // 隐藏导航条
  44. .backgroundColor('#ffecb8b8')
  45. .ignoreLayoutSafeArea([LayoutSafeAreaType.SYSTEM], [LayoutSafeAreaEdge.TOP, LayoutSafeAreaEdge.BOTTOM])
  46. .onReady((ctx: NavDestinationContext) => {
  47. this.stack = ctx.pathStack;
  48. })
  49. }
  50. }
  51. @Entry
  52. @Component
  53. struct ExamplePage {
  54. private stack: NavPathStack = new NavPathStack();
  55. aboutToAppear(): void {
  56. this.stack.pushPath({name: "portrait"});
  57. }
  58. @Builder
  59. MyPageMap(name: string) {
  60. if (name === 'portrait') {
  61. PortraitPage();
  62. } else {
  63. LandscapePage();
  64. }
  65. }
  66. build() {
  67. Navigation(this.stack) {
  68. }
  69. .width('100%')
  70. .height('100%')
  71. .hideNavBar(true)
  72. .navDestination(this.MyPageMap)
  73. }
  74. }

示例5(NavDestination的onActive与onInActive生命周期)

从API version 17开始,NavDestination新增onActiveonInactive属性。该示例演示onActive与onInactive生命周期的各种触发场景。

收起
自动换行
深色代码主题
复制
  1. import { promptAction, ComponentContent, OverlayManager } from '@kit.ArkUI';
  2. class Params {
  3. text: string = "";
  4. offset: Position;
  5. constructor(text: string, offset: Position) {
  6. this.text = text;
  7. this.offset = offset;
  8. }
  9. }
  10. let overlayShownTag: boolean = false;
  11. @Builder
  12. function builderText(params: Params) {
  13. Column() {
  14. Text('I am ' + params.text)
  15. .fontWeight(FontWeight.Bolder)
  16. .align(Alignment.Center)
  17. .fontSize(25)
  18. .offset({ y: '10%' })
  19. }
  20. .backgroundColor(params.text === 'overlay' ? '#ffc' : '#ccf')
  21. .width('100%')
  22. .height('100%')
  23. .offset(params.offset)
  24. }
  25. @Entry
  26. @Component
  27. struct Index {
  28. stack: NavPathStack = new NavPathStack();
  29. @Builder
  30. pageMap(name: string) {
  31. if (name === 'standard' || name === 'Home') {
  32. NavDest({
  33. name: name
  34. })
  35. }
  36. else if (name === 'dialog') {
  37. NavDest({
  38. name: name,
  39. mode: NavDestinationMode.DIALOG,
  40. positionY: '40%'
  41. })
  42. }
  43. }
  44. aboutToAppear(): void {
  45. this.stack.pushPath({name: 'Home'});
  46. }
  47. build() {
  48. Navigation(this.stack) {
  49. }
  50. .hideNavBar(true)
  51. .navDestination(this.pageMap)
  52. }
  53. }
  54. @Component
  55. struct NavDest {
  56. @State positionY: string = '0%';
  57. name: string = 'NA';
  58. mode: NavDestinationMode = NavDestinationMode.STANDARD;
  59. build() {
  60. NavDestination() {
  61. NavBody()
  62. }
  63. .backgroundColor(this.mode === NavDestinationMode.DIALOG ? Color.Pink : undefined)
  64. .height(this.mode === NavDestinationMode.DIALOG ? '65%' : '100%')
  65. .mode(this.mode)
  66. .title(this.name)
  67. .position({ y: this.positionY })
  68. .onActive((reason: NavDestinationActiveReason) => {
  69. let onActiveMsg: string = `[activeTest] ${this.name} onActive, reason: ${reason}`;
  70. console.info(onActiveMsg);
  71. // API version 17版本,请替换为promptAction.showToast接口。从API version 18开始,请使用示例中的promptAction.openToast接口。
  72. promptAction.openToast({ message: onActiveMsg }).catch(() => {
  73. console.info('open toast failed');
  74. });
  75. })
  76. .onInactive((reason: NavDestinationActiveReason) => {
  77. let onInActiveMsg: string = `[activeTest] ${this.name} onInactive, reason: ${reason}`;
  78. console.info(onInActiveMsg);
  79. // API version 17版本,请替换为promptAction.showToast接口。从API version 18开始,请使用示例中的promptAction.openToast接口。
  80. promptAction.openToast({ message: onInActiveMsg }).catch(() => {
  81. console.info('open toast failed');
  82. });
  83. })
  84. .onBackPressed(() => {
  85. if (overlayShownTag) {
  86. overlayShownTag = false;
  87. this.getUIContext().getOverlayManager().hideAllComponentContents();
  88. return true;
  89. }
  90. return false;
  91. })
  92. }
  93. }
  94. @Component
  95. struct NavBody {
  96. @State isShow: boolean = false;
  97. @State isBindSheetShow: boolean = false;
  98. stack: NavPathStack = new NavPathStack();
  99. aboutToAppear(): void {
  100. this.stack = this.queryNavigationInfo()?.pathStack!;
  101. }
  102. @Builder
  103. myBuilder(id: string) {
  104. Column() {
  105. Text('I am ' + id)
  106. .fontWeight(FontWeight.Bolder)
  107. .align(Alignment.Center)
  108. .fontSize(25)
  109. .offset({ y: '10%' })
  110. }
  111. .width('100%')
  112. .height('100%')
  113. }
  114. build() {
  115. Column() {
  116. Row() {
  117. Button('pushPath standard')
  118. .margin(5)
  119. .onClick(() => {
  120. this.stack.pushPath({name: 'standard'});
  121. })
  122. Button('pushPath dialog')
  123. .margin(5)
  124. .onClick(() => {
  125. this.stack.pushPath({name: 'dialog'});
  126. })
  127. }
  128. Column() {
  129. Row() {
  130. Button("open Modal")
  131. .onClick(() => {
  132. this.isShow = true;
  133. })
  134. .fontColor(Color.Black)
  135. .backgroundColor('#ccc')
  136. .margin(5)
  137. .bindContentCover(
  138. this.isShow,
  139. this.myBuilder('modal'), {
  140. backgroundColor: '#fcf',
  141. onDisappear: () => {
  142. this.isShow = false;
  143. }
  144. })
  145. Button("open BindSheet")
  146. .onClick(() => {
  147. this.isBindSheetShow = true;
  148. })
  149. .fontColor(Color.Black)
  150. .backgroundColor('#ccc')
  151. .margin(5)
  152. .bindSheet($$this.isBindSheetShow, this.myBuilder('bindSheet'), {
  153. height: '60%',
  154. backgroundColor: '#cfc'
  155. })
  156. }
  157. Row() {
  158. Button("open Dialog")
  159. .onClick(() => {
  160. let componentContent = new ComponentContent(
  161. this.getUIContext(), wrapBuilder<[Params]>(builderText),
  162. new Params('dialog', {y: '10%'}));
  163. this.getUIContext().getPromptAction().openCustomDialog(componentContent)
  164. .then(() => {
  165. console.info('[activeTest] open custom dialog success');
  166. })
  167. .catch(() => {
  168. console.info('[activeTest] open custom dialog failed');
  169. })
  170. })
  171. .fontColor(Color.Black)
  172. .backgroundColor('#ccc')
  173. .margin(5)
  174. Button("open Overlay")
  175. .onClick(() => {
  176. let componentContent = new ComponentContent(
  177. this.getUIContext(), wrapBuilder<[Params]>(builderText),
  178. new Params('overlay', {y: '10%'}));
  179. this.getUIContext().getOverlayManager().addComponentContent(componentContent);
  180. this.getUIContext().getOverlayManager().showComponentContent(componentContent);
  181. overlayShownTag = true;
  182. })
  183. .fontColor(Color.Black)
  184. .backgroundColor('#ccc')
  185. .margin(5)
  186. }
  187. }
  188. .width('95%')
  189. }
  190. .width('100%')
  191. .height('100%')
  192. }
  193. }

NavDestination其他用法可参考Navigation示例

在 API参考 中进行搜索
请输入您想要搜索的关键词