鸿蒙5.0版开发：ArkTS组件-基础组件（Navigation）

往期鸿蒙全套实战文章必看：

• 鸿蒙开发核心知识点，看这篇文章就够了

• 最新版！鸿蒙HarmonyOS Next应用开发实战学习路线

• 鸿蒙HarmonyOS NEXT开发技术最全学习路线指南

• 鸿蒙应用开发实战项目，看这一篇文章就够了（部分项目附源码）

---

Navigation

Navigation组件是路由导航的根视图容器，一般作为Page页面的根容器使用，其内部默认包含了标题栏、内容区和工具栏，其中内容区默认首页显示导航内容（Navigation的子组件）或非首页显示（NavDestination的子组件），首页和非首页通过路由进行切换。

说明：

该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

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

子组件

可以包含子组件。

从API Version 9开始，推荐与NavRouter组件搭配使用。

从API Version 10开始，推荐使用NavPathStack配合navDestination属性进行页面路由。

接口

Navigation

Navigation()

Navigation10+

Navigation(pathInfos: NavPathStack)

绑定路由栈到Navigation组件。

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

参数：

参数名	参数类型	必填	参数描述
pathInfos	NavPathStack	否	路由栈信息。

属性

除支持通用属性外，还支持以下属性：

title

title(value: ResourceStr | CustomBuilder | NavigationCommonTitle | NavigationCustomTitle, options?: NavigationTitleOptions)

设置页面标题。

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

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

参数：

参数名	类型	必填	说明
value	ResourceStr10+ | CustomBuilder | NavigationCommonTitle9+ | NavigationCustomTitle9+	是	页面标题，使用NavigationCustomTitle类型设置height高度时，titleMode属性不会生效。字符串超长时，如果不设置副标题，先缩小再换行（2行）最后…截断。如果设置副标题，先缩小最后…截断。
options	NavigationTitleOptions11+	否	标题栏选项。

subTitle(deprecated)

subTitle(value: string)

设置页面副标题。

从API Version 9开始废弃，建议使用title代替。

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

参数：

参数名	类型	必填	说明
value	string	是	页面副标题。

menus

menus(value: Array<NavigationMenuItem> | CustomBuilder)

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

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

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

参数：

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

titleMode

titleMode(value: NavigationTitleMode)

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

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

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

参数：

参数名	类型	必填	说明
value	NavigationTitleMode	是	页面标题栏显示模式。 默认值：NavigationTitleMode.Free

toolBar(deprecated)

toolBar(value: object | CustomBuilder)

设置工具栏内容。不设置时不显示工具栏。items均分底部工具栏，在每个均分内容区布局文本和图标，文本超长时，逐级缩小，缩小之后换行，最后…截断。

从API version 10开始，该接口不再维护。

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

参数：

参数名	类型	必填	说明
value	object | CustomBuilder	是	工具栏内容。

object类型说明：

名称	类型	必填	描述
value	string	是	工具栏单个选项的显示文本。
icon	string	否	工具栏单个选项的图标资源路径。
action	() => void	否	当前选项被选中的事件回调。

toolbarConfiguration10+

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

设置工具栏内容。不设置时不显示工具栏。

卡片能力： 从API version 10开始，该接口支持在ArkTS卡片中使用。

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

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

参数：

参数名	类型	必填	说明
value	Array<ToolbarItem>  | CustomBuilder	是	工具栏内容，使用Array<ToolbarItem>写法设置的工具栏有如下特性： 工具栏所有选项均分底部工具栏，在每个均分内容区布局文本和图标。 文本超长时，若工具栏选项个数小于5个，优先拓展选项的宽度，最大宽度与屏幕等宽，其次逐级缩小，缩小之后换行，最后…截断。 竖屏最多支持显示5个图标，多余的图标会被放入自动生成的更多图标。横屏下必须配合menus属性的Array<NavigationMenuItem>使用，底部工具栏会自动隐藏，同时底部工具栏所有选项移动至页面右上角菜单。 使用CustomBuilder写法为用户自定义工具栏选项，除均分底部工具栏外不具备以上功能。
options