单选按钮组

单选按钮组允许用户从一组选项中选择一个。

当用户需要查看所有可用选项时，请使用单选按钮。如果可用选项可以折叠，请考虑使用 Select 组件，因为它占用空间更少。

单选按钮应默认选择最常用的选项。

单选按钮组

RadioGroup 是一个有用的包装器，用于将 Radio 组件分组，从而提供更简单的 API，并为该组提供适当的键盘可访问性。

性别

女性男性其他

<FormControl>
  <FormLabel id="demo-radio-buttons-group-label">Gender</FormLabel>
  <RadioGroup
    aria-labelledby="demo-radio-buttons-group-label"
    defaultValue="female"
    name="radio-buttons-group"
  >
    <FormControlLabel value="female" control={<Radio />} label="Female" />
    <FormControlLabel value="male" control={<Radio />} label="Male" />
    <FormControlLabel value="other" control={<Radio />} label="Other" />
  </RadioGroup>
</FormControl>

<FormControl>
  <FormLabel id="demo-radio-buttons-group-label">Gender</FormLabel>
  <RadioGroup
    aria-labelledby="demo-radio-buttons-group-label"
    defaultValue="female"
    name="radio-buttons-group"
  >
    <FormControlLabel value="female" control={<Radio />} label="Female" />
    <FormControlLabel value="male" control={<Radio />} label="Male" />
    <FormControlLabel value="other" control={<Radio />} label="Other" />
  </RadioGroup>
</FormControl>

按 Enter 键开始编辑

方向

要水平排列按钮，请设置 `row` 属性

性别

女性男性其他其他

受控

您可以使用 `value` 和 `onChange` 属性控制单选按钮

性别

女性男性

<FormControl>
  <FormLabel id="demo-controlled-radio-buttons-group">Gender</FormLabel>
  <RadioGroup
    aria-labelledby="demo-controlled-radio-buttons-group"
    name="controlled-radio-buttons-group"
    value={value}
    onChange={handleChange}
  >
    <FormControlLabel value="female" control={<Radio />} label="Female" />
    <FormControlLabel value="male" control={<Radio />} label="Male" />
  </RadioGroup>
</FormControl>

<FormControl>
  <FormLabel id="demo-controlled-radio-buttons-group">Gender</FormLabel>
  <RadioGroup
    aria-labelledby="demo-controlled-radio-buttons-group"
    name="controlled-radio-buttons-group"
    value={value}
    onChange={handleChange}
  >
    <FormControlLabel value="female" control={<Radio />} label="Female" />
    <FormControlLabel value="male" control={<Radio />} label="Male" />
  </RadioGroup>
</FormControl>

按 Enter 键开始编辑

独立单选按钮

Radio 也可以独立使用，无需 RadioGroup 包装器。

<Radio
  checked={selectedValue === 'a'}
  onChange={handleChange}
  value="a"
  name="radio-buttons"
  inputProps={{ 'aria-label': 'A' }}
/>
<Radio
  checked={selectedValue === 'b'}
  onChange={handleChange}
  value="b"
  name="radio-buttons"
  inputProps={{ 'aria-label': 'B' }}
/>

<Radio
  checked={selectedValue === 'a'}
  onChange={handleChange}
  value="a"
  name="radio-buttons"
  inputProps={{ 'aria-label': 'A' }}
/>
<Radio
  checked={selectedValue === 'b'}
  onChange={handleChange}
  value="b"
  name="radio-buttons"
  inputProps={{ 'aria-label': 'B' }}
/>

按 Enter 键开始编辑

尺寸

使用 `size` 属性或自定义 svg 图标的字体大小来更改单选按钮的大小。

<Radio {...controlProps('a')} size="small" />
<Radio {...controlProps('b')} />
<Radio
  {...controlProps('c')}
  sx={{
    '& .MuiSvgIcon-root': {
      fontSize: 28,
    },
  }}
/>

<Radio {...controlProps('a')} size="small" />
<Radio {...controlProps('b')} />
<Radio
  {...controlProps('c')}
  sx={{
    '& .MuiSvgIcon-root': {
      fontSize: 28,
    },
  }}
/>

按 Enter 键开始编辑

颜色

<Radio {...controlProps('a')} />
<Radio {...controlProps('b')} color="secondary" />
<Radio {...controlProps('c')} color="success" />
<Radio {...controlProps('d')} color="default" />
<Radio
  {...controlProps('e')}
  sx={{
    color: pink[800],
    '&.Mui-checked': {
      color: pink[600],
    },
  }}
/>

<Radio {...controlProps('a')} />
<Radio {...controlProps('b')} color="secondary" />
<Radio {...controlProps('c')} color="success" />
<Radio {...controlProps('d')} color="default" />
<Radio
  {...controlProps('e')}
  sx={{
    color: pink[800],
    '&.Mui-checked': {
      color: pink[600],
    },
  }}
/>

按 Enter 键开始编辑

标签位置

您可以使用 `FormControlLabel` 组件的 `labelPlacement` 属性更改标签的位置

标签位置

底部尾部

显示错误

通常，单选按钮应默认选择一个值。如果不是这种情况，您可以在提交表单时未选择任何值的情况下显示错误

自定义

这是自定义组件的示例。您可以在覆盖文档页面中了解更多信息。

性别

女性男性其他（禁用选项）

`useRadioGroup`

对于高级自定义用例，公开了一个 `useRadioGroup()` hook。它返回父单选按钮组的上下文值。Radio 组件在内部使用此 hook。

API

import { useRadioGroup } from '@mui/material/RadioGroup';

返回值

value (对象)

value.name (字符串 [可选])：用于引用控件值的名称。
value.onChange (函数 [可选])：当选择单选按钮时触发的回调。
value.value (任意类型 [可选])：所选单选按钮的值。

示例

第一第二

<RadioGroup name="use-radio-group" defaultValue="first">
  <MyFormControlLabel value="first" label="First" control={<Radio />} />
  <MyFormControlLabel value="second" label="Second" control={<Radio />} />
</RadioGroup>

<RadioGroup name="use-radio-group" defaultValue="first">
  <MyFormControlLabel value="first" label="First" control={<Radio />} />
  <MyFormControlLabel value="second" label="Second" control={<Radio />} />
</RadioGroup>

按 Enter 键开始编辑

何时使用

复选框 vs. 单选按钮

可访问性

(WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/radio/)

所有表单控件都应具有标签，包括单选按钮、复选框和开关。在大多数情况下，这是通过使用 `<label>` 元素 (FormControlLabel) 完成的。
当无法使用标签时，需要直接向 input 组件添加属性。在这种情况下，您可以通过 `inputProps` 属性应用附加属性（例如 `aria-label`、`aria-labelledby`、`title`）。

<Radio
  value="radioA"
  inputProps={{
    'aria-label': 'Radio A',
  }}
/>

API

请参阅下面的文档，以获得此处提及的组件的所有可用属性和类的完整参考。