鸿蒙6.1 @ohos.router坑：push/replace废迁pushUrl/replaceUrl+RouterMode enum非字符串

JaneConan

213人浏览 · 2026-08-12 15:36:58

JaneConan · 2026-08-12 15:36:58 发布

本文是「鸿蒙 6.1 API 23 开发坑系列」第 9 篇（非 UI 系第 3 篇）。本篇讲 @ohos.router namespace（API 8+，鸿蒙 6.1 API 23 基座）——页面路由 router.pushUrl/router.replaceUrl/router.back + RouterMode/RouterOptions/RouterState 类型。鸿蒙坑根因：① router.push/router.replace/router.back/router.getParams/router.getState/router.getLength 是废弃顶层函数（API 18 废弃，迁移到 router.pushUrl/router.replaceUrl + UIContext.getRouter() 实例方法）；② RouterMode enum 常量 Standard=0（多实例）/Single=1（单实例）不是字符串 'Standard'；③ RouterOptions.url 是页面绝对路径（pages/target/target）不是相对路径；④ router.getParams() 返回 Object 不是 any（取字段要 as Record<string, 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-dom（useNavigate hook 返回 navigate 函数，传字符串路径 + state 对象）：

// React Router：useNavigate 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.replaceUrl namespace 顶层函数（RouterOptions 带 url+params，第二参 RouterMode enum 常量不是字符串）：

// ArkTS router.pushUrl：namespace 顶层函数，RouterMode enum 常量不是字符串
import router from '@ohos.router'  // ✅ default import（router 是 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 废弃迁移 pushUrl，RouterMode enum 常量不是字符串

React Router vs 鸿蒙 router 的区别：React 把页面路由当 hook（useNavigate() 返回 navigate 函数，传字符串路径 + { state, replace } 对象，replace: true 用字段控制销毁），ArkTS 把页面路由当 namespace 顶层函数（router.pushUrl(options, mode) 带 RouterOptions + RouterMode enum 常量，replaceUrl 用独立函数不用字段控制销毁）。根因不是 hook 是 namespace 顶层函数——鸿蒙 router.push/router.replace 废弃迁移到 router.pushUrl/router.replaceUrl（API 18 废弃），RouterMode enum 常量 Standard/Single 不是字符串（React 'STANDARD'/'SINGLE' 不存在，鸿蒙 enum 值是数字 0/1）。

二、根因：鸿蒙 @ohos.router 的六个绑定机制

鸿蒙 @ohos.router namespace（API 8+）核心导出 router.pushUrl/router.replaceUrl/router.back/router.getParams/router.getState/router.getLength 顶层函数（多数 API 18 废弃迁移到 UIContext.getRouter()）+ RouterMode/RouterOptions/RouterState 类型。绑定机制来自六重根因。

机制 1：router.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'

// ❌ 废弃 API（API 9~17）：router.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/replaceUrl，IDE 警告 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。React navigate('/path') 没有 deprecated 版本，鸿蒙 router.push deprecated 是因为 API 18 把路由统一到 UIContext.getRouter() 实例方法（跟篇 6 animator.create 废弃迁移到 getUIContext().createAnimator() 同理）。

机制 2：RouterMode enum 常量 Standard=0/Single=1 不是字符串’Standard’

鸿蒙坑根因：RouterMode enum 常量 Standard=0（多实例）/Single=1（单实例），不是字符串 '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 常量 Standard=0 / Single=1（不是字符串）
router.pushUrl({ url: 'pages/target/target' }, router.RouterMode.Standard)  // ✅ enum 常量 Standard=0
router.pushUrl({ url: 'pages/target/target' }, router.RouterMode.Single)    // ✅ enum 常量 Single=1

// ✅ RouterMode enum 常量语义：
// Standard=0：多实例模式（默认），目标页面添加到栈顶，无论栈中是否存在相同 url 的页面
// Single=1：单实例模式，如果目标 url 已存在于栈中，则移动该页面到栈顶（不重复创建）
const standardMode: router.RouterMode = router.RouterMode.Standard  // ✅ Standard=0（多实例）
const singleMode: router.RouterMode = router.RouterMode.Single      // ✅ Single=1（单实例）
// 鸿蒙坑根因：RouterMode enum 常量 Standard/Single 不是字符串，enum 值是数字 0/1

RouterMode enum 坑根因：鸿蒙 RouterMode enum 的两个常量是 Standard=0（多实例模式，默认，目标页面添加到栈顶无论栈中是否存在相同 url）/Single=1（单实例模式，如果目标 url 已存在于栈中则移动该页面到栈顶不重复创建）。鸿蒙坑：传字符串 'Standard' 触发 Type 'string' is not assignable to type 'RouterMode' 编译错——必须传 router.RouterMode.Standard enum 常量（enum 值是数字 0 不是字符串）。React navigate('/path') 没有 mode 参数（用 { replace: true } 字段控制），鸿蒙 router.pushUrl(options, mode) 第二参是 RouterMode enum 控制单实例/多实例（不是 replace 语义，replace 用 router.replaceUrl 独立函数）。

机制 3：RouterOptions.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 数组第一个数据项）。React navigate('/target') 传相对路径（跟 BrowserRouter 的 basename 拼接），鸿蒙 router.pushUrl({ url: 'pages/target/target' }) 传 pages/ 开头绝对路径（跟 main_pages.json 一致）。

机制 4：router.getParams() 返回 Object 不是 any——取字段要 as Record<string, string>

鸿蒙坑根因：router.getParams() 返回 Object 不是 any，取字段要 as Record<string, 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 Record<string, string> 转型后取字段（Object 不是 any 不能直接取）
const paramsObj: Object = router.getParams()  // ✅ getParams 返回 Object
if (paramsObj) {
  const obj = paramsObj as Record<string, string>  // ✅ as Record 转型
  console.info('keyValue: ' + obj.keyValue)  // ✅ Record 转型后能取字段
}
// 鸿蒙坑根因：getParams 返回 Object 不是 any，取字段要 as Record<string, string> 转型

getParams Object 坑根因：鸿蒙 router.getParams(): Object 的返回类型是 Object（不是 TypeScript 的 any），Object 类型没有字段访问（编译错 Property 'keyValue' does not exist on type 'Object'）。鸿蒙坑：React useLocation().state 返回 any 可以直接取字段（state.keyValue），鸿蒙 router.getParams() 返回 Object 不能直接取字段——必须 as Record<string, string>（或 as Record<string, Object>）转型后才能访问字段。ArkTS 严格模式 Object 类型没有字段访问（跟 TypeScript 的 any 不同），必须显式转型到 Record 类型才能取字段。

机制 5：RouterState 真属性是 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 不是 stackLength，getLength 返回 string 不是 number

RouterState 无 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()) 转数字）。React useLocation() 没有 stackLength 概念（React Router 不维护页面栈），鸿蒙 router.getState() 返回单页状态 + router.getLength() 返回栈长度字符串。

机制 6：router.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() 返回到当前页，状态不丢）。鸿蒙坑：React navigate('/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.back+getParams+getState），路由状态（routerStatus 未跳 + modeValue 未设 + stackLength/getState），要点说明 7 条
RouterMode enum 常量态：点击「① 验证 RouterMode enum 常量」按钮，显示「✅ RouterMode enum 常量验证：Standard=0（多实例）/ Single=1（单实例）不是字符串」+ modeValue 值——RouterMode enum 常量不是字符串验证
router.pushUrl 不废弃 push 态：点击「② 验证 router.pushUrl 不是废弃 push」按钮，显示「✅ router.pushUrl 验证：不是废弃的 router.push，RouterMode.Standard enum 常量」——router.push 废弃迁移 pushUrl 验证
router.replaceUrl 不废弃 replace 态：点击「③ 验证 router.replaceUrl 不是废弃 replace」按钮，显示「✅ router.replaceUrl 验证：不是废弃的 router.replace，RouterMode.Single 单实例」——router.replace 废弃迁移 replaceUrl 验证
router.back+getParams+getState 态：点击「④ 验证 router.back + getParams + getState」按钮，显示「✅ router.back/getParams/getState 验证：RouterState 真属性 index/name 不是 stackLength」+ stackLength 值 + getState 值——RouterState 真属性 index/name + getLength 返回 string 验证

四、真解法：鸿蒙 @ohos.router 的四个场景

场景 1：router.pushUrl 带 RouterMode.Standard 压栈跳转 + params 传参——90% 场景首选

基础压栈跳转用 router.pushUrl(options, router.RouterMode.Standard) + params 传参：

// ✅ 场景 1：router.pushUrl 带 RouterMode.Standard 压栈跳转 + params 传参（API 9，90% 场景首选）
import router from '@ohos.router'  // ✅ default import（router 是 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 返回 Promise<void>（可以 .then 链，也可以不接）
  }

  build() { Column({ space: 8 }) { Button('跳转').onClick(() => this.navigateToTarget()) } }
}
// router.pushUrl + RouterMode.Standard：90% 场景首选，压栈跳转保留状态能 back 返回

鸿蒙 @ohos.router API 真名坑：import router from '@ohos.router'（default import，router 是 namespace）；router.pushUrl(options: RouterOptions, mode: RouterMode): Promise<void>（带 RouterMode enum 常量第二参，不是废弃的 router.push）；router.replaceUrl(options: RouterOptions, mode: RouterMode): Promise<void>（替换当前页销毁，不是废弃的 router.replace）；router.back(options?: RouterOptions): void（返回上一页，带 url 返回指定页）；router.getParams(): Object（返回 Object 不是 any，取字段要 as Record）；router.getState(): RouterState（真属性 index/name/path 不是 stackLength）；router.getLength(): string（返回 string 不是 number）；router.RouterMode enum 常量 Standard=0/Single=1（不是字符串）；SysCap SystemCapability.ArkUI.ArkUI.Full；@atomicservice 原子化服务（API 11+）。

场景 2：router.replaceUrl 带 RouterMode.Single 替换跳转 + 销毁当前页

替换跳转用 router.replaceUrl(options, router.RouterMode.Single) 销毁当前页：

// ✅ 场景 2：router.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 已存在于栈中则移动该页面到栈顶不重复创建）；鸿蒙坑：React navigate('/path', { replace: true }) 用 replace: true 字段控制销毁，鸿蒙 router.replaceUrl 用独立函数控制销毁（不是 pushUrl 的字段）；登录后用 replaceUrl 替换登录页避免用户 back 返回到登录页（跟 React 登录后 navigate('/home', { replace: true }) 同理，但鸿蒙用独立函数）。

场景 3：router.back 返回上一页 + router.getParams 取参数 + as Record 转型

返回上一页用 router.back()，取参数用 router.getParams() + as Record<string, string> 转型：

// ✅ 场景 3：router.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 Record<string, string> 转型后取字段（Object 不能直接取字段）
      const obj = params as Record<string, 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 Record<string, string> 转型）；鸿蒙坑：React useLocation().state 返回 any 可以直接取字段（state.keyValue），鸿蒙 router.getParams() 返回 Object 不能直接取字段——必须 as Record<string, string> 转型后才能访问字段（ArkTS 严格模式 Object 无字段访问）；React navigate(-1) 返回上一页，鸿蒙 router.back() 返回上一页（语义一致但鸿蒙是独立函数不是 navigate(-1)）。

场景 4：router.getState 取当前页状态 + router.getLength 取栈长度 + router.clear 清空

取当前页状态用 router.getState()（真属性 index/name/path），取栈长度用 router.getLength()（返回 string），清空用 router.clear()：

// ✅ 场景 4：router.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 + clear：RouterState 真属性 index/name/path，getLength 返回 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() 清空历史页面——鸿蒙维护页面栈（栈容量 32），React Router 不维护页面栈（用浏览器 history）。

五、一句话哲学

写鸿蒙 ArkTS 记住：router 不是 React Router 是「namespace 顶层函数 pushUrl/replaceUrl + RouterMode enum」——鸿蒙 6.1 API 23 @ohos.router namespace（API 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.Full，@atomicservice，API 18 废弃迁移到 UIContext.getRouter() 实例方法）。根因不是 hook 是 namespace 顶层函数——router.push/router.replace 废弃迁移到 router.pushUrl/router.replaceUrl（✅ router.pushUrl(options, mode) 不是废弃的 router.push，❌ router.push deprecated 有 IDE 警告 'push' has been deprecated，API 18 废弃迁移到 UIContext.getRouter() 实例方法），RouterMode enum 常量 Standard=0/Single=1 不是字符串 'Standard'（✅ router.RouterMode.Standard/router.RouterMode.Single enum 常量，❌ 传字符串 'Standard' 触发 Type 'string' is not assignable to type 'RouterMode' 编译错，enum 值是数字 0/1 不是字符串），RouterOptions.url 是页面绝对路径 pages/target/target 不是相对路径 /target（✅ pages/ 开头对应 main_pages.json pages 列表，❌ 相对路径 /target 运行错页面不存在，特殊值 '/' 跳首页），router.getParams() 返回 Object 不是 any（✅ as Record<string, 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（本文）