# 单选组

一组交互式单选按钮，一次只能选择一个按钮。

```jsx
<RadioGroup.Root defaultValue="1" name="example">
  <RadioGroup.Item value="1">默认</RadioGroup.Item>

  <RadioGroup.Item value="2">舒适</RadioGroup.Item>

  <RadioGroup.Item value="3">紧凑</RadioGroup.Item>
</RadioGroup.Root>
```

## [API 参考](#api-参考)

该组件继承自 [单选组原语](/primitives/docs/components/radio-group) 的属性，并支持 [常见的边距属性](/themes/docs/overview/layout#margin-props)。

### [根节点](#根节点)

包含单选组的所有部分。

| Prop           | Type                               | Default          |
| -------------- | ---------------------------------- | ---------------- |
| `asChild`      | `boolean`                          | No default value |
| `size`         | `Responsive<"1" \| "2" \| "3">`    | `"2"`            |
| `variant`      | `"classic" \| "surface" \| "soft"` | `"surface"`      |
| `color`        | `enum`                             | No default value |
| `highContrast` | `boolean`                          | No default value |

### [项目](#项目)

组内可选中的项。

## [示例](#示例)

### [尺寸](#尺寸)

使用 `size` 属性来控制单选按钮的大小。

```jsx
<Flex align="center" gap="2">
  <RadioGroup.Root size="1" defaultValue="1">
    <RadioGroup.Item value="1" />
  </RadioGroup.Root>

  <RadioGroup.Root size="2" defaultValue="1">
    <RadioGroup.Item value="1" />
  </RadioGroup.Root>

  <RadioGroup.Root size="3" defaultValue="1">
    <RadioGroup.Item value="1" />
  </RadioGroup.Root>
</Flex>
```

### [变体](#变体)

使用 `variant` 属性来控制单选按钮的视觉风格。

```jsx
<Flex gap="2">
  <Flex direction="column" asChild gap="2">
    <RadioGroup.Root variant="surface" defaultValue="1">
      <RadioGroup.Item value="1" />

      <RadioGroup.Item value="2" />
    </RadioGroup.Root>
  </Flex>

  <Flex direction="column" asChild gap="2">
    <RadioGroup.Root variant="classic" defaultValue="1">
      <RadioGroup.Item value="1" />

      <RadioGroup.Item value="2" />
    </RadioGroup.Root>
  </Flex>

  <Flex direction="column" asChild gap="2">
    <RadioGroup.Root variant="soft" defaultValue="1">
      <RadioGroup.Item value="1" />

      <RadioGroup.Item value="2" />
    </RadioGroup.Root>
  </Flex>
</Flex>
```

### [颜色](#颜色)

使用 `color` 属性分配特定的 [颜色](/themes/docs/theme/color)。

```jsx
<Flex gap="2">
  <RadioGroup.Root color="indigo" defaultValue="1">
    <RadioGroup.Item value="1" />
  </RadioGroup.Root>

  <RadioGroup.Root color="cyan" defaultValue="1">
    <RadioGroup.Item value="1" />
  </RadioGroup.Root>

  <RadioGroup.Root color="orange" defaultValue="1">
    <RadioGroup.Item value="1" />
  </RadioGroup.Root>

  <RadioGroup.Root color="crimson" defaultValue="1">
    <RadioGroup.Item value="1" />
  </RadioGroup.Root>
</Flex>
```

### [高对比度](#高对比度)

使用 `highContrast` 属性提高与背景的颜色对比度。

```jsx
<Grid rows="2" gap="2" display="inline-grid" flow="column">
  <RadioGroup.Root color="indigo" defaultValue="1">
    <RadioGroup.Item value="1" />
  </RadioGroup.Root>

  <RadioGroup.Root color="indigo" defaultValue="1" highContrast>
    <RadioGroup.Item value="1" />
  </RadioGroup.Root>

  <RadioGroup.Root color="cyan" defaultValue="1">
    <RadioGroup.Item value="1" />
  </RadioGroup.Root>

  <RadioGroup.Root color="cyan" defaultValue="1" highContrast>
    <RadioGroup.Item value="1" />
  </RadioGroup.Root>

  <RadioGroup.Root color="orange" defaultValue="1">
    <RadioGroup.Item value="1" />
  </RadioGroup.Root>

  <RadioGroup.Root color="orange" defaultValue="1" highContrast>
    <RadioGroup.Item value="1" />
  </RadioGroup.Root>

  <RadioGroup.Root color="crimson" defaultValue="1">
    <RadioGroup.Item value="1" />
  </RadioGroup.Root>

  <RadioGroup.Root color="crimson" defaultValue="1" highContrast>
    <RadioGroup.Item value="1" />
  </RadioGroup.Root>

  <RadioGroup.Root color="gray" defaultValue="1">
    <RadioGroup.Item value="1" />
  </RadioGroup.Root>

  <RadioGroup.Root color="gray" defaultValue="1" highContrast>
    <RadioGroup.Item value="1" />
  </RadioGroup.Root>
</Grid>
```

### [对齐](#对齐)

将 `RadioGroup.Item` 组合在 `Text` 中会自动与文本的第一行居中对齐。

```jsx
<Flex direction="column" gap="3">
  <RadioGroup.Root size="1" defaultValue="1">
    <Text as="label" size="2">
      <Flex gap="2">
        <RadioGroup.Item value="1" /> 默认
      </Flex>
    </Text>

    <Text as="label" size="2">
      <Flex gap="2">
        <RadioGroup.Item value="2" /> 紧凑
      </Flex>
    </Text>
  </RadioGroup.Root>

  <RadioGroup.Root size="2" defaultValue="1">
    <Text as="label" size="3">
      <Flex gap="2">
        <RadioGroup.Item value="1" /> 默认
      </Flex>
    </Text>

    <Text as="label" size="3">
      <Flex gap="2">
        <RadioGroup.Item value="2" /> 紧凑
      </Flex>
    </Text>
  </RadioGroup.Root>

  <RadioGroup.Root size="3" defaultValue="1">
    <Text as="label" size="4">
      <Flex gap="2">
        <RadioGroup.Item value="1" /> 默认
      </Flex>
    </Text>

    <Text as="label" size="4">
      <Flex gap="2">
        <RadioGroup.Item value="2" /> 紧凑
      </Flex>
    </Text>
  </RadioGroup.Root>
</Flex>
```

在多行文本中也会自动保持良好的对齐。

### [禁用](#禁用)

使用原生 `disabled` 属性创建一个禁用的单选按钮。

```jsx
<Flex direction="column" gap="2">
  <RadioGroup.Root defaultValue="2">
    <RadioGroup.Item value="1">关闭</RadioGroup.Item>

    <RadioGroup.Item value="2">开启</RadioGroup.Item>
  </RadioGroup.Root>

  <RadioGroup.Root defaultValue="2">
    <RadioGroup.Item value="1" disabled>
      关闭
    </RadioGroup.Item>

    <RadioGroup.Item value="2" disabled>
      开启
    </RadioGroup.Item>
  </RadioGroup.Root>
</Flex>
```

<!--$-->

<!--/$-->