---
title: "单选框"
description: "RadioGroup 在一组互斥选项里选一个：方向键移动选中项、整组只有一个 Tab 停留点、随表单提交。"
---
> Documentation Index
> Fetch the complete documentation index at: https://ui-sdk.ndjp.net/llms.txt
> Use this file to discover all available pages before exploring further.
# 单选框
`Radio`（单选框）与 `RadioGroup` 用于选项不多、只能选一个的场景，例如配送方式或套餐。组只保存一个值，整组只有一个 Tab 停留点，方向键在选项间移动并直接选中。可多选时用[复选框](https://ui-sdk.ndjp.net/docs/components/checkbox)；选项很多、需要收起时用[选择器](https://ui-sdk.ndjp.net/docs/components/select)。
## 组合
```text
RadioGroup
├── Radio
│ └── RadioIndicator
└── Radio
└── RadioIndicator
```
每个 `Radio` 都要有 `value`，并和它的文字一起包在 `label` 里。组的值就是被选中那一项的 `value`；`RadioIndicator` 只在所属项选中时显示。
## 用法
```tsx
import { Field, FieldLabel } from "@ui-sdk/react/field";
import { Radio, RadioGroup, RadioIndicator } from "@ui-sdk/react/radio";
const speeds = [{ value: "standard", label: "标准" }, { value: "express", label: "加急" }, { value: "overnight", label: "次日达" }];
配送方式
{speeds.map((speed) => (
))}
;
```
外层字段的标签为整组命名；不用字段时给组传 `aria-label` 或 `aria-labelledby`。不传 `defaultValue` 时初始没有选中项，`Tab` 会落在第一个可用选项上。
## 说明文字与选项卡
某个选项需要额外解释时，把它单独放进一个 `Field`，用 `FieldLabel` 与 `FieldDescription`：内层字段把两者关联到这一项，外层字段仍为整组命名。
```tsx
邮件通知
每日汇总
每天早上一封邮件。
```
把整张卡的内容包进同一个 `label`，卡片任意位置都可点击；卡片自身的选中外观用 `:has([data-checked])` 表达，例如 `[data-slot="card"]:has([data-checked]) { border-color: var(--color-brand); background: var(--color-brand-wash); }`。
需要把一组选择连同标题、说明一起描述时，用 `FieldSet` 与 `FieldLegend`，再用 `aria-labelledby` 指向 legend 的 id、`aria-describedby` 指向说明的 id。
## 指示器动画
`RadioIndicator` 出现的首帧带 `data-starting-style`，退场期间带 `data-ending-style`，并在退场动画结束前保持挂载，因此可以直接用过渡：
```css
[data-slot="radio-indicator"] {
transition: opacity 0.15s, scale 0.15s;
&:is([data-starting-style], [data-ending-style]) {
opacity: 0;
scale: 0.5;
}
}
```
`keepMounted` 让指示器在未选中时也留在页面里（带 `data-unchecked`），可以做悬停预览小圆点这类效果。参见[样式与动画](https://ui-sdk.ndjp.net/docs/concepts/styling-and-animation)。
## 受控、控制器与循环
```tsx
const [value, setValue] = React.useState("standard");
setValue(next)} loop={false}>
…
;
```
`value` 传 `null` 表示都不选中。`onValueChange(value, details)` 的 `details.reason` 区分 `item-press`、`list-navigation`、`reset`、`restore` 与 `imperative`，`details.cancel()` 可拦截变更，参见[状态与事件](https://ui-sdk.ndjp.net/docs/concepts/state-and-events)。
方向键默认首尾循环，`loop={false}` 让它停在两端。要从组件树外操作，用 `createRadioGroupController()` 创建控制器传给组，调用 `getValue / setValue / focus`；`setValue` 对禁用项与只读组无效，被取消时返回 `false`。参见[控制器](https://ui-sdk.ndjp.net/docs/concepts/controllers)。
## 表单与校验
给组传 `name` 才会提交值，不传则不提交任何数据；`form` 可关联页面中其他表单的 id，表单重置回到 `defaultValue`。`required` 在未选中时阻止提交；放进带 `FieldError` 的[字段](https://ui-sdk.ndjp.net/docs/components/field)里，提交失败会在组下方显示错误并把焦点移到组上。
```tsx
订单通知
请选择订单通知方式。
```
`disabled` 可以放在组上或单个 `Radio` 上：禁用项不可聚焦、不可选中，方向键会跳过它；禁用的组不提交值。`readOnly` 保留焦点移动与提交，但不改变选中项。外层 `