单选按钮组

一组可供选择的按钮——称为单选按钮——在任何时候最多只能选择一个按钮。

import * as React from "react";
import { RadioGroup } from "radix-ui";
import "./styles.css";

const RadioGroupDemo = () => (
	<form>
		<RadioGroup.Root
			className="RadioGroupRoot"
			defaultValue="default"
			aria-label="View density"
		>
			<div style={{ display: "flex", alignItems: "center" }}>
				<RadioGroup.Item className="RadioGroupItem" value="default" id="r1">
					<RadioGroup.Indicator className="RadioGroupIndicator" />
				</RadioGroup.Item>
				<label className="Label" htmlFor="r1">
					Default
				</label>
			</div>
			<div style={{ display: "flex", alignItems: "center" }}>
				<RadioGroup.Item className="RadioGroupItem" value="comfortable" id="r2">
					<RadioGroup.Indicator className="RadioGroupIndicator" />
				</RadioGroup.Item>
				<label className="Label" htmlFor="r2">
					Comfortable
				</label>
			</div>
			<div style={{ display: "flex", alignItems: "center" }}>
				<RadioGroup.Item className="RadioGroupItem" value="compact" id="r3">
					<RadioGroup.Indicator className="RadioGroupIndicator" />
				</RadioGroup.Item>
				<label className="Label" htmlFor="r3">
					Compact
				</label>
			</div>
		</RadioGroup.Root>
	</form>
);

export default RadioGroupDemo;

Features

完整的键盘导航。
支持水平/垂直方向。
可以是受控或非受控模式。

结构

导入所有部分并将它们组合在一起。

import { RadioGroup } from "radix-ui";

export default () => (
    <RadioGroup.Root>
        <RadioGroup.Item>
            <RadioGroup.Indicator />
        </RadioGroup.Item>
    </RadioGroup.Root>
);

API 参考

根元素

包含单选按钮组的所有部分。

Prop	Type	Default
`asChild`	`boolean`	`false`
`defaultValue`	`string`	No default value
`value`	`string`	No default value
`onValueChange`	`function`	No default value
`disabled`	`boolean`	No default value
`name`	`string`	No default value
`required`	`boolean`	No default value
`orientation`	`enum`	`undefined`
`dir`	`enum`	No default value
`loop`	`boolean`	`true`

Data attribute	Values
`[data-disabled]`	禁用时存在

项目

组中的一个可被选中的项目。当在 form 中使用时，它将渲染一个 input 以确保事件正确传播。

Prop	Type	Default
`asChild`	`boolean`	`false`
`value`	`string`	No default value
`disabled`	`boolean`	No default value
`required`	`boolean`	No default value

Data attribute	Values
`[data-state]`	`"checked" \| "unchecked"`
`[data-disabled]`	禁用时存在

指示器

当单选按钮项处于选中状态时渲染。您可以直接设置该元素的样式，也可以将其用作放置图标的包装器，或二者兼有。

Prop	Type	Default
`asChild`	`boolean`	`false`
`forceMount`	`boolean`	No default value

Data attribute	Values
`[data-state]`	`"checked" \| "unchecked"`
`[data-disabled]`	禁用时存在

示例

解耦隐藏输入

默认情况下，RadioGroup.Item 会渲染一个视觉隐藏的 input，用于表单提交。若要重新组合、移动或排除该输入，可以改用更底层的部件来构建每个项目。

重要： 这些部件尚不稳定，并带有 unstable_ 前缀，因此其 API 可能会在未来版本中发生变化。

RadioGroup.unstable_ItemProvider 提供项目状态，并接受项目的 value 和 disabled 属性。
RadioGroup.unstable_ItemTrigger 是包裹 RadioGroup.Indicator 的交互元素。
RadioGroup.unstable_ItemBubbleInput 是 RadioGroup.Item 默认渲染的视觉隐藏输入。不需要表单提交时，可以省略它。

import { RadioGroup } from "radix-ui";

export default () => (
	<RadioGroup.Root>
		{["one", "two", "three"].map((value) => (
			<RadioGroup.unstable_ItemProvider key={value} value={value}>
				<RadioGroup.unstable_ItemTrigger>
					<RadioGroup.Indicator />
				</RadioGroup.unstable_ItemTrigger>
				<RadioGroup.unstable_ItemBubbleInput />
			</RadioGroup.unstable_ItemProvider>
		))}
	</RadioGroup.Root>
);

可访问性

遵循单选按钮组 WAI-ARIA 设计模式并使用移动 tabindex 来管理单选按钮项之间的焦点移动。

键盘交互

Key	Description
`Tab`	将焦点移动到已选中的单选按钮项或组中的第一个单选按钮项。
`Space`	当焦点位于未选中的单选按钮项时，选中它。
`ArrowDown`	移动焦点并选中组中的下一个单选按钮项。
`ArrowRight`	移动焦点并选中组中的下一个单选按钮项。
`ArrowUp`	将焦点移动到组中的上一个单选按钮项。
`ArrowLeft`	将焦点移动到组中的上一个单选按钮项。

上一篇进度条 Progress

下一篇滚动区域 Scroll Area

在 GitHub 上编辑此页面

概览 Overview

指南 Guides

组件 Components

通用工具 Utilities

单选按钮组

Features