NavPathStack 是鸿蒙 Navigation 路由的核心控制器

NavPathStack 是鸿蒙 Navigation 路由的核心控制器，负责管理页面栈（即页面导航历史记录）。通过可视化栈结构模型，可以直观理解其操作逻辑：

📚 NavPathStack 页面栈模型

graph LR A[栈底] --> B[首页] B --> C[列表页] C --> D[详情页]:::current classDef current fill:#FFD700,stroke:#333;

栈底固定：首页（Root Page）始终位于栈底，不可移除
栈顶活跃 ：栈顶页面（如图中详情页）是当前用户可见页面
最大深度：默认支持32层页面栈（超出会触发警告）

⚙️ 核心操作可视化解析

1. 页面跳转（Push）

typescript 复制代码

stack.pushPath({ name: 'PaymentPage', params: { orderId: 123 } })

栈变化：

css 复制代码

[ 首页 → 列表页 → 详情页 ] → 新增支付页 → [首页 → 列表页 → 详情页 → 支付页]

用途：打开新页面（如从商品页进入支付页）

2. 页面返回（Pop）

typescript 复制代码

stack.pop() // 返回上一页
stack.popToIndex(1) // 返回栈中第2个页面

栈变化：

css 复制代码

[首页 → 列表页 → 详情页 → 支付页] → 移除支付页 → [首页 → 列表页 → 详情页]

生命周期触发：

支付页触发 onWillDisappear → onDisappear
详情页触发 onShown（重新激活）

3. 页面替换（Replace）

typescript 复制代码

stack.replaceTop({ name: 'NewDetail', params: { id: 456 } })

栈变化：

css 复制代码

[首页 → 列表页 → 旧详情页] → 替换顶部 → [首页 → 列表页 → 新详情页]

场景：更新当前页数据而不新增历史记录（如刷新详情页）

4. 页面删除（Remove）

typescript 复制代码

stack.removeByName('ListPage') // 删除指定页面
stack.removeByIndexes([1,2]) // 删除多个页面

栈变化：

css 复制代码

[首页 → 列表页 → 详情页 → 支付页] → 删除列表页 → [首页 → 详情页 → 支付页]

注意事项：

删除中间页面时，其上的页面会下移填补位置
若删除当前页，会自动激活新栈顶页面

5. 参数获取（Get Params）

typescript 复制代码

// 获取当前页参数
const currentParams = stack.getParamByName('DetailPage') 

// 获取任意栈中页面参数
const listParams = stack.getParamByIndex(1)

数据流示意图：

css 复制代码

[首页] --无参数--> 
[列表页] --{category:"电子"}--> 
[详情页] --{id:123}--> 
[当前页]

特点：参数与页面绑定，页面销毁时参数自动释放

6. 路由拦截（Interception）

typescript 复制代码

stack.setInterception((routeInfo) => {
  if (routeInfo.name === 'VIPPage' && !user.isVIP) {
    return { redirect: 'UpgradePage' } // 拦截并重定向
  }
  return { proceed: true } // 放行
})

拦截时机：

sequenceDiagram User->>+Stack: 请求跳转VIP页 Stack->>Interceptor: 检查权限 Interceptor-->>Stack: 拒绝请求 Stack->>User: 重定向至升级页

典型场景：登录验证、支付拦截、权限控制

🔄 生命周期联动关系

操作	当前页触发事件	新页触发事件
Push	`onHidden`	`aboutToAppear`→`onShown`
Pop	`onWillDisappear`	`onShown`
Replace	`aboutToDisappear`	`onReady`→`onShown`
Remove	`aboutToDisappear`	无（非活跃页不触发）

⚠️ 关键规则：仅栈顶页面处于活跃状态，其他页面保留实例但冻结渲染

💡 实战应用技巧

单例页面优化

typescript 复制代码

// 检查页面是否已在栈中
if (!stack.findIndexByName('ChatPage')) {
    stack.pushPath({ name: 'ChatPage' }) // 避免重复创建
}

深度链接跳转

typescript 复制代码

// 解析URL：app://shop/list?category=food
stack.popToIndex(0) // 回首页
stack.pushPath({ name: 'ShopPage' })
stack.pushPath({ 
    name: 'ListPage', 
    params: { category: 'food' } 
})

路由状态持久化

typescript 复制代码

// 保存栈状态
AppStorage.set('savedStack', stack.serialize())

// 恢复栈状态
const saved = AppStorage.get('savedStack')
stack.restore(saved)

通过可视化模型理解 NavPathStack 操作，可避免常见问题如：页面重复创建、参数传递丢失、生命周期错乱等。结合路由拦截和栈操作API，能实现复杂场景如：电商购物流程、银行身份验证跳转等。