前言

NavDestination 是 Navigation 路由体系中每个"页面"的容器——它提供标题栏、工具栏、菜单栏、返回按钮等页面级 UI 结构，同时管理页面内容的渲染。每个通过 pushPath 进入的"页面"实际上都是一个 NavDestination 实例。

本文以「猫猫大作战」中排行榜详情页和游戏结束页为锚点，讲解 NavDestination 的结构组成、自定义标题栏、菜单栏和工具栏以及生命周期管理。

提示：本系列不讲 ArkTS 基础语法与环境搭建，假设你已跟完第 1–83 篇。本篇是阶段三第 84 篇。

一、NavDestination 基本结构

1.1 最简实现

@Component
struct LeaderboardPage {
  build() {
    NavDestination() {
      // 页面内容
      Column() {
        Text('排行榜内容区')
          .fontSize(20)
      }
      .padding(16)
    }
    .title('排行榜')                   // 标题栏
  }
}

1.2 核心属性

属性	说明	示例
.title()	标题栏	.title('排行榜')
.menu()	菜单栏（右上角）	.menu(this.MenuBuilder)
.toolBar()	底部工具栏	.toolBar(this.ToolBarBuilder)
.backButtonIcon()	自定义返回图标	.backButtonIcon($r('sys.media.ohos_ic_back'))
.hideTitleBar()	隐藏标题栏	.hideTitleBar(true)
.hideBackButton()	隐藏返回按钮	.hideBackButton()
.mode()	导航栏显示模式	.mode(NavDestinationMode.STANDARD)

二、标题栏配置

2.1 标准标题

NavDestination() {
  // 页面内容
}
.title('排行榜')                    // 纯文本标题
.title({
  text: '排行榜',
  textColor: '#2C3E50',
  fontSize: 18
})                                  // 自定义样式标题

2.2 自定义标题栏

@Component
struct LeaderboardPage {
  @Builder
  CustomTitle() {
    Row() {
      Text('🏆')
        .fontSize(24)
      Text('排行榜')
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
        .margin({ left: 8 })
      Text('TOP 100')
        .fontSize(12)
        .fontColor('#999')
        .margin({ left: 8 })
    }
  }

  build() {
    NavDestination() {
      List() { /* 排行榜列表 */ }
    }
    .title(this.CustomTitle())      // 自定义标题
  }
}

三、菜单栏与工具栏

3.1 菜单栏（右上角）

@Component
struct LeaderboardPage {
  @Builder
  MenuArea() {
    Row() {
      Image($r('app.media.icon_search'))
        .width(24)
        .height(24)
        .margin({ right: 12 })
        .onClick(() => {
          console.info('搜索')
        })
      Image($r('app.media.icon_filter'))
        .width(24)
        .height(24)
        .onClick(() => {
          console.info('筛选')
        })
    }
  }

  build() {
    NavDestination() {
      List() { /* 排行榜列表 */ }
    }
    .title('排行榜')
    .menu(this.MenuArea)
  }
}

3.2 工具栏（底部）

@Component
struct GameOverPage {
  @Builder
  ToolBarArea() {
    Row() {
      Button('再来一局')
        .width('45%')
        .backgroundColor('#2ECC71')
        .onClick(() => {
          console.info('重新开始')
        })
      Blank().width('10%')
      Button('返回主页')
        .width('45%')
        .backgroundColor('#95A5A6')
        .onClick(() => {
          console.info('返回主页')
        })
    }
    .padding(12)
    .width('100%')
  }

  build() {
    NavDestination() {
      Column() {
        Text('游戏结束')
          .fontSize(28)
        Text('得分: 88888')
          .fontSize(20)
      }
      .padding(24)
    }
    .title('游戏结束')
    .hideBackButton(true)           // 游戏结束页隐藏返回
    .toolBar(this.ToolBarArea)
  }
}

四、返回按钮控制

4.1 隐藏/显示返回按钮

// 隐藏返回按钮（适用于首页、登录页等）
NavDestination()
  .hideBackButton(true)

// 自定义返回图标
NavDestination()
  .backButtonIcon($r('sys.media.ohos_ic_back'))

// 拦截返回事件
NavDestination()
  .onBackPressed(() => {
    console.info('返回被拦截')
    return true  // true=拦截（不返回），false=放行（返回）
  })

4.2 返回确认

@Component
struct GameBoardPage {
  @State showConfirm: boolean = false;

  build() {
    NavDestination() {
      // 游戏棋盘内容
    }
    .title('游戏中')
    .onBackPressed(() => {
      // 游戏进行中时阻止返回，弹出确认框
      if (this.isPlaying) {
        AlertDialog.show({
          message: '确定要退出游戏吗？',
          primaryButton: { value: '继续游戏', action: () => {} },
          secondaryButton: { value: '退出', action: () => {
            this.navStack.pop()
          }}
        });
        return true  // 拦截返回，显示确认框
      }
      return false  // 放行返回
    })
  }
}

五、生命周期

5.1 NavDestination 生命周期

NavDestination 的生命周期与页面栈操作一一对应：

pushPath('pages/Leaderboard')
    ↓
Leaderboard 的 NavDestination 创建
    ↓
aboutToAppear()
    ↓
build()
    ↓
onDidBuild()
    ↓
onPageShow()     ← 页面可见

pop()
    ↓
onPageHide()     ← 页面隐藏
aboutToDisappear() ← 页面销毁

5.2 生命周期回调

@Component
struct LeaderboardPage {
  aboutToAppear() {
    console.info('排行榜页即将出现')
  }

  onPageShow() {
    console.info('排行榜页可见')
    // 刷新数据
  }

  onPageHide() {
    console.info('排行榜页隐藏')
    // 暂停视频等
  }

  aboutToDisappear() {
    console.info('排行榜页销毁')
    // 释放资源
  }
}

六、总结

NavDestination 是 Navigation 体系中的页面容器，提供了标题栏、菜单栏、工具栏等页面级 UI 组件，支持自定义样式和返回控制。

核心要点：

• NavDestination 是 Navigation 中每个"页面"的容器
• .title() 标题栏，支持文本和 @Builder 自定义
• .menu() 右上角菜单栏，.toolBar() 底部工具栏
• .hideBackButton() 隐藏返回按钮
• .onBackPressed() 拦截返回事件
• 生命周期：aboutToAppear → build → onPageShow → onPageHide → aboutToDisappear

下一篇预告：第 85 篇将深入 navDestination @Builder 注册式跳转，讲解严格模式下的页面注册要求。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

---

相关资源：

• NavDestination 组件参考
• Navigation 跳转
• Navigation 架构介绍
• 开源鸿蒙跨平台社区
• 第 83 篇：NavPathStack
• 第 85 篇：navDestination @Builder