Flutter三方库适配OpenHarmony【harmony_ui】展示类控件实战文本字阶、图片、进度、徽标与数据可视化前言harmony_ui是 Material/Cupertino 风格的 Flutter 组件库完整实现了HarmonyOS 设计语言覆盖官方「控件概览」6 大类 42 个控件并额外实现了沉浸光感材质与 UI Design Kit 增强能力。本系列按官方控件类别逐类实战上一篇讲了导航类标题栏/子页签/底部页签/轮播本篇是第 2 篇展示类。展示类是 6 大类中控件数量最多的一类13 个文本/子标题、图片、分隔器、进度条、新事件标记、索引条、滚动条、即时反馈、气泡提示、数据可视化、二维码、空白、文本时钟。它们决定了页面的信息呈现质感——字阶是否分明、图片圆角是否规范、徽标红点是否克制鸿蒙视觉的细节基本都藏在这一类里。所有示例代码都在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是可选配套图标包不引入也不影响组件使用。一、展示类总览官方控件实现一句话说明文本 / 子标题OhosText/OhosSubheader13 级字阶 / 列表分组标题图片OhosImage默认 8vp 圆角、选中描边、占位图分隔器OhosDivider列表内细分隔线进度条OhosProgressIndicator圆形无限 / 线性有值两种新事件标记OhosBadge数字角标 / 红点挂图标和页签索引条OhosAlphabetIndexerA-Z 侧边索引条滚动条OhosScrollbar跟随 ScrollController 的圆角拇指即时反馈showOhosToast轻量 Toast支持图标即时操作showOhosSnackBar消息 操作撤销等气泡提示showOhosPopup锚定控件的气泡引导数据可视化OhosDataPanel标题 指标网格面板二维码OhosQrCode内置二维码生成qr 包空白 / 文本时钟OhosBlank/OhosTextClock弹性空白 / 实时时钟文本展示类整体效果gallery「展示」分类页模拟器实机展示类OhosText全字阶、进度条、OhosBadge数字/红点、索引条、滚动条、即时反馈、数据面板、二维码、文本时钟等二、文本 OhosText 与字阶2.1 十三级字阶HarmonyOS 设计语言最容易被忽略的一点文字不是大小随意而是字阶对齐。OhosText的level参数提供与官方一致的 13 级字阶字阶字号典型用途displayLarge36sp首页超大数字统计值displayMedium32sp大数字展示headlineLarge28sp页面主标题headlineMedium24sp章节标题titleLarge20sp卡片标题titleMedium17sp次级标题titleSmall16sp小标题bodyLarge16sp正文默认bodyMedium15sp次级正文bodySmall14sp辅助正文labelLarge16sp大号标签按钮文字labelMedium14sp中号标签labelSmall12sp小号标签角标说明OhosText(营收 128 万,level:OhosTextLevel.displayLarge);OhosText(经营周报,level:OhosTextLevel.headlineMedium);OhosText(数据来源本地门店系统,level:OhosTextLevel.labelSmall);color不传时按字阶自动取主题四级文字色90%/60%/40%/20%maxLinesoverflow控制截断卡片标题常用maxLines: 1, overflow: TextOverflow.ellipsis非鸿蒙平台自动回退系统字体鸿蒙设备上使用原生HarmonyOS Sans。2.2 子标题 OhosSubheader列表分组标题设置页的通用网络等分组行用OhosSubheader支持尾部文案与点击OhosSubheader(title:推荐,trailing:更多,onTrailingTap:_openMore,)提示字阶是档位不是建议值——同一个 App 里正文应始终用bodyLarge/bodyMedium不要为了看起来更大随意跳级这是鸿蒙设计语言克制的来源。2.3 字阶组合完整示例一个统计卡片页的完整字阶搭配displayLarge headlineMedium bodyLarge labelSmall 四档OhosCard(child:Column(crossAxisAlignment:CrossAxisAlignment.start,children:[constOhosText(本月营收,level:OhosTextLevel.labelMedium),constSizedBox(height:8),constRow(crossAxisAlignment:CrossAxisAlignment.end,children:[OhosText(128,level:OhosTextLevel.displayLarge),OhosText( 万元,level:OhosTextLevel.titleMedium),],),constSizedBox(height:12),constOhosText(较上月增长 12.4%主要来自周末促销活动的订单增长。,level:OhosTextLevel.bodyLarge,),constSizedBox(height:16),constOhosText(更新于 10 月 20 日 18:00,level:OhosTextLevel.labelSmall),],),)三、图片 OhosImageOhosImage对齐官方图片规范默认8vp 圆角、BoxFit.cover裁切内置选中描边与占位图// 基础用法OhosImage(image:NetworkImage(https://example.com/cover.png),width:120,height:120,)// 选中态品牌色描边图片选择器场景OhosImage(image:fileImage,width:84,height:84,borderRadius:12,selected:_selected.contains(i),borderColor:constColor(0xFF0A59F7),)// 占位图加载完成前显示OhosImage(image:NetworkImage(https://example.com/cover.png),width:double.infinity,height:180,placeholder:constCenter(child:CircularProgressIndicator(strokeWidth:2)),)borderRadius默认取主题小圆角 8vp横幅图可传 16轮播/九宫格等场景与OhosSwiper、OhosGrid组合使用导航类与容器类篇有示例。四、进度条 OhosProgressIndicator两种形态圆形无限加载与线性有值进度均为静态构造器直接创建// 圆形无限转圈加载态constOhosProgressIndicator.circular()// 线性0-1 进度值下载/上传OhosProgressIndicator.linear(value:0.6)颜色默认取主题品牌色直径与线宽对齐官方规范按钮内置加载态OhosButton(loading: true)内部就是圆形进度不需要自己拼Row。五、新事件标记 OhosBadgeOhosBadge提供数字角标与红点两种形态可包裹任意子控件通常是图标超过maxCount显示 “99”// 数字角标包裹一个图标OhosBadge(count:5,child:constIcon(Icons.chat_bubble_outline),)// 红点无数字的新事件提示OhosBadge(isDot:true,child:constIcon(Icons.notifications_none),)// 挂在底部页签上见导航类篇OhosNavigationDestination(icon:constIcon(Icons.person_outline),label:我的,badge:constOhosBadge(count:5),)maxCount默认 99超出显示 “99”offset微调角标位置color默认取主题功能色红色系。克制原则同屏红点最多 1-2 个。全应用所有图标都挂角标等于没有角标——鸿蒙设计语言对新事件标记的定位是稀缺信号不是装饰。六、索引条与滚动条6.1 OhosAlphabetIndexer联系人列表标配的 A-Z 侧边索引条滑动/点击回传字母配合OhosSubheader分组实现跳转Row(children:[Expanded(child:ListView(children:[constOhosSubheader(title:A),OhosListTile(title:constText(阿宝)),constOhosSubheader(title:B),OhosListTile(title:constText(冰冰)),// ...],),),OhosAlphabetIndexer(indexer:ABCDEFGHIJKLMNOPQRSTUVWXYZ#.split(),onSelected:(Stringletter)_scrollToGroup(letter),),],)size默认 24×360vpitemHeight默认 20vp选中字母时的放大反馈由组件内部处理业务只需处理onSelected。6.2 OhosScrollbar跟随任意ScrollController的圆角拇指滚动条替代 Flutter 原生Scrollbar的细线样式final_scScrollController();OhosScrollbar(controller:_sc,thumbRadius:4,// 拇指圆角thickness:8,// 拇指粗细child:ListView.builder(controller:_sc,itemCount:200,itemBuilder:(_,int i)OhosListTile(title:Text(条目$i)),),)七、即时反馈与气泡提示7.1 showOhosToast 即时反馈轻量 Toast居中/顶部短暂提示支持图标配 ohos_icons 字体图标showOhosToast(context,操作成功,icon:OhosIcons.checkmark_circle_fill);7.2 showOhosSnackBar 即时操作比 Toast 多一个操作位撤销/查看详情悬浮显示、可配背景色resident: true常驻模式见系列第 7 篇增强类showOhosSnackBar(context,message:已删除 1 个文件,actionLabel:撤销,onAction:()showOhosToast(context,已撤销),);7.3 showOhosPopup 气泡提示通过GlobalKey锚定目标控件的气泡引导新手引导、功能说明场景finalpayButtonKeyGlobalKey();// 在目标控件上挂 keyElevatedButton(key:payButtonKey,onPressed:_pay,child:constText(支付));// 展示气泡showOhosPopup(context:context,content:长按扫码支付,targetKey:payButtonKey,);气泡提示实机效果showOhosPopup气泡提示锚定目标控件圆角气泡 指向箭头反馈三件套的选型一句话无操作 → Toast一句话 一个操作 → SnackBar要指着某个控件说 → Popup。选错通道是展示类最常见的手感不对来源。八、数据可视化、二维码与工具小组件8.1 OhosDataPanel标题 指标网格的数据面板统计页/仪表盘直接可用支持千分位小数与前后缀OhosDataPanel(title:经营数据,entries:const{营收:128,订单:356,客单价:36,好评率:98.6,},columns:2,decimals:1,prefix:¥,)8.2 OhosQrCode内置二维码生成基于 qr 包也是harmony_ui唯一第三方依赖OhosQrCode(data:https://atomgit.com/oh-flutter/harmony_ui,size:160,)8.3 OhosTextClock、OhosBlank 与 OhosDivider三个小而美的工具组件// 实时文本时钟每秒刷新支持 y/M/d/H/m/s 格式 tokenOhosTextClock(format:yyyy年MM月dd日 HH:mm,textStyle:constTextStyle(fontSize:28,fontWeight:FontWeight.w300),)// 弹性空白有限空间内填满剩余高度把后续子项推到底部Column(children:[constOhosText(顶部内容),constOhosBlank(),constOhosText(底部操作区),])// 分隔器列表内细分隔线constOhosDivider()九、在鸿蒙模拟器上运行展示类全部控件在 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_examplegallery 主页的 7 大分类入口展示类为其中之一gallery 主页组件、展示、操作、输入、选择、容器 6 大控件分类 布局与动效入口十、最佳实践按场景选组件的速查表场景推荐组件备注页面主标题OhosText(headlineLarge/Medium)一屏最多一个卡片内数字OhosText(displayLarge)labelMedium说明大数字配小单位列表分组标题OhosSubheader支持尾部更多封面/头像OhosImage列表 8vp、头图 16vp 圆角加载等待OhosProgressIndicator.circular()按钮内用loading: true任务进度OhosProgressIndicator.linear(value:)0-1 值新事件OhosBadge数字优先、红点兜底联系人定位OhosAlphabetIndexer配合分组列表长列表滚动OhosScrollbar挂 ScrollController轻提示showOhosToast一句话、无操作可撤销操作showOhosSnackBar带操作位功能引导showOhosPopup锚定 GlobalKey统计面板OhosDataPanel指标网格分享码OhosQrCode内置生成时间显示OhosTextClock别自己起 Timer实践要点字阶纪律页面内文字只允许 2-3 个字阶如 headlineMedium bodyLarge labelSmall先定字阶再写页面图片统一圆角同一页面内图片圆角保持一致列表 8vp、卡片头图 16vpOhosImage默认值就是规范值反馈分级Toast / SnackBar / Popup 按信息量 × 操作数选型不要混用角标稀缺全应用同屏红点 ≤ 2 个数字角标优先红点“99” 兜底时钟用组件需要实时时间的地方用OhosTextClock不要用Timer手动刷Text——组件内部已处理秒级定时与格式解析空态用 OhosBlank列表为空时配合OhosBlank做垂直居中而不是写死SizedBox(height: 300)。十一、常见问题 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.3 13 级字阶应该用哪几档同一个页面控制在 2–3 档标题用headlineMedium/titleLarge正文用bodyLarge/bodyMedium说明文字用labelSmall。字阶是版式层级而不是字号菜单不要为了看起来更大随意跨档。11.4 长文本溢出、卡片标题被撑开OhosText支持maxLines与overflow卡片标题固定maxLines: 1, overflow: TextOverflow.ellipsis多行正文用bodyLarge正常换行不要用固定高度容器硬裁。11.5OhosQrCode还要单独安装qr吗不需要。harmony_ui已把qr作为唯一三方依赖内置业务工程只要引入harmony_ui即可生成二维码只有项目里另外直接调用qrAPI 时才需要自己声明。11.6 Toast / SnackBar / Popup 不显示三者都依赖当前的Overlay/Navigator确认调用发生在MaterialApp之内的页面上下文showOhosPopup还需要目标控件的GlobalKey且目标已完成布局。页面销毁后的异步回调会被丢弃先判断mounted。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。总结展示类 13 个控件看似零散其实共同指向一件事信息呈现的克制与对齐。字阶 13 档、图片 8vp 圆角、进度条品牌色、角标 “99” 兜底、气泡锚定控件——harmony_ui把这些官方细节都固化成了默认值业务代码只需要用不需要调。下一篇进入操作类按钮五种样式、下拉按钮、状态按钮、操作块、工具栏、核心操作栏与菜单把用户主动交互的入口一次讲全。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源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/鸿蒙社区 Flutter 分叉https://atomgit.com/oh-flutter/flutter_flutter配套图标包 ohos_iconshttps://pub.dev/packages/ohos_icons二维码生成 qr 包https://pub.dev/packages/qr官方控件概览https://developer.huawei.com/consumer/cn/doc/doccenter-ux-design/general_overview-0000001929599380官方色彩 Token 文档https://developer.huawei.com/consumer/cn/doc/doccenter-ux-design/color-0000001776857164fvm 多版本管理https://fvm.app
