鸿蒙开发中Radio组件的详细使用-CSDN博客

本文链接：https://blog.csdn.net/wangsen927/article/details/148069661

本文同步发表于我的微信公众号，微信搜索程语新视界即可关注，每个工作日都有文章更新

一、Radio组件基础

1. 核心特性

单选功能：同一group下的Radio只能选中一个
状态控制：通过checked属性设置选中状态（true/false）
事件响应：支持onChange事件监听选中状态变化

2. 创建Radio

// 基本创建方式
Radio({ value: '选项1', group: 'testGroup' })
  .checked(true) // 默认选中
  .onChange((isChecked: boolean) => {
    if (isChecked) console.log('选中状态变化')
  })

3. 属性说明

属性名	类型	必填	说明
`value`	string	是	选项唯一标识符
`group`	string	是	分组标识（同组互斥）
`checked`	boolean	否	默认选中状态

二、高级功能与API

1. 样式定制（API 12+）

预设样式：通过indicatorType设置选中图标（默认为RadioIndicatorType.TICK）

Radio({ value: '选项2', group: 'testGroup' })
  .indicatorType(RadioIndicatorType.CIRCLE) // 圆形指示器

完全自定义：使用indicatorBuilder自定义选中状态UI

@Entry
@Component
struct RadioExample {
  @State currentSelect: string = ''

  @Builder
  customIndicator(isChecked: boolean) {
    Column() {
      Image(isChecked ? $r('app.media.star_filled') : $r('app.media.star_outline'))
        .width(24)
        .height(24)
      Text(isChecked ? '已选' : '未选')
        .fontColor(isChecked ? Color.Blue : Color.Grey)
    }
  }

  build() {
    Column() {
      Radio({ value: 'A', group: 'demo' })
        .indicatorBuilder(this.customIndicator)
        .onChange((checked) => checked && (this.currentSelect = 'A'))
      
      Radio({ value: 'B', group: 'demo' })
        .indicatorBuilder(this.customIndicator)
        .onChange((checked) => checked && (this.currentSelect = 'B'))
    }
  }
}

效果：

未选中状态显示灰色星框图标和灰色文字
选中状态显示蓝色实心星图标和蓝色文字

参数传递机制解析：

隐式参数传递：indicatorBuilder 会自动将当前选中状态（boolean类型）作为参数传递给绑定的构建函数，无需手动传参。

系统自动调用：当Radio状态变化时，框架会自动调用 customIndicator 并传入当前的 isChecked 值，开发者只需定义函数逻辑即可。

如果需要更复杂的样式控制，建议使用indicatorBuilder或组合组件方案

2. 低版本兼容方案（API <10）

通过组合组件模拟Radio行为：

@Entry
@Component
struct CustomRadio {
  @State isChecked: boolean = false

  build() {
    Row() {
      Image(this.isChecked ? $r('app.media.checked') : $r('app.media.unchecked'))
        .onClick(() => this.isChecked = !this.isChecked)
      Text('选项1')
    }
  }
}

适用场景：

需要兼容低版本API
需实现复杂自定义效果（如渐变背景）

方案对比总结

方法	支持版本	可定制程度	实现复杂度
`radioStyle`	API 12+	低（仅边框颜色）	简单
`indicatorBuilder`	API 12+	高（完全自定义UI）	中等
组合组件	全版本	高（需手动实现逻辑）	复杂

3. 样式对象`RadioStyle`

属性名	类型	说明
`checkedBackgroundColor`	Color	选中状态背景色
`uncheckedBorderColor`	Color	未选中边框色
`indicatorColor`	Color	选中指示器颜色

const myStyle: RadioStyle = {
  checkedBackgroundColor: Color.Blue,
  uncheckedBorderColor: Color.Grey
}
Radio({...}).radioStyle(myStyle)

三、实战案例

1. 设置偏好选项

@Entry
@Component
struct SettingsPage {
  @State soundMode: string = 'ring'

  build() {
    Column() {
      Radio({ value: 'ring', group: 'soundGroup' })
        .checked(this.soundMode === 'ring')
        .onChange((checked) => checked && (this.soundMode = 'ring'))
      Text('响铃模式')

      Radio({ value: 'vibrate', group: 'soundGroup' })
        .onChange((checked) => checked && (this.soundMode = 'vibrate'))
      Text('振动模式')
    }
  }
}

2. 动态表单选项

@Entry
@Component
struct SurveyForm {
  @State options: string[] = ['选项A', '选项B', '选项C']
  @State selectedValue: string = ''

  build() {
    List() {
      ForEach(this.options, (item) => {
        ListItem() {
          Row() {
            Radio({ value: item, group: 'surveyGroup' })
              .checked(this.selectedValue === item)
              .onChange((checked) => checked && (this.selectedValue = item))
            Text(item)
          }
        }
      })
    }
  }
}

四、注意事项

分组必要性：未设置group属性的Radio不会互斥
性能优化：避免在onChange中执行耗时操作
兼容性：自定义样式需注意API版本要求（如indicatorBuilder需API 12+）
状态管理：推荐配合@State管理选中状态

五、常见问题

1. 如何获取当前选中项？

// 通过@State变量记录选中值
@State currentValue: string = ''
Radio({ value: 'opt1', group: 'myGroup' })
  .onChange((checked) => checked && (this.currentValue = 'opt1'))

2. 如何清空选择？

// 设置所有Radio的checked为false
this.options.forEach(item => item.checked = false)

3. 动态修改选项列表？

// 更新数据源触发UI刷新
this.options = [...this.options, '新增选项']