HarmonyOS应用开发实战：猫猫大作战-NavDestination 的结构组成、自定义标题栏、菜单栏和工具栏以及生命周期管理

前言

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 核心属性

二、标题栏配置

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