ArkTS 单选框（Radio）组件 详解

ArkTS 单选框（Radio）组件 详解

鸿蒙第四期开发者活动

---

一、什么是 Radio 单选框？

Radio（单选框） 是 ArkTS 提供的一个选择组件，用于在一组互斥的选项中让用户只能选择 其中一个。它通常配合标签/说明文本组合使用，例如：

• 选择性别（男 / 女 / 其他）
• 选择模式（响铃 / 振动 / 静音）
• 选择支付方式

只要是一组选项只能选一个的场景，就基本会用到它。华为开发者

---

二、什么时候用 Radio？

Radio 的设计初衷非常明确：在一组选项里只能让用户选择一个值。和它相对的还有：

• Checkbox（多选框） → 可以多选
• Toggle/开关 → 两种状态切换

因此 Radio 不是用来做“开关”、“打钩确认”，它专注于“互斥选择”。华为开发者

典型场景包括：

表单里的单项选择
设定项里选择一种模式
用户偏好配置选项

---

三、基本用法（一句话上手）

Radio 是一个无子组件的组件，它通过传入一个 配置对象 来初始化：

Radio({ value: 'option1', group: 'modeGroup' })

解释一下：

• value: 当前这项的“值/标识”，不一定是显示内容
• group: 所属组名称，同一组里只有一个可以被选中

只要 group 一致，多个 Radio 就会自动互斥。华为开发者

---

四、属性详解（按实用排序）

---

1) value — 当前项的唯一值

这是区分不同 Radio 的标识：

Radio({ value: 'male', group: 'gender' })

虽然它写在配置里，但通常不显示在 UI 上，而是用于内部识别/状态管理。华为开发者

---

2) group — 所属组名（互斥逻辑核心）

同一组的 Radio 互相排斥，只能有一个被选中：

Radio({ value: 'male', group: 'gender' })
Radio({ value: 'female', group: 'gender' })

这两项在同一组，用户选了一个，另一个自动取消。华为开发者

---

3) .checked(true|false) — 是否选中

你可以通过方法来设置某个 Radio 的初始选中状态：

Radio({ value: 'male', group: 'gender' })
  .checked(true)

这会让它在一开始就是“已选中状态”。华为开发者

---

4) indicatorType / 自定义指示器（视觉样式）

从 API 12+ 开始你可以设置 Radio 的指示器显示样式：

• RadioIndicatorType.TICK（勾选样式）
• RadioIndicatorType.DOT（点样式）
• RadioIndicatorType.CUSTOM（自定义 UI）

如果没明确设置，默认是 TICK。CSDN

---

5) indicatorBuilder — 自定义指示器 UI

结合 RadioIndicatorType.CUSTOM，你可以用自己的组件来替换默认样式：

比如：

Radio({ value:'opt1', group:'g' })
  .indicatorBuilder(() => Text('✔'))

这样选中时就显示你自定义的内容。CSDN

---

6) radioStyle({...}) — 视觉样式配置

Radio 支持设置样式，例如：

• checkedBackgroundColor → 选中状态底色
• uncheckedBorderColor → 未选中边框颜色
• indicatorColor → 内部指示器颜色

这些样式属性让单选框在不同状态下看起来更符合设计规范。CSDN

---

五事件与状态监听

最常用也是核心的就是 选中状态变化监听：

onChange((isChecked) => {})

当用户点击这个 Radio 时，这个回调会触发：

Radio({ value:'male', group:'gender' })
  .onChange((isChecked: boolean) => {
    if (isChecked) {
      // 这个项刚刚被选中
    }
  })

isChecked 为 true 表示当前这个项被选中（之前可能没选）。CSDN

---

六、实战写法（代码示例）

在真实 UI 里，你几乎不会单独放一个 Radio，而是会把它和说明文字一起放在 Row/Column 里：

示例：性别单选选择

Column({ space: 12 }) {
  Row({ space: 8, alignItems: ItemAlign.Center }) {
    Radio({ value: 'male', group: 'gender' })
      .onChange(isChecked => {
        if (isChecked) this.selectedGender = 'male'
      })
    Text('男')
  }
  Row({ space: 8, alignItems: ItemAlign.Center }) {
    Radio({ value: 'female', group: 'gender' })
      .onChange(isChecked => {
        if (isChecked) this.selectedGender = 'female'
      })
    Text('女')
  }
}

这种写法清晰，将 Radio 和标签组合，并监听选中后做状态更新。CSDN

---

示例：带初始默认选中值

Radio({ value:'opt1', group:'g' })
  .checked(true)
  .onChange(isChecked => {
    console.log('opt1 选中：', isChecked)
  })

Radio({ value:'opt2', group:'g' })
  .onChange(isChecked => {
    console.log('opt2 选中：', isChecked)
  })

这种模式常用于“默认值/预选项”场景。CSDN

---

七、布局与组合模式（常见方式）

Radio 通常是和文字标签组合，并通过布局组件来呈现：

横排排列

Row({ space: 16 }) {
  Row({ space: 4, alignItems: ItemAlign.Center }) {
    Radio({ value:'a', group:'grp' })
    Text('选项 A')
  }
  Row({ space: 4, alignItems: ItemAlign.Center }) {
    Radio({ value:'b', group:'grp' })
    Text('选项 B')
  }
}

这种写法适用于选项较少的场景（比如男女）。

竖排排列

Column({ space: 12 }) {
  ForEach(['A','B','C'], (item) => {
    Row({ space: 6, alignItems: ItemAlign.Center }) {
      Radio({ value:item, group:'grp' })
      Text(`选项 ${item}`)
    }
  })
}

当选项多时用竖排更易读。

---

八、注意事项与常见坑

同一组别（group）才能互斥 → 如果写成不同 group，它们不会互斥。华为开发者
状态变化要用事件 onChange 监听** → 这样才能在 UI 之外处理业务逻辑。CSDN
自定义指示器需配合类型 CUSTOM → 否则 builder 不会生效。CSDN
样式属性从 API 10/12 版本开始支持 → 如果你用的是更早的 SDK，某些属性可能不生效。CSDN

---

九、总结（像真实开发者写的重点回顾）

方面	说明
组件作用	在一组选项中让用户 只能选一个
核心属性	value, group, .checked()
事件	onChange 监听选中/取消状态
样式	支持指示器样式、选中/未选中颜色定制
组合建议	和 Row/Column + Text 一起构建可读性 UI

Radio 是单选逻辑最直观的解决方案，项目里只要是互斥选项，一般就用它来承载状态选择。华为开发者