Flutter三方庫適配OpenHarmony【harmony_ui】展示類控件實(shí)戰(zhàn)文本字階、圖片、進(jìn)度、徽標(biāo)與數(shù)據(jù)可視化前言harmony_ui是 Material/Cupertino 風(fēng)格的 Flutter 組件庫完整實(shí)現(xiàn)了HarmonyOS 設(shè)計語言覆蓋官方「控件概覽」6 大類 42 個控件并額外實(shí)現(xiàn)了沉浸光感材質(zhì)與 UI Design Kit 增強(qiáng)能力。本系列按官方控件類別逐類實(shí)戰(zhàn)上一篇講了導(dǎo)航類標(biāo)題欄/子頁簽/底部頁簽/輪播本篇是第 2 篇展示類。展示類是 6 大類中控件數(shù)量最多的一類13 個文本/子標(biāo)題、圖片、分隔器、進(jìn)度條、新事件標(biāo)記、索引條、滾動條、即時反饋、氣泡提示、數(shù)據(jù)可視化、二維碼、空白、文本時鐘。它們決定了頁面的信息呈現(xiàn)質(zhì)感——字階是否分明、圖片圓角是否規(guī)范、徽標(biāo)紅點(diǎn)是否克制鴻蒙視覺的細(xì)節(jié)基本都藏在這一類里。所有示例代碼都在OpenHarmony 模擬器上直接運(yùn)行驗證Flutter3.47.7-ohos-1.0.1 DevEco Studio26.0.0 Release截圖環(huán)境API 261280×2832。環(huán)境搭建、依賴引入與構(gòu)建步驟見文首「環(huán)境與版本」「安裝與引入 harmony_ui」以及第九節(jié)倉庫地址AtomGit / GitHub。環(huán)境與版本本文的示例與截圖基于以下環(huán)境組合2026-10 實(shí)測組件版本說明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運(yùn)行設(shè)備OpenHarmony 模擬器API 261280×2832環(huán)境搭建分叉獲取、DevEco Studio 與 SDK 配置、模擬器創(chuàng)建請按官方指導(dǎo)操作OpenHarmony-flutter 環(huán)境搭建指導(dǎo)。harmony_ui是純 Dart/Flutter 組件庫不依賴 ohos 平臺通道在官方 Flutter SDK 上也能運(yùn)行用于跨平臺預(yù)覽。只有跑example/ohos工程、構(gòu)建 HAP 時才需要上面的 OH 適配版 SDK。安裝與引入 harmony_uiharmony_ui已發(fā)布到 pub.dev當(dāng)前最新版本是0.3.0。在應(yīng)用工程的pubspec.yaml中聲明dependencies:flutter:sdk:flutterharmony_ui:^0.3.0然后拉取依賴fvm flutter pub get如果團(tuán)隊需要固定到倉庫的某個提交例如使用尚未發(fā)版的修復(fù)改用 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避免構(gòu)建結(jié)果隨上游漂移。harmony_ui目前只依賴qr一個三方包ohos_icons是可選配套圖標(biāo)包不引入也不影響組件使用。一、展示類總覽官方控件實(shí)現(xiàn)一句話說明文本 / 子標(biāo)題OhosText/OhosSubheader13 級字階 / 列表分組標(biāo)題圖片OhosImage默認(rèn) 8vp 圓角、選中描邊、占位圖分隔器OhosDivider列表內(nèi)細(xì)分隔線進(jìn)度條OhosProgressIndicator圓形無限 / 線性有值兩種新事件標(biāo)記OhosBadge數(shù)字角標(biāo) / 紅點(diǎn)掛圖標(biāo)和頁簽索引條OhosAlphabetIndexerA-Z 側(cè)邊索引條滾動條OhosScrollbar跟隨 ScrollController 的圓角拇指即時反饋showOhosToast輕量 Toast支持圖標(biāo)即時操作showOhosSnackBar消息 操作撤銷等氣泡提示showOhosPopup錨定控件的氣泡引導(dǎo)數(shù)據(jù)可視化OhosDataPanel標(biāo)題 指標(biāo)網(wǎng)格面板二維碼OhosQrCode內(nèi)置二維碼生成qr 包空白 / 文本時鐘OhosBlank/OhosTextClock彈性空白 / 實(shí)時時鐘文本展示類整體效果gallery「展示」分類頁模擬器實(shí)機(jī)展示類OhosText全字階、進(jìn)度條、OhosBadge數(shù)字/紅點(diǎn)、索引條、滾動條、即時反饋、數(shù)據(jù)面板、二維碼、文本時鐘等二、文本 OhosText 與字階2.1 十三級字階HarmonyOS 設(shè)計語言最容易被忽略的一點(diǎn)文字不是大小隨意而是字階對齊。OhosText的level參數(shù)提供與官方一致的 13 級字階字階字號典型用途displayLarge36sp首頁超大數(shù)字統(tǒng)計值displayMedium32sp大數(shù)字展示headlineLarge28sp頁面主標(biāo)題headlineMedium24sp章節(jié)標(biāo)題titleLarge20sp卡片標(biāo)題titleMedium17sp次級標(biāo)題titleSmall16sp小標(biāo)題bodyLarge16sp正文默認(rèn)bodyMedium15sp次級正文bodySmall14sp輔助正文labelLarge16sp大號標(biāo)簽按鈕文字labelMedium14sp中號標(biāo)簽labelSmall12sp小號標(biāo)簽角標(biāo)說明OhosText(營收 128 萬,level:OhosTextLevel.displayLarge);OhosText(經(jīng)營周報,level:OhosTextLevel.headlineMedium);OhosText(數(shù)據(jù)來源本地門店系統(tǒng),level:OhosTextLevel.labelSmall);color不傳時按字階自動取主題四級文字色90%/60%/40%/20%maxLinesoverflow控制截斷卡片標(biāo)題常用maxLines: 1, overflow: TextOverflow.ellipsis非鴻蒙平臺自動回退系統(tǒng)字體鴻蒙設(shè)備上使用原生HarmonyOS Sans。2.2 子標(biāo)題 OhosSubheader列表分組標(biāo)題設(shè)置頁的通用網(wǎng)絡(luò)等分組行用OhosSubheader支持尾部文案與點(diǎn)擊OhosSubheader(title:推薦,trailing:更多,onTrailingTap:_openMore,)提示字階是檔位不是建議值——同一個 App 里正文應(yīng)始終用bodyLarge/bodyMedium不要為了看起來更大隨意跳級這是鴻蒙設(shè)計語言克制的來源。2.3 字階組合完整示例一個統(tǒng)計卡片頁的完整字階搭配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對齊官方圖片規(guī)范默認(rèn)8vp 圓角、BoxFit.cover裁切內(nèi)置選中描邊與占位圖// 基礎(chǔ)用法OhosImage(image:NetworkImage(https://example.com/cover.png),width:120,height:120,)// 選中態(tài)品牌色描邊圖片選擇器場景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默認(rèn)取主題小圓角 8vp橫幅圖可傳 16輪播/九宮格等場景與OhosSwiper、OhosGrid組合使用導(dǎo)航類與容器類篇有示例。四、進(jìn)度條 OhosProgressIndicator兩種形態(tài)圓形無限加載與線性有值進(jìn)度均為靜態(tài)構(gòu)造器直接創(chuàng)建// 圓形無限轉(zhuǎn)圈加載態(tài)constOhosProgressIndicator.circular()// 線性0-1 進(jìn)度值下載/上傳OhosProgressIndicator.linear(value:0.6)顏色默認(rèn)取主題品牌色直徑與線寬對齊官方規(guī)范按鈕內(nèi)置加載態(tài)OhosButton(loading: true)內(nèi)部就是圓形進(jìn)度不需要自己拼Row。五、新事件標(biāo)記 OhosBadgeOhosBadge提供數(shù)字角標(biāo)與紅點(diǎn)兩種形態(tài)可包裹任意子控件通常是圖標(biāo)超過maxCount顯示 “99”// 數(shù)字角標(biāo)包裹一個圖標(biāo)OhosBadge(count:5,child:constIcon(Icons.chat_bubble_outline),)// 紅點(diǎn)無數(shù)字的新事件提示OhosBadge(isDot:true,child:constIcon(Icons.notifications_none),)// 掛在底部頁簽上見導(dǎo)航類篇OhosNavigationDestination(icon:constIcon(Icons.person_outline),label:我的,badge:constOhosBadge(count:5),)maxCount默認(rèn) 99超出顯示 “99”offset微調(diào)角標(biāo)位置color默認(rèn)取主題功能色紅色系?？酥圃瓌t同屏紅點(diǎn)最多 1-2 個。全應(yīng)用所有圖標(biāo)都掛角標(biāo)等于沒有角標(biāo)——鴻蒙設(shè)計語言對新事件標(biāo)記的定位是稀缺信號不是裝飾。六、索引條與滾動條6.1 OhosAlphabetIndexer聯(lián)系人列表標(biāo)配的 A-Z 側(cè)邊索引條滑動/點(diǎn)擊回傳字母配合OhosSubheader分組實(shí)現(xiàn)跳轉(zhuǎn)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默認(rèn) 24×360vpitemHeight默認(rèn) 20vp選中字母時的放大反饋由組件內(nèi)部處理業(yè)務(wù)只需處理onSelected。6.2 OhosScrollbar跟隨任意ScrollController的圓角拇指滾動條替代 Flutter 原生Scrollbar的細(xì)線樣式final_scScrollController();OhosScrollbar(controller:_sc,thumbRadius:4,// 拇指圓角thickness:8,// 拇指粗細(xì)child:ListView.builder(controller:_sc,itemCount:200,itemBuilder:(_,int i)OhosListTile(title:Text(條目$i)),),)七、即時反饋與氣泡提示7.1 showOhosToast 即時反饋輕量 Toast居中/頂部短暫提示支持圖標(biāo)配 ohos_icons 字體圖標(biāo)showOhosToast(context,操作成功,icon:OhosIcons.checkmark_circle_fill);7.2 showOhosSnackBar 即時操作比 Toast 多一個操作位撤銷/查看詳情懸浮顯示、可配背景色resident: true常駐模式見系列第 7 篇增強(qiáng)類showOhosSnackBar(context,message:已刪除 1 個文件,actionLabel:撤銷,onAction:()showOhosToast(context,已撤銷),);7.3 showOhosPopup 氣泡提示通過GlobalKey錨定目標(biāo)控件的氣泡引導(dǎo)新手引導(dǎo)、功能說明場景finalpayButtonKeyGlobalKey();// 在目標(biāo)控件上掛 keyElevatedButton(key:payButtonKey,onPressed:_pay,child:constText(支付));// 展示氣泡showOhosPopup(context:context,content:長按掃碼支付,targetKey:payButtonKey,);氣泡提示實(shí)機(jī)效果showOhosPopup氣泡提示錨定目標(biāo)控件圓角氣泡 指向箭頭反饋三件套的選型一句話無操作 → Toast一句話 一個操作 → SnackBar要指著某個控件說 → Popup。選錯通道是展示類最常見的手感不對來源。八、數(shù)據(jù)可視化、二維碼與工具小組件8.1 OhosDataPanel標(biāo)題 指標(biāo)網(wǎng)格的數(shù)據(jù)面板統(tǒng)計頁/儀表盤直接可用支持千分位小數(shù)與前后綴OhosDataPanel(title:經(jīng)營數(shù)據(jù),entries:const{營收:128,訂單:356,客單價:36,好評率:98.6,},columns:2,decimals:1,prefix:￥,)8.2 OhosQrCode內(nèi)置二維碼生成基于 qr 包也是harmony_ui唯一第三方依賴OhosQrCode(data:https://atomgit.com/oh-flutter/harmony_ui,size:160,)8.3 OhosTextClock、OhosBlank 與 OhosDivider三個小而美的工具組件// 實(shí)時文本時鐘每秒刷新支持 y/M/d/H/m/s 格式 tokenOhosTextClock(format:yyyy年MM月dd日 HH:mm,textStyle:constTextStyle(fontSize:28,fontWeight:FontWeight.w300),)// 彈性空白有限空間內(nèi)填滿剩余高度把后續(xù)子項推到底部Column(children:[constOhosText(頂部內(nèi)容),constOhosBlank(),constOhosText(底部操作區(qū)),])// 分隔器列表內(nèi)細(xì)分隔線constOhosDivider()九、在鴻蒙模擬器上運(yùn)行展示類全部控件在 gallery 示例應(yīng)用的「展示」分類頁可交互運(yùn)行最短運(yùn)行路徑安裝3.47.7-ohos-1.0.1的 OH 適配版 SDK。該版本在倉庫里是 git tag按 tag 淺克隆到 fvm 版本目錄后在工程內(nèi)切換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# 應(yīng)輸出 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如果命令不可用按文首的環(huán)境搭建指導(dǎo)檢查DEVECO_SDK_HOME、JAVA_HOME與hdc進(jìn)入example/fvm flutter pub get fvm flutter create --platforms ohos .構(gòu)建并安裝到模擬器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 大控件分類 布局與動效入口十、最佳實(shí)踐按場景選組件的速查表場景推薦組件備注頁面主標(biāo)題OhosText(headlineLarge/Medium)一屏最多一個卡片內(nèi)數(shù)字OhosText(displayLarge)labelMedium說明大數(shù)字配小單位列表分組標(biāo)題OhosSubheader支持尾部更多封面/頭像OhosImage列表 8vp、頭圖 16vp 圓角加載等待OhosProgressIndicator.circular()按鈕內(nèi)用loading: true任務(wù)進(jìn)度OhosProgressIndicator.linear(value:)0-1 值新事件OhosBadge數(shù)字優(yōu)先、紅點(diǎn)兜底聯(lián)系人定位OhosAlphabetIndexer配合分組列表長列表滾動OhosScrollbar掛 ScrollController輕提示showOhosToast一句話、無操作可撤銷操作showOhosSnackBar帶操作位功能引導(dǎo)showOhosPopup錨定 GlobalKey統(tǒng)計面板OhosDataPanel指標(biāo)網(wǎng)格分享碼OhosQrCode內(nèi)置生成時間顯示OhosTextClock別自己起 Timer實(shí)踐要點(diǎn)字階紀(jì)律頁面內(nèi)文字只允許 2-3 個字階如 headlineMedium bodyLarge labelSmall先定字階再寫頁面圖片統(tǒng)一圓角同一頁面內(nèi)圖片圓角保持一致列表 8vp、卡片頭圖 16vpOhosImage默認(rèn)值就是規(guī)范值反饋分級Toast / SnackBar / Popup 按信息量 × 操作數(shù)選型不要混用角標(biāo)稀缺全應(yīng)用同屏紅點(diǎn) ≤ 2 個數(shù)字角標(biāo)優(yōu)先紅點(diǎn)“99” 兜底時鐘用組件需要實(shí)時時間的地方用OhosTextClock不要用Timer手動刷Text——組件內(nèi)部已處理秒級定時與格式解析空態(tài)用 OhosBlank列表為空時配合OhosBlank做垂直居中而不是寫死SizedBox(height: 300)。十一、常見問題 FAQ11.1flutter pub get找不到 harmony_ui先確認(rèn)pubspec.yaml寫的是harmony_ui: ^0.3.0或按文首 git 依賴寫法固定ref: v0.3.0pub.dev 與 git 兩種方式不要同時聲明。改完后執(zhí)行fvm flutter clean fvm flutter pub get仍異常時刪除pubspec.lock與.dart_tool/重試不要手改鎖文件。11.2 組件顏色、字階與截圖不一致通常是沒有注入主題。OhosTheme要包住頁面根節(jié)點(diǎn)MaterialApp.home或builder組件通過OhosTheme.of(context)讀取 Token只 import 組件庫不會自動注入。確認(rèn)后再檢查是否顯式覆蓋了顏色或字階參數(shù)。11.3 13 級字階應(yīng)該用哪幾檔同一個頁面控制在 2–3 檔標(biāo)題用headlineMedium/titleLarge正文用bodyLarge/bodyMedium說明文字用labelSmall。字階是版式層級而不是字號菜單不要為了看起來更大隨意跨檔。11.4 長文本溢出、卡片標(biāo)題被撐開OhosText支持maxLines與overflow卡片標(biāo)題固定maxLines: 1, overflow: TextOverflow.ellipsis多行正文用bodyLarge正常換行不要用固定高度容器硬裁。11.5OhosQrCode還要單獨(dú)安裝qr嗎不需要。harmony_ui已把qr作為唯一三方依賴內(nèi)置業(yè)務(wù)工程只要引入harmony_ui即可生成二維碼只有項目里另外直接調(diào)用qrAPI 時才需要自己聲明。11.6 Toast / SnackBar / Popup 不顯示三者都依賴當(dāng)前的Overlay/Navigator確認(rèn)調(diào)用發(fā)生在MaterialApp之內(nèi)的頁面上下文showOhosPopup還需要目標(biāo)控件的GlobalKey且目標(biāo)已完成布局。頁面銷毀后的異步回調(diào)會被丟棄先判斷mounted。11.7 構(gòu)建時報npm not found、hvigor不存在或DEVECO_SDK_HOME錯誤說明 DevEco 工具鏈沒有進(jìn)入 PATH。執(zhí)行source env.sh按 DevEco Studio 26.0.0 Release 的默認(rèn)安裝路徑配置確認(rèn)node、ohpm、hvigor、hdc都可執(zhí)行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安裝。真機(jī)安裝與flutter run熱重載需要調(diào)試證書簽名。11.9 官方 FlutterAndroid / iOS / Web上能用嗎可以。harmony_ui是純 Dart/Flutter 實(shí)現(xiàn)不依賴平臺通道字體、光感與模糊的最終效果會隨平臺渲染能力略有差異?？缙脚_預(yù)覽用官方 Flutter 即可鴻蒙模擬器/真機(jī)驗證請使用 3.47.7-ohos-1.0.1?？偨Y(jié)展示類 13 個控件看似零散其實(shí)共同指向一件事信息呈現(xiàn)的克制與對齊。字階 13 檔、圖片 8vp 圓角、進(jìn)度條品牌色、角標(biāo) “99” 兜底、氣泡錨定控件——harmony_ui把這些官方細(xì)節(jié)都固化成了默認(rèn)值業(yè)務(wù)代碼只需要用不需要調(diào)。下一篇進(jìn)入操作類按鈕五種樣式、下拉按鈕、狀態(tài)按鈕、操作塊、工具欄、核心操作欄與菜單把用戶主動交互的入口一次講全。如果這篇文章對你有幫助歡迎點(diǎn)贊、收藏?、關(guān)注你的支持是我持續(xù)創(chuàng)作的動力相關(guān)資源harmony_ui 倉庫AtomGithttps://atomgit.com/oh-flutter/harmony_uiharmony_ui 倉庫GitHubhttps://github.com/shaohushuo/harmony_uiharmony_ui pub.dev 發(fā)布頁https://pub.dev/packages/harmony_uiFlutter OH 適配版3.47.7-ohos-1.0.1https://atomgit.com/oh-flutter/flutter_flutterFlutter OH 環(huán)境搭建指導(dǎo)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/鴻蒙社區(qū) Flutter 分叉https://atomgit.com/oh-flutter/flutter_flutter配套圖標(biāo)包 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