文档中心

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

说明

该组件从API Version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
该组件从API Version 11开始默认支持安全区避让特性(默认值为：expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM]))，开发者可以重写该属性覆盖默认行为，API Version 11之前的版本需配合expandSafeArea属性实现安全区避让。
NavDestination组件必须配合Navigation使用，作为Navigation目的页面的根节点，单独使用只能作为普通容器组件，不具备路由相关属性能力。
如果页面栈中间页面的生命周期发生变化，跳转之前的栈顶Destination的生命周期(onWillShow, onShown, onHidden, onWillDisappear)与跳转之后的栈顶Destination的生命周期(onWillShow, onShown, onHidden, onWillDisappear)均在最后触发。
NavDestination未设置主副标题并且没有返回键时，不显示标题栏。

子组件

说明

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

接口

NavDestination()

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

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

属性

支持通用属性。

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

title

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

设置页面标题。使用NavigationCustomTitle类型设置height高度时，titleMode属性不会生效。字符串超长时，如果不设置副标题，先缩小再换行2行后以...截断。如果设置副标题，先缩小后以...截断。

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

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

参数：

参数名	类型	必填	说明
value	string \| CustomBuilder \| NavDestinationCommonTitle \| NavDestinationCustomTitle	是	页面标题。
options¹²⁺	NavigationTitleOptions	否	标题栏选项。

hideTitleBar

hideTitleBar(value: boolean)

设置是否隐藏标题栏。

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

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

参数：

参数名	类型	必填	说明
value	boolean	是	是否隐藏标题栏。默认值：false true: 隐藏标题栏。 false: 显示标题栏。

参数名

类型

必填

说明

value

boolean

是

是否隐藏标题栏。

默认值：false

true: 隐藏标题栏。

false: 显示标题栏。

mode ¹¹⁺

mode(value: NavDestinationMode)

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

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

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

参数：

参数名	类型	必填	说明
value	NavDestinationMode	是	NavDestination类型。默认值: NavDestinationMode.STANDARD

参数名

类型

必填

说明

value

NavDestinationMode

是

NavDestination类型。

默认值: NavDestinationMode.STANDARD

backButtonIcon¹¹⁺

backButtonIcon(value: ResourceStr | PixelMap | SymbolGlyphModifier)

说明

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

设置标题栏返回键图标。

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

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

参数：

参数名	类型	必填	说明
value	ResourceStr \| PixelMap \| SymbolGlyphModifier¹²⁺	是	标题栏返回键图标。

menus¹²⁺

menus(value: Array<NavigationMenuItem> | CustomBuilder)

说明

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

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

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

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

参数：

参数名	类型	必填	说明
value	Array<NavigationMenuItem> \| CustomBuilder	是	页面右上角菜单。

ignoreLayoutSafeArea¹²⁺

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

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

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

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

参数：

参数名	类型	必填	说明
types	Array <LayoutSafeAreaType>	否	配置扩展安全区域的类型。默认值: [LayoutSafeAreaType.SYSTEM]
edges	Array <LayoutSafeAreaEdge>	否	配置扩展安全区域的方向。默认值: [LayoutSafeAreaEdge.TOP, LayoutSafeAreaEdge.BOTTOM]。

参数名

类型

必填

说明

types

Array <LayoutSafeAreaType>

否

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

默认值:

[LayoutSafeAreaType.SYSTEM]

edges

Array <LayoutSafeAreaEdge>

否

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

默认值:

[LayoutSafeAreaEdge.TOP, LayoutSafeAreaEdge.BOTTOM]。

说明

组件设置LayoutSafeArea之后生效的条件为：

设置LayoutSafeAreaType.SYSTEM时，组件的边界与非安全区域重合时组件能够延伸到非安全区域下。例如：设备顶部状态栏高度100，组件在屏幕中纵向方位的绝对偏移需要在0到100之间。

若组件延伸到非安全区域内，此时在非安全区域里触发的事件（例如：点击事件）等可能会被系统拦截，优先响应状态栏等系统组件。

systemBarStyle¹²⁺

systemBarStyle(style: Optional<SystemBarStyle>)

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

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

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

参数：

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

说明

必须配合Navigation使用，作为其Navigation目的页面的根节点时才能生效。
其他使用限制请参考Navigation对应的systemBarStyle属性说明。

NavDestinationMode枚举说明 ¹¹⁺

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

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

名称	说明
STANDARD	标准模式的NavDestination。
DIALOG	默认透明，进出页面栈不影响下层NavDestination的生命周期，不支持系统转场动画。

事件

除支持通用事件外，还支持如下事件：

onShown¹⁰⁺

onShown(callback: () => void)

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

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

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

onHidden¹⁰⁺

onHidden(callback: () => void)

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

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

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

onWillAppear¹²⁺

onWillAppear(callback: Callback<void>)

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

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

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

onWillShow¹²⁺

onWillShow(callback: Callback<void>)

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

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

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

onWillHide¹²⁺

onWillHide(callback: Callback<void>)

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

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

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

onWillDisappear¹²⁺

onWillDisappear(callback: Callback<void>)

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

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

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

onBackPressed¹⁰⁺

onBackPressed(callback: () => boolean)

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

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

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

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

onReady¹¹⁺

onReady(callback: Callback<NavDestinationContext>)

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

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

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

NavDestinationCommonTitle

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

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

名称	类型	必填	说明
main	string	是	设置主标题。
sub	string	是	设置副标题。

NavDestinationCustomTitle

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

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

名称	类型	必填	说明
builder	CustomBuilder	是	设置标题栏内容。
height	TitleHeight \| Length	是	设置标题栏高度。

NavDestinationContext¹¹⁺

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

名称	类型	必填	说明
pathInfo	NavPathInfo	是	跳转NavDestination时指定的参数。元服务API：从API version 11开始，该接口支持在元服务中使用。
pathStack	NavPathStack	是	当前NavDestination所处的页面栈。元服务API：从API version 11开始，该接口支持在元服务中使用。
navDestinationId¹²⁺	string	否	当前NavDestination的唯一ID，由系统自动生成，和组件通用属性id无关。元服务API：从API version 12开始，该接口支持在元服务中使用。

名称

类型

必填

说明

pathInfo

NavPathInfo

是

跳转NavDestination时指定的参数。

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

pathStack

NavPathStack

是

当前NavDestination所处的页面栈。

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

navDestinationId¹²⁺

string

否

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

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

getConfigInRouteMap¹²⁺

getConfigInRouteMap(): RouteMapConfig |undefined

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

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

返回值

类型	说明
RouteMapConfig	当前页面路由配置信息。
undefined	当该页面不是通过路由表配置时返回undefined。

RouteMapConfig¹²⁺

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

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

名称	类型	必填	说明
name	string	是	页面名称。
pageSourceFile	string	是	页面在当前包中的路径。
data	Object	是	页面自定义字段信息。

示例（NavDestination使用）

NavDestination用法可参考Navigation示例。

NavDestination

子组件

接口

属性

title

hideTitleBar

mode 11+

backButtonIcon11+

menus12+

ignoreLayoutSafeArea12+

systemBarStyle12+

NavDestinationMode枚举说明 11+

事件

onShown10+

onHidden10+

onWillAppear12+

onWillShow12+

onWillHide12+

onWillDisappear12+

onBackPressed10+

onReady11+

NavDestinationCommonTitle

NavDestinationCustomTitle

NavDestinationContext11+

getConfigInRouteMap12+

RouteMapConfig12+

示例（NavDestination使用）

mode ¹¹⁺

backButtonIcon¹¹⁺

menus¹²⁺

ignoreLayoutSafeArea¹²⁺

systemBarStyle¹²⁺

NavDestinationMode枚举说明 ¹¹⁺

onShown¹⁰⁺

onHidden¹⁰⁺

onWillAppear¹²⁺

onWillShow¹²⁺

onWillHide¹²⁺

onWillDisappear¹²⁺

onBackPressed¹⁰⁺

onReady¹¹⁺

NavDestinationContext¹¹⁺

getConfigInRouteMap¹²⁺

RouteMapConfig¹²⁺