前言harmony_ui是 Material/Cupertino 风格的 Flutter 组件库完整实现了HarmonyOS 设计语言覆盖官方「控件概览」6 大类 42 个控件并额外实现了沉浸光感材质与 UI Design Kit 增强能力。本系列按官方控件类别逐类实战前五篇分别是导航类、展示类、操作类、输入类、选择类本篇是第 6 篇容器类。容器类是装内容的壳列表/列表项OhosList/OhosListTile承载信息流与设置页卡片OhosCard是信息流的单元弹出框showOhosDialog、气泡showOhosPopup、半模态showOhosBottomSheet是内容之外的第二层空间。其中半模态面板默认使用ULTRA_THICK 沉浸光感材质是容器类与第 7 篇增强类的交汇点。所有示例代码都在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是可选配套图标包不引入也不影响组件使用。一、容器类总览官方控件实现一句话说明列表 / 列表项OhosList/OhosListTile分组列表选中态/危险项卡片OhosCard24vp 大圆角按压反馈弹出框OhosAlertDialog/showOhosDialog双按钮确认危险操作红色气泡提示showOhosPopup锚定控件的功能引导半模态面板showOhosBottomSheetULTRA_THICK 光感材质布局容器栅格/响应式OhosGrid/OhosResponsiveBuilder4/8/12 列断点布局增强横滑列表项OhosListItem左滑操作整划删除容器类整体效果gallery「容器」分类页模拟器实机容器类OhosList分组列表、OhosCard卡片、showOhosDialog弹出框、showOhosBottomSheet光感半模态面板二、列表 OhosList 与列表项2.1 分组列表OhosList是分组标题 列表项 分隔线的组合容器设置页标准形态。header传OhosSubheader支持尾部更多OhosList(header:constOhosSubheader(title:通用),children:[OhosListTile(leading:constIcon(Icons.wifi),title:constText(无线网络),subtitle:constText(已连接),trailing:constIcon(Icons.chevron_right),onTap:_openWifi,),constOhosDivider(),OhosListTile(leading:constIcon(Icons.bluetooth),title:constText(蓝牙),trailing:constIcon(Icons.chevron_right),onTap:_openBluetooth,),],)OhosListTile四区结构leading / title / subtitle / trailing与ListTile一致行高、内边距、分隔线全部按官方规范内置。2.2 选中态与危险项列表项内置两个官方状态selected品牌色高亮表示当前项与danger危险操作红色文字OhosList(header:constOhosSubheader(title:通知),children:[OhosListTile(leading:constIcon(Icons.push_pin_outlined),title:constText(消息推送),selected:true,// 选中态品牌色高亮trailing:OhosSwitch(value:_push,onChanged:_onPush),),constOhosDivider(),OhosListTile(leading:constIcon(Icons.delete_outline),title:constText(清空聊天记录),danger:true,// 危险项红色onTap:_clearChat,),],)长列表场景用ListView.builderOhosListTile手工拼装OhosList适合短列表直铺列表项按压反馈10% 黑叠加内置无需InkWell包裹。三、卡片 OhosCard3.1 基础卡片OhosCard对齐官方卡片规范24vp 大圆角、分层背景comp_background_primary白底、按压反馈默认内边距 16vpOhosCard(onTap:_openDetail,child:constColumn(crossAxisAlignment:CrossAxisAlignment.start,children:[OhosText(卡片标题,level:OhosTextLevel.titleLarge),SizedBox(height:8),OhosText(卡片摘要文字最多两行超出省略。,level:OhosTextLevel.bodyMedium),],),)elevation默认 0鸿蒙卡片靠背景分层而非投影特殊场景可加margin/color可覆盖默认值灰底卡片用theme.compBackgroundGrayColor。3.2 图片卡片信息流单元的标准结构头图 标题 摘要 尾部信息OhosCard(onTap:_openDetail,margin:constEdgeInsets.symmetric(horizontal:16,vertical:8),child:Column(crossAxisAlignment:CrossAxisAlignment.start,children:const[OhosImage(image:NetworkImage(https://example.com/cover.png),height:160,borderRadius:20,),SizedBox(height:12),Padding(padding:EdgeInsets.symmetric(horizontal:4),child:Column(crossAxisAlignment:CrossAxisAlignment.start,children:[OhosText(文章标题,level:OhosTextLevel.titleMedium),SizedBox(height:4),OhosText(摘要文字摘要文字摘要文字摘要文字摘要文字。,level:OhosTextLevel.bodySmall),SizedBox(height:12),Row(children:[Icon(Icons.person_outline,size:16,color:Colors.black38),SizedBox(width:4),Text(作者名,style:TextStyle(fontSize:12,color:Colors.black38)),],),],),),],),)卡片圆角层次卡片 24vp 卡片内图片 20~16vp 图片内元素 8vp——圆角逐级递减是鸿蒙嵌套容器的视觉惯例OhosImage默认 8vp 正好对应最内层。四、弹出框 showOhosDialogshowOhosDialog返回FutureOhosDialogAction支持danger危险色对齐官方弹出框规范finalbool?okawaitshowOhosDialogbool(context:context,title:删除文件,content:删除后无法恢复请确认是否继续。,actions:[OhosDialogAction(label:取消,onPressed:()Navigator.pop(context,false),),OhosDialogAction(label:删除,danger:true,onPressed:()Navigator.pop(context,true),),],);场景标题按钮组合备注破坏性确认具体后果取消 危险操作删除/清空/退订普通确认动作名取消 确定提交/退出登录信息告知结果单按钮知道了操作完成提示选择问题多选项2-3 个互斥选项对话框内容保持标题 两行内说明长内容改用半模态返回值为最后一个Navigator.pop的值未操作点遮罩按默认策略处理。弹出框实机效果showOhosDialog弹出框标题、内容、取消/危险删除双操作五、气泡提示 showOhosPopupshowOhosPopup通过GlobalKey锚定目标控件显示圆角气泡 指向箭头用于新手引导与功能说明展示类篇有基本用法这里讲组合模式finalguideKeyGlobalKey();// 分步引导第 1 步指向搜索框showOhosPopup(context:context,content:在这里搜索全部内容,targetKey:guideKey,);多个引导步骤时业务侧维护步骤索引每步换一个targetKey气泡与OhosBadge红点配合红点吸引注意 气泡说明功能是标准引导组合引导状态是否已展示过用本地存储记录避免每次启动重复弹。六、半模态面板 showOhosBottomSheet6.1 基本半模态showOhosBottomSheet从底部滑出半模态面板默认 ULTRA_THICK 光感材质40vp sigma适合分享面板、筛选面板、信息预览awaitshowOhosBottomSheet(context:context,title:分享到,content:SizedBox(height:200,child:Row(mainAxisAlignment:MainAxisAlignment.spaceEvenly,children:const[// 分享入口图标],),),)dismissLabel提供底部关闭按钮文案如完成不传则无showCloseButton控制标题栏右上角关闭图标默认 true返回Futurevoid关闭即返回需要结果的场景用共享 State 或改造为FutureBuilder。6.2 光感调参需要更通透或更厚重的半模态时脱离便捷函数直接用OhosLightMaterial包自己的面板完整原理见第 7 篇增强类// 更通透模糊与光池减弱OhosLightMaterial(level:OhosLightMaterialLevel.thick,effectTuning:constOhosLightEffectTuning(blurScale:0.8,glowScale:0.6,),child:mySheet,)// 更厚重开启光感漫射OhosLightMaterial(level:OhosLightMaterialLevel.ultraThick,effectTuning:constOhosLightEffectTuning(scatterScale:0.6),child:mySheet,)半模态面板实机效果showOhosBottomSheet半模态面板ULTRA_THICK 光感材质 底部滑出七、布局容器 OhosGrid 与 OhosResponsiveBuilder容器类的隐藏成员官方布局规范栅格/断点在harmony_ui里由两个布局组件实现。7.1 栅格 OhosGrid断点决定列数600vp 四列 / 600-840vp 八列 / ≥840vp 十二列OhosGridItem(columnSpan:)按列跨排布内容最大宽度 2220vpOhosGrid(children:[OhosGridItem(columnSpan:2,child:cardA),OhosGridItem(columnSpan:2,child:cardB),OhosGridItem(columnSpan:4,child:bannerCard),// 通栏],)7.2 响应式 OhosResponsiveBuilderOhosResponsiveBuilder依据窗口宽度重建子树挪移/折行/分栏的响应式策略都建立在它之上。回调拿到OhosWindowSize对象除type外还直接给出当前断点的columns4/8/12、margin16/24/32vp、gutter8/12/16vpOhosResponsiveBuilder(builder:(context,size){// size.type: compact(600) / medium(600-840) / large(≥840)returnswitch(size.type){OhosWindowSizeType.compactsingleColumnLayout,OhosWindowSizeType.mediumtwoColumnLayout,OhosWindowSizeType.largesideBySideLayout,};},)size.isCompact/isMedium/isLarge是便捷布尔值简单判断不用解枚举size.useSideTab≥840vp 为 true宽屏建议切换侧边页签OhosSideBar见第 7 篇size.pagePadding直接返回当前断点的水平内边距页面根部套一层即可对齐规范。栅格与断点演示实机效果布局与动效栅格系统、响应式断点1/2/4 列切换与沉浸光感入口八、横滑列表项 OhosListItem列表项的增强形态——左滑显示操作按钮、整划删除fullDelete属于 UI Design Kit 能力完整用法见第 7 篇增强类这里给出容器视角的集成方式// 在 ListView 里逐行包裹ListView.builder(itemCount:rows.length,itemBuilder:(_,int i)OhosListItem(fullDelete:true,onFullDelete:()setState(()rows.removeAt(i)),actions:[OhosSwipeAction(icon:constIcon(Icons.delete_outline_rounded),backgroundColor:OhosTheme.of(context).dangerColor,onTap:()setState(()rows.removeAt(i)),),],child:OhosListTile(title:Text(rows[i]),),),)整划删除阈值、越界自动回调由组件内部处理横滑与列表滚动手势的冲突已做仲裁横向滑动不会被竖向滚动吃掉。九、在鸿蒙模拟器上运行容器类全部控件在 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在模拟器上渲染正常真机如遇模糊边缘异常优先关闭scatterScale漫射再排查而不是降模糊档位。十、最佳实践容器类控件的选型速查场景推荐容器备注设置页OhosListOhosSubheader分组短列表直铺长列表ListView.builderOhosListTile分页/懒加载信息流单元OhosCard24vp 圆角圆角逐级递减确认/选择showOhosDialog标题 两行内功能引导showOhosPopup 红点状态本地记录分享/筛选showOhosBottomSheetULTRA_THICK 光感宽屏网格OhosGridOhosGridItem4/8/12 列断点响应式重构OhosResponsiveBuilder三档断点重建列表行操作OhosListItem左滑 整划删除实践要点第二层空间选型信息 ≤2 行用对话框需要操作区/滚动区用半模态指着控件说用气泡——三层空间各司其职卡片零投影鸿蒙卡片层次靠背景分层白卡 灰底elevation默认保持 0投影是 Material 思维半模态结果回传showOhosBottomSheet返回void需要结果时用全局状态或事件总线别在content里塞回调地狱横滑删除加撤销onFullDelete后跟一个showOhosSnackBar(撤销)误删成本直接归零断点先想清楚用OhosResponsiveBuilder前先在纸上画三档断点的布局草图避免代码里堆满if (width 840)。十一、常见问题 FAQ11.1flutter pub get找不到 harmony_ui先确认pubspec.yaml写的是harmony_ui: ^0.3.0或按文首 git 依赖写法固定ref: v0.3.0pub.dev 与 git 两种方式不要同时声明。改完后执行fvm flutter clean fvm flutter pub get仍异常时删除pubspec.lock与.dart_tool/重试不要手改锁文件。11.2 组件颜色、字阶与截图不一致通常是没有注入主题。OhosTheme要包住页面根节点MaterialApp.home或builder组件通过OhosTheme.of(context)读取 Token只 import 组件库不会自动注入。确认后再检查是否显式覆盖了颜色或字阶参数。11.3showOhosDialog里 setState 报错或弹窗不关闭异步确认后先判断mounted再更新页面状态并用Navigator.pop(context, result)关闭弹窗不要在弹窗内容里直接操作已被销毁的页面State。11.4showOhosBottomSheet怎么把选择结果带回页面它返回void不承载返回值。需要结果时在面板内更新全局状态、Provider/Bloc或通过事件回调把结果写回页面别在content里堆回调链。11.5 卡片内图片圆角看起来不对遵循圆角逐级递减卡片 24vp 卡内图片 16–20vp 图片内元素 8vp。OhosImage默认 8vp放进卡片时按层级覆盖不要给整张卡片再套一层裁剪。11.6OhosListItem左滑与页面横滑手势冲突横滑列表项应放在纵向列表内避免再嵌套横向PageView同一行只保留一个左滑操作区整划删除与按钮删除不要同时启用。11.7 构建时报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而不是安装根目录。11.8 模拟器安装失败或提示签名错误OpenHarmony 模拟器接受未签名 debug HAP先fvm flutter build hap --debug --no-codesign再用hdc install -r build/ohos/hap/entry-default-unsigned.hap安装。真机安装与flutter run热重载需要调试证书签名。11.9 官方 FlutterAndroid / iOS / Web上能用吗可以。harmony_ui是纯 Dart/Flutter 实现不依赖平台通道字体、光感与模糊的最终效果会随平台渲染能力略有差异。跨平台预览用官方 Flutter 即可鸿蒙模拟器/真机验证请使用 3.47.7-ohos-1.0.1。总结容器类是壳的艺术列表装信息、卡片装单元、对话框/半模态/气泡装第二层空间栅格与断点装响应式。harmony_ui把 24vp 卡片圆角、分组列表行高、ULTRA_THICK 光感半模态这些官方细节都固化成了默认值六大类别至此全部讲完加上第 7 篇增强类沉浸光感 UI Design Kit整个harmony_ui的组件版图就完整了。至此本系列 7 篇全部完结导航、展示、操作、输入、选择、容器六大类别 增强类收官。所有代码可在仓库example/的 gallery 应用中交互验证欢迎在 OpenHarmony 模拟器上跑起来。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源harmony_ui 仓库AtomGitoh-flutter/harmony_uiharmony_ui 仓库GitHubshaohushuo/harmony_ui鸿蒙社区 Flutter 分叉CPF-Flutter/flutter_flutter配套图标包 ohos_iconspub.dev/packages/ohos_icons官方控件概览42 控件清单general_overview官方布局基础栅格/断点design-layout-basics官方沉浸光感半模态材质依据immersivelightfvm 多版本管理fvm.app
