Flutter三方库适配OpenHarmony【harmony_ui】选择类控件实战勾选、单选、开关、评分、滑动条与颜色选择器前言harmony_ui是 Material/Cupertino 风格的 Flutter 组件库完整实现了HarmonyOS 设计语言覆盖官方「控件概览」6 大类 42 个控件并额外实现了沉浸光感材质与 UI Design Kit 增强能力。本系列按官方控件类别逐类实战前四篇分别是导航类、展示类、操作类、输入类本篇是第 5 篇选择类。选择类解决的是从选项里挑的问题官方共 6 个控件勾选框/单选按钮/开关三件套、评分条OhosRatingBar、滑动条OhosSlider、选择器showOhosPicker外加颜色选择器OhosColorPicker与分段按钮OhosSegmentedButton两个增强项。这一类控件的 API 与 Flutter 内置组件高度一致但单选按钮的签名与 Material 不同不是 groupValue 模式迁移时要特别注意。所有示例代码都在OpenHarmony 模拟器上直接运行验证Flutter3.47.7-ohos-1.0.1 DevEco Studio26.0.0 Release截图环境API 261280×2832。环境搭建、依赖引入与构建步骤见文首「环境与版本」「安装与引入 harmony_ui」以及第十节仓库地址AtomGit / GitHub。环境与版本本文的示例与截图基于以下环境组合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环境搭建分叉获取、DevEco Studio 与 SDK 配置、模拟器创建请按官方指导操作OpenHarmony-flutter 环境搭建指导。harmony_ui是纯 Dart/Flutter 组件库不依赖 ohos 平台通道在官方 Flutter SDK 上也能运行用于跨平台预览。只有跑example/ohos工程、构建 HAP 时才需要上面的 OH 适配版 SDK。安装与引入 harmony_uiharmony_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 getpub.dev 与 git 两种方式二选一不要同时声明。CI 中建议固定 tag如v0.3.0而不是main避免构建结果随上游漂移。harmony_ui目前只依赖qr一个三方包ohos_icons是可选配套图标包不引入也不影响组件使用。一、选择类总览官方控件实现一句话说明勾选框OhosCheckbox多选圆角边框单选按钮OhosRadio单选注意非 groupValue 模式开关OhosSwitch50×30 胶囊开关评分条OhosRatingBar星级评分点击当前星减一滑动条OhosSlider刻度 拖动气泡数值选择器showOhosPicker底部弹层选择Future 返回增强分段按钮OhosSegmentedButton2-N 段互斥切换增强颜色选择器OhosColorPicker网格/光谱/滑块三模式 收藏选择类整体效果gallery「选择」分类页模拟器实机选择类勾选/单选/开关三件套、星级评分、带气泡数值的滑动条、分段按钮、颜色选择器与底部选择器二、勾选框 OhosCheckbox2.1 基本用法OhosCheckbox是圆角边框复选框选中时品牌色填充 白色对勾与 Material 的方框风格略有不同OhosCheckbox(value:_agreed,onChanged:(bool v)setState(()_agreedv),)onChanged: null即禁用态灰化不可点activeColor可覆盖选中色默认品牌色#0A59F7size默认 24vp。2.2 与列表项组合协议勾选是勾选框最高频的场景放在列表项行尾或页面底部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:《用户协议》,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 模式。每个单选按钮自己判断自己是否被选中选中逻辑由业务层维护。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是设置页的标准形态如通知方式选择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比只点圆圈更符合移动操作习惯建议保留单选组互斥逻辑在业务层选中 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(系统语言),trailing:constIcon(Icons.chevron_right),onTap:_openLanguage,),],)五、评分条 OhosRatingBarOhosRatingBar星级评分value为整数星数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是整数星不支持半星。需要 4.5 分展示的详情页用整数星 文字 4.5组合或用只读评分条 数字文案。六、滑动条 OhosSlider6.1 带刻度OhosSlider支持divisions刻度音量、亮度场景拖动时值吸附到刻度OhosSlider(value:_volume,onChanged:(double v)setState(()_volumev),min:0,max:100,divisions:20,// 20 段刻度label:音量,// 可选标签)6.2 拖动气泡数值showValueBubble: true开启拖动气泡拖动时拇指上方浮出当前数值松手消失——鸿蒙应用音量条的标志性交互OhosSlider(value:_brightness,onChanged:(double v)setState(()_brightnessv),min:20,max:100,divisions:10,showValueBubble:true,)enabled: false整体禁用灰化如亮度跟随系统时禁用手动条activeColor覆盖已滑过区间的颜色连续onChanged高频触发亮度/音量场景即时应用没问题网络请求场景要防抖同输入类搜索框的思路。七、分段按钮 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参数决定显示哪些模式页签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 通道调节],)三种模式的适用场景模式交互场景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],)颜色选择器实机效果光谱模式选中态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第二行小字城市 省份、联系人 部门finalint?contactawaitshowOhosPickerint(context:context,title:选择联系人,items:[OhosPickerItem(label:张三,subtitle:产品部,value:1),OhosPickerItem(label:李四,subtitle:研发部,value:2),OhosPickerItem(label:王五,subtitle:设计部,value:3),],);取消点遮罩/下滑返回null与选中值区分开处理选项多时底部面板自带滚动无需分页。十、在鸿蒙模拟器上运行与最佳实践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如果命令不可用按文首的环境搭建指导检查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 选型速查场景推荐控件备注协议勾选OhosCheckbox行内 富文本链接二选一/多选一OhosRadio组非 groupValue 模式功能开关OhosSwitch设置行尾标配服务评分OhosRatingBar整数星再点当前星减一音量/亮度OhosSlider(divisions bubble)刻度 气泡连续数值OhosSlider高频回调注意防抖视图切换无内容页OhosSegmentedButton2-4 段视图切换带内容页OhosTabBar(capsule)导航类篇主题色/有限候选OhosColorPicker(grid)可加收藏自由取色OhosColorPicker(spectrum/sliders)光谱 滑块列表选择常驻OhosSelect操作类篇选项 ≤5列表选择弹层showOhosPicker选项多、带副标题10.3 实践要点三件套别混用多选 Checkbox、单选 Radio、开关 Switch 语义严格分开——启用/关闭永远用 Switch不要用 Checkbox 当开关单选组整行可点OhosListTile(onTap:) 行尾OhosRadio点击热区比只点圆圈大得多禁用态传 null三件套统一onChanged: null禁用配合主题灰化不需要自己包Opacity评分条只读场景传 nullonChanged: null的评分条是纯展示详情页大量使用滑块高频回调OhosSlider拖动期间每帧回调网络类副作用放onChanged外的松手时机可结合Listenable或业务节流。十一、常见问题 FAQ11.1flutter pub get找不到 harmony_ui先确认pubspec.yaml写的是harmony_ui: ^0.3.0或按文首 git 依赖写法固定ref: v0.3.0pub.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.3OhosRadio为什么没有groupValue它刻意采用单实例布尔值模式value表示自己是否选中互斥逻辑由业务层维护选中 A 时把 B/C 的value置为false。直接照搬 FlutterRadioT的 groupValue 写法会编译不过。11.4OhosRatingBar支持半星吗不支持它按整数星计数。需要展示 4.5 分时用整数星 文字 4.5组合或使用只读评分条配数字文案不要试图通过starSize模拟半星。11.5OhosColorPicker三种模式怎么选网格模式适合预设色板光谱模式适合自由取色滑块模式适合精确调 RGB/HSV三种模式共用同一套value/onChanged切换模式不会丢失当前颜色。11.6showOhosPicker取消后返回什么取消点遮罩或下滑返回null与选中值区分开处理选项较多时面板自带滚动不需要分页也不要把null当成某个默认选项。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 官方 FlutterAndroid / iOS / Web上能用吗可以。harmony_ui是纯 Dart/Flutter 实现不依赖平台通道字体、光感与模糊的最终效果会随平台渲染能力略有差异。跨平台预览用官方 Flutter 即可鸿蒙模拟器/真机验证请使用 3.47.7-ohos-1.0.1。总结选择类的核心是形态与场景的匹配勾选/单选/开关对应多选/单选/开关三种布尔语义评分/滑动对应离散打分/连续数值选择器/颜色选择器对应从集合里挑。harmony_ui把每种形态都做到了官方规范的默认值水平业务侧唯一要留神的是OhosRadio的非 groupValue 签名——迁移 Material 代码时这一处必须手动改。下一篇进入容器类列表/列表项、卡片、弹出框、气泡提示与光感半模态面板把装内容的壳讲全六大类别系列到此收官增强类见第 7 篇。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源harmony_ui 仓库AtomGitoh-flutter/harmony_uiharmony_ui 仓库GitHubshaohushuo/harmony_ui鸿蒙社区 Flutter 分叉CPF-Flutter/flutter_flutter配套图标包 ohos_iconspub.dev/packages/ohos_icons官方控件概览42 控件清单general_overview官方色彩 Token 文档颜色选择器色板依据colorfvm 多版本管理fvm.app
