本文是「鸿蒙 6.1 API 23 开发坑系列」第 9 篇非 UI 系第 3 篇。本篇讲ohos.routernamespaceAPI 8鸿蒙 6.1 API 23 基座——页面路由router.pushUrl/router.replaceUrl/router.backRouterMode/RouterOptions/RouterState类型。鸿蒙坑根因①router.push/router.replace/router.back/router.getParams/router.getState/router.getLength是废弃顶层函数API 18 废弃迁移到router.pushUrl/router.replaceUrlUIContext.getRouter()实例方法②RouterModeenum 常量Standard0多实例/Single1单实例不是字符串Standard③RouterOptions.url是页面绝对路径pages/target/target不是相对路径④router.getParams()返回Object不是any取字段要as Recordstring, string⑤RouterState真属性是index/name/path不是stackLength栈长度用router.getLength()返回string不是number⑥router.replaceUrl销毁被替换的页面router.pushUrl保留当前页状态压栈。一、开篇鸿蒙 router 不是 React Router是「namespace 顶层函数 pushUrl/replaceUrl RouterMode enum」你写 React 时页面路由用react-router-domuseNavigatehook 返回 navigate 函数传字符串路径 state 对象// React RouteruseNavigate hook 返回函数传字符串路径 state 对象 import { useNavigate } from react-router-dom // ✅ React Router hook const navigate useNavigate() // ✅ navigate 是函数 navigate(/target, { state: { keyValue: hello react router } }) // ✅ 传字符串路径 state 对象 // React navigate(/path, { state }) 传字符串路径replace 用 { replace: true } navigate(/target, { replace: true }) // ✅ replace:true 销毁当前页鸿蒙用 replaceUrl 不是 replace 字段你写鸿蒙 ArkTS 时页面路由用router.pushUrl/router.replaceUrlnamespace 顶层函数RouterOptions带urlparams第二参RouterModeenum 常量不是字符串// ArkTS router.pushUrlnamespace 顶层函数RouterMode enum 常量不是字符串 import router from ohos.router // ✅ default importrouter 是 namespace const options: router.RouterOptions { url: pages/target/target, // ✅ url 是页面绝对路径pages/target/target不是相对路径 params: { keyValue: hello harmony router } // ✅ params 传 Object 不是 state 字段 } // ✅ router.pushUrl 带 RouterMode enum 常量不是字符串Standard不是 { replace: true } 字段 router.pushUrl(options, router.RouterMode.Standard) // ✅ pushUrl RouterMode.Standard enum 常量 // ✅ router.replaceUrl 替换当前页销毁不是 navigate 的 { replace: true } 字段 router.replaceUrl(options, router.RouterMode.Single) // ✅ replaceUrl RouterMode.Single // 鸿蒙坑根因router.push 废弃迁移 pushUrlRouterMode enum 常量不是字符串React Router vs 鸿蒙 router 的区别React 把页面路由当 hookuseNavigate()返回navigate函数传字符串路径 { state, replace }对象replace: true用字段控制销毁ArkTS 把页面路由当 namespace 顶层函数router.pushUrl(options, mode)带RouterOptionsRouterModeenum 常量replaceUrl用独立函数不用字段控制销毁。根因不是 hook 是 namespace 顶层函数——鸿蒙router.push/router.replace废弃迁移到router.pushUrl/router.replaceUrlAPI 18 废弃RouterModeenum 常量Standard/Single不是字符串ReactSTANDARD/SINGLE不存在鸿蒙 enum 值是数字0/1。二、根因鸿蒙 ohos.router 的六个绑定机制鸿蒙ohos.routernamespaceAPI 8核心导出router.pushUrl/router.replaceUrl/router.back/router.getParams/router.getState/router.getLength顶层函数多数 API 18 废弃迁移到UIContext.getRouter()RouterMode/RouterOptions/RouterState类型。绑定机制来自六重根因。机制 1router.push/replace 废弃顶层函数——迁移到 router.pushUrl/replaceUrl鸿蒙坑根因router.push/router.replace是废弃顶层函数API 18 废弃迁移到router.pushUrl/router.replaceUrl// ❌ 鸿蒙坑router.push/replace 是废弃顶层函数API 18 废弃迁移到 pushUrl/replaceUrl import router from ohos.router // ❌ 废弃 APIAPI 9~17router.push 是废弃顶层函数IDE 警告 push has been deprecated router.push({ url: pages/target/target }) // ❌ 废弃 deprecated 有 IDE 警告 router.replace({ url: pages/target/target }) // ❌ 废弃 deprecated // ✅ 正确用法router.pushUrl/router.replaceUrl不是废弃的 router.push/replace const options: router.RouterOptions { url: pages/target/target, params: { keyValue: hello } } router.pushUrl(options, router.RouterMode.Standard) // ✅ pushUrl 不是废弃的 push router.replaceUrl(options, router.RouterMode.Single) // ✅ replaceUrl 不是废弃的 replace // 鸿蒙坑根因router.push/replace 废弃迁移到 router.pushUrl/replaceUrlIDE 警告 deprecated废弃 push/replace 坑根因鸿蒙 API 9~17 用router.push(options)/router.replace(options)顶层函数跳转页面API 18 废弃迁移到router.pushUrl(options, mode)/router.replaceUrl(options, mode)带RouterMode第二参。鸿蒙坑用废弃router.push不会编译错是 deprecated 不是 removed但 IDE 警告push has been deprecated且废弃的push没有RouterMode参数无法指定单实例/多实例——新代码必须router.pushUrl。Reactnavigate(/path)没有 deprecated 版本鸿蒙router.pushdeprecated 是因为 API 18 把路由统一到UIContext.getRouter()实例方法跟篇 6animator.create废弃迁移到getUIContext().createAnimator()同理。机制 2RouterMode enum 常量 Standard0/Single1 不是字符串’Standard’鸿蒙坑根因RouterModeenum 常量Standard0多实例/Single1单实例不是字符串Standard// ❌ 鸿蒙坑RouterMode enum 常量不是字符串Standard传字符串编译错 import router from ohos.router // ❌ 传字符串Standard编译错RouterMode 类型是 enum 不是 string router.pushUrl({ url: pages/target/target }, Standard) // ❌ 第二参类型 RouterMode 不是 string router.pushUrl({ url: pages/target/target }, Single) // ❌ 传字符串编译错 // ✅ 正确用法RouterMode enum 常量 Standard0 / Single1不是字符串 router.pushUrl({ url: pages/target/target }, router.RouterMode.Standard) // ✅ enum 常量 Standard0 router.pushUrl({ url: pages/target/target }, router.RouterMode.Single) // ✅ enum 常量 Single1 // ✅ RouterMode enum 常量语义 // Standard0多实例模式默认目标页面添加到栈顶无论栈中是否存在相同 url 的页面 // Single1单实例模式如果目标 url 已存在于栈中则移动该页面到栈顶不重复创建 const standardMode: router.RouterMode router.RouterMode.Standard // ✅ Standard0多实例 const singleMode: router.RouterMode router.RouterMode.Single // ✅ Single1单实例 // 鸿蒙坑根因RouterMode enum 常量 Standard/Single 不是字符串enum 值是数字 0/1RouterMode enum 坑根因鸿蒙RouterModeenum 的两个常量是Standard0多实例模式默认目标页面添加到栈顶无论栈中是否存在相同 url/Single1单实例模式如果目标 url 已存在于栈中则移动该页面到栈顶不重复创建。鸿蒙坑传字符串Standard触发Type string is not assignable to type RouterMode编译错——必须传router.RouterMode.Standardenum 常量enum 值是数字0不是字符串。Reactnavigate(/path)没有 mode 参数用{ replace: true }字段控制鸿蒙router.pushUrl(options, mode)第二参是RouterModeenum 控制单实例/多实例不是 replace 语义replace 用router.replaceUrl独立函数。机制 3RouterOptions.url 是页面绝对路径不是相对路径——pages/target/target 不是 /target鸿蒙坑根因RouterOptions.url是页面绝对路径pages/target/target不是相对路径/target// ❌ 鸿蒙坑RouterOptions.url 是页面绝对路径不是相对路径 import router from ohos.router // ❌ 传相对路径/target运行错url 要 pages 列表里的绝对路径不是相对路径 router.pushUrl({ url: /target }, router.RouterMode.Standard) // ❌ 相对路径运行错页面不存在 // ❌ 传 ./pages/target/target运行错不要 ./ 前缀要 pages/ 开头 router.pushUrl({ url: ./pages/target/target }, router.RouterMode.Standard) // ❌ 不要 ./ 前缀 // ✅ 正确用法url 是页面绝对路径pages/target/target对应 main_pages.json 里 pages 列表 router.pushUrl({ url: pages/target/target }, router.RouterMode.Standard) // ✅ pages/ 开头绝对路径 // ✅ 特殊值/跳转到首页main_pages.json 里 src 数组第一个数据项 router.pushUrl({ url: / }, router.RouterMode.Standard) // ✅ / 跳首页 // 鸿蒙坑根因url 是 pages/target/target 绝对路径不是相对路径对应 main_pages.json pages 列表RouterOptions url 路径坑根因鸿蒙RouterOptions.url的值是页面绝对路径pages/target/target对应main_pages.json里pages列表的条目不是 React 的相对路径/target。鸿蒙坑传相对路径/target运行错页面不存在router.pushUrl找不到pages列表里的匹配项传./pages/target/target也错不要./前缀要pages/开头——必须传pages/target/target绝对路径跟main_pages.json里src数组的条目一致。特殊值/跳转到首页src数组第一个数据项。Reactnavigate(/target)传相对路径跟BrowserRouter的basename拼接鸿蒙router.pushUrl({ url: pages/target/target })传pages/开头绝对路径跟main_pages.json一致。机制 4router.getParams() 返回 Object 不是 any——取字段要 as Recordstring, string鸿蒙坑根因router.getParams()返回Object不是any取字段要as Recordstring, string// ❌ 鸿蒙坑router.getParams() 返回 Object 不是 any直接取字段编译错 import router from ohos.router // ❌ 直接取字段编译错Object 类型没有字段访问any 才能直接取 const params router.getParams() // ❌ params 类型是 Object 不是 any // console.info(params.keyValue) // ❌ Object 类型没有 keyValue 字段编译错 Property does not exist // ✅ 正确用法as Recordstring, string 转型后取字段Object 不是 any 不能直接取 const paramsObj: Object router.getParams() // ✅ getParams 返回 Object if (paramsObj) { const obj paramsObj as Recordstring, string // ✅ as Record 转型 console.info(keyValue: obj.keyValue) // ✅ Record 转型后能取字段 } // 鸿蒙坑根因getParams 返回 Object 不是 any取字段要 as Recordstring, string 转型getParams Object 坑根因鸿蒙router.getParams(): Object的返回类型是Object不是 TypeScript 的anyObject类型没有字段访问编译错Property keyValue does not exist on type Object。鸿蒙坑ReactuseLocation().state返回any可以直接取字段state.keyValue鸿蒙router.getParams()返回Object不能直接取字段——必须as Recordstring, string或as Recordstring, Object转型后才能访问字段。ArkTS 严格模式Object类型没有字段访问跟 TypeScript 的any不同必须显式转型到Record类型才能取字段。机制 5RouterState 真属性是 index/name/path 不是 stackLength——栈长度用 router.getLength() 返回 string鸿蒙坑根因RouterState真属性是index/name/path不是stackLength栈长度用router.getLength()返回string不是number// ❌ 鸿蒙坑RouterState 没有 stackLength 属性真属性是 index/name/path import router from ohos.router // ❌ state.stackLength 编译错RouterState 没有 stackLength 属性 const state router.getState() // console.info(stackLength: state.stackLength) // ❌ Property stackLength does not exist // ✅ 正确用法RouterState 真属性 index/name/path不是 stackLength const state2 router.getState() console.info(index: state2.index) // ✅ index 是当前页面在栈中的索引从栈底到栈顶从 1 开始 console.info(name: state2.name) // ✅ name 是当前页面的名称对应文件名 console.info(path: state2.path) // ✅ path 是当前页面的路径 // ✅ 栈长度用 router.getLength() 返回 string 不是 number鸿蒙把栈长度编码成字符串 const stackLengthStr: string router.getLength() // ✅ getLength 返回 string 不是 number console.info(stackLength: stackLengthStr) // ✅ 字符串栈长度 // 鸿蒙坑根因RouterState 真属性 index/name/path 不是 stackLengthgetLength 返回 string 不是 numberRouterState 无 stackLength 坑根因鸿蒙router.getState(): RouterState返回的RouterState真属性是index: number当前页面在栈中的索引从栈底到栈顶从 1 开始/name: string当前页面名称对应文件名/path: string当前页面路径/params: Object当前页面携带的参数API 12没有stackLength属性。鸿蒙坑state.stackLength编译错Property stackLength does not exist on type RouterState——栈长度要用router.getLength()单独方法取且getLength()返回string不是number鸿蒙把栈长度编码成字符串要parseInt(getLength())转数字。ReactuseLocation()没有 stackLength 概念React Router 不维护页面栈鸿蒙router.getState()返回单页状态 router.getLength()返回栈长度字符串。机制 6router.replaceUrl 销毁被替换的页面——router.pushUrl 保留当前页状态压栈鸿蒙坑根因router.replaceUrl销毁被替换的页面无法返回router.pushUrl保留当前页状态压栈可以返回// ✅ router.replaceUrl 销毁被替换的页面 vs router.pushUrl 保留当前页状态压栈 import router from ohos.router const options: router.RouterOptions { url: pages/target/target } // ✅ router.pushUrl压栈跳转保留当前页状态可以 router.back() 返回 router.pushUrl(options, router.RouterMode.Standard) // ✅ 压栈当前页状态保留 // 当前页在栈里router.back() 能返回到当前页状态不丢 // ✅ router.replaceUrl替换跳转销毁当前页无法 router.back() 返回 router.replaceUrl(options, router.RouterMode.Single) // ✅ 替换当前页销毁 // 当前页被销毁router.back() 无法返回到当前页状态丢失 // 鸿蒙坑根因replaceUrl 销毁当前页无法返回pushUrl 压栈保留状态能返回replaceUrl vs pushUrl 销毁坑根因鸿蒙router.replaceUrl(options, mode)替换当前页并销毁被替换的页面释放资源无法router.back()返回到被替换的页router.pushUrl(options, mode)压栈跳转保留当前页状态可以router.back()返回到当前页状态不丢。鸿蒙坑Reactnavigate(/path, { replace: true })用replace: true字段控制销毁replace: false默认压栈鸿蒙router.replaceUrl用独立函数控制销毁不是pushUrl的字段——鸿蒙把 replace 语义做成独立函数router.replaceUrl跟 React 的{ replace: true }字段不同。页面栈最大容量 32 个页面超过调router.clear()清空历史页面释放内存。三、真机配图鸿蒙 ohos.router 页面路由坑——RouterMode enum 常量 pushUrl/replaceUrl 不废弃真机配图展示鸿蒙 ohos.router 页面路由坑初始态鸿蒙 6.1 ohos.router 页面路由坑标题4 个验证按钮① RouterMode enum 常量 / ② router.pushUrl 不废弃 push / ③ router.replaceUrl 不废弃 replace / ④ router.backgetParamsgetState路由状态routerStatus 未跳 modeValue 未设 stackLength/getState要点说明 7 条RouterMode enum 常量态点击「① 验证 RouterMode enum 常量」按钮显示「✅ RouterMode enum 常量验证Standard0多实例/ Single1单实例不是字符串」 modeValue 值——RouterMode enum 常量不是字符串验证router.pushUrl 不废弃 push 态点击「② 验证 router.pushUrl 不是废弃 push」按钮显示「✅ router.pushUrl 验证不是废弃的 router.pushRouterMode.Standard enum 常量」——router.push 废弃迁移 pushUrl 验证router.replaceUrl 不废弃 replace 态点击「③ 验证 router.replaceUrl 不是废弃 replace」按钮显示「✅ router.replaceUrl 验证不是废弃的 router.replaceRouterMode.Single 单实例」——router.replace 废弃迁移 replaceUrl 验证router.backgetParamsgetState 态点击「④ 验证 router.back getParams getState」按钮显示「✅ router.back/getParams/getState 验证RouterState 真属性 index/name 不是 stackLength」 stackLength 值 getState 值——RouterState 真属性 index/name getLength 返回 string 验证四、真解法鸿蒙 ohos.router 的四个场景场景 1router.pushUrl 带 RouterMode.Standard 压栈跳转 params 传参——90% 场景首选基础压栈跳转用router.pushUrl(options, router.RouterMode.Standard)params传参// ✅ 场景 1router.pushUrl 带 RouterMode.Standard 压栈跳转 params 传参API 990% 场景首选 import router from ohos.router // ✅ default importrouter 是 namespace Entry Component struct Index { navigateToTarget() { const options: router.RouterOptions { url: pages/target/target, // ✅ url 是 pages/ 开头绝对路径不是相对路径 params: { keyValue: hello h9 router, userId: 123 } // ✅ params 传 Object 不是 state 字段 } // ✅ router.pushUrl 带 RouterMode enum 常量不是字符串Standard不是废弃的 router.push router.pushUrl(options, router.RouterMode.Standard) // ✅ 压栈跳转保留当前页状态 // ✅ pushUrl 返回 Promisevoid可以 .then 链也可以不接 } build() { Column({ space: 8 }) { Button(跳转).onClick(() this.navigateToTarget()) } } } // router.pushUrl RouterMode.Standard90% 场景首选压栈跳转保留状态能 back 返回鸿蒙 ohos.router API 真名坑import router from ohos.routerdefault importrouter是 namespacerouter.pushUrl(options: RouterOptions, mode: RouterMode): Promisevoid带RouterModeenum 常量第二参不是废弃的router.pushrouter.replaceUrl(options: RouterOptions, mode: RouterMode): Promisevoid替换当前页销毁不是废弃的router.replacerouter.back(options?: RouterOptions): void返回上一页带url返回指定页router.getParams(): Object返回Object不是any取字段要as Recordrouter.getState(): RouterState真属性index/name/path不是stackLengthrouter.getLength(): string返回string不是numberrouter.RouterModeenum 常量Standard0/Single1不是字符串SysCapSystemCapability.ArkUI.ArkUI.Fullatomicservice原子化服务API 11。场景 2router.replaceUrl 带 RouterMode.Single 替换跳转 销毁当前页替换跳转用router.replaceUrl(options, router.RouterMode.Single)销毁当前页// ✅ 场景 2router.replaceUrl 带 RouterMode.Single 替换跳转 销毁当前页API 9 import router from ohos.router const options: router.RouterOptions { url: pages/login/login, params: { fromPage: index } } // ✅ router.replaceUrl 替换当前页并销毁不是 router.pushUrl 的 { replace: true } 字段 router.replaceUrl(options, router.RouterMode.Single) // ✅ 替换销毁当前页无法 back 返回 // ✅ RouterMode.Single 单实例如果 login 页已在栈中则移动到栈顶不重复创建 // replaceUrl RouterMode.Single替换销毁当前页适合登录后替换登录页避免返回登录页鸿蒙 router.replaceUrl RouterMode.Single API 真名坑router.replaceUrl(options, mode)替换当前页并销毁被替换的页面释放资源无法router.back()返回RouterMode.Single单实例模式如果目标 url 已存在于栈中则移动该页面到栈顶不重复创建鸿蒙坑Reactnavigate(/path, { replace: true })用replace: true字段控制销毁鸿蒙router.replaceUrl用独立函数控制销毁不是pushUrl的字段登录后用replaceUrl替换登录页避免用户back返回到登录页跟 React 登录后navigate(/home, { replace: true })同理但鸿蒙用独立函数。场景 3router.back 返回上一页 router.getParams 取参数 as Record 转型返回上一页用router.back()取参数用router.getParams()as Recordstring, string转型// ✅ 场景 3router.back 返回上一页 router.getParams 取参数 as Record 转型API 9 import router from ohos.router Entry Component struct Target { State receivedValue: string (未取) aboutToAppear() { // ✅ router.getParams() 取跳转时传递的参数返回 Object 不是 any const params: Object router.getParams() // ✅ getParams 返回 Object if (params) { // ✅ as Recordstring, string 转型后取字段Object 不能直接取字段 const obj params as Recordstring, string // ✅ as Record 转型 this.receivedValue obj.keyValue // ✅ Record 转型后能取 keyValue 字段 } else { this.receivedValue (无参数) } } goBack() { // ✅ router.back() 不带参返回上一页带 url 返回指定页 router.back() // ✅ 返回上一页 // ✅ router.back({ url: pages/index/index }) 带 url 返回指定页如果栈中有该页 } build() { Column({ space: 8 }) { Text(received: this.receivedValue) Button(返回).onClick(() this.goBack()) } } } // router.back 返回 getParams 取参数getParams 返回 Object 要 as Record 转型取字段鸿蒙 router.back getParams API 真名坑router.back(options?: RouterOptions): void不带参返回上一页带{ url }返回指定页如果栈中有该页router.getParams(): Object返回Object不是any取字段要as Recordstring, string转型鸿蒙坑ReactuseLocation().state返回any可以直接取字段state.keyValue鸿蒙router.getParams()返回Object不能直接取字段——必须as Recordstring, string转型后才能访问字段ArkTS 严格模式Object无字段访问Reactnavigate(-1)返回上一页鸿蒙router.back()返回上一页语义一致但鸿蒙是独立函数不是navigate(-1)。场景 4router.getState 取当前页状态 router.getLength 取栈长度 router.clear 清空取当前页状态用router.getState()真属性index/name/path取栈长度用router.getLength()返回string清空用router.clear()// ✅ 场景 4router.getState 取当前页状态 router.getLength 取栈长度 router.clear 清空API 8 import router from ohos.router // ✅ router.getState() 取当前页状态RouterState 真属性 index/name/path 不是 stackLength const state router.getState() console.info(当前页索引: state.index) // ✅ index 从栈底到栈顶从 1 开始 console.info(当前页名称: state.name) // ✅ name 对应文件名 console.info(当前页路径: state.path) // ✅ path 对应页面路径 // ✅ router.getLength() 取页面栈长度返回 string 不是 number要 parseInt 转数字 const stackLengthStr: string router.getLength() // ✅ getLength 返回 string const stackLengthNum: number parseInt(stackLengthStr, 10) // ✅ parseInt 转数字 console.info(页面栈长度: stackLengthNum) // ✅ 页面栈最大容量 32 个页面超过调 router.clear() 清空历史页面释放内存 if (stackLengthNum 30) { router.clear() // ✅ clear() 清空所有历史页面仅保留当前页在栈顶 } // router.getState getLength clearRouterState 真属性 index/name/pathgetLength 返回 string鸿蒙 router.getState getLength clear API 真名坑router.getState(): RouterState真属性index: number/name: string/path: string/params: Object没有stackLength属性router.getLength(): string返回string不是number要parseInt(getLength(), 10)转数字router.clear(): void清空所有历史页面仅保留当前页在栈顶页面栈最大容量 32鸿蒙坑React Router 没有stackLength/getLength/clear概念React Router 不维护页面栈鸿蒙router.getState()返回单页状态 router.getLength()返回栈长度字符串 router.clear()清空历史页面——鸿蒙维护页面栈栈容量 32React Router 不维护页面栈用浏览器 history。五、一句话哲学写鸿蒙 ArkTS 记住router 不是 React Router 是「namespace 顶层函数 pushUrl/replaceUrl RouterMode enum」——鸿蒙 6.1 API 23ohos.routernamespaceAPI 8鸿蒙 6.1 API 23 基座router.pushUrl/router.replaceUrl/router.back/router.getParams/router.getState/router.getLength/router.clear顶层函数 RouterMode/RouterOptions/RouterState类型SysCap SystemCapability.ArkUI.ArkUI.FullatomicserviceAPI 18 废弃迁移到 UIContext.getRouter() 实例方法。根因不是 hook 是 namespace 顶层函数——router.push/router.replace废弃迁移到router.pushUrl/router.replaceUrl✅router.pushUrl(options, mode)不是废弃的router.push❌router.pushdeprecated 有 IDE 警告push has been deprecatedAPI 18 废弃迁移到UIContext.getRouter()实例方法RouterModeenum 常量Standard0/Single1不是字符串Standard✅router.RouterMode.Standard/router.RouterMode.Singleenum 常量❌ 传字符串Standard触发Type string is not assignable to type RouterMode编译错enum 值是数字0/1不是字符串RouterOptions.url是页面绝对路径pages/target/target不是相对路径/target✅pages/开头对应main_pages.jsonpages 列表❌ 相对路径/target运行错页面不存在特殊值/跳首页router.getParams()返回Object不是any✅as Recordstring, string转型后取字段❌params.keyValue触发Property does not exist on type Object编译错ArkTS 严格模式Object无字段访问RouterState真属性index/name/path不是stackLength✅state.index/state.name/state.path真属性❌state.stackLength触发Property stackLength does not exist编译错栈长度用router.getLength()单独方法取router.getLength()返回string不是number✅parseInt(router.getLength(), 10)转数字❌const len: number router.getLength()触发Type string is not assignable to type number编译错鸿蒙把栈长度编码成字符串router.replaceUrl销毁当前页无法back返回不是pushUrl的{ replace: true }字段是独立函数router.pushUrl压栈保留当前页状态能back返回页面栈最大容量 32 超过调router.clear()清空。router.push 废弃迁移 pushUrl RouterMode enum 常量不是字符串 url 绝对路径 getParams Object 要 as Record RouterState 真属性 index/name getLength 返回 string是鸿蒙 6.1 ohos.router 页面路由坑核心能力系列回链鸿蒙 7.0 新特性篇 1~17沉浸式毛玻璃/Component3D/智能体框架/方舟引擎/星盾安全/星河互联/空间音频/可变字体/游戏快启/分布式数据盾/LTPO 可变帧率/AI 文档识别/多形态服务窗口/AI 反诈/机密计算/空间计算/小艺全面进化鸿蒙 6.1 API 23 开发坑系列篇 1「ArkUI.modifier 装饰器坑」——attributeModifier AttributeModifier 状态化节点修改器鸿蒙 6.1 API 23 开发坑系列篇 2「arkui.componentSnapshot 组件截图坑」——get/getSync/createFromBuilder 返回 image.PixelMap 像素图鸿蒙 6.1 API 23 开发坑系列篇 3「arkui.node 节点坑」——NodeController abstract class makeNode override BuilderNode WrappedBuilder鸿蒙 6.1 API 23 开发坑系列篇 4「arkui.UIContext UI 上下文坑」——runScopedTask 不是 runScopedOnUiThread 11 个子管理器鸿蒙 6.1 API 23 开发坑系列篇 5「arkui.observer UI 观察器坑」——uiObserver namespace 真名不是 observer on type string literal鸿蒙 6.1 API 23 开发坑系列篇 6「ohos.animator 动画器坑」——import kit.ArkUI 不是 ohos.animator onFrame 驼峰不是废弃 onframe getUIContext().createAnimator 不是废弃 animator.create 持引用 aboutToDisappear cancel鸿蒙 6.1 API 23 开发坑系列篇 7「ohos.net.http HTTP 请求坑」——HttpDataType 常量是 STRING 不是 STRING_TYPE HttpRequest 是 interface 不能 new http.createHttp() 工厂造实例 on/off 监听不是 addEventListener header Record 不是 Headers RequestMethod enum 不是字符串鸿蒙 6.1 API 23 开发坑系列篇 8「ohos.file.fs 文件管理坑」——writeSync/readSync 是 namespace 顶层函数不是 File 实例方法 第一参传 file.fd 文件描述符 ReadOptions 无 encoding 读 ArrayBuffer 裸字节 WriteOptions 带 encoding 写字符串指定编码 closeSync(file) 传 File 不是 fd OpenMode enum 不是 flags 数字鸿蒙 6.1 API 23 开发坑系列篇 9「ohos.router 页面路由坑」——router.push/replace 废弃迁移 pushUrl/replaceUrl RouterMode enum 常量 Standard/Single 不是字符串 RouterOptions.url 绝对路径不是相对路径 getParams 返回 Object 要 as Record 转型 RouterState 真属性 index/name 不是 stackLength getLength 返回 string 不是 number本文
鸿蒙6.1 @ohos.router坑：push/replace废迁pushUrl/replaceUrl+RouterMode enum非字符串
本文是「鸿蒙 6.1 API 23 开发坑系列」第 9 篇非 UI 系第 3 篇。本篇讲ohos.routernamespaceAPI 8鸿蒙 6.1 API 23 基座——页面路由router.pushUrl/router.replaceUrl/router.backRouterMode/RouterOptions/RouterState类型。鸿蒙坑根因①router.push/router.replace/router.back/router.getParams/router.getState/router.getLength是废弃顶层函数API 18 废弃迁移到router.pushUrl/router.replaceUrlUIContext.getRouter()实例方法②RouterModeenum 常量Standard0多实例/Single1单实例不是字符串Standard③RouterOptions.url是页面绝对路径pages/target/target不是相对路径④router.getParams()返回Object不是any取字段要as Recordstring, string⑤RouterState真属性是index/name/path不是stackLength栈长度用router.getLength()返回string不是number⑥router.replaceUrl销毁被替换的页面router.pushUrl保留当前页状态压栈。一、开篇鸿蒙 router 不是 React Router是「namespace 顶层函数 pushUrl/replaceUrl RouterMode enum」你写 React 时页面路由用react-router-domuseNavigatehook 返回 navigate 函数传字符串路径 state 对象// React RouteruseNavigate hook 返回函数传字符串路径 state 对象 import { useNavigate } from react-router-dom // ✅ React Router hook const navigate useNavigate() // ✅ navigate 是函数 navigate(/target, { state: { keyValue: hello react router } }) // ✅ 传字符串路径 state 对象 // React navigate(/path, { state }) 传字符串路径replace 用 { replace: true } navigate(/target, { replace: true }) // ✅ replace:true 销毁当前页鸿蒙用 replaceUrl 不是 replace 字段你写鸿蒙 ArkTS 时页面路由用router.pushUrl/router.replaceUrlnamespace 顶层函数RouterOptions带urlparams第二参RouterModeenum 常量不是字符串// ArkTS router.pushUrlnamespace 顶层函数RouterMode enum 常量不是字符串 import router from ohos.router // ✅ default importrouter 是 namespace const options: router.RouterOptions { url: pages/target/target, // ✅ url 是页面绝对路径pages/target/target不是相对路径 params: { keyValue: hello harmony router } // ✅ params 传 Object 不是 state 字段 } // ✅ router.pushUrl 带 RouterMode enum 常量不是字符串Standard不是 { replace: true } 字段 router.pushUrl(options, router.RouterMode.Standard) // ✅ pushUrl RouterMode.Standard enum 常量 // ✅ router.replaceUrl 替换当前页销毁不是 navigate 的 { replace: true } 字段 router.replaceUrl(options, router.RouterMode.Single) // ✅ replaceUrl RouterMode.Single // 鸿蒙坑根因router.push 废弃迁移 pushUrlRouterMode enum 常量不是字符串React Router vs 鸿蒙 router 的区别React 把页面路由当 hookuseNavigate()返回navigate函数传字符串路径 { state, replace }对象replace: true用字段控制销毁ArkTS 把页面路由当 namespace 顶层函数router.pushUrl(options, mode)带RouterOptionsRouterModeenum 常量replaceUrl用独立函数不用字段控制销毁。根因不是 hook 是 namespace 顶层函数——鸿蒙router.push/router.replace废弃迁移到router.pushUrl/router.replaceUrlAPI 18 废弃RouterModeenum 常量Standard/Single不是字符串ReactSTANDARD/SINGLE不存在鸿蒙 enum 值是数字0/1。二、根因鸿蒙 ohos.router 的六个绑定机制鸿蒙ohos.routernamespaceAPI 8核心导出router.pushUrl/router.replaceUrl/router.back/router.getParams/router.getState/router.getLength顶层函数多数 API 18 废弃迁移到UIContext.getRouter()RouterMode/RouterOptions/RouterState类型。绑定机制来自六重根因。机制 1router.push/replace 废弃顶层函数——迁移到 router.pushUrl/replaceUrl鸿蒙坑根因router.push/router.replace是废弃顶层函数API 18 废弃迁移到router.pushUrl/router.replaceUrl// ❌ 鸿蒙坑router.push/replace 是废弃顶层函数API 18 废弃迁移到 pushUrl/replaceUrl import router from ohos.router // ❌ 废弃 APIAPI 9~17router.push 是废弃顶层函数IDE 警告 push has been deprecated router.push({ url: pages/target/target }) // ❌ 废弃 deprecated 有 IDE 警告 router.replace({ url: pages/target/target }) // ❌ 废弃 deprecated // ✅ 正确用法router.pushUrl/router.replaceUrl不是废弃的 router.push/replace const options: router.RouterOptions { url: pages/target/target, params: { keyValue: hello } } router.pushUrl(options, router.RouterMode.Standard) // ✅ pushUrl 不是废弃的 push router.replaceUrl(options, router.RouterMode.Single) // ✅ replaceUrl 不是废弃的 replace // 鸿蒙坑根因router.push/replace 废弃迁移到 router.pushUrl/replaceUrlIDE 警告 deprecated废弃 push/replace 坑根因鸿蒙 API 9~17 用router.push(options)/router.replace(options)顶层函数跳转页面API 18 废弃迁移到router.pushUrl(options, mode)/router.replaceUrl(options, mode)带RouterMode第二参。鸿蒙坑用废弃router.push不会编译错是 deprecated 不是 removed但 IDE 警告push has been deprecated且废弃的push没有RouterMode参数无法指定单实例/多实例——新代码必须router.pushUrl。Reactnavigate(/path)没有 deprecated 版本鸿蒙router.pushdeprecated 是因为 API 18 把路由统一到UIContext.getRouter()实例方法跟篇 6animator.create废弃迁移到getUIContext().createAnimator()同理。机制 2RouterMode enum 常量 Standard0/Single1 不是字符串’Standard’鸿蒙坑根因RouterModeenum 常量Standard0多实例/Single1单实例不是字符串Standard// ❌ 鸿蒙坑RouterMode enum 常量不是字符串Standard传字符串编译错 import router from ohos.router // ❌ 传字符串Standard编译错RouterMode 类型是 enum 不是 string router.pushUrl({ url: pages/target/target }, Standard) // ❌ 第二参类型 RouterMode 不是 string router.pushUrl({ url: pages/target/target }, Single) // ❌ 传字符串编译错 // ✅ 正确用法RouterMode enum 常量 Standard0 / Single1不是字符串 router.pushUrl({ url: pages/target/target }, router.RouterMode.Standard) // ✅ enum 常量 Standard0 router.pushUrl({ url: pages/target/target }, router.RouterMode.Single) // ✅ enum 常量 Single1 // ✅ RouterMode enum 常量语义 // Standard0多实例模式默认目标页面添加到栈顶无论栈中是否存在相同 url 的页面 // Single1单实例模式如果目标 url 已存在于栈中则移动该页面到栈顶不重复创建 const standardMode: router.RouterMode router.RouterMode.Standard // ✅ Standard0多实例 const singleMode: router.RouterMode router.RouterMode.Single // ✅ Single1单实例 // 鸿蒙坑根因RouterMode enum 常量 Standard/Single 不是字符串enum 值是数字 0/1RouterMode enum 坑根因鸿蒙RouterModeenum 的两个常量是Standard0多实例模式默认目标页面添加到栈顶无论栈中是否存在相同 url/Single1单实例模式如果目标 url 已存在于栈中则移动该页面到栈顶不重复创建。鸿蒙坑传字符串Standard触发Type string is not assignable to type RouterMode编译错——必须传router.RouterMode.Standardenum 常量enum 值是数字0不是字符串。Reactnavigate(/path)没有 mode 参数用{ replace: true }字段控制鸿蒙router.pushUrl(options, mode)第二参是RouterModeenum 控制单实例/多实例不是 replace 语义replace 用router.replaceUrl独立函数。机制 3RouterOptions.url 是页面绝对路径不是相对路径——pages/target/target 不是 /target鸿蒙坑根因RouterOptions.url是页面绝对路径pages/target/target不是相对路径/target// ❌ 鸿蒙坑RouterOptions.url 是页面绝对路径不是相对路径 import router from ohos.router // ❌ 传相对路径/target运行错url 要 pages 列表里的绝对路径不是相对路径 router.pushUrl({ url: /target }, router.RouterMode.Standard) // ❌ 相对路径运行错页面不存在 // ❌ 传 ./pages/target/target运行错不要 ./ 前缀要 pages/ 开头 router.pushUrl({ url: ./pages/target/target }, router.RouterMode.Standard) // ❌ 不要 ./ 前缀 // ✅ 正确用法url 是页面绝对路径pages/target/target对应 main_pages.json 里 pages 列表 router.pushUrl({ url: pages/target/target }, router.RouterMode.Standard) // ✅ pages/ 开头绝对路径 // ✅ 特殊值/跳转到首页main_pages.json 里 src 数组第一个数据项 router.pushUrl({ url: / }, router.RouterMode.Standard) // ✅ / 跳首页 // 鸿蒙坑根因url 是 pages/target/target 绝对路径不是相对路径对应 main_pages.json pages 列表RouterOptions url 路径坑根因鸿蒙RouterOptions.url的值是页面绝对路径pages/target/target对应main_pages.json里pages列表的条目不是 React 的相对路径/target。鸿蒙坑传相对路径/target运行错页面不存在router.pushUrl找不到pages列表里的匹配项传./pages/target/target也错不要./前缀要pages/开头——必须传pages/target/target绝对路径跟main_pages.json里src数组的条目一致。特殊值/跳转到首页src数组第一个数据项。Reactnavigate(/target)传相对路径跟BrowserRouter的basename拼接鸿蒙router.pushUrl({ url: pages/target/target })传pages/开头绝对路径跟main_pages.json一致。机制 4router.getParams() 返回 Object 不是 any——取字段要 as Recordstring, string鸿蒙坑根因router.getParams()返回Object不是any取字段要as Recordstring, string// ❌ 鸿蒙坑router.getParams() 返回 Object 不是 any直接取字段编译错 import router from ohos.router // ❌ 直接取字段编译错Object 类型没有字段访问any 才能直接取 const params router.getParams() // ❌ params 类型是 Object 不是 any // console.info(params.keyValue) // ❌ Object 类型没有 keyValue 字段编译错 Property does not exist // ✅ 正确用法as Recordstring, string 转型后取字段Object 不是 any 不能直接取 const paramsObj: Object router.getParams() // ✅ getParams 返回 Object if (paramsObj) { const obj paramsObj as Recordstring, string // ✅ as Record 转型 console.info(keyValue: obj.keyValue) // ✅ Record 转型后能取字段 } // 鸿蒙坑根因getParams 返回 Object 不是 any取字段要 as Recordstring, string 转型getParams Object 坑根因鸿蒙router.getParams(): Object的返回类型是Object不是 TypeScript 的anyObject类型没有字段访问编译错Property keyValue does not exist on type Object。鸿蒙坑ReactuseLocation().state返回any可以直接取字段state.keyValue鸿蒙router.getParams()返回Object不能直接取字段——必须as Recordstring, string或as Recordstring, Object转型后才能访问字段。ArkTS 严格模式Object类型没有字段访问跟 TypeScript 的any不同必须显式转型到Record类型才能取字段。机制 5RouterState 真属性是 index/name/path 不是 stackLength——栈长度用 router.getLength() 返回 string鸿蒙坑根因RouterState真属性是index/name/path不是stackLength栈长度用router.getLength()返回string不是number// ❌ 鸿蒙坑RouterState 没有 stackLength 属性真属性是 index/name/path import router from ohos.router // ❌ state.stackLength 编译错RouterState 没有 stackLength 属性 const state router.getState() // console.info(stackLength: state.stackLength) // ❌ Property stackLength does not exist // ✅ 正确用法RouterState 真属性 index/name/path不是 stackLength const state2 router.getState() console.info(index: state2.index) // ✅ index 是当前页面在栈中的索引从栈底到栈顶从 1 开始 console.info(name: state2.name) // ✅ name 是当前页面的名称对应文件名 console.info(path: state2.path) // ✅ path 是当前页面的路径 // ✅ 栈长度用 router.getLength() 返回 string 不是 number鸿蒙把栈长度编码成字符串 const stackLengthStr: string router.getLength() // ✅ getLength 返回 string 不是 number console.info(stackLength: stackLengthStr) // ✅ 字符串栈长度 // 鸿蒙坑根因RouterState 真属性 index/name/path 不是 stackLengthgetLength 返回 string 不是 numberRouterState 无 stackLength 坑根因鸿蒙router.getState(): RouterState返回的RouterState真属性是index: number当前页面在栈中的索引从栈底到栈顶从 1 开始/name: string当前页面名称对应文件名/path: string当前页面路径/params: Object当前页面携带的参数API 12没有stackLength属性。鸿蒙坑state.stackLength编译错Property stackLength does not exist on type RouterState——栈长度要用router.getLength()单独方法取且getLength()返回string不是number鸿蒙把栈长度编码成字符串要parseInt(getLength())转数字。ReactuseLocation()没有 stackLength 概念React Router 不维护页面栈鸿蒙router.getState()返回单页状态 router.getLength()返回栈长度字符串。机制 6router.replaceUrl 销毁被替换的页面——router.pushUrl 保留当前页状态压栈鸿蒙坑根因router.replaceUrl销毁被替换的页面无法返回router.pushUrl保留当前页状态压栈可以返回// ✅ router.replaceUrl 销毁被替换的页面 vs router.pushUrl 保留当前页状态压栈 import router from ohos.router const options: router.RouterOptions { url: pages/target/target } // ✅ router.pushUrl压栈跳转保留当前页状态可以 router.back() 返回 router.pushUrl(options, router.RouterMode.Standard) // ✅ 压栈当前页状态保留 // 当前页在栈里router.back() 能返回到当前页状态不丢 // ✅ router.replaceUrl替换跳转销毁当前页无法 router.back() 返回 router.replaceUrl(options, router.RouterMode.Single) // ✅ 替换当前页销毁 // 当前页被销毁router.back() 无法返回到当前页状态丢失 // 鸿蒙坑根因replaceUrl 销毁当前页无法返回pushUrl 压栈保留状态能返回replaceUrl vs pushUrl 销毁坑根因鸿蒙router.replaceUrl(options, mode)替换当前页并销毁被替换的页面释放资源无法router.back()返回到被替换的页router.pushUrl(options, mode)压栈跳转保留当前页状态可以router.back()返回到当前页状态不丢。鸿蒙坑Reactnavigate(/path, { replace: true })用replace: true字段控制销毁replace: false默认压栈鸿蒙router.replaceUrl用独立函数控制销毁不是pushUrl的字段——鸿蒙把 replace 语义做成独立函数router.replaceUrl跟 React 的{ replace: true }字段不同。页面栈最大容量 32 个页面超过调router.clear()清空历史页面释放内存。三、真机配图鸿蒙 ohos.router 页面路由坑——RouterMode enum 常量 pushUrl/replaceUrl 不废弃真机配图展示鸿蒙 ohos.router 页面路由坑初始态鸿蒙 6.1 ohos.router 页面路由坑标题4 个验证按钮① RouterMode enum 常量 / ② router.pushUrl 不废弃 push / ③ router.replaceUrl 不废弃 replace / ④ router.backgetParamsgetState路由状态routerStatus 未跳 modeValue 未设 stackLength/getState要点说明 7 条RouterMode enum 常量态点击「① 验证 RouterMode enum 常量」按钮显示「✅ RouterMode enum 常量验证Standard0多实例/ Single1单实例不是字符串」 modeValue 值——RouterMode enum 常量不是字符串验证router.pushUrl 不废弃 push 态点击「② 验证 router.pushUrl 不是废弃 push」按钮显示「✅ router.pushUrl 验证不是废弃的 router.pushRouterMode.Standard enum 常量」——router.push 废弃迁移 pushUrl 验证router.replaceUrl 不废弃 replace 态点击「③ 验证 router.replaceUrl 不是废弃 replace」按钮显示「✅ router.replaceUrl 验证不是废弃的 router.replaceRouterMode.Single 单实例」——router.replace 废弃迁移 replaceUrl 验证router.backgetParamsgetState 态点击「④ 验证 router.back getParams getState」按钮显示「✅ router.back/getParams/getState 验证RouterState 真属性 index/name 不是 stackLength」 stackLength 值 getState 值——RouterState 真属性 index/name getLength 返回 string 验证四、真解法鸿蒙 ohos.router 的四个场景场景 1router.pushUrl 带 RouterMode.Standard 压栈跳转 params 传参——90% 场景首选基础压栈跳转用router.pushUrl(options, router.RouterMode.Standard)params传参// ✅ 场景 1router.pushUrl 带 RouterMode.Standard 压栈跳转 params 传参API 990% 场景首选 import router from ohos.router // ✅ default importrouter 是 namespace Entry Component struct Index { navigateToTarget() { const options: router.RouterOptions { url: pages/target/target, // ✅ url 是 pages/ 开头绝对路径不是相对路径 params: { keyValue: hello h9 router, userId: 123 } // ✅ params 传 Object 不是 state 字段 } // ✅ router.pushUrl 带 RouterMode enum 常量不是字符串Standard不是废弃的 router.push router.pushUrl(options, router.RouterMode.Standard) // ✅ 压栈跳转保留当前页状态 // ✅ pushUrl 返回 Promisevoid可以 .then 链也可以不接 } build() { Column({ space: 8 }) { Button(跳转).onClick(() this.navigateToTarget()) } } } // router.pushUrl RouterMode.Standard90% 场景首选压栈跳转保留状态能 back 返回鸿蒙 ohos.router API 真名坑import router from ohos.routerdefault importrouter是 namespacerouter.pushUrl(options: RouterOptions, mode: RouterMode): Promisevoid带RouterModeenum 常量第二参不是废弃的router.pushrouter.replaceUrl(options: RouterOptions, mode: RouterMode): Promisevoid替换当前页销毁不是废弃的router.replacerouter.back(options?: RouterOptions): void返回上一页带url返回指定页router.getParams(): Object返回Object不是any取字段要as Recordrouter.getState(): RouterState真属性index/name/path不是stackLengthrouter.getLength(): string返回string不是numberrouter.RouterModeenum 常量Standard0/Single1不是字符串SysCapSystemCapability.ArkUI.ArkUI.Fullatomicservice原子化服务API 11。场景 2router.replaceUrl 带 RouterMode.Single 替换跳转 销毁当前页替换跳转用router.replaceUrl(options, router.RouterMode.Single)销毁当前页// ✅ 场景 2router.replaceUrl 带 RouterMode.Single 替换跳转 销毁当前页API 9 import router from ohos.router const options: router.RouterOptions { url: pages/login/login, params: { fromPage: index } } // ✅ router.replaceUrl 替换当前页并销毁不是 router.pushUrl 的 { replace: true } 字段 router.replaceUrl(options, router.RouterMode.Single) // ✅ 替换销毁当前页无法 back 返回 // ✅ RouterMode.Single 单实例如果 login 页已在栈中则移动到栈顶不重复创建 // replaceUrl RouterMode.Single替换销毁当前页适合登录后替换登录页避免返回登录页鸿蒙 router.replaceUrl RouterMode.Single API 真名坑router.replaceUrl(options, mode)替换当前页并销毁被替换的页面释放资源无法router.back()返回RouterMode.Single单实例模式如果目标 url 已存在于栈中则移动该页面到栈顶不重复创建鸿蒙坑Reactnavigate(/path, { replace: true })用replace: true字段控制销毁鸿蒙router.replaceUrl用独立函数控制销毁不是pushUrl的字段登录后用replaceUrl替换登录页避免用户back返回到登录页跟 React 登录后navigate(/home, { replace: true })同理但鸿蒙用独立函数。场景 3router.back 返回上一页 router.getParams 取参数 as Record 转型返回上一页用router.back()取参数用router.getParams()as Recordstring, string转型// ✅ 场景 3router.back 返回上一页 router.getParams 取参数 as Record 转型API 9 import router from ohos.router Entry Component struct Target { State receivedValue: string (未取) aboutToAppear() { // ✅ router.getParams() 取跳转时传递的参数返回 Object 不是 any const params: Object router.getParams() // ✅ getParams 返回 Object if (params) { // ✅ as Recordstring, string 转型后取字段Object 不能直接取字段 const obj params as Recordstring, string // ✅ as Record 转型 this.receivedValue obj.keyValue // ✅ Record 转型后能取 keyValue 字段 } else { this.receivedValue (无参数) } } goBack() { // ✅ router.back() 不带参返回上一页带 url 返回指定页 router.back() // ✅ 返回上一页 // ✅ router.back({ url: pages/index/index }) 带 url 返回指定页如果栈中有该页 } build() { Column({ space: 8 }) { Text(received: this.receivedValue) Button(返回).onClick(() this.goBack()) } } } // router.back 返回 getParams 取参数getParams 返回 Object 要 as Record 转型取字段鸿蒙 router.back getParams API 真名坑router.back(options?: RouterOptions): void不带参返回上一页带{ url }返回指定页如果栈中有该页router.getParams(): Object返回Object不是any取字段要as Recordstring, string转型鸿蒙坑ReactuseLocation().state返回any可以直接取字段state.keyValue鸿蒙router.getParams()返回Object不能直接取字段——必须as Recordstring, string转型后才能访问字段ArkTS 严格模式Object无字段访问Reactnavigate(-1)返回上一页鸿蒙router.back()返回上一页语义一致但鸿蒙是独立函数不是navigate(-1)。场景 4router.getState 取当前页状态 router.getLength 取栈长度 router.clear 清空取当前页状态用router.getState()真属性index/name/path取栈长度用router.getLength()返回string清空用router.clear()// ✅ 场景 4router.getState 取当前页状态 router.getLength 取栈长度 router.clear 清空API 8 import router from ohos.router // ✅ router.getState() 取当前页状态RouterState 真属性 index/name/path 不是 stackLength const state router.getState() console.info(当前页索引: state.index) // ✅ index 从栈底到栈顶从 1 开始 console.info(当前页名称: state.name) // ✅ name 对应文件名 console.info(当前页路径: state.path) // ✅ path 对应页面路径 // ✅ router.getLength() 取页面栈长度返回 string 不是 number要 parseInt 转数字 const stackLengthStr: string router.getLength() // ✅ getLength 返回 string const stackLengthNum: number parseInt(stackLengthStr, 10) // ✅ parseInt 转数字 console.info(页面栈长度: stackLengthNum) // ✅ 页面栈最大容量 32 个页面超过调 router.clear() 清空历史页面释放内存 if (stackLengthNum 30) { router.clear() // ✅ clear() 清空所有历史页面仅保留当前页在栈顶 } // router.getState getLength clearRouterState 真属性 index/name/pathgetLength 返回 string鸿蒙 router.getState getLength clear API 真名坑router.getState(): RouterState真属性index: number/name: string/path: string/params: Object没有stackLength属性router.getLength(): string返回string不是number要parseInt(getLength(), 10)转数字router.clear(): void清空所有历史页面仅保留当前页在栈顶页面栈最大容量 32鸿蒙坑React Router 没有stackLength/getLength/clear概念React Router 不维护页面栈鸿蒙router.getState()返回单页状态 router.getLength()返回栈长度字符串 router.clear()清空历史页面——鸿蒙维护页面栈栈容量 32React Router 不维护页面栈用浏览器 history。五、一句话哲学写鸿蒙 ArkTS 记住router 不是 React Router 是「namespace 顶层函数 pushUrl/replaceUrl RouterMode enum」——鸿蒙 6.1 API 23ohos.routernamespaceAPI 8鸿蒙 6.1 API 23 基座router.pushUrl/router.replaceUrl/router.back/router.getParams/router.getState/router.getLength/router.clear顶层函数 RouterMode/RouterOptions/RouterState类型SysCap SystemCapability.ArkUI.ArkUI.FullatomicserviceAPI 18 废弃迁移到 UIContext.getRouter() 实例方法。根因不是 hook 是 namespace 顶层函数——router.push/router.replace废弃迁移到router.pushUrl/router.replaceUrl✅router.pushUrl(options, mode)不是废弃的router.push❌router.pushdeprecated 有 IDE 警告push has been deprecatedAPI 18 废弃迁移到UIContext.getRouter()实例方法RouterModeenum 常量Standard0/Single1不是字符串Standard✅router.RouterMode.Standard/router.RouterMode.Singleenum 常量❌ 传字符串Standard触发Type string is not assignable to type RouterMode编译错enum 值是数字0/1不是字符串RouterOptions.url是页面绝对路径pages/target/target不是相对路径/target✅pages/开头对应main_pages.jsonpages 列表❌ 相对路径/target运行错页面不存在特殊值/跳首页router.getParams()返回Object不是any✅as Recordstring, string转型后取字段❌params.keyValue触发Property does not exist on type Object编译错ArkTS 严格模式Object无字段访问RouterState真属性index/name/path不是stackLength✅state.index/state.name/state.path真属性❌state.stackLength触发Property stackLength does not exist编译错栈长度用router.getLength()单独方法取router.getLength()返回string不是number✅parseInt(router.getLength(), 10)转数字❌const len: number router.getLength()触发Type string is not assignable to type number编译错鸿蒙把栈长度编码成字符串router.replaceUrl销毁当前页无法back返回不是pushUrl的{ replace: true }字段是独立函数router.pushUrl压栈保留当前页状态能back返回页面栈最大容量 32 超过调router.clear()清空。router.push 废弃迁移 pushUrl RouterMode enum 常量不是字符串 url 绝对路径 getParams Object 要 as Record RouterState 真属性 index/name getLength 返回 string是鸿蒙 6.1 ohos.router 页面路由坑核心能力系列回链鸿蒙 7.0 新特性篇 1~17沉浸式毛玻璃/Component3D/智能体框架/方舟引擎/星盾安全/星河互联/空间音频/可变字体/游戏快启/分布式数据盾/LTPO 可变帧率/AI 文档识别/多形态服务窗口/AI 反诈/机密计算/空间计算/小艺全面进化鸿蒙 6.1 API 23 开发坑系列篇 1「ArkUI.modifier 装饰器坑」——attributeModifier AttributeModifier 状态化节点修改器鸿蒙 6.1 API 23 开发坑系列篇 2「arkui.componentSnapshot 组件截图坑」——get/getSync/createFromBuilder 返回 image.PixelMap 像素图鸿蒙 6.1 API 23 开发坑系列篇 3「arkui.node 节点坑」——NodeController abstract class makeNode override BuilderNode WrappedBuilder鸿蒙 6.1 API 23 开发坑系列篇 4「arkui.UIContext UI 上下文坑」——runScopedTask 不是 runScopedOnUiThread 11 个子管理器鸿蒙 6.1 API 23 开发坑系列篇 5「arkui.observer UI 观察器坑」——uiObserver namespace 真名不是 observer on type string literal鸿蒙 6.1 API 23 开发坑系列篇 6「ohos.animator 动画器坑」——import kit.ArkUI 不是 ohos.animator onFrame 驼峰不是废弃 onframe getUIContext().createAnimator 不是废弃 animator.create 持引用 aboutToDisappear cancel鸿蒙 6.1 API 23 开发坑系列篇 7「ohos.net.http HTTP 请求坑」——HttpDataType 常量是 STRING 不是 STRING_TYPE HttpRequest 是 interface 不能 new http.createHttp() 工厂造实例 on/off 监听不是 addEventListener header Record 不是 Headers RequestMethod enum 不是字符串鸿蒙 6.1 API 23 开发坑系列篇 8「ohos.file.fs 文件管理坑」——writeSync/readSync 是 namespace 顶层函数不是 File 实例方法 第一参传 file.fd 文件描述符 ReadOptions 无 encoding 读 ArrayBuffer 裸字节 WriteOptions 带 encoding 写字符串指定编码 closeSync(file) 传 File 不是 fd OpenMode enum 不是 flags 数字鸿蒙 6.1 API 23 开发坑系列篇 9「ohos.router 页面路由坑」——router.push/replace 废弃迁移 pushUrl/replaceUrl RouterMode enum 常量 Standard/Single 不是字符串 RouterOptions.url 绝对路径不是相对路径 getParams 返回 Object 要 as Record 转型 RouterState 真属性 index/name 不是 stackLength getLength 返回 string 不是 number本文