04.1
为什么需要导航框架
多页面应用需要统一的路由、返回栈与转场管理。Navigation 是官方推荐的一站式方案，替代老的 router.pushUrl。
新范式
HarmonyOS NEXT 主推 Navigation 声明式路由，配合 NavPathStack 精确控制页面栈，利于复杂导航与深链。
04.2
Navigation 基础
Navigation 包裹内容，navDestination 注册目标页面，按路由名切换。
@Entry @Component
struct Main {
@Provide nav: NavPathStack = new NavPathStack()
build() {
Navigation(this.nav) {
Column() { /* 首页内容 */ }
}.navDestination(this.pageMap)
}
@Builder pageMap(name: string) {
if (name === 'detail') DetailPage()
}
}04.3
NavPathStack
页面栈对象管理跳转（push）、返回（pop）与替换（replace），可跨组件共享。
this.nav.pushPath({ name: 'detail' })
this.nav.pop()
this.nav.replacePath({ name: 'profile' })04.4
路由与参数
通过 param 携带数据，目标页用 NavPathStack 的 getParam 取参。
this.nav.pushPath({ name: 'detail', param: { id: 42 } })
// 目标页
const id = this.nav.getParamByName('detail')[0]?.['id']04.5
页面生命周期
自定义组件有 aboutToAppear/aboutToDisappear；页面级有 onPageShow/onPageHide。用于加载与清理。
| 回调 | 时机 |
|---|---|
| aboutToAppear | 组件即将出现 |
| onPageShow | 页面前台显示 |
| onPageHide | 页面退到后台 |
| aboutToDisappear | 组件即将销毁 |
04.6
模态与弹窗
BindSheet/BindContentCover 实现半屏/全屏模态，AlertDialog 用于确认交互。
Button("设置").bindSheet(this.showSheet, () => { /* 半屏内容 */ })04.7
Tabs 与分栏
Tabs 实现底部/顶部多标签；宽屏用 Split 分栏呈现主从布局。
04.8
常见陷阱
反复 push 会堆积页面。应在适当时机 pop 或 replace，或用 launchMode 控制栈行为，避免内存与返回混乱。
确认 pushPath 时传了 param，且目标页在 onReady/pageShow 后读取；跨实例读取需用正确的栈引用。
04.9