：勾選、單選、開關、評分、滑動條與顏色選擇器)
Flutter三方庫適配OpenHarmony【harmony_ui】選擇類控件實戰(zhàn)勾選、單選、開關、評分、滑動條與顏色選擇器前言harmony_ui是 Material/Cupertino 風格的 Flutter 組件庫完整實現(xiàn)了HarmonyOS 設計語言覆蓋官方「控件概覽」6 大類 42 個控件并額外實現(xiàn)了沉浸光感材質與 UI Design Kit 增強能力。本系列按官方控件類別逐類實戰(zhàn)前四篇分別是導航類、展示類、操作類、輸入類本篇是第 5 篇選擇類。選擇類解決的是從選項里挑的問題官方共 6 個控件勾選框/單選按鈕/開關三件套、評分條OhosRatingBar、滑動條OhosSlider、選擇器showOhosPicker外加顏色選擇器OhosColorPicker與分段按鈕OhosSegmentedButton兩個增強項。這一類控件的 API 與 Flutter 內置組件高度一致但單選按鈕的簽名與 Material 不同不是 groupValue 模式遷移時要特別注意。所有示例代碼都在OpenHarmony 模擬器上直接運行驗證Flutter3.47.7-ohos-1.0.1 DevEco Studio26.0.0 Release截圖環(huán)境API 261280×2832。環(huán)境搭建、依賴引入與構建步驟見文首「環(huán)境與版本」「安裝與引入 harmony_ui」以及第十節(jié)倉庫地址AtomGit / GitHub。環(huán)境與版本本文的示例與截圖基于以下環(huán)境組合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環(huán)境搭建分叉獲取、DevEco Studio 與 SDK 配置、模擬器創(chuàng)建請按官方指導操作OpenHarmony-flutter 環(huán)境搭建指導。harmony_ui是純 Dart/Flutter 組件庫不依賴 ohos 平臺通道在官方 Flutter SDK 上也能運行用于跨平臺預覽。只有跑example/ohos工程、構建 HAP 時才需要上面的 OH 適配版 SDK。安裝與引入 harmony_uiharmony_ui已發(fā)布到 pub.dev當前最新版本是0.3.0。在應用工程的pubspec.yaml中聲明dependencies:flutter:sdk:flutterharmony_ui:^0.3.0然后拉取依賴fvm flutter pub get如果團隊需要固定到倉庫的某個提交例如使用尚未發(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避免構建結果隨上游漂移。harmony_ui目前只依賴qr一個三方包ohos_icons是可選配套圖標包不引入也不影響組件使用。一、選擇類總覽官方控件實現(xiàn)一句話說明勾選框OhosCheckbox多選圓角邊框單選按鈕OhosRadio單選注意非 groupValue 模式開關OhosSwitch50×30 膠囊開關評分條OhosRatingBar星級評分點擊當前星減一滑動條OhosSlider刻度 拖動氣泡數(shù)值選擇器showOhosPicker底部彈層選擇Future 返回增強分段按鈕OhosSegmentedButton2-N 段互斥切換增強顏色選擇器OhosColorPicker網格/光譜/滑塊三模式 收藏選擇類整體效果gallery「選擇」分類頁模擬器實機選擇類勾選/單選/開關三件套、星級評分、帶氣泡數(shù)值的滑動條、分段按鈕、顏色選擇器與底部選擇器二、勾選框 OhosCheckbox2.1 基本用法OhosCheckbox是圓角邊框復選框選中時品牌色填充 白色對勾與 Material 的方框風格略有不同OhosCheckbox(value:_agreed,onChanged:(bool v)setState(()_agreedv),)onChanged: null即禁用態(tài)灰化不可點activeColor可覆蓋選中色默認品牌色#0A59F7size默認 24vp。2.2 與列表項組合協(xié)議勾選是勾選框最高頻的場景放在列表項行尾或頁面底部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不同——它是單實例布爾值模式value: bool不是 groupValue 模式。每個單選按鈕自己判斷自己是否被選中選中邏輯由業(yè)務層維護。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 與列表組合單選組放進OhosList是設置頁的標準形態(tài)如通知方式選擇OhosList(header:constOhosSubheader(title:通知方式),children:[for(final(value,label)inconst[(push,應用內推送),(sms,短信),(email,郵件),])OhosListTile(title:Text(label),trailing:OhosRadio(value:_notifyvalue,onChanged:(bool _)setState(()_notifyvalue),),onTap:()setState(()_notifyvalue),),],)整行可點onTap比只點圓圈更符合移動操作習慣建議保留單選組互斥邏輯在業(yè)務層選中 A 時 B/C 的value自然變 false。四、開關 OhosSwitch4.1 設置行OhosSwitch是 50×30vp 膠囊開關設置頁行尾標配支持自定義開/關顏色OhosSwitch(value:_darkMode,onChanged:(bool v)setState(()_darkModev),activeColor:constColor(0xFF0A59F7),inactiveColor:constColor(0xFFC7C7CC),)4.2 典型設置頁設置頁的完整組合開關 單選 跳轉行混排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,// 未開啟推送時禁用),),constOhosDivider(),OhosListTile(leading:constIcon(Icons.language),title:constText(系統(tǒng)語言),trailing:constIcon(Icons.chevron_right),onTap:_openLanguage,),],)五、評分條 OhosRatingBarOhosRatingBar星級評分value為整數(shù)星數(shù)onChanged可交互傳null則只讀展示// 可交互點第幾顆給幾分OhosRatingBar(value:_rating,onChanged:(int v)setState(()_ratingv),starSize:32,)// 只讀展示商品詳情頁OhosRatingBar(value:4,onChanged:null,count:5,starSize:20)再次點擊當前星會減一點第 4 顆已是 4 分時再點回到 3 分與鴻蒙應用行為一致count默認 5支持非 5 星制如 10 分制評價顏色默認品牌色選中/ 20% 灰未選中activeColor/inactiveColor可覆蓋。注意OhosRatingBar是整數(shù)星不支持半星。需要 4.5 分展示的詳情頁用整數(shù)星 文字 4.5組合或用只讀評分條 數(shù)字文案。六、滑動條 OhosSlider6.1 帶刻度OhosSlider支持divisions刻度音量、亮度場景拖動時值吸附到刻度OhosSlider(value:_volume,onChanged:(double v)setState(()_volumev),min:0,max:100,divisions:20,// 20 段刻度label:音量,// 可選標簽)6.2 拖動氣泡數(shù)值showValueBubble: true開啟拖動氣泡拖動時拇指上方浮出當前數(shù)值松手消失——鴻蒙應用音量條的標志性交互OhosSlider(value:_brightness,onChanged:(double v)setState(()_brightnessv),min:20,max:100,divisions:10,showValueBubble:true,)enabled: false整體禁用灰化如亮度跟隨系統(tǒng)時禁用手動條activeColor覆蓋已滑過區(qū)間的顏色連續(xù)onChanged高頻觸發(fā)亮度/音量場景即時應用沒問題網絡請求場景要防抖同輸入類搜索框的思路。七、分段按鈕 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)視覺同源與子頁簽的分工分段按鈕不掛內容頁純切換控件子頁簽驅動 TabBarView 內容2-4 段切換用分段按鈕帶內容頁的切換用子頁簽。八、顏色選擇器 OhosColorPicker8.1 三種模式OhosColorPicker提供網格 / 光譜 / 滑塊三種選色模式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,// 網格預設色塊OhosColorPickerTab.spectrum,// 光譜色相條選色OhosColorPickerTab.sliders,// 滑塊RGB 通道調節(jié)],)三種模式的適用場景模式交互場景grid網格點預設色塊主題色選擇有限候選spectrum光譜色相條 明度面自由選色sliders滑塊RGB 三通道精確取色/調參8.2 收藏管理favoriteColorsonFavoritesChanged支持收藏色板常用顏色置頂管理與 UI Design Kit 顏色選擇器能力對齊OhosColorPicker(colors:palette,selectedColor:_color,onChanged:_onColorChanged,favoriteColors:_favorites,onFavoritesChanged:(ListColorcolors)setState(()_favoritescolors),tabs:const[OhosColorPickerTab.grid,OhosColorPickerTab.spectrum],)顏色選擇器實機效果光譜模式選中態(tài)OhosColorPicker光譜模式色相條選色 當前選中色預覽九、底部選擇器 showOhosPicker9.1 單選showOhosPicker彈出底部面板做列表選擇FutureT?返回選中值與 Flutter 的showModalBottomSheet習慣一致finalString?cityawaitshowOhosPickerString(context:context,title:選擇城市,initialValue:_city,// 當前值回顯items:const[OhosPickerItem(label:北京,value:beijing),OhosPickerItem(label:上海,value:shanghai),OhosPickerItem(label:深圳,value:shenzhen),],);if(city!null)setState(()_citycity);9.2 帶副標題OhosPickerItem支持subtitle第二行小字城市 省份、聯(lián)系人 部門finalint?contactawaitshowOhosPickerint(context:context,title:選擇聯(lián)系人,items:[OhosPickerItem(label:張三,subtitle:產品部,value:1),OhosPickerItem(label:李四,subtitle:研發(fā)部,value:2),OhosPickerItem(label:王五,subtitle:設計部,value:3),],);取消點遮罩/下滑返回null與選中值區(qū)分開處理選項多時底部面板自帶滾動無需分頁。十、在鴻蒙模擬器上運行與最佳實踐10.1 模擬器運行選擇類全部控件在 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如果命令不可用按文首的環(huán)境搭建指導檢查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_example10.2 選型速查場景推薦控件備注協(xié)議勾選OhosCheckbox行內 富文本鏈接二選一/多選一OhosRadio組非 groupValue 模式功能開關OhosSwitch設置行尾標配服務評分OhosRatingBar整數(shù)星再點當前星減一音量/亮度OhosSlider(divisions bubble)刻度 氣泡連續(xù)數(shù)值OhosSlider高頻回調注意防抖視圖切換無內容頁OhosSegmentedButton2-4 段視圖切換帶內容頁OhosTabBar(capsule)導航類篇主題色/有限候選OhosColorPicker(grid)可加收藏自由取色OhosColorPicker(spectrum/sliders)光譜 滑塊列表選擇常駐OhosSelect操作類篇選項 ≤5列表選擇彈層showOhosPicker選項多、帶副標題10.3 實踐要點三件套別混用多選 Checkbox、單選 Radio、開關 Switch 語義嚴格分開——啟用/關閉永遠用 Switch不要用 Checkbox 當開關單選組整行可點OhosListTile(onTap:) 行尾OhosRadio點擊熱區(qū)比只點圓圈大得多禁用態(tài)傳 null三件套統(tǒng)一onChanged: null禁用配合主題灰化不需要自己包Opacity評分條只讀場景傳 nullonChanged: null的評分條是純展示詳情頁大量使用滑塊高頻回調OhosSlider拖動期間每幀回調網絡類副作用放onChanged外的松手時機可結合Listenable或業(yè)務節(jié)流。十一、常見問題 FAQ11.1flutter pub get找不到 harmony_ui先確認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é)點MaterialApp.home或builder組件通過OhosTheme.of(context)讀取 Token只 import 組件庫不會自動注入。確認后再檢查是否顯式覆蓋了顏色或字階參數(shù)。11.3OhosRadio為什么沒有groupValue它刻意采用單實例布爾值模式value表示自己是否選中互斥邏輯由業(yè)務層維護選中 A 時把 B/C 的value置為false。直接照搬 FlutterRadioT的 groupValue 寫法會編譯不過。11.4OhosRatingBar支持半星嗎不支持它按整數(shù)星計數(shù)。需要展示 4.5 分時用整數(shù)星 文字 4.5組合或使用只讀評分條配數(shù)字文案不要試圖通過starSize模擬半星。11.5OhosColorPicker三種模式怎么選網格模式適合預設色板光譜模式適合自由取色滑塊模式適合精確調 RGB/HSV三種模式共用同一套value/onChanged切換模式不會丟失當前顏色。11.6showOhosPicker取消后返回什么取消點遮罩或下滑返回null與選中值區(qū)分開處理選項較多時面板自帶滾動不需要分頁也不要把null當成某個默認選項。11.7 構建時報npm not found、hvigor不存在或DEVECO_SDK_HOME錯誤說明 DevEco 工具鏈沒有進入 PATH。執(zhí)行source env.sh按 DevEco Studio 26.0.0 Release 的默認安裝路徑配置確認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安裝。真機安裝與flutter run熱重載需要調試證書簽名。11.9 官方 FlutterAndroid / iOS / Web上能用嗎可以。harmony_ui是純 Dart/Flutter 實現(xiàn)不依賴平臺通道字體、光感與模糊的最終效果會隨平臺渲染能力略有差異?？缙脚_預覽用官方 Flutter 即可鴻蒙模擬器/真機驗證請使用 3.47.7-ohos-1.0.1?？偨Y選擇類的核心是形態(tài)與場景的匹配勾選/單選/開關對應多選/單選/開關三種布爾語義評分/滑動對應離散打分/連續(xù)數(shù)值選擇器/顏色選擇器對應從集合里挑。harmony_ui把每種形態(tài)都做到了官方規(guī)范的默認值水平業(yè)務側唯一要留神的是OhosRadio的非 groupValue 簽名——遷移 Material 代碼時這一處必須手動改。下一篇進入容器類列表/列表項、卡片、彈出框、氣泡提示與光感半模態(tài)面板把裝內容的殼講全六大類別系列到此收官增強類見第 7 篇。如果這篇文章對你有幫助歡迎點贊、收藏?、關注你的支持是我持續(xù)創(chuàng)作的動力相關資源harmony_ui 倉庫AtomGitoh-flutter/harmony_uiharmony_ui 倉庫GitHubshaohushuo/harmony_ui鴻蒙社區(qū) Flutter 分叉CPF-Flutter/flutter_flutter配套圖標包 ohos_iconspub.dev/packages/ohos_icons官方控件概覽42 控件清單general_overview官方色彩 Token 文檔顏色選擇器色板依據colorfvm 多版本管理fvm.app Flutter三方庫適配OpenHarmony【harmony_ui】選擇類控件實戰(zhàn)：勾選、單選、開關、評分、滑動條與顏色選擇器
Flutter三方庫適配OpenHarmony【harmony_ui】選擇類控件實戰(zhàn)勾選、單選、開關、評分、滑動條與顏色選擇器前言harmony_ui是 Material/Cupertino 風格的 Flutter 組件庫完整實現(xiàn)了HarmonyOS 設計語言覆蓋官方「控件概覽」6 大類 42 個控件并額外實現(xiàn)了沉浸光感材質與 UI Design Kit 增強能力。本系列按官方控件類別逐類實戰(zhàn)前四篇分別是導航類、展示類、操作類、輸入類本篇是第 5 篇選擇類。選擇類解決的是從選項里挑的問題官方共 6 個控件勾選框/單選按鈕/開關三件套、評分條OhosRatingBar、滑動條OhosSlider、選擇器showOhosPicker外加顏色選擇器OhosColorPicker與分段按鈕OhosSegmentedButton兩個增強項。這一類控件的 API 與 Flutter 內置組件高度一致但單選按鈕的簽名與 Material 不同不是 groupValue 模式遷移時要特別注意。所有示例代碼都在OpenHarmony 模擬器上直接運行驗證Flutter3.47.7-ohos-1.0.1 DevEco Studio26.0.0 Release截圖環(huán)境API 261280×2832。環(huán)境搭建、依賴引入與構建步驟見文首「環(huán)境與版本」「安裝與引入 harmony_ui」以及第十節(jié)倉庫地址AtomGit / GitHub。環(huán)境與版本本文的示例與截圖基于以下環(huán)境組合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環(huán)境搭建分叉獲取、DevEco Studio 與 SDK 配置、模擬器創(chuàng)建請按官方指導操作OpenHarmony-flutter 環(huán)境搭建指導。harmony_ui是純 Dart/Flutter 組件庫不依賴 ohos 平臺通道在官方 Flutter SDK 上也能運行用于跨平臺預覽。只有跑example/ohos工程、構建 HAP 時才需要上面的 OH 適配版 SDK。安裝與引入 harmony_uiharmony_ui已發(fā)布到 pub.dev當前最新版本是0.3.0。在應用工程的pubspec.yaml中聲明dependencies:flutter:sdk:flutterharmony_ui:^0.3.0然后拉取依賴fvm flutter pub get如果團隊需要固定到倉庫的某個提交例如使用尚未發(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避免構建結果隨上游漂移。harmony_ui目前只依賴qr一個三方包ohos_icons是可選配套圖標包不引入也不影響組件使用。一、選擇類總覽官方控件實現(xiàn)一句話說明勾選框OhosCheckbox多選圓角邊框單選按鈕OhosRadio單選注意非 groupValue 模式開關OhosSwitch50×30 膠囊開關評分條OhosRatingBar星級評分點擊當前星減一滑動條OhosSlider刻度 拖動氣泡數(shù)值選擇器showOhosPicker底部彈層選擇Future 返回增強分段按鈕OhosSegmentedButton2-N 段互斥切換增強顏色選擇器OhosColorPicker網格/光譜/滑塊三模式 收藏選擇類整體效果gallery「選擇」分類頁模擬器實機選擇類勾選/單選/開關三件套、星級評分、帶氣泡數(shù)值的滑動條、分段按鈕、顏色選擇器與底部選擇器二、勾選框 OhosCheckbox2.1 基本用法OhosCheckbox是圓角邊框復選框選中時品牌色填充 白色對勾與 Material 的方框風格略有不同OhosCheckbox(value:_agreed,onChanged:(bool v)setState(()_agreedv),)onChanged: null即禁用態(tài)灰化不可點activeColor可覆蓋選中色默認品牌色#0A59F7size默認 24vp。2.2 與列表項組合協(xié)議勾選是勾選框最高頻的場景放在列表項行尾或頁面底部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不同——它是單實例布爾值模式value: bool不是 groupValue 模式。每個單選按鈕自己判斷自己是否被選中選中邏輯由業(yè)務層維護。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 與列表組合單選組放進OhosList是設置頁的標準形態(tài)如通知方式選擇OhosList(header:constOhosSubheader(title:通知方式),children:[for(final(value,label)inconst[(push,應用內推送),(sms,短信),(email,郵件),])OhosListTile(title:Text(label),trailing:OhosRadio(value:_notifyvalue,onChanged:(bool _)setState(()_notifyvalue),),onTap:()setState(()_notifyvalue),),],)整行可點onTap比只點圓圈更符合移動操作習慣建議保留單選組互斥邏輯在業(yè)務層選中 A 時 B/C 的value自然變 false。四、開關 OhosSwitch4.1 設置行OhosSwitch是 50×30vp 膠囊開關設置頁行尾標配支持自定義開/關顏色OhosSwitch(value:_darkMode,onChanged:(bool v)setState(()_darkModev),activeColor:constColor(0xFF0A59F7),inactiveColor:constColor(0xFFC7C7CC),)4.2 典型設置頁設置頁的完整組合開關 單選 跳轉行混排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,// 未開啟推送時禁用),),constOhosDivider(),OhosListTile(leading:constIcon(Icons.language),title:constText(系統(tǒng)語言),trailing:constIcon(Icons.chevron_right),onTap:_openLanguage,),],)五、評分條 OhosRatingBarOhosRatingBar星級評分value為整數(shù)星數(shù)onChanged可交互傳null則只讀展示// 可交互點第幾顆給幾分OhosRatingBar(value:_rating,onChanged:(int v)setState(()_ratingv),starSize:32,)// 只讀展示商品詳情頁OhosRatingBar(value:4,onChanged:null,count:5,starSize:20)再次點擊當前星會減一點第 4 顆已是 4 分時再點回到 3 分與鴻蒙應用行為一致count默認 5支持非 5 星制如 10 分制評價顏色默認品牌色選中/ 20% 灰未選中activeColor/inactiveColor可覆蓋。注意OhosRatingBar是整數(shù)星不支持半星。需要 4.5 分展示的詳情頁用整數(shù)星 文字 4.5組合或用只讀評分條 數(shù)字文案。六、滑動條 OhosSlider6.1 帶刻度OhosSlider支持divisions刻度音量、亮度場景拖動時值吸附到刻度OhosSlider(value:_volume,onChanged:(double v)setState(()_volumev),min:0,max:100,divisions:20,// 20 段刻度label:音量,// 可選標簽)6.2 拖動氣泡數(shù)值showValueBubble: true開啟拖動氣泡拖動時拇指上方浮出當前數(shù)值松手消失——鴻蒙應用音量條的標志性交互OhosSlider(value:_brightness,onChanged:(double v)setState(()_brightnessv),min:20,max:100,divisions:10,showValueBubble:true,)enabled: false整體禁用灰化如亮度跟隨系統(tǒng)時禁用手動條activeColor覆蓋已滑過區(qū)間的顏色連續(xù)onChanged高頻觸發(fā)亮度/音量場景即時應用沒問題網絡請求場景要防抖同輸入類搜索框的思路。七、分段按鈕 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)視覺同源與子頁簽的分工分段按鈕不掛內容頁純切換控件子頁簽驅動 TabBarView 內容2-4 段切換用分段按鈕帶內容頁的切換用子頁簽。八、顏色選擇器 OhosColorPicker8.1 三種模式OhosColorPicker提供網格 / 光譜 / 滑塊三種選色模式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,// 網格預設色塊OhosColorPickerTab.spectrum,// 光譜色相條選色OhosColorPickerTab.sliders,// 滑塊RGB 通道調節(jié)],)三種模式的適用場景模式交互場景grid網格點預設色塊主題色選擇有限候選spectrum光譜色相條 明度面自由選色sliders滑塊RGB 三通道精確取色/調參8.2 收藏管理favoriteColorsonFavoritesChanged支持收藏色板常用顏色置頂管理與 UI Design Kit 顏色選擇器能力對齊OhosColorPicker(colors:palette,selectedColor:_color,onChanged:_onColorChanged,favoriteColors:_favorites,onFavoritesChanged:(ListColorcolors)setState(()_favoritescolors),tabs:const[OhosColorPickerTab.grid,OhosColorPickerTab.spectrum],)顏色選擇器實機效果光譜模式選中態(tài)OhosColorPicker光譜模式色相條選色 當前選中色預覽九、底部選擇器 showOhosPicker9.1 單選showOhosPicker彈出底部面板做列表選擇FutureT?返回選中值與 Flutter 的showModalBottomSheet習慣一致finalString?cityawaitshowOhosPickerString(context:context,title:選擇城市,initialValue:_city,// 當前值回顯items:const[OhosPickerItem(label:北京,value:beijing),OhosPickerItem(label:上海,value:shanghai),OhosPickerItem(label:深圳,value:shenzhen),],);if(city!null)setState(()_citycity);9.2 帶副標題OhosPickerItem支持subtitle第二行小字城市 省份、聯(lián)系人 部門finalint?contactawaitshowOhosPickerint(context:context,title:選擇聯(lián)系人,items:[OhosPickerItem(label:張三,subtitle:產品部,value:1),OhosPickerItem(label:李四,subtitle:研發(fā)部,value:2),OhosPickerItem(label:王五,subtitle:設計部,value:3),],);取消點遮罩/下滑返回null與選中值區(qū)分開處理選項多時底部面板自帶滾動無需分頁。十、在鴻蒙模擬器上運行與最佳實踐10.1 模擬器運行選擇類全部控件在 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如果命令不可用按文首的環(huán)境搭建指導檢查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_example10.2 選型速查場景推薦控件備注協(xié)議勾選OhosCheckbox行內 富文本鏈接二選一/多選一OhosRadio組非 groupValue 模式功能開關OhosSwitch設置行尾標配服務評分OhosRatingBar整數(shù)星再點當前星減一音量/亮度OhosSlider(divisions bubble)刻度 氣泡連續(xù)數(shù)值OhosSlider高頻回調注意防抖視圖切換無內容頁OhosSegmentedButton2-4 段視圖切換帶內容頁OhosTabBar(capsule)導航類篇主題色/有限候選OhosColorPicker(grid)可加收藏自由取色OhosColorPicker(spectrum/sliders)光譜 滑塊列表選擇常駐OhosSelect操作類篇選項 ≤5列表選擇彈層showOhosPicker選項多、帶副標題10.3 實踐要點三件套別混用多選 Checkbox、單選 Radio、開關 Switch 語義嚴格分開——啟用/關閉永遠用 Switch不要用 Checkbox 當開關單選組整行可點OhosListTile(onTap:) 行尾OhosRadio點擊熱區(qū)比只點圓圈大得多禁用態(tài)傳 null三件套統(tǒng)一onChanged: null禁用配合主題灰化不需要自己包Opacity評分條只讀場景傳 nullonChanged: null的評分條是純展示詳情頁大量使用滑塊高頻回調OhosSlider拖動期間每幀回調網絡類副作用放onChanged外的松手時機可結合Listenable或業(yè)務節(jié)流。十一、常見問題 FAQ11.1flutter pub get找不到 harmony_ui先確認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é)點MaterialApp.home或builder組件通過OhosTheme.of(context)讀取 Token只 import 組件庫不會自動注入。確認后再檢查是否顯式覆蓋了顏色或字階參數(shù)。11.3OhosRadio為什么沒有groupValue它刻意采用單實例布爾值模式value表示自己是否選中互斥邏輯由業(yè)務層維護選中 A 時把 B/C 的value置為false。直接照搬 FlutterRadioT的 groupValue 寫法會編譯不過。11.4OhosRatingBar支持半星嗎不支持它按整數(shù)星計數(shù)。需要展示 4.5 分時用整數(shù)星 文字 4.5組合或使用只讀評分條配數(shù)字文案不要試圖通過starSize模擬半星。11.5OhosColorPicker三種模式怎么選網格模式適合預設色板光譜模式適合自由取色滑塊模式適合精確調 RGB/HSV三種模式共用同一套value/onChanged切換模式不會丟失當前顏色。11.6showOhosPicker取消后返回什么取消點遮罩或下滑返回null與選中值區(qū)分開處理選項較多時面板自帶滾動不需要分頁也不要把null當成某個默認選項。11.7 構建時報npm not found、hvigor不存在或DEVECO_SDK_HOME錯誤說明 DevEco 工具鏈沒有進入 PATH。執(zhí)行source env.sh按 DevEco Studio 26.0.0 Release 的默認安裝路徑配置確認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安裝。真機安裝與flutter run熱重載需要調試證書簽名。11.9 官方 FlutterAndroid / iOS / Web上能用嗎可以。harmony_ui是純 Dart/Flutter 實現(xiàn)不依賴平臺通道字體、光感與模糊的最終效果會隨平臺渲染能力略有差異?？缙脚_預覽用官方 Flutter 即可鴻蒙模擬器/真機驗證請使用 3.47.7-ohos-1.0.1?？偨Y選擇類的核心是形態(tài)與場景的匹配勾選/單選/開關對應多選/單選/開關三種布爾語義評分/滑動對應離散打分/連續(xù)數(shù)值選擇器/顏色選擇器對應從集合里挑。harmony_ui把每種形態(tài)都做到了官方規(guī)范的默認值水平業(yè)務側唯一要留神的是OhosRadio的非 groupValue 簽名——遷移 Material 代碼時這一處必須手動改。下一篇進入容器類列表/列表項、卡片、彈出框、氣泡提示與光感半模態(tài)面板把裝內容的殼講全六大類別系列到此收官增強類見第 7 篇。如果這篇文章對你有幫助歡迎點贊、收藏?、關注你的支持是我持續(xù)創(chuàng)作的動力相關資源harmony_ui 倉庫AtomGitoh-flutter/harmony_uiharmony_ui 倉庫GitHubshaohushuo/harmony_ui鴻蒙社區(qū) Flutter 分叉CPF-Flutter/flutter_flutter配套圖標包 ohos_iconspub.dev/packages/ohos_icons官方控件概覽42 控件清單general_overview官方色彩 Token 文檔顏色選擇器色板依據colorfvm 多版本管理fvm.app