前言harmony_ui是 Material/Cupertino 風(fēng)格的 Flutter 組件庫完整實(shí)現(xiàn)了HarmonyOS 設(shè)計(jì)語言覆蓋官方「控件概覽」6 大類 42 個(gè)控件并額外實(shí)現(xiàn)了沉浸光感材質(zhì)與 UI Design Kit 增強(qiáng)能力。本系列按官方控件類別逐類實(shí)戰(zhàn)前五篇分別是導(dǎo)航類、展示類、操作類、輸入類、選擇類本篇是第 6 篇容器類。容器類是裝內(nèi)容的殼列表/列表項(xiàng)OhosList/OhosListTile承載信息流與設(shè)置頁卡片OhosCard是信息流的單元彈出框showOhosDialog、氣泡showOhosPopup、半模態(tài)showOhosBottomSheet是內(nèi)容之外的第二層空間。其中半模態(tài)面板默認(rèn)使用ULTRA_THICK 沉浸光感材質(zhì)是容器類與第 7 篇增強(qiáng)類的交匯點(diǎn)。所有示例代碼都在OpenHarmony 模擬器上直接運(yùn)行驗(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í)測(cè)組件版本說明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)建請(qǐng)按官方指導(dǎo)操作OpenHarmony-flutter 環(huán)境搭建指導(dǎo)。harmony_ui是純 Dart/Flutter 組件庫不依賴 ohos 平臺(tái)通道在官方 Flutter SDK 上也能運(yùn)行用于跨平臺(tái)預(yù)覽。只有跑example/ohos工程、構(gòu)建 HAP 時(shí)才需要上面的 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)隊(duì)需要固定到倉庫的某個(gè)提交例如使用尚未發(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 兩種方式二選一不要同時(shí)聲明。CI 中建議固定 tag如v0.3.0而不是main避免構(gòu)建結(jié)果隨上游漂移。harmony_ui目前只依賴qr一個(gè)三方包ohos_icons是可選配套圖標(biāo)包不引入也不影響組件使用。一、容器類總覽官方控件實(shí)現(xiàn)一句話說明列表 / 列表項(xiàng)OhosList/OhosListTile分組列表選中態(tài)/危險(xiǎn)項(xiàng)卡片OhosCard24vp 大圓角按壓反饋彈出框OhosAlertDialog/showOhosDialog雙按鈕確認(rèn)危險(xiǎn)操作紅色氣泡提示showOhosPopup錨定控件的功能引導(dǎo)半模態(tài)面板showOhosBottomSheetULTRA_THICK 光感材質(zhì)布局容器柵格/響應(yīng)式OhosGrid/OhosResponsiveBuilder4/8/12 列斷點(diǎn)布局增強(qiáng)橫滑列表項(xiàng)OhosListItem左滑操作整劃刪除容器類整體效果gallery「容器」分類頁模擬器實(shí)機(jī)容器類OhosList分組列表、OhosCard卡片、showOhosDialog彈出框、showOhosBottomSheet光感半模態(tài)面板二、列表 OhosList 與列表項(xiàng)2.1 分組列表OhosList是分組標(biāo)題 列表項(xiàng) 分隔線的組合容器設(shè)置頁標(biāo)準(zhǔn)形態(tài)。header傳OhosSubheader支持尾部更多OhosList(header:constOhosSubheader(title:通用),children:[OhosListTile(leading:constIcon(Icons.wifi),title:constText(無線網(wǎng)絡(luò)),subtitle:constText(已連接),trailing:constIcon(Icons.chevron_right),onTap:_openWifi,),constOhosDivider(),OhosListTile(leading:constIcon(Icons.bluetooth),title:constText(藍(lán)牙),trailing:constIcon(Icons.chevron_right),onTap:_openBluetooth,),],)OhosListTile四區(qū)結(jié)構(gòu)leading / title / subtitle / trailing與ListTile一致行高、內(nèi)邊距、分隔線全部按官方規(guī)范內(nèi)置。2.2 選中態(tài)與危險(xiǎn)項(xiàng)列表項(xiàng)內(nèi)置兩個(gè)官方狀態(tài)selected品牌色高亮表示當(dāng)前項(xiàng)與danger危險(xiǎn)操作紅色文字OhosList(header:constOhosSubheader(title:通知),children:[OhosListTile(leading:constIcon(Icons.push_pin_outlined),title:constText(消息推送),selected:true,// 選中態(tài)品牌色高亮trailing:OhosSwitch(value:_push,onChanged:_onPush),),constOhosDivider(),OhosListTile(leading:constIcon(Icons.delete_outline),title:constText(清空聊天記錄),danger:true,// 危險(xiǎn)項(xiàng)紅色onTap:_clearChat,),],)長列表場(chǎng)景用ListView.builderOhosListTile手工拼裝OhosList適合短列表直鋪列表項(xiàng)按壓反饋10% 黑疊加內(nèi)置無需InkWell包裹。三、卡片 OhosCard3.1 基礎(chǔ)卡片OhosCard對(duì)齊官方卡片規(guī)范24vp 大圓角、分層背景comp_background_primary白底、按壓反饋默認(rèn)內(nèi)邊距 16vpOhosCard(onTap:_openDetail,child:constColumn(crossAxisAlignment:CrossAxisAlignment.start,children:[OhosText(卡片標(biāo)題,level:OhosTextLevel.titleLarge),SizedBox(height:8),OhosText(卡片摘要文字最多兩行超出省略。,level:OhosTextLevel.bodyMedium),],),)elevation默認(rèn) 0鴻蒙卡片靠背景分層而非投影特殊場(chǎng)景可加margin/color可覆蓋默認(rèn)值灰底卡片用theme.compBackgroundGrayColor。3.2 圖片卡片信息流單元的標(biāo)準(zhǔn)結(jié)構(gòu)頭圖 標(biāo)題 摘要 尾部信息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(文章標(biāo)題,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 卡片內(nèi)圖片 20~16vp 圖片內(nèi)元素 8vp——圓角逐級(jí)遞減是鴻蒙嵌套容器的視覺慣例OhosImage默認(rèn) 8vp 正好對(duì)應(yīng)最內(nèi)層。四、彈出框 showOhosDialogshowOhosDialog返回FutureOhosDialogAction支持danger危險(xiǎn)色對(duì)齊官方彈出框規(guī)范finalbool?okawaitshowOhosDialogbool(context:context,title:刪除文件,content:刪除后無法恢復(fù)請(qǐng)確認(rèn)是否繼續(xù)。,actions:[OhosDialogAction(label:取消,onPressed:()Navigator.pop(context,false),),OhosDialogAction(label:刪除,danger:true,onPressed:()Navigator.pop(context,true),),],);場(chǎng)景標(biāo)題按鈕組合備注破壞性確認(rèn)具體后果取消 危險(xiǎn)操作刪除/清空/退訂普通確認(rèn)動(dòng)作名取消 確定提交/退出登錄信息告知結(jié)果單按鈕知道了操作完成提示選擇問題多選項(xiàng)2-3 個(gè)互斥選項(xiàng)對(duì)話框內(nèi)容保持標(biāo)題 兩行內(nèi)說明長內(nèi)容改用半模態(tài)返回值為最后一個(gè)Navigator.pop的值未操作點(diǎn)遮罩按默認(rèn)策略處理。彈出框?qū)崣C(jī)效果showOhosDialog彈出框標(biāo)題、內(nèi)容、取消/危險(xiǎn)刪除雙操作五、氣泡提示 showOhosPopupshowOhosPopup通過GlobalKey錨定目標(biāo)控件顯示圓角氣泡 指向箭頭用于新手引導(dǎo)與功能說明展示類篇有基本用法這里講組合模式finalguideKeyGlobalKey();// 分步引導(dǎo)第 1 步指向搜索框showOhosPopup(context:context,content:在這里搜索全部內(nèi)容,targetKey:guideKey,);多個(gè)引導(dǎo)步驟時(shí)業(yè)務(wù)側(cè)維護(hù)步驟索引每步換一個(gè)targetKey氣泡與OhosBadge紅點(diǎn)配合紅點(diǎn)吸引注意 氣泡說明功能是標(biāo)準(zhǔn)引導(dǎo)組合引導(dǎo)狀態(tài)是否已展示過用本地存儲(chǔ)記錄避免每次啟動(dòng)重復(fù)彈。六、半模態(tài)面板 showOhosBottomSheet6.1 基本半模態(tài)showOhosBottomSheet從底部滑出半模態(tài)面板默認(rèn) ULTRA_THICK 光感材質(zhì)40vp sigma適合分享面板、篩選面板、信息預(yù)覽awaitshowOhosBottomSheet(context:context,title:分享到,content:SizedBox(height:200,child:Row(mainAxisAlignment:MainAxisAlignment.spaceEvenly,children:const[// 分享入口圖標(biāo)],),),)dismissLabel提供底部關(guān)閉按鈕文案如完成不傳則無showCloseButton控制標(biāo)題欄右上角關(guān)閉圖標(biāo)默認(rèn) true返回Futurevoid關(guān)閉即返回需要結(jié)果的場(chǎng)景用共享 State 或改造為FutureBuilder。6.2 光感調(diào)參需要更通透或更厚重的半模態(tài)時(shí)脫離便捷函數(shù)直接用OhosLightMaterial包自己的面板完整原理見第 7 篇增強(qiáng)類// 更通透模糊與光池減弱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,)半模態(tài)面板實(shí)機(jī)效果showOhosBottomSheet半模態(tài)面板ULTRA_THICK 光感材質(zhì) 底部滑出七、布局容器 OhosGrid 與 OhosResponsiveBuilder容器類的隱藏成員官方布局規(guī)范柵格/斷點(diǎn)在harmony_ui里由兩個(gè)布局組件實(shí)現(xiàn)。7.1 柵格 OhosGrid斷點(diǎn)決定列數(shù)600vp 四列 / 600-840vp 八列 / ≥840vp 十二列OhosGridItem(columnSpan:)按列跨排布內(nèi)容最大寬度 2220vpOhosGrid(children:[OhosGridItem(columnSpan:2,child:cardA),OhosGridItem(columnSpan:2,child:cardB),OhosGridItem(columnSpan:4,child:bannerCard),// 通欄],)7.2 響應(yīng)式 OhosResponsiveBuilderOhosResponsiveBuilder依據(jù)窗口寬度重建子樹挪移/折行/分欄的響應(yīng)式策略都建立在它之上?；卣{(diào)拿到OhosWindowSize對(duì)象除type外還直接給出當(dāng)前斷點(diǎn)的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是便捷布爾值簡(jiǎn)單判斷不用解枚舉size.useSideTab≥840vp 為 true寬屏建議切換側(cè)邊頁簽OhosSideBar見第 7 篇size.pagePadding直接返回當(dāng)前斷點(diǎn)的水平內(nèi)邊距頁面根部套一層即可對(duì)齊規(guī)范。柵格與斷點(diǎn)演示實(shí)機(jī)效果布局與動(dòng)效柵格系統(tǒng)、響應(yīng)式斷點(diǎn)1/2/4 列切換與沉浸光感入口八、橫滑列表項(xiàng) OhosListItem列表項(xiàng)的增強(qiáng)形態(tài)——左滑顯示操作按鈕、整劃刪除fullDelete屬于 UI Design Kit 能力完整用法見第 7 篇增強(qiáng)類這里給出容器視角的集成方式// 在 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]),),),)整劃刪除閾值、越界自動(dòng)回調(diào)由組件內(nèi)部處理橫滑與列表滾動(dòng)手勢(shì)的沖突已做仲裁橫向滑動(dòng)不會(huì)被豎向滾動(dòng)吃掉。九、在鴻蒙模擬器上運(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只識(shí)別分支名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_example半模態(tài)的光感材質(zhì)依賴BackdropFilter在模擬器上渲染正常真機(jī)如遇模糊邊緣異常優(yōu)先關(guān)閉scatterScale漫射再排查而不是降模糊檔位。十、最佳實(shí)踐容器類控件的選型速查場(chǎng)景推薦容器備注設(shè)置頁OhosListOhosSubheader分組短列表直鋪長列表ListView.builderOhosListTile分頁/懶加載信息流單元OhosCard24vp 圓角圓角逐級(jí)遞減確認(rèn)/選擇showOhosDialog標(biāo)題 兩行內(nèi)功能引導(dǎo)showOhosPopup 紅點(diǎn)狀態(tài)本地記錄分享/篩選showOhosBottomSheetULTRA_THICK 光感寬屏網(wǎng)格OhosGridOhosGridItem4/8/12 列斷點(diǎn)響應(yīng)式重構(gòu)OhosResponsiveBuilder三檔斷點(diǎn)重建列表行操作OhosListItem左滑 整劃刪除實(shí)踐要點(diǎn)第二層空間選型信息 ≤2 行用對(duì)話框需要操作區(qū)/滾動(dòng)區(qū)用半模態(tài)指著控件說用氣泡——三層空間各司其職卡片零投影鴻蒙卡片層次靠背景分層白卡 灰底elevation默認(rèn)保持 0投影是 Material 思維半模態(tài)結(jié)果回傳showOhosBottomSheet返回void需要結(jié)果時(shí)用全局狀態(tài)或事件總線別在content里塞回調(diào)地獄橫滑刪除加撤銷onFullDelete后跟一個(gè)showOhosSnackBar(撤銷)誤刪成本直接歸零斷點(diǎn)先想清楚用OhosResponsiveBuilder前先在紙上畫三檔斷點(diǎn)的布局草圖避免代碼里堆滿if (width 840)。十一、常見問題 FAQ11.1flutter pub get找不到 harmony_ui先確認(rèn)pubspec.yaml寫的是harmony_ui: ^0.3.0或按文首 git 依賴寫法固定ref: v0.3.0pub.dev 與 git 兩種方式不要同時(shí)聲明。改完后執(zhí)行fvm flutter clean fvm flutter pub get仍異常時(shí)刪除pubspec.lock與.dart_tool/重試不要手改鎖文件。11.2 組件顏色、字階與截圖不一致通常是沒有注入主題。OhosTheme要包住頁面根節(jié)點(diǎn)MaterialApp.home或builder組件通過OhosTheme.of(context)讀取 Token只 import 組件庫不會(huì)自動(dòng)注入。確認(rèn)后再檢查是否顯式覆蓋了顏色或字階參數(shù)。11.3showOhosDialog里 setState 報(bào)錯(cuò)或彈窗不關(guān)閉異步確認(rèn)后先判斷mounted再更新頁面狀態(tài)并用Navigator.pop(context, result)關(guān)閉彈窗不要在彈窗內(nèi)容里直接操作已被銷毀的頁面State。11.4showOhosBottomSheet怎么把選擇結(jié)果帶回頁面它返回void不承載返回值。需要結(jié)果時(shí)在面板內(nèi)更新全局狀態(tài)、Provider/Bloc或通過事件回調(diào)把結(jié)果寫回頁面別在content里堆回調(diào)鏈。11.5 卡片內(nèi)圖片圓角看起來不對(duì)遵循圓角逐級(jí)遞減卡片 24vp 卡內(nèi)圖片 16–20vp 圖片內(nèi)元素 8vp。OhosImage默認(rèn) 8vp放進(jìn)卡片時(shí)按層級(jí)覆蓋不要給整張卡片再套一層裁剪。11.6OhosListItem左滑與頁面橫滑手勢(shì)沖突橫滑列表項(xiàng)應(yīng)放在縱向列表內(nèi)避免再嵌套橫向PageView同一行只保留一個(gè)左滑操作區(qū)整劃刪除與按鈕刪除不要同時(shí)啟用。11.7 構(gòu)建時(shí)報(bào)npm not found、hvigor不存在或DEVECO_SDK_HOME錯(cuò)誤說明 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 模擬器安裝失敗或提示簽名錯(cuò)誤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)不依賴平臺(tái)通道字體、光感與模糊的最終效果會(huì)隨平臺(tái)渲染能力略有差異。跨平臺(tái)預(yù)覽用官方 Flutter 即可鴻蒙模擬器/真機(jī)驗(yàn)證請(qǐng)使用 3.47.7-ohos-1.0.1?？偨Y(jié)容器類是殼的藝術(shù)列表裝信息、卡片裝單元、對(duì)話框/半模態(tài)/氣泡裝第二層空間柵格與斷點(diǎn)裝響應(yīng)式。harmony_ui把 24vp 卡片圓角、分組列表行高、ULTRA_THICK 光感半模態(tài)這些官方細(xì)節(jié)都固化成了默認(rèn)值六大類別至此全部講完加上第 7 篇增強(qiáng)類沉浸光感 UI Design Kit整個(gè)harmony_ui的組件版圖就完整了。至此本系列 7 篇全部完結(jié)導(dǎo)航、展示、操作、輸入、選擇、容器六大類別 增強(qiáng)類收官。所有代碼可在倉庫example/的 gallery 應(yīng)用中交互驗(yàn)證歡迎在 OpenHarmony 模擬器上跑起來。如果這篇文章對(duì)你有幫助歡迎點(diǎn)贊、收藏?、關(guān)注你的支持是我持續(xù)創(chuàng)作的動(dòng)力相關(guān)資源harmony_ui 倉庫AtomGitoh-flutter/harmony_uiharmony_ui 倉庫GitHubshaohushuo/harmony_ui鴻蒙社區(qū) Flutter 分叉CPF-Flutter/flutter_flutter配套圖標(biāo)包 ohos_iconspub.dev/packages/ohos_icons官方控件概覽42 控件清單general_overview官方布局基礎(chǔ)柵格/斷點(diǎn)design-layout-basics官方沉浸光感半模態(tài)材質(zhì)依據(jù)immersivelightfvm 多版本管理fvm.app