Flutter三方库适配OpenHarmony【harmony_ui】导航类控件实战标题栏、子页签、底部页签与轮播前言harmony_ui是 Material/Cupertino 风格的 Flutter 组件库完整实现了HarmonyOS 设计语言覆盖官方「控件概览」的 6 大类 42 个控件并额外实现了沉浸光感材质与 UI Design Kit 增强能力。本系列按官方控件类别逐类实战本篇是第 1 篇导航类。导航类是应用骨架的第一层标题栏OhosAppBar定义页面头部子页签OhosTabBar做页面内切换底部页签OhosNavigationBar做全局导航轮播OhosSwiper与导航点OhosPageIndicator承载首屏内容流。5 个控件全部对齐官方规范且是沉浸光感落点最集中的类别——标题栏、底部页签的光感材质、动态模糊、光池效果都在这里。本系列全部代码都在OpenHarmony 模拟器上直接运行验证Flutter3.47.7-ohos-1.0.1 DevEco Studio26.0.0 Release截图环境API 261280×2832。环境搭建、依赖引入与构建步骤见文首「环境与版本」「安装与引入 harmony_ui」以及第九节仓库地址AtomGit / GitHub。环境与版本本文的示例与截图基于以下环境组合2026-10 实测组件版本说明Flutter SDKOH 适配版3.47.7-ohos-1.0.1oh-flutter/flutter_flutteroh-3.47-dev分支DevEco Studio26.0.0 Release提供 hvigor / ohpm / hdc / JBR 等工具链OpenHarmony SDK / APIAPI 2626.0.0模拟器与 SDK 均为 API 26运行设备OpenHarmony 模拟器API 261280×2832环境搭建分叉获取、DevEco Studio 与 SDK 配置、模拟器创建请按官方指导操作OpenHarmony-flutter 环境搭建指导。harmony_ui是纯 Dart/Flutter 组件库不依赖 ohos 平台通道在官方 Flutter SDK 上也能运行用于跨平台预览。只有跑example/ohos工程、构建 HAP 时才需要上面的 OH 适配版 SDK。安装与引入 harmony_uiharmony_ui已发布到 pub.dev当前最新版本是0.3.0。在应用工程的pubspec.yaml中声明dependencies:flutter:sdk:flutterharmony_ui:^0.3.0然后拉取依赖fvm flutter pub get如果团队需要固定到仓库的某个提交例如使用尚未发版的修复改用 git 依赖dependencies:harmony_ui:git:url:https://atomgit.com/oh-flutter/harmony_ui.gitref:v0.3.0# 固定 tag写 main 则跟随最新提交fvm flutter pub getpub.dev 与 git 两种方式二选一不要同时声明。CI 中建议固定 tag如v0.3.0而不是main避免构建结果随上游漂移。harmony_ui目前只依赖qr一个三方包ohos_icons是可选配套图标包不引入也不影响组件使用。一、导航类总览官方「导航类」共 5 个控件harmony_ui实现如下官方控件实现关键特性标题栏OhosAppBar沉浸光感、动态模糊滚动效果、自动返回键子页签OhosTabBar下划线 24×3vp / 胶囊两种形态、分割线跟手底部页签OhosNavigationBar平铺 48vp / 悬浮 56vp、光池跟随、角标导航点OhosPageIndicator轮播指示点支持自定义颜色尺寸轮播OhosSwiper自动播放、循环、内置指示点使用导航类组件前先用OhosTheme包一层应用根节点所有颜色走主题 Tokenimportpackage:flutter/material.dart;importpackage:harmony_ui/harmony_ui.dart;voidmain()runApp(constMyApp());classMyAppextendsStatelessWidget{constMyApp({super.key});overrideWidgetbuild(BuildContextcontext){returnMaterialApp(home:OhosTheme(data:OhosThemeData.light(),// 或 OhosThemeData.dark()child:constHomePage(),),);}}二、标题栏 OhosAppBar2.1 基础结构OhosAppBar是PreferredSizeWidget可直接传给OhosScaffold.appBar。高度默认56vptitle/leading/actions三区结构OhosScaffold(appBar:OhosAppBar(title:constText(设置),actions:[OhosIconButton(icon:constIcon(Icons.search),onPressed:_onSearch),OhosIconButton(icon:constIcon(Icons.more_horiz),onPressed:_onMore),],),body:constMyBody(),)title任意 Widget通常用OhosText标题字阶leading左侧区域不传且页面可pop时自动插入返回键automaticallyImplyLeading默认 trueactions右侧图标按钮列表推荐 2-3 个图标 24×24vpelevation默认 0鸿蒙风格标题栏不做投影分层层次交给光感材质。2.2 自定义高度与背景height/backgroundColor/scrolledBackgroundColor都开放。沉浸式页面内容延伸到标题栏后面把背景设为透明OhosAppBar(height:64,backgroundColor:Colors.transparent,title:constOhosText(首页,level:OhosTextLevel.headlineMedium),)注意OhosScaffold内部把OhosAppBar与body按 Column 布局v0.1.0 之前是 Stack 叠加导致内容被遮挡已修复。要做内容穿透标题栏的沉浸式效果用scrollEffect动态模糊见 3.2 节而不是自己改 Scaffold 布局。三、沉浸光感标题栏3.1 光感材质 lightMaterial打开lightMaterial: true标题栏背景由不透明色替换为ULTRA_THIN 光感材质8vp sigma 模糊 表面填充 顶部渐变淡出悬浮在内容之上的薄纱效果OhosAppBar(lightMaterial:true,// 默认档位 ultraThinlightLevel:OhosLightMaterialLevel.ultraThin,// 可显式指定五档之一title:constText(首页),actions:const[OhosIconButton(icon:Icon(Icons.more_horiz),onPressed:null),],)3.2 动态模糊 scrollEffectscrollEffect是 UI Design Kit「动态模糊标题栏」能力的实现内容穿透标题栏滚动滚动位移进入blurEffectiveStartOffset ~ blurEffectiveEndOffset区间后模糊背板按进度淡入。三种效果类型OhosAppBar(backgroundColor:Colors.transparent,title:constText(首页),scrollController:_scroller,scrollEffect:constOhosAppBarScrollEffectOptions(effect:OhosAppBarScrollEffectType.commonBlur,blurEffectiveStartOffset:0,// 开始产生模糊的偏移blurEffectiveEndOffset:60,// 模糊达到满值的偏移blurSigma:10,// 模糊强度),scrolledBackgroundColor:Colors.white,)效果类型行为适用场景commonBlur进入区间后常显模糊背板常规内容流页面transitionBlur模糊随滚动进度连续变化沉浸式首屏gradientBlur模糊 渐变蒙层叠加大图头部页面动态模糊标题栏在模拟器上的实机效果滚动后背板淡入动态模糊标题栏内容穿透滚动进入阈值区间后commonBlur背板淡入四、子页签 OhosTabBar4.1 下划线式OhosTabBar与 Flutter 的TabBar一样需要配合TabController/DefaultTabController使用tabs传ListWidget。下划线式默认的指示条严格对齐官方规范24×3vp 品牌色DefaultTabController(length:3,child:Scaffold(body:NestedScrollView(headerSliverBuilder:(_,__)[SliverToBoxAdapter(child:OhosTabBar(tabs:const[Text(推荐),Text(热榜),Text(关注)],type:OhosTabBarType.underline,// 默认值可省略),),],body:constTabBarView(children:[Center(child:Text(推荐页)),Center(child:Text(热榜页)),Center(child:Text(关注页))],),),),)页签可滚动isScrollable: true页签数量多时不换行、横向滑动指示条颜色indicatorColor默认取主题品牌色#0A59F7。4.2 胶囊式胶囊式capsule激活项品牌色实底、未激活项comp_background_gray灰底对齐官方子页签规范OhosTabBar(tabs:const[Text(日),Text(周),Text(月)],type:OhosTabBarType.capsule,height:40,)多选/筛选场景用OhosChipGroup胶囊组合间距默认 8vp官方建议不宜过大OhosChipGroup(items:constOhosChipItem[OhosChipItem(label:Text(全部)),OhosChipItem(label:Text(进行中)),OhosChipItem(label:Text(已完成)),],multiple:true,// 多选模式selectedIndexes:_selected,// 已选索引集合onSelectionChanged:(Setintv)setState(()_selectedv),)导航类组件整体效果沉浸光感标题栏 子页签 ChipGroup 底部页签导航类顶部沉浸光感标题栏中部下划线 胶囊子页签与 ChipGroup底部平铺/悬浮页签胶囊子页签 ChipGroup 多选实机效果胶囊式子页签激活项品牌色实底、未激活灰底ChipGroup 多选筛选五、子页签分割线divider 三模式OhosTabBar通过dividerOhosTabBarDividerOptions控制页签栏下方的分割线三种模式模式行为OhosTabBarDividerMode.visible常显OhosTabBarDividerMode.none常隐OhosTabBarDividerMode.followScroll跟手内容下滑淡入、回顶淡出OhosTabBar(tabs:const[Text(推荐),Text(热榜),Text(关注)],divider:constOhosTabBarDividerOptions(mode:OhosTabBarDividerMode.followScroll,followStartOffset:0,// 开始淡入的滚动偏移followEndOffset:20,// 淡入完成的滚动偏移strokeWidth:1,),scrollController:_scroller,// followScroll 模式必须提供)分割线实机效果visible常显模式子页签分割线常显 / 常隐 / 跟手三种模式提示分割线颜色默认取主题font_fourth20% 黑可用divider.color覆盖startMargin/endMargin可让分割线两端缩进与内容边距对齐。六、底部页签 OhosNavigationBar6.1 平铺式与悬浮式OhosNavigationBar对齐官方底部页签规范平铺式高48vp通栏悬浮式高56vp圆角悬浮条激活项用 20% 品牌色comp_emphasize_secondary填充图标 24×24vp页签数量建议3-5 个形态默认高度外观典型场景tile平铺默认48vp通栏无投影标准应用float悬浮56vp圆角悬浮条 投影配合沉浸光感// 平铺式OhosNavigationBar(currentIndex:_index,onDestinationSelected:(int i)setState(()_indexi),destinations:const[OhosNavigationDestination(icon:Icon(Icons.home_outlined),label:首页),OhosNavigationDestination(icon:Icon(Icons.square_grid_2x2),label:组件),OhosNavigationDestination(icon:Icon(Icons.person_outline),label:我的),],)6.2 双图标与角标每个页签可以配置selectedIcon选中态图标不传则用icon与badge图标角标OhosBadge数字或红点OhosNavigationDestination(icon:constIcon(Icons.person_outline),selectedIcon:constIcon(Icons.person_filled),label:我的,badge:constOhosBadge(count:5),// 数字角标不传 count 为红点)七、光感底部页签与光池悬浮式 lightMaterial: true是导航类的光感重头戏THIN 材质16vp sigma悬浮条彩色光池跟随选中项移动按压时指尖出现光晕OhosNavigationBar(type:OhosNavigationBarType.float,lightMaterial:true,lightLevel:OhosLightMaterialLevel.thin,// 悬浮式默认档位glow:true,// 光池跟随选中项enablePressGlow:true,// 按压触发指尖光斑currentIndex:_index,onDestinationSelected:(int i)setState(()_indexi),destinations:destinations,)光池移动带动画过渡切换页签时光晕平滑滑动而非瞬移按压光斑抬手后自动淡出与OhosGeometry.spring90ms曲线一致光池配色来自OhosLightPalette.glowColors明暗主题自动适配。平铺式与悬浮式底部页签实机对比底部页签上为平铺式48vp 通栏下为悬浮式56vp 圆角悬浮条 光感材质八、轮播 OhosSwiper 与导航点8.1 OhosSwiperOhosSwiper封装了PageView内置自动播放、循环与指示点是首屏 Banner 的主力OhosSwiper(height:180,autoPlay:true,autoPlayInterval:constDuration(seconds:4),loop:true,// 无限循环indicator:true,// 内置导航点默认开启clipRadius:BorderRadius.circular(16),onPageChanged:(int i)setState(()_pagei),children:[OhosImage(image:NetworkImage(https://example.com/a.png),width:double.infinity),OhosImage(image:NetworkImage(https://example.com/b.png),width:double.infinity),OhosImage(image:NetworkImage(https://example.com/c.png),width:double.infinity),],)8.2 OhosPageIndicator需要自定义指示点位置如放在图片外时OhosSwiper(indicator: false)关掉内置点用OhosPageIndicator单独渲染Column(children:[SizedBox(height:180,child:OhosSwiper(indicator:false,children:bannerImages),),constSizedBox(height:12),OhosPageIndicator(count:3,currentIndex:_page,dotSize:8,spacing:6,),],)activeColor/inactiveColor默认取主题色品牌色 / 20% 黑导航点尺寸默认 8vp、间距 6vp与官方规范一致。8.3 导航类常见坑OhosTabBar不传 controller既没有TabController也没有DefaultTabController祖先时会取不到控制器而报错页签页务必用DefaultTabController(length:)包裹轮播图片不圆角OhosImage自带圆角但OhosSwiper翻页切换时会露出直角边缘给OhosSwiper(clipRadius:)传同样的圆角悬浮页签被内容遮挡OhosNavigationBar(type: float)悬浮在内容之上页面底部要留 56vp 安全区的 padding否则最后一行列表会被盖住动态模糊不生效scrollEffect必须同时传scrollController且滚动容器真实使用它backgroundColor设为不透明色时模糊被背景挡住需设透明。九、在鸿蒙模拟器上运行导航类的所有效果光感标题栏、动态模糊、光池都在 gallery 示例应用的「导航」分类页可交互运行。最短运行路径安装3.47.7-ohos-1.0.1的 OH 适配版 SDK。该版本在仓库里是 git tag按 tag 浅克隆到 fvm 版本目录后在工程内切换gitclone--depth1--branch3.47.7-ohos-1.0.1\https://atomgit.com/oh-flutter/flutter_flutter.git\~/fvm/versions/ohos/oh-3.47.7-releasecdharmony_ui 仓库根目录fvm use ohos/oh-3.47.7-release fvm flutter--version# 应输出 Flutter 3.47.7-ohos-1.0.1fvm 的fvm install alias/ref只识别分支名3.47.7-ohos-1.0.1是 tag不能直接 install按上面的方式 clone 到版本目录后fvm use即可。source env.sh加载 DevEco Studio26.0.0 Release的工具链node / ohpm / hvigor / SDK toolchains如果命令不可用按文首的环境搭建指导检查DEVECO_SDK_HOME、JAVA_HOME与hdc进入example/fvm flutter pub get fvm flutter create --platforms ohos .构建并安装到模拟器fvm flutter build hap--debug--no-codesign hdc list targets hdcinstall-rbuild/ohos/hap/entry-default-unsigned.hap hdc shell aa start-aEntryAbility-bcom.example.ohos_ui_example光感效果依赖BackdropFilter模拟器与真机渲染一致若真机上模糊边缘有毛刺优先检查设备 GPU 驱动而非组件参数。十、最佳实践层级唯一一个页面只有一个标题栏actions最多 3 个按钮更多操作收进更多菜单页签数量底部页签 3-5 个子页签 2-5 个超出说明信息架构该拆页了光感节制标题栏 悬浮底部页签同时开光感即可弹层再叠加光感时注意同屏模糊层数量≥3 层时低端机会掉帧动态模糊阈值blurEffectiveEndOffset建议 40-80vp太小模糊感突兀太大几乎看不到选中态图标底部页签务必配selectedIcon线性→面性切换是官方视觉的重要组成部分宽屏适配≥840vp 窗口建议底部页签改侧边页签OhosSideBar见系列第 7 篇增强类导航与反馈联动页签切换失败时配合showOhosToast提示切换成功保持静默——导航层成功不打扰、失败有交代。十一、常见问题 FAQ11.1flutter pub get找不到 harmony_ui先确认版本口径pub.dev 上最新为0.3.0pubspec.yaml写harmony_ui: ^0.3.0若使用 git 依赖检查url/ref是否可达并确认没有同时声明 pub.dev 与 git 两份依赖。改完后执行fvm flutter clean fvm flutter pub get如果仍解析到旧版本删除pubspec.lock与.dart_tool/后重试不要手改pubspec.lock。11.2 组件能编译但运行时颜色/字阶与截图不一致通常是主题没有注入。OhosTheme要放在MaterialApp.home或builder里包住页面根节点所有Ohos*组件都通过OhosTheme.of(context)读取 TokenMaterialApp(home:OhosTheme(data:OhosThemeData.light(),// 或 OhosThemeData.dark()child:constHomePage(),),);只import package:harmony_ui/harmony_ui.dart不会自动注入主题未包OhosTheme时组件会回退到默认亮色 Token。11.3 光感、动态模糊不生效按顺序检查OhosAppBar(scrollEffect: ...)是否同时传了scrollController且滚动容器真的使用了这个 controllerbackgroundColor是否被设成了不透明色——不透明背景会挡住BackdropFilter需要透明或半透明同一屏的模糊层是否过多标题栏 悬浮页签 弹层同时开启。层数越多开销越大减少层数通常比调参数更有效。11.4 真机上模糊边缘有毛刺、光感发灰模拟器与真机的光感效果基本一致真机出现边缘毛刺时优先排查设备 GPU 驱动与系统版本而不是组件参数。可以在真机上把scatterScale调低、glowScale略降后再对比深色模式如果过曝glowScale建议保持在 0.8–0.9。11.5 页签报No TabController轮播图片露出直角这是组件约定不是 bugOhosTabBar需要有TabController或DefaultTabController祖先页签页用DefaultTabController(length: ...)包住即可OhosSwiper翻页时会裁切子组件的圆角需要给OhosSwiper(clipRadius:)传与OhosImage相同的圆角。更多导航类细节见 8.3 节。11.6 构建时报npm not found、hvigor不存在或DEVECO_SDK_HOME错误说明 DevEco 工具链没有进入 PATH。在仓库根目录执行source env.sh按 DevEco Studio 26.0.0 Release 的默认安装路径配置确认node、ohpm、hvigor、hdc都可执行DEVECO_SDK_HOME必须指向.../Contents/sdk而不是 DevEco 的安装根目录。首次构建前可用fvm flutter doctor -v检查 OHOS 设备识别情况。11.7 模拟器安装失败或提示签名错误OpenHarmony 模拟器接受未签名 debug HAPfvm flutter build hap--debug--no-codesign hdcinstall-rbuild/ohos/hap/entry-default-unsigned.hap如果要用flutter run热重载 / 断点调试则需要签名配置在 DevEco Studio 中打开example/ohos勾选自动签名或参考 oh-flutter 的自动签名方案。真机安装必须使用调试证书签名的 HAP。11.8 能在官方 FlutterAndroid / iOS / Web上使用吗可以。harmony_ui是纯 Dart/Flutter 组件库不依赖平台通道差异主要在视觉HarmonyOS 字体在非鸿蒙平台会回退到系统字体光感与模糊的最终效果也取决于平台 GPU。跨平台预览用官方 Flutter 即可鸿蒙模拟器/真机验证使用 3.47.7-ohos-1.0.1。11.9 该用 pub.dev 的 0.3.0还是仓库 main以 pub.dev 的0.3.0为准它对应仓库 tagv0.3.0main可能包含尚未发版的改动。生产项目固定版本号或 tag尝鲜再跟main。升级前查看 CHANGELOG确认是否有 API 变更。总结导航类 5 个控件是harmony_ui与官方规范对齐度最高的一组标题栏 56vp、下划线指示条 24×3vp、平铺 48vp / 悬浮 56vp 底部页签数字都来自官方文档不是拍脑袋调的。加上沉浸光感标题栏、动态模糊与光池跟随导航层就能达到以假乱真的鸿蒙质感。下一篇进入展示类文本字阶、图片、进度条、徽标、索引条、二维码等 13 个控件逐个拆解。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源harmony_ui 仓库AtomGithttps://atomgit.com/oh-flutter/harmony_uiharmony_ui 仓库GitHubhttps://github.com/shaohushuo/harmony_uiharmony_ui pub.dev 发布页https://pub.dev/packages/harmony_uiFlutter OH 适配版3.47.7-ohos-1.0.1https://atomgit.com/oh-flutter/flutter_flutterFlutter OH 环境搭建指导https://atomgit.com/oh-flutter/flutter_samples/blob/master/ohos/docs/03_environment/OpenHarmony-flutter%E7%8E%AF%E5%A2%83%E6%90%AD%E5%BB%BA%E6%8C%87%E5%AF%BC.mdDevEco Studio 官方页面本文使用 26.0.0 Releasehttps://developer.huawei.com/consumer/cn/deveco-studio/配套图标包 ohos_iconshttps://pub.dev/packages/ohos_icons官方底部页签规范https://developer.huawei.com/consumer/cn/doc/doccenter-ux-design/bottomtab-0000001956787789官方子页签规范https://developer.huawei.com/consumer/cn/doc/doccenter-ux-design/chipsgroup-0000001929788350官方沉浸光感规范https://developer.huawei.com/consumer/cn/doc/doccenter-ux-design/immersivelight-0000002612101053fvm 多版本管理https://fvm.app Flutter三方库适配OpenHarmony【harmony_ui】导航类控件实战：标题栏、子页签、底部页签与轮播
Flutter三方库适配OpenHarmony【harmony_ui】导航类控件实战标题栏、子页签、底部页签与轮播前言harmony_ui是 Material/Cupertino 风格的 Flutter 组件库完整实现了HarmonyOS 设计语言覆盖官方「控件概览」的 6 大类 42 个控件并额外实现了沉浸光感材质与 UI Design Kit 增强能力。本系列按官方控件类别逐类实战本篇是第 1 篇导航类。导航类是应用骨架的第一层标题栏OhosAppBar定义页面头部子页签OhosTabBar做页面内切换底部页签OhosNavigationBar做全局导航轮播OhosSwiper与导航点OhosPageIndicator承载首屏内容流。5 个控件全部对齐官方规范且是沉浸光感落点最集中的类别——标题栏、底部页签的光感材质、动态模糊、光池效果都在这里。本系列全部代码都在OpenHarmony 模拟器上直接运行验证Flutter3.47.7-ohos-1.0.1 DevEco Studio26.0.0 Release截图环境API 261280×2832。环境搭建、依赖引入与构建步骤见文首「环境与版本」「安装与引入 harmony_ui」以及第九节仓库地址AtomGit / GitHub。环境与版本本文的示例与截图基于以下环境组合2026-10 实测组件版本说明Flutter SDKOH 适配版3.47.7-ohos-1.0.1oh-flutter/flutter_flutteroh-3.47-dev分支DevEco Studio26.0.0 Release提供 hvigor / ohpm / hdc / JBR 等工具链OpenHarmony SDK / APIAPI 2626.0.0模拟器与 SDK 均为 API 26运行设备OpenHarmony 模拟器API 261280×2832环境搭建分叉获取、DevEco Studio 与 SDK 配置、模拟器创建请按官方指导操作OpenHarmony-flutter 环境搭建指导。harmony_ui是纯 Dart/Flutter 组件库不依赖 ohos 平台通道在官方 Flutter SDK 上也能运行用于跨平台预览。只有跑example/ohos工程、构建 HAP 时才需要上面的 OH 适配版 SDK。安装与引入 harmony_uiharmony_ui已发布到 pub.dev当前最新版本是0.3.0。在应用工程的pubspec.yaml中声明dependencies:flutter:sdk:flutterharmony_ui:^0.3.0然后拉取依赖fvm flutter pub get如果团队需要固定到仓库的某个提交例如使用尚未发版的修复改用 git 依赖dependencies:harmony_ui:git:url:https://atomgit.com/oh-flutter/harmony_ui.gitref:v0.3.0# 固定 tag写 main 则跟随最新提交fvm flutter pub getpub.dev 与 git 两种方式二选一不要同时声明。CI 中建议固定 tag如v0.3.0而不是main避免构建结果随上游漂移。harmony_ui目前只依赖qr一个三方包ohos_icons是可选配套图标包不引入也不影响组件使用。一、导航类总览官方「导航类」共 5 个控件harmony_ui实现如下官方控件实现关键特性标题栏OhosAppBar沉浸光感、动态模糊滚动效果、自动返回键子页签OhosTabBar下划线 24×3vp / 胶囊两种形态、分割线跟手底部页签OhosNavigationBar平铺 48vp / 悬浮 56vp、光池跟随、角标导航点OhosPageIndicator轮播指示点支持自定义颜色尺寸轮播OhosSwiper自动播放、循环、内置指示点使用导航类组件前先用OhosTheme包一层应用根节点所有颜色走主题 Tokenimportpackage:flutter/material.dart;importpackage:harmony_ui/harmony_ui.dart;voidmain()runApp(constMyApp());classMyAppextendsStatelessWidget{constMyApp({super.key});overrideWidgetbuild(BuildContextcontext){returnMaterialApp(home:OhosTheme(data:OhosThemeData.light(),// 或 OhosThemeData.dark()child:constHomePage(),),);}}二、标题栏 OhosAppBar2.1 基础结构OhosAppBar是PreferredSizeWidget可直接传给OhosScaffold.appBar。高度默认56vptitle/leading/actions三区结构OhosScaffold(appBar:OhosAppBar(title:constText(设置),actions:[OhosIconButton(icon:constIcon(Icons.search),onPressed:_onSearch),OhosIconButton(icon:constIcon(Icons.more_horiz),onPressed:_onMore),],),body:constMyBody(),)title任意 Widget通常用OhosText标题字阶leading左侧区域不传且页面可pop时自动插入返回键automaticallyImplyLeading默认 trueactions右侧图标按钮列表推荐 2-3 个图标 24×24vpelevation默认 0鸿蒙风格标题栏不做投影分层层次交给光感材质。2.2 自定义高度与背景height/backgroundColor/scrolledBackgroundColor都开放。沉浸式页面内容延伸到标题栏后面把背景设为透明OhosAppBar(height:64,backgroundColor:Colors.transparent,title:constOhosText(首页,level:OhosTextLevel.headlineMedium),)注意OhosScaffold内部把OhosAppBar与body按 Column 布局v0.1.0 之前是 Stack 叠加导致内容被遮挡已修复。要做内容穿透标题栏的沉浸式效果用scrollEffect动态模糊见 3.2 节而不是自己改 Scaffold 布局。三、沉浸光感标题栏3.1 光感材质 lightMaterial打开lightMaterial: true标题栏背景由不透明色替换为ULTRA_THIN 光感材质8vp sigma 模糊 表面填充 顶部渐变淡出悬浮在内容之上的薄纱效果OhosAppBar(lightMaterial:true,// 默认档位 ultraThinlightLevel:OhosLightMaterialLevel.ultraThin,// 可显式指定五档之一title:constText(首页),actions:const[OhosIconButton(icon:Icon(Icons.more_horiz),onPressed:null),],)3.2 动态模糊 scrollEffectscrollEffect是 UI Design Kit「动态模糊标题栏」能力的实现内容穿透标题栏滚动滚动位移进入blurEffectiveStartOffset ~ blurEffectiveEndOffset区间后模糊背板按进度淡入。三种效果类型OhosAppBar(backgroundColor:Colors.transparent,title:constText(首页),scrollController:_scroller,scrollEffect:constOhosAppBarScrollEffectOptions(effect:OhosAppBarScrollEffectType.commonBlur,blurEffectiveStartOffset:0,// 开始产生模糊的偏移blurEffectiveEndOffset:60,// 模糊达到满值的偏移blurSigma:10,// 模糊强度),scrolledBackgroundColor:Colors.white,)效果类型行为适用场景commonBlur进入区间后常显模糊背板常规内容流页面transitionBlur模糊随滚动进度连续变化沉浸式首屏gradientBlur模糊 渐变蒙层叠加大图头部页面动态模糊标题栏在模拟器上的实机效果滚动后背板淡入动态模糊标题栏内容穿透滚动进入阈值区间后commonBlur背板淡入四、子页签 OhosTabBar4.1 下划线式OhosTabBar与 Flutter 的TabBar一样需要配合TabController/DefaultTabController使用tabs传ListWidget。下划线式默认的指示条严格对齐官方规范24×3vp 品牌色DefaultTabController(length:3,child:Scaffold(body:NestedScrollView(headerSliverBuilder:(_,__)[SliverToBoxAdapter(child:OhosTabBar(tabs:const[Text(推荐),Text(热榜),Text(关注)],type:OhosTabBarType.underline,// 默认值可省略),),],body:constTabBarView(children:[Center(child:Text(推荐页)),Center(child:Text(热榜页)),Center(child:Text(关注页))],),),),)页签可滚动isScrollable: true页签数量多时不换行、横向滑动指示条颜色indicatorColor默认取主题品牌色#0A59F7。4.2 胶囊式胶囊式capsule激活项品牌色实底、未激活项comp_background_gray灰底对齐官方子页签规范OhosTabBar(tabs:const[Text(日),Text(周),Text(月)],type:OhosTabBarType.capsule,height:40,)多选/筛选场景用OhosChipGroup胶囊组合间距默认 8vp官方建议不宜过大OhosChipGroup(items:constOhosChipItem[OhosChipItem(label:Text(全部)),OhosChipItem(label:Text(进行中)),OhosChipItem(label:Text(已完成)),],multiple:true,// 多选模式selectedIndexes:_selected,// 已选索引集合onSelectionChanged:(Setintv)setState(()_selectedv),)导航类组件整体效果沉浸光感标题栏 子页签 ChipGroup 底部页签导航类顶部沉浸光感标题栏中部下划线 胶囊子页签与 ChipGroup底部平铺/悬浮页签胶囊子页签 ChipGroup 多选实机效果胶囊式子页签激活项品牌色实底、未激活灰底ChipGroup 多选筛选五、子页签分割线divider 三模式OhosTabBar通过dividerOhosTabBarDividerOptions控制页签栏下方的分割线三种模式模式行为OhosTabBarDividerMode.visible常显OhosTabBarDividerMode.none常隐OhosTabBarDividerMode.followScroll跟手内容下滑淡入、回顶淡出OhosTabBar(tabs:const[Text(推荐),Text(热榜),Text(关注)],divider:constOhosTabBarDividerOptions(mode:OhosTabBarDividerMode.followScroll,followStartOffset:0,// 开始淡入的滚动偏移followEndOffset:20,// 淡入完成的滚动偏移strokeWidth:1,),scrollController:_scroller,// followScroll 模式必须提供)分割线实机效果visible常显模式子页签分割线常显 / 常隐 / 跟手三种模式提示分割线颜色默认取主题font_fourth20% 黑可用divider.color覆盖startMargin/endMargin可让分割线两端缩进与内容边距对齐。六、底部页签 OhosNavigationBar6.1 平铺式与悬浮式OhosNavigationBar对齐官方底部页签规范平铺式高48vp通栏悬浮式高56vp圆角悬浮条激活项用 20% 品牌色comp_emphasize_secondary填充图标 24×24vp页签数量建议3-5 个形态默认高度外观典型场景tile平铺默认48vp通栏无投影标准应用float悬浮56vp圆角悬浮条 投影配合沉浸光感// 平铺式OhosNavigationBar(currentIndex:_index,onDestinationSelected:(int i)setState(()_indexi),destinations:const[OhosNavigationDestination(icon:Icon(Icons.home_outlined),label:首页),OhosNavigationDestination(icon:Icon(Icons.square_grid_2x2),label:组件),OhosNavigationDestination(icon:Icon(Icons.person_outline),label:我的),],)6.2 双图标与角标每个页签可以配置selectedIcon选中态图标不传则用icon与badge图标角标OhosBadge数字或红点OhosNavigationDestination(icon:constIcon(Icons.person_outline),selectedIcon:constIcon(Icons.person_filled),label:我的,badge:constOhosBadge(count:5),// 数字角标不传 count 为红点)七、光感底部页签与光池悬浮式 lightMaterial: true是导航类的光感重头戏THIN 材质16vp sigma悬浮条彩色光池跟随选中项移动按压时指尖出现光晕OhosNavigationBar(type:OhosNavigationBarType.float,lightMaterial:true,lightLevel:OhosLightMaterialLevel.thin,// 悬浮式默认档位glow:true,// 光池跟随选中项enablePressGlow:true,// 按压触发指尖光斑currentIndex:_index,onDestinationSelected:(int i)setState(()_indexi),destinations:destinations,)光池移动带动画过渡切换页签时光晕平滑滑动而非瞬移按压光斑抬手后自动淡出与OhosGeometry.spring90ms曲线一致光池配色来自OhosLightPalette.glowColors明暗主题自动适配。平铺式与悬浮式底部页签实机对比底部页签上为平铺式48vp 通栏下为悬浮式56vp 圆角悬浮条 光感材质八、轮播 OhosSwiper 与导航点8.1 OhosSwiperOhosSwiper封装了PageView内置自动播放、循环与指示点是首屏 Banner 的主力OhosSwiper(height:180,autoPlay:true,autoPlayInterval:constDuration(seconds:4),loop:true,// 无限循环indicator:true,// 内置导航点默认开启clipRadius:BorderRadius.circular(16),onPageChanged:(int i)setState(()_pagei),children:[OhosImage(image:NetworkImage(https://example.com/a.png),width:double.infinity),OhosImage(image:NetworkImage(https://example.com/b.png),width:double.infinity),OhosImage(image:NetworkImage(https://example.com/c.png),width:double.infinity),],)8.2 OhosPageIndicator需要自定义指示点位置如放在图片外时OhosSwiper(indicator: false)关掉内置点用OhosPageIndicator单独渲染Column(children:[SizedBox(height:180,child:OhosSwiper(indicator:false,children:bannerImages),),constSizedBox(height:12),OhosPageIndicator(count:3,currentIndex:_page,dotSize:8,spacing:6,),],)activeColor/inactiveColor默认取主题色品牌色 / 20% 黑导航点尺寸默认 8vp、间距 6vp与官方规范一致。8.3 导航类常见坑OhosTabBar不传 controller既没有TabController也没有DefaultTabController祖先时会取不到控制器而报错页签页务必用DefaultTabController(length:)包裹轮播图片不圆角OhosImage自带圆角但OhosSwiper翻页切换时会露出直角边缘给OhosSwiper(clipRadius:)传同样的圆角悬浮页签被内容遮挡OhosNavigationBar(type: float)悬浮在内容之上页面底部要留 56vp 安全区的 padding否则最后一行列表会被盖住动态模糊不生效scrollEffect必须同时传scrollController且滚动容器真实使用它backgroundColor设为不透明色时模糊被背景挡住需设透明。九、在鸿蒙模拟器上运行导航类的所有效果光感标题栏、动态模糊、光池都在 gallery 示例应用的「导航」分类页可交互运行。最短运行路径安装3.47.7-ohos-1.0.1的 OH 适配版 SDK。该版本在仓库里是 git tag按 tag 浅克隆到 fvm 版本目录后在工程内切换gitclone--depth1--branch3.47.7-ohos-1.0.1\https://atomgit.com/oh-flutter/flutter_flutter.git\~/fvm/versions/ohos/oh-3.47.7-releasecdharmony_ui 仓库根目录fvm use ohos/oh-3.47.7-release fvm flutter--version# 应输出 Flutter 3.47.7-ohos-1.0.1fvm 的fvm install alias/ref只识别分支名3.47.7-ohos-1.0.1是 tag不能直接 install按上面的方式 clone 到版本目录后fvm use即可。source env.sh加载 DevEco Studio26.0.0 Release的工具链node / ohpm / hvigor / SDK toolchains如果命令不可用按文首的环境搭建指导检查DEVECO_SDK_HOME、JAVA_HOME与hdc进入example/fvm flutter pub get fvm flutter create --platforms ohos .构建并安装到模拟器fvm flutter build hap--debug--no-codesign hdc list targets hdcinstall-rbuild/ohos/hap/entry-default-unsigned.hap hdc shell aa start-aEntryAbility-bcom.example.ohos_ui_example光感效果依赖BackdropFilter模拟器与真机渲染一致若真机上模糊边缘有毛刺优先检查设备 GPU 驱动而非组件参数。十、最佳实践层级唯一一个页面只有一个标题栏actions最多 3 个按钮更多操作收进更多菜单页签数量底部页签 3-5 个子页签 2-5 个超出说明信息架构该拆页了光感节制标题栏 悬浮底部页签同时开光感即可弹层再叠加光感时注意同屏模糊层数量≥3 层时低端机会掉帧动态模糊阈值blurEffectiveEndOffset建议 40-80vp太小模糊感突兀太大几乎看不到选中态图标底部页签务必配selectedIcon线性→面性切换是官方视觉的重要组成部分宽屏适配≥840vp 窗口建议底部页签改侧边页签OhosSideBar见系列第 7 篇增强类导航与反馈联动页签切换失败时配合showOhosToast提示切换成功保持静默——导航层成功不打扰、失败有交代。十一、常见问题 FAQ11.1flutter pub get找不到 harmony_ui先确认版本口径pub.dev 上最新为0.3.0pubspec.yaml写harmony_ui: ^0.3.0若使用 git 依赖检查url/ref是否可达并确认没有同时声明 pub.dev 与 git 两份依赖。改完后执行fvm flutter clean fvm flutter pub get如果仍解析到旧版本删除pubspec.lock与.dart_tool/后重试不要手改pubspec.lock。11.2 组件能编译但运行时颜色/字阶与截图不一致通常是主题没有注入。OhosTheme要放在MaterialApp.home或builder里包住页面根节点所有Ohos*组件都通过OhosTheme.of(context)读取 TokenMaterialApp(home:OhosTheme(data:OhosThemeData.light(),// 或 OhosThemeData.dark()child:constHomePage(),),);只import package:harmony_ui/harmony_ui.dart不会自动注入主题未包OhosTheme时组件会回退到默认亮色 Token。11.3 光感、动态模糊不生效按顺序检查OhosAppBar(scrollEffect: ...)是否同时传了scrollController且滚动容器真的使用了这个 controllerbackgroundColor是否被设成了不透明色——不透明背景会挡住BackdropFilter需要透明或半透明同一屏的模糊层是否过多标题栏 悬浮页签 弹层同时开启。层数越多开销越大减少层数通常比调参数更有效。11.4 真机上模糊边缘有毛刺、光感发灰模拟器与真机的光感效果基本一致真机出现边缘毛刺时优先排查设备 GPU 驱动与系统版本而不是组件参数。可以在真机上把scatterScale调低、glowScale略降后再对比深色模式如果过曝glowScale建议保持在 0.8–0.9。11.5 页签报No TabController轮播图片露出直角这是组件约定不是 bugOhosTabBar需要有TabController或DefaultTabController祖先页签页用DefaultTabController(length: ...)包住即可OhosSwiper翻页时会裁切子组件的圆角需要给OhosSwiper(clipRadius:)传与OhosImage相同的圆角。更多导航类细节见 8.3 节。11.6 构建时报npm not found、hvigor不存在或DEVECO_SDK_HOME错误说明 DevEco 工具链没有进入 PATH。在仓库根目录执行source env.sh按 DevEco Studio 26.0.0 Release 的默认安装路径配置确认node、ohpm、hvigor、hdc都可执行DEVECO_SDK_HOME必须指向.../Contents/sdk而不是 DevEco 的安装根目录。首次构建前可用fvm flutter doctor -v检查 OHOS 设备识别情况。11.7 模拟器安装失败或提示签名错误OpenHarmony 模拟器接受未签名 debug HAPfvm flutter build hap--debug--no-codesign hdcinstall-rbuild/ohos/hap/entry-default-unsigned.hap如果要用flutter run热重载 / 断点调试则需要签名配置在 DevEco Studio 中打开example/ohos勾选自动签名或参考 oh-flutter 的自动签名方案。真机安装必须使用调试证书签名的 HAP。11.8 能在官方 FlutterAndroid / iOS / Web上使用吗可以。harmony_ui是纯 Dart/Flutter 组件库不依赖平台通道差异主要在视觉HarmonyOS 字体在非鸿蒙平台会回退到系统字体光感与模糊的最终效果也取决于平台 GPU。跨平台预览用官方 Flutter 即可鸿蒙模拟器/真机验证使用 3.47.7-ohos-1.0.1。11.9 该用 pub.dev 的 0.3.0还是仓库 main以 pub.dev 的0.3.0为准它对应仓库 tagv0.3.0main可能包含尚未发版的改动。生产项目固定版本号或 tag尝鲜再跟main。升级前查看 CHANGELOG确认是否有 API 变更。总结导航类 5 个控件是harmony_ui与官方规范对齐度最高的一组标题栏 56vp、下划线指示条 24×3vp、平铺 48vp / 悬浮 56vp 底部页签数字都来自官方文档不是拍脑袋调的。加上沉浸光感标题栏、动态模糊与光池跟随导航层就能达到以假乱真的鸿蒙质感。下一篇进入展示类文本字阶、图片、进度条、徽标、索引条、二维码等 13 个控件逐个拆解。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源harmony_ui 仓库AtomGithttps://atomgit.com/oh-flutter/harmony_uiharmony_ui 仓库GitHubhttps://github.com/shaohushuo/harmony_uiharmony_ui pub.dev 发布页https://pub.dev/packages/harmony_uiFlutter OH 适配版3.47.7-ohos-1.0.1https://atomgit.com/oh-flutter/flutter_flutterFlutter OH 环境搭建指导https://atomgit.com/oh-flutter/flutter_samples/blob/master/ohos/docs/03_environment/OpenHarmony-flutter%E7%8E%AF%E5%A2%83%E6%90%AD%E5%BB%BA%E6%8C%87%E5%AF%BC.mdDevEco Studio 官方页面本文使用 26.0.0 Releasehttps://developer.huawei.com/consumer/cn/deveco-studio/配套图标包 ohos_iconshttps://pub.dev/packages/ohos_icons官方底部页签规范https://developer.huawei.com/consumer/cn/doc/doccenter-ux-design/bottomtab-0000001956787789官方子页签规范https://developer.huawei.com/consumer/cn/doc/doccenter-ux-design/chipsgroup-0000001929788350官方沉浸光感规范https://developer.huawei.com/consumer/cn/doc/doccenter-ux-design/immersivelight-0000002612101053fvm 多版本管理https://fvm.app