HarmonyOS：Navigation 和 NavDestination 组件详解

最新推荐文章于 2025-11-23 18:17:23 发布

原创最新推荐文章于 2025-11-23 18:17:23 发布 · 426 阅读

9 ·

CC 4.0 BY-SA版权

文章标签：

#harmonyos #华为 #鸿蒙 #深度学习

鸿蒙HarmonyOS 专栏收录该内容

15 篇文章

订阅专栏

🌐 导航系统架构概览

HarmonyOS 导航系统采用声明式UI+集中式路由管理架构：

🚀 核心组件详解

组件	作用	关键特性
Navigation	导航容器	管理页面栈、路由跳转、全局配置
NavPathStack	导航状态控制器	提供push/pop/clear等栈操作方法
NavDestination	页面容器	定义页面内容、绑定导航栈
mode属性	控制导航显示模式	Auto/Stack/Split三种模式

📁 完整文件结构

💻 核心代码实现

index.ets (主页面)：

@Entry
@Component
struct Index {
  // ✅ 创建导航栈实例
  pathStack: NavPathStack = new NavPathStack()
  @State currentMode: NavigationMode = NavigationMode.Auto // 响应式模式控制
  
  build() {
    Navigation(this.pathStack) {
      Column() {
        Button('跳转到第二页')
          .onClick(() => {
            //  🚀 导航跳转
            this.pathStack.pushPath({
              name: 'Second',
              params: { id: 100 }  
            })
          })
          
        Button('切换模式')
          .onClick(() => {
            // 动态切换模式
            this.currentMode = (this.currentMode === NavigationMode.Stack) 
              ? NavigationMode.Split 
              : NavigationMode.Stack
          })
      }
    }
    // ✅ 关键：设置导航模式
    .mode(this.currentMode)
    .navBarVisibility(NavBarVisibility.Visible)
  }
  
  aboutToAppear() {
    // 设备自适应逻辑
    display.on('change', () => {
      const displayInfo = display.getDefaultDisplaySync()
      this.currentMode = displayInfo.width >= 600 
        ? NavigationMode.Split 
        : NavigationMode.Stack
    })
  }
}

Second.ets (二级页面)：

@Builder
export function showPageBuilder() {
  Second()
}

@Component
struct Second {
  private pathStack?: NavPathStack
  
  build() {
    NavDestination() {
      Column() {
        Text('当前ID: ' + (this.pathStack?.getParams()?.id || 0))
        Button('返回首页')
          .onClick(() => this.pathStack?.pop())
      }
    }
    .onReady((ctx: NavDestinationContext) => {
      this.pathStack = ctx.pathStack
      console.log('接收参数:', ctx.params)
    })
  }
}

router_map.json (路由映射)：

{
  "routerMap": [
    {
      "name": "Second",
      "pageSourceFile": "src/main/ets/Second.ets",
      "buildFunction": "showPageBuilder"
    }
  ]
}

module.json (全局配置)：

{
  "module": {
    "routerMap": "$profile:router_map",
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "supportSplit": true,
        "forcedSplit": false
      }
    ]
  }
}

📊 Navigation的mode属性详解

模式值	说明	适用场景	动画效果
`Auto`	自动模式(默认)	通用设备	自动切换动画
`Stack`	堆栈模式	手机设备	右滑入/左滑出
`Split`	分屏模式	平板/折叠屏	无过渡动画

模式切换逻辑：

模式自适应代码：

aboutToAppear() {
  display.on('change', () => {
    const displayInfo = display.getDefaultDisplaySync()
    this.currentMode = displayInfo.width >= 600 
      ? NavigationMode.Split 
      : NavigationMode.Stack
  })
}