HarmonyOS应用开发实战萌宠日记 - 子页面路由实现前言NavDestination是 HarmonyOS 中与Navigation组件配套使用的子页面容器它负责渲染通过NavPathStack.pushPath()跳转到的目标页面。在萌宠日记中我们通过 NavDestination 实现了宠物档案、成长时间轴、社区发现、相册、提醒事项等子页面的路由注册。本文将从萌宠日记的 NavDestination 使用出发深入解析子页面路由的原理、Builder 注册方式、页面生命周期和配置技巧。一、NavDestination 概述1.1 组件定位NavDestination 是 Navigation 导航体系中的目标页面容器当通过NavPathStack.pushPath({ name: xxx })跳转时Navigation 会自动查找并渲染对应名称的 NavDestination。组件角色说明Navigation导航容器管理导航栏、页面栈、转场动画NavPathStack导航栈管理页面路径栈NavDestination目标页面渲染跳转到的页面内容1.2 萌宠日记的 NavDestination 注册// Index.ets — 三个 Tab 的 NavDestination 注册 Builder HomeNavDestinations() { NavDestination() { PetProfilePage() }.title(宠物档案) NavDestination() { GrowthTimelinePage() }.title(成长时间轴) NavDestination() { CommunityPage() }.title(发现) } Builder DiaryNavDestinations() { NavDestination() { WriteDiaryPage() }.title(写日记) } Builder RecordNavDestinations() { NavDestination() { AlbumPage() }.title(相册) NavDestination() { ReminderPage() }.title(提醒事项) }提示NavDestination 通过Builder构建函数注册Navigation 通过navDestination属性引用该构建函数。每个Builder中可以包含多个NavDestinationNavigation 会根据pushPath的name参数自动匹配对应的 NavDestination。二、NavDestination 与 Builder 的绑定2.1 绑定方式// Navigation 组件上绑定 navDestination 属性 Navigation(this.homeStack) { HomePage({...}) } .hideTitleBar(true) .navDestination(this.HomeNavDestinations) // 绑定 Builder 构建函数2.2 匹配机制用户调用: this.homeStack.pushPath({ name: petProfile }) ↓ Navigation 在当前绑定的 Builder 中查找 name 为 petProfile 的 NavDestination ↓ 匹配到 HomeNavDestinations 中的 NavDestination { PetProfilePage() } ↓ 渲染 PetProfilePage 并显示导航栏标题宠物档案2.3 匹配规则匹配方式说明示例name 匹配通过 NavDestination 的 name 属性匹配NavDestination().name(petProfile)默认匹配未指定 name 时按 NavDestination 声明顺序匹配按 Builder 中的顺序三、NavDestination 的核心属性3.1 title 属性NavDestination() { PetProfilePage() } .title(宠物档案) // 导航栏标题title属性控制导航栏左侧显示的标题文字属性值效果title宠物档案显示标题文字title支持资源引用$r(app.string.pet_profile)3.2 其他常用属性NavDestination() { PetProfilePage() } .title(宠物档案) .hideTitleBar(false) // 是否隐藏标题栏 .mode(NavDestinationMode.STANDARD) // 页面模式 .onBackClick(() { // 自定义返回按钮点击事件 console.log(Back clicked) })属性类型说明默认值titlestring导航栏标题—hideTitleBarboolean是否隐藏标题栏falsemodeNavDestinationMode页面模式STANDARDonBackClick回调返回按钮点击事件默认出栈四、NavDestination 的模式4.1 两种模式// 标准模式默认 NavDestination() .mode(NavDestinationMode.STANDARD) // 弹窗模式 NavDestination() .mode(NavDestinationMode.DIALOG)模式说明适用场景STANDARD全屏页面占用整个 Navigation 区域默认页面跳转DIALOG弹窗样式背景半透明确认框、选择器、临时操作4.2 DIALOG 模式的应用// 弹窗模式的 NavDestination 示例 Builder DialogDestinations() { NavDestination() { Column({ space: 16 }) { Text(确认删除日记) .fontSize(18) .fontWeight(FontWeight.Bold) Row({ space: 12 }) { Button(取消).onClick(() this.homeStack.pop()) Button(确认).onClick(() { // 删除操作 this.homeStack.pop() }) } } .padding(24) } .mode(NavDestinationMode.DIALOG) .title(提示) }五、标题栏控制5.1 标题栏样式NavDestination() { PetProfilePage() } .title(宠物档案) // 标题栏默认包含返回按钮 标题文字5.2 隐藏标题栏// 首页 Tab 的 Navigation 隐藏了标题栏 Navigation(this.homeStack) { HomePage({...}) } .hideTitleBar(true) // 隐藏标题栏 .navDestination(this.HomeNavDestinations) // 子页面使用 NavDestination 自身的标题栏 // 在 NavDestination 中不设置 hideTitleBar继承 Navigation 设置5.3 标题栏显示策略页面Navigation hideTitleBarNavDestination 标题最终效果首页true—无标题栏宠物档案true继承宠物档案显示标题栏成长时间轴true继承成长时间轴显示标题栏发现true继承发现显示标题栏六、返回按钮处理6.1 默认返回行为NavDestination 的标题栏会自动显示返回按钮‹点击后执行NavPathStack.pop()返回上一页。6.2 自定义返回NavDestination() { PetProfilePage() } .title(宠物档案) .onBackClick(() { // 自定义返回逻辑 console.log(Custom back click) // 可以在这里执行保存、确认等操作 this.homeStack.pop() // 最后调用 pop 返回 })6.3 禁用返回// 禁用返回按钮通过隐藏标题栏实现 NavDestination() { PetProfilePage() } .hideTitleBar(true) // 隐藏标题栏同时隐藏返回按钮七、页面参数传递7.1 接收参数// 在 NavDestination 中获取传递的参数 Builder PetProfileNavDestination() { NavDestination() { // 通过 NavPathStack 的 getParamByName 获取参数 PetProfilePage() } .title(宠物档案) .onReady(() { // 获取当前页面的参数 const params this.homeStack.getParamByName(petProfile) console.log(Received params:, params) }) }7.2 参数传递实践// 发起跳转时传递参数 this.homeStack.pushPath({ name: petProfile, param: { petId: 123, petName: 豆豆 } }) // 在目标页面中通过 NavPathStack 获取参数 aboutToAppear(): void { // 页面可以通过 State 或 prop 接收参数 // 父组件在 NavDestination 中直接传入 }八、NavDestination 生命周期8.1 生命周期回调Builder HomeNavDestinations() { NavDestination() { PetProfilePage() } .title(宠物档案) .onReady(() { // 页面准备就绪已渲染完成 console.log(NavDestination ready) }) .onShown(() { // 页面显示时每次回到该页面触发 console.log(NavDestination shown) }) .onHidden(() { // 页面隐藏时切换到其他页面 console.log(NavDestination hidden) }) }8.2 生命周期对比回调触发时机触发次数onReady页面首次渲染完成仅一次onShown页面每次显示包括首次每次显示onHidden页面每次隐藏每次隐藏九、与 router 跳转的对比9.1 两种路由方式对比维度Navigation NavDestinationrouter.pushUrl导航栏自动管理标题栏和返回按钮需手动布局页面栈NavPathStack 统一管理全局页面栈转场动画内置淡入淡出需自定义动画参数传递通过 pushPath 的 param通过 router 的 params状态保持栈内页面保持状态页面销毁重建9.2 萌宠日记的选择场景使用方式原因闪屏 → 主页router.pushUrl全局跳转非 Navigation 体系Tab 内子页面NavPathStack.pushPath独立的导航栈管理普通页面跳转NavPathStack.pushPath自动管理标题栏十、最佳实践10.1 NavDestination 设计规范每个 Navigation 绑定一个Builder该 Builder 中包含该 Tab 的所有子页面子页面命名与pushPath的name保持一致使用title属性设置导航栏标题需要自定义返回逻辑时使用onBackClick在onShown中刷新页面数据10.2 常见问题问题原因解决方案页面跳转后不显示 NavDestinationBuilder 中未注册对应的 NavDestination检查pushPath的 name 与 NavDestination 是否匹配导航栏标题不显示title 属性未设置添加.title(标题)返回按钮不显示hideTitleBar 设置为 true设置hideTitleBar(false)自定义返回逻辑不生效onBackClick 未正确绑定检查 onBackClick 回调函数总结本文从萌宠日记的NavDestination使用出发深入解析了子页面路由的完整实现组件定位Navigation 导航体系中的目标页面容器Builder 注册通过 navDestination 属性绑定构建函数核心属性title、hideTitleBar、mode、onBackClick两种模式STANDARD 全屏模式、DIALOG 弹窗模式标题栏控制显示/隐藏标题栏、返回按钮处理参数传递通过 pushPath 传递参数NavDestination 中接收生命周期onReady、onShown、onHidden 回调与 router 对比Navigation 体系更适合复杂页面导航NavDestination 与 Navigation、NavPathStack 共同构成了 HarmonyOS 强大的导航体系掌握这三者的配合使用是构建复杂多页面应用的基础。下一篇我们将深入Tab 切换状态保持与页面缓存解析 Tab 切换时页面的状态保持机制。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源NavDestination 组件https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-navdestinationNavigation 组件https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-navigationBuilder 装饰器https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-builder页面路由开发指导https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-routingNavPathStack 开发指导https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-navigation-navigation页面转场动画https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-page-transition应用导航设计https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/design-navigationTabs 组件与 Navigation 结合https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/tabs-navigation
HarmonyOS应用开发实战：萌宠日记 - 子页面路由实现
HarmonyOS应用开发实战萌宠日记 - 子页面路由实现前言NavDestination是 HarmonyOS 中与Navigation组件配套使用的子页面容器它负责渲染通过NavPathStack.pushPath()跳转到的目标页面。在萌宠日记中我们通过 NavDestination 实现了宠物档案、成长时间轴、社区发现、相册、提醒事项等子页面的路由注册。本文将从萌宠日记的 NavDestination 使用出发深入解析子页面路由的原理、Builder 注册方式、页面生命周期和配置技巧。一、NavDestination 概述1.1 组件定位NavDestination 是 Navigation 导航体系中的目标页面容器当通过NavPathStack.pushPath({ name: xxx })跳转时Navigation 会自动查找并渲染对应名称的 NavDestination。组件角色说明Navigation导航容器管理导航栏、页面栈、转场动画NavPathStack导航栈管理页面路径栈NavDestination目标页面渲染跳转到的页面内容1.2 萌宠日记的 NavDestination 注册// Index.ets — 三个 Tab 的 NavDestination 注册 Builder HomeNavDestinations() { NavDestination() { PetProfilePage() }.title(宠物档案) NavDestination() { GrowthTimelinePage() }.title(成长时间轴) NavDestination() { CommunityPage() }.title(发现) } Builder DiaryNavDestinations() { NavDestination() { WriteDiaryPage() }.title(写日记) } Builder RecordNavDestinations() { NavDestination() { AlbumPage() }.title(相册) NavDestination() { ReminderPage() }.title(提醒事项) }提示NavDestination 通过Builder构建函数注册Navigation 通过navDestination属性引用该构建函数。每个Builder中可以包含多个NavDestinationNavigation 会根据pushPath的name参数自动匹配对应的 NavDestination。二、NavDestination 与 Builder 的绑定2.1 绑定方式// Navigation 组件上绑定 navDestination 属性 Navigation(this.homeStack) { HomePage({...}) } .hideTitleBar(true) .navDestination(this.HomeNavDestinations) // 绑定 Builder 构建函数2.2 匹配机制用户调用: this.homeStack.pushPath({ name: petProfile }) ↓ Navigation 在当前绑定的 Builder 中查找 name 为 petProfile 的 NavDestination ↓ 匹配到 HomeNavDestinations 中的 NavDestination { PetProfilePage() } ↓ 渲染 PetProfilePage 并显示导航栏标题宠物档案2.3 匹配规则匹配方式说明示例name 匹配通过 NavDestination 的 name 属性匹配NavDestination().name(petProfile)默认匹配未指定 name 时按 NavDestination 声明顺序匹配按 Builder 中的顺序三、NavDestination 的核心属性3.1 title 属性NavDestination() { PetProfilePage() } .title(宠物档案) // 导航栏标题title属性控制导航栏左侧显示的标题文字属性值效果title宠物档案显示标题文字title支持资源引用$r(app.string.pet_profile)3.2 其他常用属性NavDestination() { PetProfilePage() } .title(宠物档案) .hideTitleBar(false) // 是否隐藏标题栏 .mode(NavDestinationMode.STANDARD) // 页面模式 .onBackClick(() { // 自定义返回按钮点击事件 console.log(Back clicked) })属性类型说明默认值titlestring导航栏标题—hideTitleBarboolean是否隐藏标题栏falsemodeNavDestinationMode页面模式STANDARDonBackClick回调返回按钮点击事件默认出栈四、NavDestination 的模式4.1 两种模式// 标准模式默认 NavDestination() .mode(NavDestinationMode.STANDARD) // 弹窗模式 NavDestination() .mode(NavDestinationMode.DIALOG)模式说明适用场景STANDARD全屏页面占用整个 Navigation 区域默认页面跳转DIALOG弹窗样式背景半透明确认框、选择器、临时操作4.2 DIALOG 模式的应用// 弹窗模式的 NavDestination 示例 Builder DialogDestinations() { NavDestination() { Column({ space: 16 }) { Text(确认删除日记) .fontSize(18) .fontWeight(FontWeight.Bold) Row({ space: 12 }) { Button(取消).onClick(() this.homeStack.pop()) Button(确认).onClick(() { // 删除操作 this.homeStack.pop() }) } } .padding(24) } .mode(NavDestinationMode.DIALOG) .title(提示) }五、标题栏控制5.1 标题栏样式NavDestination() { PetProfilePage() } .title(宠物档案) // 标题栏默认包含返回按钮 标题文字5.2 隐藏标题栏// 首页 Tab 的 Navigation 隐藏了标题栏 Navigation(this.homeStack) { HomePage({...}) } .hideTitleBar(true) // 隐藏标题栏 .navDestination(this.HomeNavDestinations) // 子页面使用 NavDestination 自身的标题栏 // 在 NavDestination 中不设置 hideTitleBar继承 Navigation 设置5.3 标题栏显示策略页面Navigation hideTitleBarNavDestination 标题最终效果首页true—无标题栏宠物档案true继承宠物档案显示标题栏成长时间轴true继承成长时间轴显示标题栏发现true继承发现显示标题栏六、返回按钮处理6.1 默认返回行为NavDestination 的标题栏会自动显示返回按钮‹点击后执行NavPathStack.pop()返回上一页。6.2 自定义返回NavDestination() { PetProfilePage() } .title(宠物档案) .onBackClick(() { // 自定义返回逻辑 console.log(Custom back click) // 可以在这里执行保存、确认等操作 this.homeStack.pop() // 最后调用 pop 返回 })6.3 禁用返回// 禁用返回按钮通过隐藏标题栏实现 NavDestination() { PetProfilePage() } .hideTitleBar(true) // 隐藏标题栏同时隐藏返回按钮七、页面参数传递7.1 接收参数// 在 NavDestination 中获取传递的参数 Builder PetProfileNavDestination() { NavDestination() { // 通过 NavPathStack 的 getParamByName 获取参数 PetProfilePage() } .title(宠物档案) .onReady(() { // 获取当前页面的参数 const params this.homeStack.getParamByName(petProfile) console.log(Received params:, params) }) }7.2 参数传递实践// 发起跳转时传递参数 this.homeStack.pushPath({ name: petProfile, param: { petId: 123, petName: 豆豆 } }) // 在目标页面中通过 NavPathStack 获取参数 aboutToAppear(): void { // 页面可以通过 State 或 prop 接收参数 // 父组件在 NavDestination 中直接传入 }八、NavDestination 生命周期8.1 生命周期回调Builder HomeNavDestinations() { NavDestination() { PetProfilePage() } .title(宠物档案) .onReady(() { // 页面准备就绪已渲染完成 console.log(NavDestination ready) }) .onShown(() { // 页面显示时每次回到该页面触发 console.log(NavDestination shown) }) .onHidden(() { // 页面隐藏时切换到其他页面 console.log(NavDestination hidden) }) }8.2 生命周期对比回调触发时机触发次数onReady页面首次渲染完成仅一次onShown页面每次显示包括首次每次显示onHidden页面每次隐藏每次隐藏九、与 router 跳转的对比9.1 两种路由方式对比维度Navigation NavDestinationrouter.pushUrl导航栏自动管理标题栏和返回按钮需手动布局页面栈NavPathStack 统一管理全局页面栈转场动画内置淡入淡出需自定义动画参数传递通过 pushPath 的 param通过 router 的 params状态保持栈内页面保持状态页面销毁重建9.2 萌宠日记的选择场景使用方式原因闪屏 → 主页router.pushUrl全局跳转非 Navigation 体系Tab 内子页面NavPathStack.pushPath独立的导航栈管理普通页面跳转NavPathStack.pushPath自动管理标题栏十、最佳实践10.1 NavDestination 设计规范每个 Navigation 绑定一个Builder该 Builder 中包含该 Tab 的所有子页面子页面命名与pushPath的name保持一致使用title属性设置导航栏标题需要自定义返回逻辑时使用onBackClick在onShown中刷新页面数据10.2 常见问题问题原因解决方案页面跳转后不显示 NavDestinationBuilder 中未注册对应的 NavDestination检查pushPath的 name 与 NavDestination 是否匹配导航栏标题不显示title 属性未设置添加.title(标题)返回按钮不显示hideTitleBar 设置为 true设置hideTitleBar(false)自定义返回逻辑不生效onBackClick 未正确绑定检查 onBackClick 回调函数总结本文从萌宠日记的NavDestination使用出发深入解析了子页面路由的完整实现组件定位Navigation 导航体系中的目标页面容器Builder 注册通过 navDestination 属性绑定构建函数核心属性title、hideTitleBar、mode、onBackClick两种模式STANDARD 全屏模式、DIALOG 弹窗模式标题栏控制显示/隐藏标题栏、返回按钮处理参数传递通过 pushPath 传递参数NavDestination 中接收生命周期onReady、onShown、onHidden 回调与 router 对比Navigation 体系更适合复杂页面导航NavDestination 与 Navigation、NavPathStack 共同构成了 HarmonyOS 强大的导航体系掌握这三者的配合使用是构建复杂多页面应用的基础。下一篇我们将深入Tab 切换状态保持与页面缓存解析 Tab 切换时页面的状态保持机制。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源NavDestination 组件https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-navdestinationNavigation 组件https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-navigationBuilder 装饰器https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-builder页面路由开发指导https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-routingNavPathStack 开发指导https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-navigation-navigation页面转场动画https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-page-transition应用导航设计https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/design-navigationTabs 组件与 Navigation 结合https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/tabs-navigation
