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 26，1280×2832）。环境搭建、依赖引入与构建步骤见文首「环境与版本」「安装与引入 harmony_ui」以及第九节；仓库地址：AtomGit / GitHub。

环境与版本

本文的示例与截图基于以下环境组合（2026-10 实测）：

环境搭建（分叉获取、DevEco Studio 与 SDK 配置、模拟器创建）请按官方指导操作：OpenHarmony-flutter 环境搭建指导。

harmony_ui是纯 Dart/Flutter 组件库，不依赖 ohos 平台通道；在官方 Flutter SDK 上也能运行（用于跨平台预览）。只有跑example/ohos工程、构建 HAP 时才需要上面的 OH 适配版 SDK。

安装与引入 harmony_ui

harmony_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 get

pub.dev 与 git 两种方式二选一，不要同时声明。CI 中建议固定 tag（如v0.3.0）而不是main，避免构建结果随上游漂移。harmony_ui目前只依赖qr一个三方包，ohos_icons是可选配套图标包，不引入也不影响组件使用。

一、展示类总览

展示类整体效果（gallery「展示」分类页，模拟器实机）：

展示类：OhosText全字阶、进度条、OhosBadge数字/红点、索引条、滚动条、即时反馈、数据面板、二维码、文本时钟等

二、文本 OhosText 与字阶

2.1 十三级字阶

HarmonyOS 设计语言最容易被忽略的一点：文字不是"大小随意"，而是"字阶对齐"。OhosText的level参数提供与官方一致的 13 级字阶：

OhosText('营收 128 万',level:OhosTextLevel.displayLarge);OhosText('经营周报',level:OhosTextLevel.headlineMedium);OhosText('数据来源：本地门店系统',level:OhosTextLevel.labelSmall);

• color不传时按字阶自动取主题四级文字色（90%/60%/40%/20%）；
• maxLines+overflow控制截断：卡片标题常用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),],),)

三、图片 OhosImage

OhosImage对齐官方图片规范：默认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。

五、新事件标记 OhosBadge

OhosBadge提供数字角标与红点两种形态，可包裹任意子控件（通常是图标），超过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×360vp，itemHeight默认 20vp；
• 选中字母时的放大反馈由组件内部处理，业务只需处理onSelected。

6.2 OhosScrollbar

跟随任意ScrollController的圆角拇指滚动条，替代 Flutter 原生Scrollbar的细线样式：

final_sc=ScrollController();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锚定目标控件的气泡引导，新手引导、功能说明场景：

finalpayButtonKey=GlobalKey();// 在目标控件上挂 key：ElevatedButton(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 示例应用的「展示」分类页可交互运行，最短运行路径：

1. 安装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-releasecd<harmony_ui 仓库根目录>fvm use ohos/oh-3.47.7-release fvm flutter--version# 应输出 Flutter 3.47.7-ohos-1.0.1

   fvm 的fvm install <alias>/<ref>只识别分支名，3.47.7-ohos-1.0.1是 tag，不能直接 install；按上面的方式 clone 到版本目录后fvm use即可。

2. source env.sh加载 DevEco Studio26.0.0 Release的工具链（node / ohpm / hvigor / SDK toolchains）；如果命令不可用，按文首的环境搭建指导检查DEVECO_SDK_HOME、JAVA_HOME与hdc；

3. 进入example/：fvm flutter pub get && fvm flutter create --platforms ohos .；

4. 构建并安装到模拟器：

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

gallery 主页的 7 大分类入口（展示类为其中之一）：

gallery 主页：组件、展示、操作、输入、选择、容器 6 大控件分类 + 布局与动效入口

十、最佳实践

按场景选组件的速查表：

实践要点：

• 字阶纪律：页面内文字只允许 2-3 个字阶（如 headlineMedium + bodyLarge + labelSmall），先定字阶再写页面；
• 图片统一圆角：同一页面内图片圆角保持一致（列表 8vp、卡片头图 16vp），OhosImage默认值就是规范值；
• 反馈分级：Toast / SnackBar / Popup 按"信息量 × 操作数"选型，不要混用；
• 角标稀缺：全应用同屏红点 ≤ 2 个，数字角标优先红点，“99+” 兜底；
• 时钟用组件：需要实时时间的地方用OhosTextClock，不要用Timer手动刷Text——组件内部已处理秒级定时与格式解析；
• 空态用 OhosBlank：列表为空时配合OhosBlank做垂直居中，而不是写死SizedBox(height: 300)。

十一、常见问题 FAQ

11.1flutter pub get找不到 harmony_ui？

先确认pubspec.yaml写的是harmony_ui: ^0.3.0，或按文首 git 依赖写法固定ref: v0.3.0；pub.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 官方 Flutter（Android / iOS / Web）上能用吗？

可以。harmony_ui是纯 Dart/Flutter 实现，不依赖平台通道；字体、光感与模糊的最终效果会随平台渲染能力略有差异。跨平台预览用官方 Flutter 即可，鸿蒙模拟器/真机验证请使用 3.47.7-ohos-1.0.1。

总结

展示类 13 个控件看似零散，其实共同指向一件事：信息呈现的克制与对齐。字阶 13 档、图片 8vp 圆角、进度条品牌色、角标 “99+” 兜底、气泡锚定控件——harmony_ui把这些官方细节都固化成了默认值，业务代码只需要"用"，不需要"调"。

下一篇进入操作类：按钮五种样式、下拉按钮、状态按钮、操作块、工具栏、核心操作栏与菜单，把"用户主动交互"的入口一次讲全。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：

• harmony_ui 仓库（AtomGit）：https://atomgit.com/oh-flutter/harmony_ui
• harmony_ui 仓库（GitHub）：https://github.com/shaohushuo/harmony_ui
• harmony_ui pub.dev 发布页：https://pub.dev/packages/harmony_ui
• Flutter OH 适配版（3.47.7-ohos-1.0.1）：https://atomgit.com/oh-flutter/flutter_flutter
• Flutter 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.md
• DevEco Studio 官方页面（本文使用 26.0.0 Release）：https://developer.huawei.com/consumer/cn/deveco-studio/
• 鸿蒙社区 Flutter 分叉：https://atomgit.com/oh-flutter/flutter_flutter
• 配套图标包 ohos_icons：https://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-0000001776857164
• fvm 多版本管理：https://fvm.app