Radio 单选框组件

用户可以通过单选按钮从一组中选择一个选项。

当用户想要看到所有的选项时，可以使用单选按钮。如果可用的选项可以折叠，请考虑使用选择组件，因为它使用的空间较少。

默认情况下，单选按钮应该选择了最常用的选项。

Radio group

RadioGroup 适用于一组 Radio，它提供相对简单的 API 并且能够使用键盘对该 RadioGroup 进行控制。

Gender

FemaleMaleOther

<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>

Press Enter to start editing

方向

要使按钮水平布局，需要将 row 属性设置为：

Gender

FemaleMaleOtherother

Controlled

You can control the radio with the value and onChange props:

Gender

FemaleMale

<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>

Press Enter to start editing

Standalone radio buttons 独立的单选框按钮

Radio 也可以单独使用，无需额外的 RadioGroup wrapper。

<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' }}
/>

Press Enter to start editing

Size 大小

Use the size prop or customize the font size of the svg icons to change the size of the radios.

<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,
    },
  }}
/>

Press Enter to start editing

Color 颜色

<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],
    },
  }}
/>

Press Enter to start editing

标签放置

你可以用 FormControlLabel 组件的 labelPlacement 属性来改变标签的位置。

Label placement

TopStartBottomEnd

显示错误

一般来说，单选按钮应带有一个默认选中的值。如果不是这种情况，若用户在提交表单时如果未选择任何值，您可以让其显示一个错误：

Customized radios 自定义单选框

以下是自定义组件的一个示例。 You can learn more about this in the overrides documentation page.

Gender

FemaleMaleOther(Disabled option)

`useRadioGroup`

对于需要高级定制用例的情况，您可以使用一个 useRadioGroup() hook。这将会返回单选框组上下文的值。单选框组件在其内部会使用这个 hook。

API

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

返回结果

value (object):

value.name (string [optional])：用于引用控件值的名称。
value.onChange (func [optional])：选择单选按钮时触发的回调。
value.value (any [optional])：所被选定的单选框的值。

示例

FirstSecond

<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>

Press Enter to start editing

什么时候使用

多选框对比单选按钮（Radio Buttons）

无障碍设计

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

所有表单控件都应该带有标签，而这包括了单选按钮，复选框和开关。 In most cases, this is done by using the <label> element (FormControlLabel).
如果无法使用标签，您则必须在输入组件中直接添加属性。在这种情况下，您可以经由 inputProps 属性，来附着一些额外的属性（例如 arial-label，aria-labelledby，title）。

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

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.