Flutter三方庫適配OpenHarmony【harmony_ui】選擇類控件實(shí)戰(zhàn)勾選、單選、開關(guān)、評(píng)分、滑動(dòng)條與顏色選擇器前言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)航類、展示類、操作類、輸入類本篇是第 5 篇選擇類。選擇類解決的是從選項(xiàng)里挑的問題官方共 6 個(gè)控件勾選框/單選按鈕/開關(guān)三件套、評(píng)分條OhosRatingBar、滑動(dòng)條OhosSlider、選擇器showOhosPicker外加顏色選擇器OhosColorPicker與分段按鈕OhosSegmentedButton兩個(gè)增強(qiáng)項(xiàng)。這一類控件的 API 與 Flutter 內(nèi)置組件高度一致但單選按鈕的簽名與 Material 不同不是 groupValue 模式遷移時(shí)要特別注意。所有示例代碼都在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í)測組件版本說明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)一句話說明勾選框OhosCheckbox多選圓角邊框單選按鈕OhosRadio單選注意非 groupValue 模式開關(guān)OhosSwitch50×30 膠囊開關(guān)評(píng)分條OhosRatingBar星級(jí)評(píng)分點(diǎn)擊當(dāng)前星減一滑動(dòng)條OhosSlider刻度 拖動(dòng)氣泡數(shù)值選擇器showOhosPicker底部彈層選擇Future 返回增強(qiáng)分段按鈕OhosSegmentedButton2-N 段互斥切換增強(qiáng)顏色選擇器OhosColorPicker網(wǎng)格/光譜/滑塊三模式 收藏選擇類整體效果gallery「選擇」分類頁模擬器實(shí)機(jī)選擇類勾選/單選/開關(guān)三件套、星級(jí)評(píng)分、帶氣泡數(shù)值的滑動(dòng)條、分段按鈕、顏色選擇器與底部選擇器二、勾選框 OhosCheckbox2.1 基本用法OhosCheckbox是圓角邊框復(fù)選框選中時(shí)品牌色填充 白色對(duì)勾與 Material 的方框風(fēng)格略有不同OhosCheckbox(value:_agreed,onChanged:(bool v)setState(()_agreedv),)onChanged: null即禁用態(tài)灰化不可點(diǎn)activeColor可覆蓋選中色默認(rèn)品牌色#0A59F7size默認(rèn) 24vp。2.2 與列表項(xiàng)組合協(xié)議勾選是勾選框最高頻的場景放在列表項(xiàng)行尾或頁面底部Row(children:[OhosCheckbox(value:_agreed,onChanged:(bool v)setState(()_agreedv),),constSizedBox(width:8),Expanded(child:RichText(text:TextSpan(text:我已閱讀并同意,style:TextStyle(fontSize:13,color:Colors.black54),children:const[TextSpan(text:《用戶協(xié)議》,style:TextStyle(color:Color(0xFF0A59F7))),TextSpan(text:與,style:TextStyle(color:Colors.black54)),TextSpan(text:《隱私政策》,style:TextStyle(color:Color(0xFF0A59F7))),],),),),],)三、單選按鈕 OhosRadio3.1 單選組注意OhosRadio的簽名與 Flutter 的RadioT不同——它是單實(shí)例布爾值模式value: bool不是 groupValue 模式。每個(gè)單選按鈕自己判斷自己是否被選中選中邏輯由業(yè)務(wù)層維護(hù)。class_PlanPageStateextendsStatePlanPage{String_planmonth;Widget_radioRow(Stringvalue,Stringlabel){returnInkWell(onTap:()setState(()_planvalue),child:Row(children:[OhosRadio(value:_planvalue,// 自己是否選中onChanged:(bool _)setState(()_planvalue),),constSizedBox(width:8),Text(label),],),);}overrideWidgetbuild(BuildContextcontext){returnColumn(children:[_radioRow(month,包月 ￥ 30/月),_radioRow(year,包年 ￥ 300/年),],);}}3.2 與列表組合單選組放進(jìn)OhosList是設(shè)置頁的標(biāo)準(zhǔn)形態(tài)如通知方式選擇OhosList(header:constOhosSubheader(title:通知方式),children:[for(final(value,label)inconst[(push,應(yīng)用內(nèi)推送),(sms,短信),(email,郵件),])OhosListTile(title:Text(label),trailing:OhosRadio(value:_notifyvalue,onChanged:(bool _)setState(()_notifyvalue),),onTap:()setState(()_notifyvalue),),],)整行可點(diǎn)onTap比只點(diǎn)圓圈更符合移動(dòng)操作習(xí)慣建議保留單選組互斥邏輯在業(yè)務(wù)層選中 A 時(shí) B/C 的value自然變 false。四、開關(guān) OhosSwitch4.1 設(shè)置行OhosSwitch是 50×30vp 膠囊開關(guān)設(shè)置頁行尾標(biāo)配支持自定義開/關(guān)顏色OhosSwitch(value:_darkMode,onChanged:(bool v)setState(()_darkModev),activeColor:constColor(0xFF0A59F7),inactiveColor:constColor(0xFFC7C7CC),)4.2 典型設(shè)置頁設(shè)置頁的完整組合開關(guān) 單選 跳轉(zhuǎn)行混排OhosList(header:constOhosSubheader(title:通用),children:[OhosListTile(leading:constIcon(Icons.dark_mode_outlined),title:constText(深色模式),trailing:OhosSwitch(value:_dark,onChanged:_onDarkMode),),constOhosDivider(),OhosListTile(leading:constIcon(Icons.notifications_none),title:constText(免打擾),trailing:OhosSwitch(value:_dnd,onChanged:_dndEnabled?_onDnd:null,// 未開啟推送時(shí)禁用),),constOhosDivider(),OhosListTile(leading:constIcon(Icons.language),title:constText(系統(tǒng)語言),trailing:constIcon(Icons.chevron_right),onTap:_openLanguage,),],)五、評(píng)分條 OhosRatingBarOhosRatingBar星級(jí)評(píng)分value為整數(shù)星數(shù)onChanged可交互傳null則只讀展示// 可交互點(diǎn)第幾顆給幾分OhosRatingBar(value:_rating,onChanged:(int v)setState(()_ratingv),starSize:32,)// 只讀展示商品詳情頁OhosRatingBar(value:4,onChanged:null,count:5,starSize:20)再次點(diǎn)擊當(dāng)前星會(huì)減一點(diǎn)第 4 顆已是 4 分時(shí)再點(diǎn)回到 3 分與鴻蒙應(yīng)用行為一致count默認(rèn) 5支持非 5 星制如 10 分制評(píng)價(jià)顏色默認(rèn)品牌色選中/ 20% 灰未選中activeColor/inactiveColor可覆蓋。注意OhosRatingBar是整數(shù)星不支持半星。需要 4.5 分展示的詳情頁用整數(shù)星 文字 4.5組合或用只讀評(píng)分條 數(shù)字文案。六、滑動(dòng)條 OhosSlider6.1 帶刻度OhosSlider支持divisions刻度音量、亮度場景拖動(dòng)時(shí)值吸附到刻度OhosSlider(value:_volume,onChanged:(double v)setState(()_volumev),min:0,max:100,divisions:20,// 20 段刻度label:音量,// 可選標(biāo)簽)6.2 拖動(dòng)氣泡數(shù)值showValueBubble: true開啟拖動(dòng)氣泡拖動(dòng)時(shí)拇指上方浮出當(dāng)前數(shù)值松手消失——鴻蒙應(yīng)用音量條的標(biāo)志性交互OhosSlider(value:_brightness,onChanged:(double v)setState(()_brightnessv),min:20,max:100,divisions:10,showValueBubble:true,)enabled: false整體禁用灰化如亮度跟隨系統(tǒng)時(shí)禁用手動(dòng)條activeColor覆蓋已滑過區(qū)間的顏色連續(xù)onChanged高頻觸發(fā)亮度/音量場景即時(shí)應(yīng)用沒問題網(wǎng)絡(luò)請(qǐng)求場景要防抖同輸入類搜索框的思路。七、分段按鈕 OhosSegmentedButton2-N 段互斥切換視圖切換日/周/月、列表模式列表/宮格泛型T與選擇器同款OhosSegmentedButtonString(segments:const[OhosSegment(label:日,value:day),OhosSegment(label:周,value:week),OhosSegment(label:月,value:month),],selected:_view,onSelected:(Stringv)setState(()_viewv),)選中段品牌色高亮與膠囊子頁簽OhosTabBar(type: capsule)視覺同源與子頁簽的分工分段按鈕不掛內(nèi)容頁純切換控件子頁簽驅(qū)動(dòng) TabBarView 內(nèi)容2-4 段切換用分段按鈕帶內(nèi)容頁的切換用子頁簽。八、顏色選擇器 OhosColorPicker8.1 三種模式OhosColorPicker提供網(wǎng)格 / 光譜 / 滑塊三種選色模式OhosColorPickerTab通過tabs參數(shù)決定顯示哪些模式頁簽OhosColorPicker(colors:const[Color(0xFF0A59F7),Color(0xFF64BB5C),Color(0xFFE84026),Color(0xFFF7B500),Color(0xFF8B5CF6),],selectedColor:_color,onChanged:(Colorc)setState(()_colorc),tabs:const[OhosColorPickerTab.grid,// 網(wǎng)格預(yù)設(shè)色塊OhosColorPickerTab.spectrum,// 光譜色相條選色OhosColorPickerTab.sliders,// 滑塊RGB 通道調(diào)節(jié)],)三種模式的適用場景模式交互場景grid網(wǎng)格點(diǎn)預(yù)設(shè)色塊主題色選擇有限候選spectrum光譜色相條 明度面自由選色sliders滑塊RGB 三通道精確取色/調(diào)參8.2 收藏管理favoriteColorsonFavoritesChanged支持收藏色板常用顏色置頂管理與 UI Design Kit 顏色選擇器能力對(duì)齊OhosColorPicker(colors:palette,selectedColor:_color,onChanged:_onColorChanged,favoriteColors:_favorites,onFavoritesChanged:(ListColorcolors)setState(()_favoritescolors),tabs:const[OhosColorPickerTab.grid,OhosColorPickerTab.spectrum],)顏色選擇器實(shí)機(jī)效果光譜模式選中態(tài)OhosColorPicker光譜模式色相條選色 當(dāng)前選中色預(yù)覽九、底部選擇器 showOhosPicker9.1 單選showOhosPicker彈出底部面板做列表選擇FutureT?返回選中值與 Flutter 的showModalBottomSheet習(xí)慣一致finalString?cityawaitshowOhosPickerString(context:context,title:選擇城市,initialValue:_city,// 當(dāng)前值回顯items:const[OhosPickerItem(label:北京,value:beijing),OhosPickerItem(label:上海,value:shanghai),OhosPickerItem(label:深圳,value:shenzhen),],);if(city!null)setState(()_citycity);9.2 帶副標(biāo)題OhosPickerItem支持subtitle第二行小字城市 省份、聯(lián)系人 部門finalint?contactawaitshowOhosPickerint(context:context,title:選擇聯(lián)系人,items:[OhosPickerItem(label:張三,subtitle:產(chǎn)品部,value:1),OhosPickerItem(label:李四,subtitle:研發(fā)部,value:2),OhosPickerItem(label:王五,subtitle:設(shè)計(jì)部,value:3),],);取消點(diǎn)遮罩/下滑返回null與選中值區(qū)分開處理選項(xiàng)多時(shí)底部面板自帶滾動(dòng)無需分頁。十、在鴻蒙模擬器上運(yùn)行與最佳實(shí)踐10.1 模擬器運(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_example10.2 選型速查場景推薦控件備注協(xié)議勾選OhosCheckbox行內(nèi) 富文本鏈接二選一/多選一OhosRadio組非 groupValue 模式功能開關(guān)OhosSwitch設(shè)置行尾標(biāo)配服務(wù)評(píng)分OhosRatingBar整數(shù)星再點(diǎn)當(dāng)前星減一音量/亮度OhosSlider(divisions bubble)刻度 氣泡連續(xù)數(shù)值OhosSlider高頻回調(diào)注意防抖視圖切換無內(nèi)容頁OhosSegmentedButton2-4 段視圖切換帶內(nèi)容頁OhosTabBar(capsule)導(dǎo)航類篇主題色/有限候選OhosColorPicker(grid)可加收藏自由取色OhosColorPicker(spectrum/sliders)光譜 滑塊列表選擇常駐OhosSelect操作類篇選項(xiàng) ≤5列表選擇彈層showOhosPicker選項(xiàng)多、帶副標(biāo)題10.3 實(shí)踐要點(diǎn)三件套別混用多選 Checkbox、單選 Radio、開關(guān) Switch 語義嚴(yán)格分開——啟用/關(guān)閉永遠(yuǎn)用 Switch不要用 Checkbox 當(dāng)開關(guān)單選組整行可點(diǎn)OhosListTile(onTap:) 行尾OhosRadio點(diǎn)擊熱區(qū)比只點(diǎn)圓圈大得多禁用態(tài)傳 null三件套統(tǒng)一onChanged: null禁用配合主題灰化不需要自己包Opacity評(píng)分條只讀場景傳 nullonChanged: null的評(píng)分條是純展示詳情頁大量使用滑塊高頻回調(diào)OhosSlider拖動(dòng)期間每幀回調(diào)網(wǎng)絡(luò)類副作用放onChanged外的松手時(shí)機(jī)可結(jié)合Listenable或業(yè)務(wù)節(jié)流。十一、常見問題 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.3OhosRadio為什么沒有g(shù)roupValue它刻意采用單實(shí)例布爾值模式value表示自己是否選中互斥邏輯由業(yè)務(wù)層維護(hù)選中 A 時(shí)把 B/C 的value置為false。直接照搬 FlutterRadioT的 groupValue 寫法會(huì)編譯不過。11.4OhosRatingBar支持半星嗎不支持它按整數(shù)星計(jì)數(shù)。需要展示 4.5 分時(shí)用整數(shù)星 文字 4.5組合或使用只讀評(píng)分條配數(shù)字文案不要試圖通過starSize模擬半星。11.5OhosColorPicker三種模式怎么選網(wǎng)格模式適合預(yù)設(shè)色板光譜模式適合自由取色滑塊模式適合精確調(diào) RGB/HSV三種模式共用同一套value/onChanged切換模式不會(huì)丟失當(dāng)前顏色。11.6showOhosPicker取消后返回什么取消點(diǎn)遮罩或下滑返回null與選中值區(qū)分開處理選項(xiàng)較多時(shí)面板自帶滾動(dòng)不需要分頁也不要把null當(dāng)成某個(gè)默認(rèn)選項(xiàng)。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é)選擇類的核心是形態(tài)與場景的匹配勾選/單選/開關(guān)對(duì)應(yīng)多選/單選/開關(guān)三種布爾語義評(píng)分/滑動(dòng)對(duì)應(yīng)離散打分/連續(xù)數(shù)值選擇器/顏色選擇器對(duì)應(yīng)從集合里挑。harmony_ui把每種形態(tài)都做到了官方規(guī)范的默認(rèn)值水平業(yè)務(wù)側(cè)唯一要留神的是OhosRadio的非 groupValue 簽名——遷移 Material 代碼時(shí)這一處必須手動(dòng)改。下一篇進(jìn)入容器類列表/列表項(xiàng)、卡片、彈出框、氣泡提示與光感半模態(tài)面板把裝內(nèi)容的殼講全六大類別系列到此收官增強(qiáng)類見第 7 篇。如果這篇文章對(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官方色彩 Token 文檔顏色選擇器色板依據(jù)colorfvm 多版本管理fvm.app