一、核心定位与功能

1. 组件角色根容器：作为页面根布局，管理标题栏、工具栏、导航栏及内容区。导航模式：支持三种显示模式：Stack（单页面）：移动端主流模式，每次只显示一个页面。Split（分栏）：大屏设备（如平板）分左右栏显示，左侧导航列表 + 右侧详情。Auto（自适应）：设备宽度 >520vp 时自动切换为分栏模式，否则为单页。
2. 与Router的关系能力NavigationRouter页面栈管理❌ 仅同级切换✅ 跨层级跳转 & 页面栈维护参数传递❌ 不支持直接传参✅ 通过params传递JSON对象适用场景Tab导航/侧边栏（同级页面）跨页面跳转（如首页→详情页）协作方式：在NavDestination内仍需调用@ohos.router实现跨层级跳转6。

二、核心组件与结构

1. 关键子组件NavDestination：定义内容页，需配置title和布局内容。NavRouter：导航项容器，必须包含两个子组件（如Text+NavDestination），点击自动跳转至关联的NavDestination。NavRouter() { Text("设置") // 导航项UI NavDestination() { // 关联内容页 Text("设置页面内容") }.title("设置页") }
2. 路由栈管理NavPathStack：控制页面跳转逻辑，核心方法：pushPathByName("PageName")：跳转至指定页面。clear()：清空栈返回首页。页面上下文传递：通过NavDestinationContext获取共享的pathStack实例。

三、路由配置方式

1. 两种页面跳转实现属性绑定：直接设置navDestination属性，需在Builder函数内包含NavDestination组件。路由表配置（推荐）：步骤1：在module.json5声明路由表路径：{ "routerMap": "$profile:route_map" }步骤2：在resources/base/profile/创建route_map.json：{ "routerMap": [ { "name": "MainPage", // 页面名（支持中文） "pageSourceFile": "src/main/ets/pages/MainPage.ets", "buildFunction": "MainPageBuilder" // @Builder入口函数 } ] }注意：使用路由表时需移除navDestination属性，否则优先级冲突。

四、开发避坑指南

1. 预览器限制路由表配置的跳转在预览器中可能失败且无报错提示，需在本地模拟器测试。
2. NavRouter子组件约束子组件数必须为2，且第二个必须是NavDestination，否则跳转失效。
3. 路由传参陷阱Navigation不支持直接传参，需结合@ohos.router的params传递对象（对象内禁含方法变量）。

五、高级特性

1. 动态导航模式切换.mode(NavigationMode.Auto) // 根据屏幕宽度自动切换布局:cite[4]
2. 沉浸式标题栏通过titleMode设置标题样式（Full/Mini/Free）。
3. 共享元素动画使用geometryTransition实现NavDestination间元素共享动画（Router不支持）。
4. 路由拦截通过setInterception拦截跳转（如登录验证），Router无此能力。

六、最佳实践总结

性能提示：分栏模式（Split）适合平板/车机，单页模式（Stack）节省移动端内存；使用NavPathStack.removeByName()清理无用页面栈，避免内存泄漏。

🔚 总结

Navigation 是鸿蒙ArkUI的强交互型导航容器，专注于同级页面的布局管理与视觉导航（如Tab/分栏），需与Router协同实现完整路由能力16。开发时优先采用路由表配置，严格遵循NavRouter子组件约束，并在模拟器中验证跳转逻辑，可高效构建自适应多端导航体系 。