前言Navigation 路由体系的核心设计之一是注册式跳转——所有可能跳转的目标页都通过navDestination的Builder统一注册在 Navigation 组件中。这种模式让路由关系一目了然也支持严格模式下的编译期检查。本文以「猫猫大作战」的 Navigation 页面系统为锚点讲解 navDestination Builder 的注册机制、严格模式要求、跨模块页面注册以及代码组织的最佳实践。提示本系列不讲 ArkTS 基础语法与环境搭建假设你已跟完第 1–84 篇。本篇是阶段三第 85 篇。一、navDestination Builder 注册1.1 基本注册模式Entry Component struct GameApp { private navStack: NavPathStack new NavPathStack(); build() { Navigation(this.navStack) { this.MainMenu() } .navDestination(this.pageBuilder) // ← 注册页面构建器 } // 页面构建器 — 根据 name 返回对应页面 Builder pageBuilder(name: string, param: Object) { if (name pages/Index) { IndexPage({ param: param }) } else if (name pages/Leaderboard) { LeaderboardPage({ param: param }) } else if (name pages/Settings) { SettingsPage({ param: param }) } } Builder MainMenu() { Column() { Button(排行榜) .onClick(() { this.navStack.pushPath({ name: pages/Leaderboard, param: { from: menu } }) }) } } }1.2 工作流程用户点击排行榜按钮 ↓ navStack.pushPath({ name: pages/Leaderboard }) ↓ Navigation 收到 pushPath 请求 ↓ 调用 pageBuilder(pages/Leaderboard, param) ↓ pageBuilder 匹配 name 返回 LeaderboardPage 组件 ↓ NavDestination 渲染到屏幕上二、严格模式要求2.1 严格模式从 API 12 开始Navigation 支持strictMode严格模式。开启后pushPath调用的 name 必须在navDestination中被显式注册Navigation(this.navStack) { // NavBar 内容 } .navDestination(this.pageBuilder) .enableStrictMode(true) // 开启严格模式严格模式下的规则行为非严格模式严格模式未注册的 name运行时崩溃编译期警告参数类型校验无推荐显式接口页面管理按 name 匹配按 name 类型匹配2.2 严格模式下的 Builder 写法Builder pageBuilder(name: string, param: Object) { if (name pages/Index) { IndexPage({ param: param as IndexParam }) } else if (name pages/Leaderboard) { LeaderboardPage({ param: param as LeaderboardParam }) } // 如果 name 没有匹配任何条件 → 严格模式下编译报错 }2.3 定义参数接口// 为每个页面定义参数类型 interface IndexParam { fromLogin?: boolean; } interface LeaderboardParam { highScore: number; playerName?: string; } interface SettingsParam { tab?: number; }三、多模块页面注册3.1 拆分为多个 Builder当页面数量增多时拆分为多个 Builder 文件// pageBuilder.ets — 统一路由表 Builder export function PageBuilder(name: string, param: Object) { if (name.startsWith(pages/game/)) { GamePageBuilder(name, param) } else if (name.startsWith(pages/user/)) { UserPageBuilder(name, param) } else if (name.startsWith(pages/shop/)) { ShopPageBuilder(name, param) } } // gamePages.ets Builder function GamePageBuilder(name: string, param: Object) { if (name pages/game/Board) { GameBoard({ param }) } else if (name pages/game/Over) { GameOver({ param }) } }3.2 跨 HAP 模块注册// feature 模块暴露的路由注册函数 export function registerRankingRoutes(stack: NavPathStack) { stack.pushPath({ name: pages/ranking/Main, param: {} }) } // entry 模块使用 import { registerRankingRoutes } from ohos/rankingFeature; registerRankingRoutes(this.navStack);四、 navDestination 与 NavigationMode4.1 NavigationMode 导航模式this.navStack.pushPath({ name: pages/Leaderboard, mode: NavigationMode.STANDARD // 标准模式默认 // mode: NavigationMode.REPLACE // 替换模式 })模式说明STANDARD标准压栈默认REPLACE替换当前栈顶页五、总结navDestination Builder 是 Navigation 的“路由表“通过集中注册页面名称到组件映射关系实现 type-safe 的页面跳转。核心要点.navDestination(this.pageBuilder)注册所有目标页Builder中通过 name 匹配返回对应NavDestination组件严格模式enableStrictMode(true)提供编译期检查多模块场景下可以拆分多个 BuilderNavigationMode 控制压栈/替换模式下一篇预告第 86 篇将深入 NavPathStack 的查询 API——getAllPathName、getParamByName 等栈操作。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源Navigation 跳转文档Navigation 架构Navigation 组件参考开源鸿蒙跨平台社区第 84 篇NavDestination第 86 篇NavPathStack 查询 API