一、为什么 Navigation 让你头疼？

在 HarmonyOS 开发中，页面路由是建立多页面应用的主要能力。但很多新手会遇到：

• 路由配置文件忘记写或方法写错导致页面根本不跳转；
• 没有使用 NavDestination 包裹子页面直接返回 “未找到匹配的建立函数”；
• 拦截器使用不当，导致死循环或拦截失效。

二、Navigation 主要概念与常见误区

Navigation 是官方推荐的路由容器，支持三种显示模式：单栏、分栏和自适应。它比传统 Router 更加灵活，但也更容易被误用。

主要组成

• NavPathStack: 栈控制器，提供 push/pop/replace/clear 等操作。按理说，
• NavDestination: 子页面根容器。每个目标页面都必须包裹在这里。
• .navDestination: 映射表属性，用于关联页面名称与建立函数。

说到常见错误提示，

• "RouterMap is missing"：说明你忘记在 module.json5 中声明 $profile:router_map
• "No NavDestination found"：说明目标页面不是 NavDestination 或者没有导出 @Builder 函数。
• "Invalid path name"：跳转时传入了不存在的 name。话说回来，

三、实战示例：登录页 → 个人中心页   

1️⃣ 项目文件结构

src/main/ets/
├── pages/
│ ├── Index.ets // 登录页
│ └── ProfilePage.ets // 个人中心页
└── resources/base/profile/
└── router_map.json // 路由映射表

2️⃣ 配置 router_map.json

{
"routerMap":
}

3️⃣ 在 module.json5 中声明 routerMap

{
"pages": "$profile:main_pages"。"routerMap": "$profile:router_map","requestPermissions":
}

4️⃣ 登录页实现

⚠️ 小贴士：请先确保 @Component @Entry 标注正确，否则入口会报错！下面代码已去除无用参数，简化阅读。怎么说呢，

import { buildProfilePage } from './ProfilePage';

interface IUserInfo { userName: string;}

@Entry @Component struct Index { private pageStack = new NavPathStack;

@State username = 'admin';其实，@State password = '';

build { Navigation { Column { TextInput .type;TextInput .type .showPasswordIcon;Button .width .enabled .onClick => { const param : IUserInfo = { userName: this.username };this.pageStack.pushPathByName;})，}.padding;} .title .titleMode .navDestination;}

@Builder pageMap { if buildProfilePage;} }

至于运行效果，

5️⃣ 个性化个人中心页实现

interface IParams { userName:string }

@Component struct ProfilePage {

private pageInfos : NavPathStack = {} as NavPathStack;

private userName = '默认使用者';按理说，

build { NavDestination { Column { Text.fontSize.fontWeight;Text.fontSize;其实，Button .width .onClick => { this.pageInfos.pop;})，}.padding.width.height;} .title .hideTitleBar .onReady => { this.pageInfos = context.pathStack;其实，const params = context.pathInfo.param as IParams;this.userName = params?.userName，?'未知'，}); } }

@Builderexport function buildProfilePage { ProfilePage;按理说，}

说到运行效果。

四、拦截器详解   

🔥 拦截器可以让你在跳转前做鉴权、埋点等统一逻辑，但如果不慎使用会导致死循环或性能下降。

• *注册位置*: 必须在生命周期早期。例如 `aboutToAppear` 或 `` 内注册，确保所有跳转被拦截。否则某些深层次跳转可能忽略拦截。
• *只拦截 push 操作*: 使用 `operation === NavigationOperation.PUSH` 可以避免干扰返回操作。若误拦截 pop，会导致返回卡住。
• *不要再触发相同拦截*: 在拦截逻辑里不要 执行同一跳转，以免进入无限循环。例如当使用者未登录时重定向到 Login 页时不要在 Login 页内部 检查同一条件。
• *清理状态*这方面，拦截成功后需要及时更新全局状态。例如设置 `isLogged` 并同步 AppStorage，否则后续判断会出现错乱。

示例代码

ts @Entry @Component struct Index {

@StorageLink isLogged:boolean=false;

private navPathStack=new NavPathStack;

aboutToAppear:void{ this.navPathStack.setInterception({ willShow:=>{ if{ const target=to as NavDestinationContext;if{ target.pathStack.pop;//取消当前推送 this.navPathStack.replacePathByName;} } } })，}

build{ /…/ } }

常见问题解答

• 为什么我被无限重定向回 Login 页？ 原因是 Login 页也触发了同一拦截逻辑。请在 Login 页内部排除该检查或使用 operation!话说回来，== NavigationOperation.PUSH。

• 如何把登录状态同步给其它模块？ 借助 将状态存进 AppStorage，全局共享即可。

• 为什么替换后仍然卡住？ 可能是 replace 的目标方法名拼写错误；或者你忘记把 replace 后的参数 null 给到目标页。

---

五、常用方法与常见陷阱汇总

# 步骤/注意点	Description

A．路由映射文件必填完整 缺少任何一条记录都会导致对应跳转失效；建议统一放置于 resources/base/ 并通过 $alias 引入 module.json5。

B．每个子页面必须是 NavDestination 并导出 Builder 函数 否则 Navigation 会抛 “No builder function for route”。请保持函数名与 json 配置一致。

C．尽量使用 Auto 模式 程序会根据宽度自动切换单栏/分栏，无需手动判断 deviceType。仅在特殊需求下才手动切换模式。按理说，

D．标题栏与菜单布局规划好 竖屏最多显示5个图标。横屏则10个，超出时请自定义 menuBuilder 或隐藏部分菜单以防 UI 崩溃。

E．利用 onReady / onBackPress 生命周期管理资源释放和数据刷新 例如在退出个人中心前保存最新数据；或者在返回主界面时更新列表数据。

Z．调试工具快速定位路由错误：打开 Debug → Logcat → filter by “Navigation” 或查看 console 输出 “Navigation” 错误日志即可快速定位缺失映射或栈异常。 建议开启 debug=true 并加入日志打印，以便追踪真实方法信息。

---

`

---