跳转到内容
编辑此页面

Radio 单选框组件

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

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

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

Radio group

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

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

方向

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

Controlled

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

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

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

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

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

标签放置

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

显示错误

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

Choose wisely

Customized radios 自定义单选框

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

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])：所被选定的单选框的值。

示例

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

什么时候使用

无障碍设计

(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