当前位置： 首页 > news >正文

HarmonyOS 6.1 实战：Navigation 路由组件全面解析

news 2026/7/22 16:08:24

前言

Navigation是 HarmonyOS ArkUI 6.x 推荐的页面导航框架，取代传统的router.push/pop模式，实现组件内路由管理。它内置 AppBar（顶部导航栏）、ToolBar（底部工具栏）、侧边导航等能力，并通过NavPathStack管理路由栈。本文完整演示从列表页到详情页的路由跳转实现。

运行效果

初始状态（列表页）

点击条目进入详情页

核心 API 一览

API说明
Navigation(pathStack)导航根容器，绑定路由栈
NavPathStack路由栈管理器，控制页面的 push/pop
NavDestination路由目标页面容器，类似 Destination
.navDestination(builder)注册路由表：名称 → 组件的映射
.title(string/CustomBuilder)AppBar 标题，支持自定义
.mode(NavigationMode)导航模式：Stack / Split / Auto
.toolbarConfiguration([])底部工具栏配置
pathStack.pushPathByName(name, param)按名称跳转
pathStack.pop()返回上一页
pathStack.popToRoot()返回根页

完整示例代码

interface ArticleItem { id: number title: string summary: string content: string author: string time: string icon: string tag: string readTime: string } // 路由参数结构 interface ArticleParam { articleId: number } @Entry @Component struct Index { private pathStack: NavPathStack = new NavPathStack() private articles: ArticleItem[] = [ { id: 1, icon: '📐', tag: '布局', title: 'Stack 层叠布局与 Overlay 浮层详解', summary: '深入理解 alignContent 九宫格、zIndex 层叠顺序与 overlay 浮层实战。', content: 'Stack 是 ArkUI 中实现层叠布局的核心容器...', author: '鸿蒙开发者', time: '2分钟前', readTime: '8分钟' }, { id: 2, icon: '📋', tag: '列表', title: 'List 高性能长列表与分组吸顶实战', summary: '虚拟化渲染原理、ListItemGroup 分组、sticky 吸顶的完整实现。', content: 'List 是 ArkUI 中专为长列表场景设计的容器...', author: '鸿蒙开发者', time: '1小时前', readTime: '10分钟' }, { id: 3, icon: '🎠', tag: '轮播', title: 'Swiper 轮播图与页面滑动完整指南', summary: 'DotIndicator 自定义样式、SwiperController 编程翻页、卡片流预览效果。', content: 'Swiper 是 ArkUI 专为轮播图和画廊设计的滑动容器...', author: '鸿蒙开发者', time: '3小时前', readTime: '7分钟' }, { id: 4, icon: '📑', tag: '导航', title: 'Tabs 标签页布局：底部导航到顶部分类', summary: '底部导航栏实现、嵌套 Tabs、自定义 TabBar 样式完整示例。', content: 'Tabs 是 ArkUI 中实现标签页导航的专用组件...', author: '鸿蒙开发者', time: '昨天', readTime: '9分钟' }, { id: 5, icon: '🗂', tag: '侧边栏', title: 'SideBarContainer 侧边导航：大屏双栏布局实战', summary: 'Embed vs Overlay 模式、autoHide 自适应、自定义汉堡菜单。', content: 'SideBarContainer 是 ArkUI 专为平板大屏设计的导航容器...', author: '鸿蒙开发者', time: '2天前', readTime: '11分钟' }, ] // 路由表：名称 → 页面 Builder 的映射 @Builder pageMap(name: string, param: ESObject) { if (name === 'detail') { ArticleDetailPage({ pathStack: this.pathStack, articleId: (param as ArticleParam).articleId, articles: this.articles }) } } @Builder listItem(article: ArticleItem) { Row({ space: 12 }) { Text(article.icon) .fontSize(24) .width(48).height(48) .textAlign(TextAlign.Center) .backgroundColor('#f0f5ff') .borderRadius(12) Column({ space: 4 }) { Text(article.title) .fontSize(14) .fontWeight(FontWeight.Medium) .fontColor('#1a1a1a') .maxLines(2) .textOverflow({ overflow: TextOverflow.Ellipsis }) Row({ space: 8 }) { Text(article.tag) .fontSize(11) .fontColor('#0066ff') .backgroundColor('#f0f5ff') .padding({ left: 6, right: 6, top: 2, bottom: 2 }) .borderRadius(4) Text(article.time).fontSize(11).fontColor('#aaa') Text(article.readTime + ' 阅读').fontSize(11).fontColor('#bbb') } } .layoutWeight(1) .alignItems(HorizontalAlign.Start) } .width('100%') .padding({ left: 16, right: 16, top: 14, bottom: 14 }) .backgroundColor('#ffffff') .border({ width: { bottom: 1 }, color: '#f5f5f5' }) .onClick(() => { // push 到详情页，传递参数 this.pathStack.pushPathByName('detail', { articleId: article.id } as ArticleParam) }) } build() { Navigation(this.pathStack) { // 列表页（根页面） Column({ space: 0 }) { // 搜索栏 Row({ space: 8 }) { Text('🔍').fontSize(16).fontColor('#888') Text('搜索文章...') .fontSize(14).fontColor('#bbb').layoutWeight(1) } .width('100%') .height(40) .padding({ left: 14, right: 14 }) .backgroundColor('#f5f5f5') .borderRadius(20) .margin({ left: 16, right: 16, top: 8, bottom: 4 }) // 文章列表 List() { ForEach(this.articles, (article: ArticleItem) => { ListItem() { this.listItem(article) } }) } .divider({ strokeWidth: 1, color: '#f8f8f8', startMargin: 76 }) .layoutWeight(1) .backgroundColor('#f8f8f8') } .width('100%') .height('100%') } .title('HarmonyOS 学习笔记') .navDestination(this.pageMap) .mode(NavigationMode.Stack) .titleMode(NavigationTitleMode.Mini) .toolbarConfiguration([ { value: '首页', icon: $r('sys.media.ohos_ic_public_home') }, { value: '设置', icon: $r('sys.media.ohos_ic_public_settings') }, ]) .width('100%') .height('100%') .backgroundColor('#f8f8f8') } } // ── 详情页组件 ── @Component struct ArticleDetailPage { pathStack: NavPathStack = new NavPathStack() articleId: number = 0 articles: ArticleItem[] = [] private getArticle(): ArticleItem { for (let i = 0; i < this.articles.length; i++) { if (this.articles[i].id === this.articleId) { return this.articles[i] } } return this.articles[0] } build() { NavDestination() { Scroll() { Column({ space: 16 }) { // 头部卡片 Column({ space: 12 }) { Text(this.getArticle().icon).fontSize(48) Text(this.getArticle().tag) .fontSize(12).fontColor('#0066ff') .backgroundColor('#f0f5ff') .padding({ left: 10, right: 10, top: 3, bottom: 3 }) .borderRadius(10) Text(this.getArticle().title) .fontSize(20).fontWeight(FontWeight.Bold).fontColor('#111').lineHeight(28) Row({ space: 12 }) { Text(this.getArticle().author).fontSize(13).fontColor('#888') Text(this.getArticle().time).fontSize(13).fontColor('#aaa') Text(this.getArticle().readTime + ' 阅读').fontSize(13).fontColor('#aaa') } } .width('100%').padding(20) .backgroundColor('#fff').borderRadius(12) .border({ width: 1, color: '#f0f0f0' }) .alignItems(HorizontalAlign.Center) // 摘要 Column({ space: 8 }) { Text('📌 摘要') .fontSize(15).fontWeight(FontWeight.Bold).fontColor('#333') Text(this.getArticle().summary) .fontSize(14).fontColor('#666').lineHeight(22) } .width('100%').padding(16) .backgroundColor('#fff').borderRadius(12) .border({ width: 1, color: '#f0f0f0' }) .alignItems(HorizontalAlign.Start) // 正文 Column({ space: 10 }) { Text('📖 正文').fontSize(15).fontWeight(FontWeight.Bold).fontColor('#333') Text(this.getArticle().content + '更多内容持续撰写中，欢迎关注本系列教程。') .fontSize(14).fontColor('#555').lineHeight(22) } .width('100%').padding(16) .backgroundColor('#fff').borderRadius(12) .border({ width: 1, color: '#f0f0f0' }) .alignItems(HorizontalAlign.Start) Column().height(20) } .width('100%').padding({ left: 16, right: 16, top: 16, bottom: 16 }) } .width('100%').height('100%') } .title(this.getArticle().title) .backButtonIcon($r('sys.media.ohos_ic_back')) .onBackPressed(() => { this.pathStack.pop() return true }) } }

关键知识点

1. NavPathStack 是路由核心

private pathStack: NavPathStack = new NavPathStack() // push：跳转到目标页，传参 this.pathStack.pushPathByName('detail', { id: 1 }) // pop：返回上一页 this.pathStack.pop() // popToRoot：返回到根页 this.pathStack.popToRoot() // 获取当前路由栈深度 this.pathStack.size()

2. navDestination：注册路由表

@Builder pageMap(name: string, param: ESObject) { if (name === 'detail') { DetailPage({ pathStack: this.pathStack, id: (param as MyParam).id }) } } Navigation(this.pathStack) .navDestination(this.pageMap) // 传入路由表 Builder

3. NavDestination：目标页面容器

每个目标页面必须用NavDestination包裹，它提供 AppBar、返回按钮等：

@Component struct DetailPage { pathStack: NavPathStack = new NavPathStack() build() { NavDestination() { // 页面内容 } .title('详情页') .onBackPressed(() => { this.pathStack.pop() return true // 返回 true 表示拦截了系统返回，由自己处理 }) } }

4. NavigationMode 三种模式

模式效果适用场景
NavigationMode.Stack全屏堆叠（手机）手机应用
NavigationMode.Split左右分栏（平板）平板大屏
NavigationMode.Auto根据屏幕宽度自适应通用（推荐）

5. 参数传递

pushPathByName的第二个参数类型是ESObject（等同于object），接收方需要做类型断言：

// 推送方 this.pathStack.pushPathByName('detail', { articleId: 1 } as ArticleParam) // 接收方（NavDestination 对应的组件属性） articleId: number = 0 // 由 Navigation 框架注入

小结

  • Navigation是 HarmonyOS 推荐的组件内路由方案，比router.push更灵活
  • NavPathStack管理路由栈，pushPathByName/pop/popToRoot是核心操作
  • navDestination(@Builder)注册路由表，建立名称到组件的映射
  • 目标页必须用NavDestination包裹，并在onBackPressed中调用pop()
  • NavigationMode.Auto自动在手机（Stack）和平板（Split）之间切换，是最佳实践
http://www.jsqmd.com/news/1242144/

相关文章：

  • 麒麟信安“一云多芯”解决方案，助力传统IT架构变革转型
  • HDI综合效益优势-平衡小型化、迭代效率与长期量产成本
  • VirtualLab Fusion中的光学各向异性介质
  • Java面试之Linux和docker
  • TikTok广告投放多少钱？2026年最新投放成本与防关联指南
  • Instagram新功能倾向创作者，普通用户与创作者需求如何平衡？
  • [SPI]SPI接口简介
  • SARS-CoV-2病毒：从分子结构到全球大流行的全面解析
  • 嵌入式系统ROM代码执行与片上调试全解析：从启动到调试的底层实践
  • Cortex-M4系统控制与异常处理寄存器深度解析：从原理到实战
  • 绿幕发灰、边缘闪烁、头发丝丢失？Runway抠像失败的7个隐性参数陷阱，今天必须改！
  • 官宣，麒麟信安服务器操作系统V3.4-5正式发布
  • SATA控制器架构深度解析：从AHCI原理到嵌入式开发实践
  • PS5 NOR Modifier：终极方案解析，如何修复损坏的PS5 NOR闪存文件
  • 【AI副业口碑裂变公式】：3个被低估的传播杠杆，90%从业者从未用过
  • 大气湍流下的少模光纤耦合
  • HarmonyOS 6.1 实战：GridRow/GridCol 响应式栅格布局详解
  • 2026留学生找工作平台评测：靠谱平台推荐与选型攻略 - 极欧测评
  • torch.distributed的通信原语选择：all_reduce、all_gather与reduce_scatter
  • Orin 上开机自启跑检测docker容器（含完整脚本）
  • TMS320C6424 DSP外设实战：PWM、VLYNQ、GPIO与JTAG深度配置指南
  • 代码不是 AI 编程的最终资产，AI Coding 真正该存的是 Checkpoint
  • 深入解析C2000 SCI模块：中断、DMA与低功耗模式实战指南
  • 鸿蒙Flutter push与pop操作：页面跳转与返回基本操作
  • 浅谈 MySQL 主从复制，优点？原理？
  • HarmonyOS应用开发实战：萌宠日记 - 活动横幅卡片设计
  • html之flex伸缩盒子；grid布局
  • WinForm集成PDF功能的技术方案与优化实践
  • 闲置贵金属无锡出手，选择合扬鉴定专业有资质 - 好物测评局
  • OptiFDTD应用：光栅耦合器