单选控件

最后更新：2026-10-17 10:55:29

当希望用户从一组选项中仅选择一个，且需要一次性展示所有可用选项时，请使用单选按钮。

选中和未选中的单选按钮

设计规范

用法

何时使用单选按钮

在以下场景中使用单选按钮：

从列表中选择单个选项。
展示所有可用选项。

如果可用选项列表可以折叠，请考虑改用下拉菜单，因为下拉菜单占用空间更少。例如，国家选择字段如果作为单选按钮组会非常大，且无法通过一次性展示所有选项来帮助用户获得更多上下文信息。

建议做法

右侧：显示“Author”和“Editor”两个单选按钮的截图，其中一个已选中
当只能从列表中选择一个项目时，请使用单选按钮。

避免做法

错误：显示“Author”和“Editor”两个复选框的截图，其中一个已选中
当只能从列表中选择一个项目时，不要使用复选框。请改用单选按钮。

默认状态

使用单选按钮时应默认选中其中一个选项（即页面加载时）。

用户控制权

在大多数交互中，用户应该能够撤销和重做他们的操作。对于大多数选择控件，您可以取消选择，但在本例中，您无法点击或轻触已选中的单选按钮来取消选中——选中是一个最终操作。如果没有默认选中项，这种最终性就无法传达。默认选中一个单选按钮向用户传达了必须在集合中选择一个的要求。

加速任务

当单选按钮集合中的一个选项是最理想或最常选择的时，默认选中它会有所帮助。这样做可以降低交互成本，节省用户的时间和点击次数。

暗示的力量

默认选中单选按钮的设计对用户有很强的暗示作用。它可以帮助用户做出最佳决定并增强他们的信心。（请谨慎使用此指导原则，仅用于善意引导。）

开发规范

用法

渲染一个使用单选输入来选择用户类型的界面。

import { RadioControl } from '@wordpress/components';
import { useState } from 'react';

const MyRadioControl = () => {
    const [ option, setOption ] = useState( 'a' );

    return (
        <RadioControl
            label="User type"
            help="The type of the current user"
            selected={ option }
            options={ [
                { label: 'Author', value: 'a' },
                { label: 'Editor', value: 'e' },
            ] }
            onChange={ ( value ) => setOption( value ) }
        />
    );
};

属性

该组件接受以下属性：

help: string | Element

如果添加此属性，将使用 help 属性的内容生成帮助文本。

必填：否

hideLabelFromVision: boolean

如果为 true，则标签仅对屏幕阅读器可见。

必填：否

label: string

如果添加此属性，将使用 label 属性的内容生成标签。

必填：否

onChange: ( value: string ) => void

接收正在选中的新选项的值作为输入的函数。

必填：是

options: { label: string, value: string, description?: string, disabled?: boolean }[]

包含选项值和标签的对象数组。

label: string 显示给用户的标签。
value: string 内部值，用于进行比较和传递给 onChange。
description: string 可选的帮助文本，显示在标签下方。
disabled: boolean 是否禁用该选项。
必填：否

selected: string

当前选中选项的 value 属性。

必填：否