---
title: Radio 单选框
description: 与 RadioGroup 组合使用，在一组选项里选中一个
---

# Radio 单选框

`G3Radio` 必须放在 `G3RadioGroup` 里才能互斥。组负责值、禁用与 `name`，单选项只声明自己的 `value` 和内容。

## 何时使用

- 选项少（2-5 个）且需要**一次看全**时，比 [Select](/ui/form/select) 更快；
- 选项是互斥的、必须选一个时使用；可以不选时用 Select 更合适；
- 选项超过 5 个、或需要展示更多信息时，用 Select；
- 只是控制某个功能的开与关，用 [Switch](/ui/form/switch)。

## 基础用法

<demo vue="radio/basic.vue" />

组会自动生成唯一的原生 `name`（`useId`），因此同页多组之间不会互相干扰，键盘方向键也能在组内来回切换。

## 纵向排列与整组禁用

组默认是水平换行的 `inline-flex`；纵向排列用外部 `style` 改 `flex-direction`，或给组包一层纵向容器。

<demo vue="radio/vertical.vue" />

## 卡片式选择

默认插槽可以放任意内容，配合 `style` 就能做成卡片选择器（常见于套餐、模板选择）。

<demo vue="radio/cards.vue" />

## API

### Props（Radio）

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `value` | `string \| number \| boolean` | **必填** | 选项值。与组 `modelValue` 做 `Object.is` 比较决定是否选中 |
| `disabled` | `boolean` | `false` | 单独禁用该项（组禁用时以组为准） |

### Props（RadioGroup）

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `modelValue` | `string \| number \| boolean` | — | 双向绑定的选中值 |
| `disabled` | `boolean` | `false` | 禁用整组 |
| `name` | `string` | 自动生成 | 原生 radio 组名，不传时用 `useId` 生成 |

### Events（RadioGroup）

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `update:modelValue` | `(value: string \| number \| boolean)` | 选中项变化 |
| `change` | `(value: string \| number \| boolean)` | 同上，便于只监听变化 |

### Slots

| 组件 | 插槽 | 说明 |
| --- | --- | --- |
| Radio | `default` | 选项文案，可放富内容 |
| RadioGroup | `default` | 组内的 `G3Radio` 列表 |

### 类型定义

```ts
export type RadioValue = string | number | boolean

export interface RadioProps {
  value: RadioValue
  disabled?: boolean
}

export interface RadioGroupProps {
  modelValue?: RadioValue
  disabled?: boolean
  name?: string
}

export interface RadioGroupContext {
  name: ComputedRef<string | undefined>
  modelValue: ComputedRef<RadioValue | undefined>
  disabled: ComputedRef<boolean>
  select: (value: RadioValue) => void
}
```

### 样式变量

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `--g3-radio-size` | `16px` | 圆圈直径 |
| `--g3-color-primary` | `#18181b` | 选中态边框与内点 |
| `--g3-bg-disabled` / `--g3-text-disabled` | `rgba(0,0,0,.04 / .25)` | 禁用态 |

## 实现说明

- 底层同样是原生 `input[type=radio]`：组用 `<div>` 包裹、每项用 `<label>` 包裹，浏览器原生提供「组内互斥 + 方向键切换」；
- 选中判断用 `Object.is`（而不是 `===`），这样 `NaN` 之类的值也能正确比较；
- 组上下文通过 `provide` 下发：`{ name, modelValue, disabled, select }`，单选项目通过 `inject` 读取；**脱离组单独使用时**会退化为「永不选中」的原生 radio（不会报错，但也不会有选中态），因此务必成对使用；
- 未显式传 `name` 时用 `useId` 生成组名，避免同页多个 radio 组因为浏览器按 `name` 分组而互相影响。