HarmonyOS6 ArkTS Radio组件使用文档

文章目录核心亮点完整代码核心参数与方法1 组件构造参数2 核心属性方法链式调用1选中状态绑定checked2样式自定义radioStyle3选中事件回调onChange3 核心枚举RadioIndicatorType4 自定义构建器Builder 自定义指示器核心变量运行效果核心使用规范1 分组规范2 状态绑定规范3 事件回调规范4 样式设计规范总结核心亮点同组互斥通过group属性标识同一组Radio保证组内仅能选中一个选项符合单选核心逻辑多样式选中图标支持系统内置TICK对勾、DOT圆点两种图标也可通过indicatorBuilder自定义选中指示器精细化样式配置通过radioStyle可单独设置选中背景色、未选中边框色、内置图标颜色适配不同UI设计规范状态双向绑定通过State变量绑定checked属性实现选中状态与页面数据实时联动支持主动修改选中状态选中事件回调onChange事件实时监听选中状态变化可在回调中处理数据更新、日志打印等业务逻辑灵活布局组件体积轻量可与Text、Flex等组件自由组合适配行内、列内等多种布局场景。完整代码// RadioFullExample.ets Entry Component struct RadioFullExample { // 分组选中状态绑定 State selectedValue: string male; // 样式切换控制 State indicatorType: RadioIndicatorType RadioIndicatorType.TICK; // 自定义选中图标Builder Builder customIndicator() { Stack({ alignContent: Alignment.Center }) { Text(✓) .fontSize(20) .fontColor(Color.White) .fontWeight(FontWeight.Bold) } .width(24) .height(24) .backgroundColor(#007DFF) .borderRadius(12) } build() { Column({ space: 30 }) { // 标题 Text(Radio 单选框完整示例) .fontSize(26) .fontWeight(FontWeight.Bold) .margin({ top: 20 }); // 1. 基础分组单选性别选择 Column({ space: 15 }) { Text(基础分组单选性别) .fontSize(18) .fontWeight(FontWeight.Medium) .alignSelf(ItemAlign.Start); Flex({ direction: FlexDirection.Row, alignItems: ItemAlign.Center }) { // 男 Radio({ value: male, group: genderGroup }) .checked(this.selectedValue male) .radioStyle({ checkedBackgroundColor: #007DFF, uncheckedBorderColor: #999999, indicatorColor: Color.White }) .onChange((isChecked) { if (isChecked) { this.selectedValue male; console.info(选中male); } }); Text(男).fontSize(16); // 女 Radio({ value: female, group: genderGroup }) .checked(this.selectedValue female) .radioStyle({ checkedBackgroundColor: #007DFF, uncheckedBorderColor: #999999, indicatorColor: Color.White }) .onChange((isChecked) { if (isChecked) { this.selectedValue female; console.info(选中female); } }); Text(女).fontSize(16); } } .width(100%) .padding(15) .backgroundColor(#F5F5F5) .borderRadius(12); // 2. 选中样式切换TICK / DOT / CUSTOM Column({ space: 15 }) { Text(选中样式切换) .fontSize(18) .fontWeight(FontWeight.Medium) .alignSelf(ItemAlign.Start); Flex({ direction: FlexDirection.Row, alignItems: ItemAlign.Center }) { Radio({ value: tick, group: styleGroup, indicatorType: RadioIndicatorType.TICK }) .checked(this.indicatorType RadioIndicatorType.TICK) .onChange(() { this.indicatorType RadioIndicatorType.TICK; }); Text(对勾TICK).fontSize(16); Radio({ value: dot, group: styleGroup, indicatorType: RadioIndicatorType.DOT }) .checked(this.indicatorType RadioIndicatorType.DOT) .onChange(() { this.indicatorType RadioIndicatorType.DOT; }); Text(圆点DOT).fontSize(16); Radio({ value: custom, group: styleGroup, indicatorType: RadioIndicatorType.CUSTOM, indicatorBuilder: this.customIndicator }) .checked(this.indicatorType RadioIndicatorType.CUSTOM) .onChange(() { this.indicatorType RadioIndicatorType.CUSTOM; }); Text(自定义).fontSize(16); } } .width(100%) .padding(15) .backgroundColor(#F5F5F5) .borderRadius(12); // 显示当前选中结果 Column({ space: 10 }) { Text(当前选中 this.selectedValue) .fontSize(18) .fontColor(#007DFF); Text(当前选中样式 ( this.indicatorType RadioIndicatorType.TICK ? TICK : this.indicatorType RadioIndicatorType.DOT ? DOT : CUSTOM )) .fontSize(16) .fontColor(#666666); } .margin({ top: 10 }); } .width(100%) .padding(20) .backgroundColor(#FFFFFF) } }运行效果如图核心参数与方法1 组件构造参数参数名类型必选/可选说明示例valuestring/number必选单选框的唯一标识用于区分同组内不同选项male/1groupstring必选分组标识相同group值的Radio为同一组组内互斥genderGroupindicatorTypeRadioIndicatorType可选选中指示器类型默认RadioIndicatorType.TICKRadioIndicatorType.DOTindicatorBuilderCustomBuilder可选自定义选中指示器构建器仅当indicatorType为CUSTOM时生效this.customIndicator2 核心属性方法链式调用1选中状态绑定checked类型boolean必选是说明控制Radio的选中状态通常与State变量联动通过条件判断实现动态绑定示例.checked(this.selectedValue male)2样式自定义radioStyle类型RadioStyle必选否说明配置Radio的基础样式支持三个核心子属性未配置时使用系统默认样式| 子属性 | 类型 | 说明 ||--------|------|------|| checkedBackgroundColor | Color/string | 选中状态下的背景色 || uncheckedBorderColor | Color/string | 未选中状态下的边框色 || indicatorColor | Color/string | 内置指示器TICK/DOT的颜色自定义指示器时此属性无效 |示例.radioStyle({ checkedBackgroundColor: #007DFF, uncheckedBorderColor: #999999, indicatorColor: Color.White })3选中事件回调onChange回调参数isChecked: boolean说明Radio选中状态发生变化时触发isChecked为true表示当前选项被选中false表示被取消同组其他选项被选中时触发业务建议仅在isChecked true时处理数据更新避免无效逻辑执行示例.onChange((isChecked) { if (isChecked) { this.selectedValue male; console.info(选中male); } })3 核心枚举RadioIndicatorType枚举值说明适用场景TICK系统内置对勾图标API12默认样式常规表单、基础选择场景DOT系统内置实心圆点图标简约UI、移动端适配场景CUSTOM自定义选中指示器需配合indicatorBuilder使用个性化UI设计、品牌定制场景4 自定义构建器Builder 自定义指示器作用当系统内置图标无法满足UI需求时通过Builder装饰器自定义选中后的展示样式支持Text、Stack、Shape等任意基础组件组合要求需保证自定义组件的宽高适配Radio默认尺寸建议24*24px避免样式错位示例通过StackText实现自定义带对勾的圆形选中指示器与系统样式保持视觉统一。核心变量变量名类型初始值作用selectedValuestringmale绑定性别选择组的选中状态存储当前选中的value值实现页面数据与Radio状态联动indicatorTypeRadioIndicatorTypeRadioIndicatorType.TICK绑定样式选择组的选中状态存储当前选中的指示器类型控制样式切换逻辑运行效果页面初始化时性别选择组默认选中男maleRadio为蓝色背景、白色对勾样式样式选择组默认选中TICK对勾下方结果栏实时显示当前选中状态点击性别选择组的女femaleRadio状态切换为选中selectedValue更新为female结果栏同步刷新控制台打印选中日志点击样式选择组的DOT圆点组内TICK自动取消选中indicatorType更新为DOT对应Radio显示实心圆点选中样式点击样式选择组的自定义对应Radio显示自定义的蓝色圆形对勾样式结果栏同步显示CUSTOM所有Radio组均实现互斥选中点击组内任意选项其他选项自动取消选中符合单选组件核心逻辑。核心使用规范1 分组规范同一组单选选项必须设置相同的group属性值且group值建议与业务场景关联如genderGroup、payTypeGroup提高代码可读性不同组单选选项必须设置不同的group属性值避免跨组互斥导致选择逻辑异常。2 状态绑定规范建议使用State/Link/Prop等状态变量绑定checked属性避免直接写死true/false保证选中状态可动态修改同组Radio的checked判断条件需基于同一个状态变量且条件值与各自的value值一一对应避免状态冲突。3 事件回调规范onChange回调中需增加isChecked true的判断因为同组其他选项被选中时当前选项的onChange会触发且isChecked为false无需处理此场景可在回调中完成数据更新、日志打印、接口请求等业务逻辑保证选中状态与业务数据一致性。4 样式设计规范checkedBackgroundColor建议使用项目主色调uncheckedBorderColor建议使用浅灰色系保证选中状态视觉醒目未选中状态不抢焦点自定义指示器时建议保持宽高一致圆形/方形与系统Radio默认尺寸适配避免与相邻Text组件布局错位Radio与配套的Text组件建议使用Flex布局并设置alignItems: ItemAlign.Center保证垂直居中对齐。总结API版本兼容组件所有功能均基于**API 12**实现若项目需适配更低API版本需做兼容处理或使用替代组件自定义指示器生效条件仅当indicatorType显式设置为RadioIndicatorType.CUSTOM时indicatorBuilder才会生效缺一不可value值唯一性同一组内的Radiovalue值必须唯一若存在相同value会导致选中状态判断异常布局间距Radio组件与相邻Text组件之间建议保留适当间距如10px避免视觉拥挤提升用户体验多端适配组件默认支持多端自适应若在穿戴设备、车机等特殊设备使用需根据设备屏幕尺寸调整组件大小和字体大小。如果这篇文章对你有帮助欢迎点赞、收藏、关注你的支持是持续创作的动力