鸿蒙HarmonyOS NEXT开发：NavDestination（基础组件）

NavDestination

作为子页面的根容器，用于显示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)均在最后触发。

子组件

说明：

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

接口

NavDestination()

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

属性

支持通用属性。

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

title

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

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

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

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

参数：

参数名	类型	必填	说明
value	string | CustomBuilder | NavigationCommonTitle | NavigationCustomTitle	是	页面标题。
options12+	NavigationTitleOptions	否	标题栏选项。

hideTitleBar

hideTitleBar(value: boolean)

设置是否隐藏标题栏。

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

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

参数：

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

mode 11+

mode(value: NavDestinationMode)

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

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

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

参数：

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

backButtonIcon11+

backButtonIcon(value: ResourceStr | PixelMap)

设置标题栏返回键图标。

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

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

参数：

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

menus12+

menus(value: Array<NavigationMenuItem> | CustomBuilder)

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

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

参数：

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

NavDestinationMode枚举说明 11+

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

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

事件

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

onShown10+

onShown(callback: () => void)

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

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

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

onHidden10+

onHidden(callback: () => void)

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

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

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

onWillAppear12+

onWillAppear(callback: Callback<void>)

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

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

onWillShow12+

onWillShow(callback: Callback<void>)

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

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

onWillHide12+

onWillHide(callback: Callback<void>)

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

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

onWillDisappear12+

onWillDisappear(callback: Callback<void>)

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

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

onBackPressed10+

onBackPressed(callback: () => boolean)

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

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

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

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

onReady11+

onReady(callback: Callback<NavDestinationContext>)

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

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

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

NavDestinationContext11+类型说明

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

getConfigInRouteMap12+

getConfigInRouteMap(): RouteMapConfig |undefined

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

返回值

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

RouteMapConfig12+类型说明

名称	类型	描述
name	string	页面名称。
pageSourceFile	string	页面在当前包中的路径。
data	object	页面自定义字段信息。

写在最后

• 如果你觉得这篇内容对你还蛮有帮助，我想邀请你帮我三个小忙：
• 点赞，转发，有你们的 『点赞和评论』，才是我创造的动力。
• 关注小编，同时可以期待后续文章ing ，不定期分享原创知识。