鸿蒙实战导航栏与顶部栏设计规范 HmTitleBar前言必读图鸿蒙实战导航栏与顶部栏设计规范 HmTitleBar第 71 篇 运行效果截图HarmonyOS NEXT导航栏是用户感知页面结构的「路标」。遵循 HarmonyOS Design 大标题栏设计规范本项目将导航栏封装为可复用的HmTitleBar组件统一管理所有页面的标题、返回按钮和右侧操作按钮。本文从规范到实现逐层解析。图HmTitleBar 组件结构——左侧返回按钮 居中标题 右侧操作区的三区域设计HmTitleBar 组件左侧区域居中标题右侧操作区返回图标按钮带文字返回键主标题 Text主副标题组合单个操作图标多个操作图标文字操作按钮一、HarmonyOS 大标题栏设计规范HarmonyOS Design 对大标题栏Large Title Bar的定义如下规范项值本项目映射标题字号28fpAppFonts.TITLE_L 28标题字重MediumAppFonts.W_MEDIUM标题颜色Text PrimaryAppColors.TEXT标题对齐左对齐HorizontalAlign.Start副标题字号12fpAppFonts.CAPTION 12副标题颜色Text TertiaryAppColors.TEXT_2纵向间距4-8vpAppSpacing.XXS 4左右边距20vpAppSpacing.L 20右侧操作区域24-44vpImage(24) / Text(18)返回按钮可选←Text 元素二、HmTitleBar 组件实现2.1 完整源码// 文件common/components/HmTitleBar.etsComponentexportstruct HmTitleBar{Proptitle:string// 标题文字Propsubtitle:string// 副标题可选PropshowBack:booleanfalse// 是否显示返回按钮PropactionIcon:Resource|nullnull// 右侧图标按钮可选PropactionText:string// 右侧文字按钮可选onAction?:()void// 操作按钮回调onBack?:()void// 返回按钮回调StatesubtitleOpacity:number0// 副标题入场动画aboutToAppear():void{// 副标题淡入动画animateTo({duration:500,curve:Curve.FastOutSlowIn},(){this.subtitleOpacity1})}build(){Row(){// ─── 左区返回按钮可选 ───if(this.showBack){Text(←).fontSize(20).fontColor(AppColors.TEXT).padding({left:0,right:10}).onClick((){if(this.onBack){this.onBack()}else{this.getUIContext().getRouter().back()}})}// ─── 中区标题 副标题 ───Column(){Text(this.title).fontSize(AppFonts.TITLE_L)// 28fp.fontWeight(AppFonts.W_MEDIUM)// Medium.fontColor(AppColors.TEXT).letterSpacing(0.5)if(this.subtitlethis.subtitle.length0){Text(this.subtitle).fontSize(AppFonts.CAPTION)// 12fp.fontColor(AppColors.TEXT_2).margin({top:AppSpacing.XXS})// 4px 间距.letterSpacing(1).opacity(this.subtitleOpacity)// 淡入动画}}.alignItems(HorizontalAlign.Start).layoutWeight(1)// ─── 右区操作按钮图标 / 文字二选一 ───if(this.actionIcon){Image(this.actionIcon).width(24).height(24).fillColor(AppColors.TEXT_2).onClick(()this.onAction?.())}if(this.actionText.length0){Text(this.actionText).fontSize(18).fontColor(AppColors.TEXT_2).onClick(()this.onAction?.())}}.width(100%).padding({left:AppSpacing.L,// 20pxright:AppSpacing.L,// 20pxtop:AppSpacing.XS,// 8pxbottom:AppSpacing.M// 16px})}}2.2 组件布局示意┌────────────────────────────────────┐ │ ← 笔迹分析报告 │ ← 有返回 图标操作 │ 2026年6月 · 共 3 段书写 │ │ │ └────────────────────────────────────┘ ┌────────────────────────────────────┐ │ 情绪趋势 设置 │ ← 无返回 文字操作 │ │ └────────────────────────────────────┘ ┌────────────────────────────────────┐ │ 合盘报告 │ ← 无返回 无操作 │ 鹿鹿 × 茂茂 · 第 87 天 │ │ │ └────────────────────────────────────┘三、组件 Props 详解3.1 Props 配置表Prop类型默认值说明必填titlestring标题文字✅ 必填subtitlestring副标题空则不显示❌ 可选showBackbooleanfalse是否显示返回按钮❌ 可选actionIconResource | nullnull右侧图标按钮❌ 可选actionTextstring右侧文字按钮❌ 可选3.2 回调Callback参数说明默认行为onAction() void右侧操作按钮点击无需实现onBack() void返回按钮点击router.back()四、各页面使用实例4.1 DuetReportPage合盘报告 · 有返回 副标题// DuetReportPage.etsHmTitleBar({title:合盘报告,subtitle:鹿鹿 ×${this.partnerName}· 第${this.daysTogether}天,showBack:true})4.2 ReportDetailPage分析详情 · 有返回// ReportDetailPage.etsHmTitleBar({title:笔迹分析报告,showBack:true})4.3 ArchivePage档案页 · 无返回// ArchivePage.etsHmTitleBar({title:笔迹档案,subtitle:${this.recordCount}段书写 ·${this.dayCount}天})4.4 TrendPage趋势页 · 带操作按钮// TrendPage.etsHmTitleBar({title:情绪趋势,subtitle:最近 30 天 · 6 维度,actionText:设置,onAction:()this.openSettings()})五、设计规范对照5.1 HarmonyOS Design 规范适配HarmonyOS 大标题栏规范 ┌──────────────────────────────────┐ │ 28fp Medium │ 操作区 24vp │ │ 文字 Primary │ 可选的图标 │ │ │ │ │ 12fp 副标题 │ │ │ 上边距 4vp │ │ └──────────────────────────────────┘ ← 20vp 边距 → ← 20vp 边距 → 本项目 HmTitleBar ✅ 标题 28fp Medium → 完全符合 ✅ 副标题 12fp 4vp 间距 ✅ 左右边距 20vp ✅ 操作区域 24/24 或 18fp 文字 ✅ 左对齐 → 符合阅读习惯5.2 返回按钮设计Text(←)// 使用文本符号而非图片图标.fontSize(20)// 20fp 与原标题协调.fontColor(AppColors.TEXT).padding({left:0,right:10})方案优点缺点文本←零资源文件、零网络请求、颜色自适应无 hover 状态Image SVG可自定义需要资源文件系统返回统一无法自定义样式本项目选择文本方案因代码极简且与整体字体风格一致。六、与 HarmonyOSNavigation组件的对比对比维度HmTitleBar自定义Navigation系统组件灵活性⭐⭐⭐⭐⭐ 完全自定义⭐⭐⭐ 固定布局代码量80 行组件0 行声明即用标题动画✅ 副标题淡入❌右侧操作区✅ icon / text 二选一✅ 支持返回按钮✅ 默认 router.back()✅ 自动路由集成需外部传递自动感知 NavPathStack本项目选择✅ 已使用❌ 项目结构更简单Navigation组件在 API 12 提供了路由感知的能力但在本项目早期采用了HmTitleBarrouter的架构已足够满足需求。七、设计原则原则 1每页都有明确的标题// ❌ 无标题栏Column(){...}// ✅ 有 HmTitleBarColumn(){HmTitleBar({title:笔迹分析报告,showBack:true})// ... 页面内容}原则 2副标题提供上下文副标题不是装饰它告诉用户「你在哪里」「有什么数据」笔迹分析报告 ← 标题页面名称 2026年6月 · 共 3 段 ← 副标题上下文数据原则 3操作按钮不超过 1 个右侧操作区建议放最重要的操作设置/筛选/分享避免拥挤。八、未来扩展// 未来可扩展搜索模式Componentexportstruct HmTitleBar{PropshowSearch:booleanfalseStateisSearching:booleanfalsebuild(){if(this.isSearching){// 替代为搜索输入框Search({placeholder:搜索笔迹...}).width(100%)}else{// 标准大标题栏}}}九、注意事项与常见问题9.1 开发注意事项在正式开发前建议按以下步骤完成环境准备与前置检查版本确认检查 DevEco Studio 与 SDK 版本确保满足目标 API Level 要求权限声明在module.json5的requestPermissions字段中提前声明所有需要的系统权限设备能力检查调用前验证设备是否支持目标能力相机、NFC、传感器等异步封装所有耗时操作数据库、文件 I/O、网络请求统一使用async/await处理资源释放在组件aboutToDisappear()生命周期钩子中及时释放系统资源防止内存泄漏9.2 常见错误与解决方案常见问题快速排查表问题类型排查方向参考方法应用崩溃查看 hilog 错误日志hilog.error(TAG, ..., e.message)状态丢失检查 AppStorage 键名拼写统一使用常量管理键名动画不流畅避免在 animateTo 回调中执行 I/O动画与数据操作分离总结✅HmTitleBar 组件80 行代码管理全应用所有页面的导航栏✅HarmonyOS Design 规范28fp 标题 12fp 副标题 20vp 边距✅三区布局左返回 中标题 右操作灵活配置✅Props 系统title / subtitle / showBack / actionIcon / actionText✅副标题淡入动画500ms FastOutSlowIn 提升页面过渡质感✅各页面实例DuetReportPage / ReportDetailPage / ArchivePage / TrendPage✅与 Navigation 对比自定义方案更灵活适合中小型项目至此第十一模块「主题系统与设计令牌第 67-71 篇」全部完成共覆盖AppColors 颜色体系、AppFonts 排版规范、线性渐变、阴影系统、HmTitleBar 导航栏。下一篇将进入第十二模块「状态管理与全局数据」讲解 AppStorage 全局状态管理、State 本地状态、路由参数传递、getUIContext 上下文获取、以及 Toast 提示反馈。 收藏提示可复用的导航栏组件比每个页面手写导航栏节省 80% 的代码量。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源Navigation 导航组件ToolBar 工具栏标题栏设计规范第67篇 颜色体系第68篇 字体令牌第70篇 阴影系统第99篇 设计模式回顾ArkUI 布局规范七、导航栏的进阶场景7.1 透明渐变导航栏在图片全屏展示页面导航栏需使用半透明背景HmTitleBar({title:报告详情,transparent:true,// 自定义参数bgColor:rgba(250, 248, 244, 0.85)})// 在页面顶部背景图上方叠加通过 Stack 实现7.2 滚动时标题栏动态显示当页面内容向上滚动到一定位置时顶部标题从透明渐变为不透明StatescrollY:number0;Scroll(){Column(){/* 页面内容 */}}.onScroll((x,y){this.scrollYy;})HmTitleBar({title:页面标题,bgOpacity:Math.min(this.scrollY/100,1)// 0→1 渐变透明度})7.3 安全区域适配顶部栏需要适配刘海屏和异形屏的安全区域Row(){/* 标题栏内容 */}.width(100%).height(56).padding({top:px2vp(AppStorage.Getnumber(statusBarHeight)??0)})如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力