> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/switch.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# Switch 开关

即时开启或关闭某项设置。


## 基础用法

使用开关切换开启和关闭状态，并提供关联名称。


开启通知

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/switch/basic.tsx"
import { Switch } from '@ifhover/leaf-ui';

export function SwitchBasic() {
  return <Switch>开启通知</Switch>;
}
```

展开代码


## 示例

### 禁用与加载

`disabled` 禁用交互。保存期间设置 `loading` 可阻止重复操作，异步请求由应用处理。


禁用

开启通知

加载

开启通知

states.tsx

复制代码

```tsx lineNumbers file="../../src/examples/switch/states.tsx"
import { Flex, Grid, Switch, Text } from '@ifhover/leaf-ui';

export function SwitchStates() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      <Text tone="muted">禁用</Text>
      <Flex align="center" wrap>
        <Switch disabled defaultChecked>
          开启通知
        </Switch>
      </Flex>
      <Text tone="muted">加载</Text>
      <Flex align="center" wrap>
        <Switch loading defaultChecked>
          开启通知
        </Switch>
      </Flex>
    </Grid>
  );
}
```

展开代码

### 尺寸

通过 `size` 设置开关尺寸。


小

开启通知

中

开启通知

大

开启通知

sizes.tsx

复制代码

```tsx lineNumbers file="../../src/examples/switch/sizes.tsx"
import { Flex, Grid, Switch, Text } from '@ifhover/leaf-ui';
import { Fragment } from 'react';

const options = [
  { value: 'sm', label: '小' },
  { value: 'md', label: '中' },
  { value: 'lg', label: '大' },
] as const;

export function SwitchSizes() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      {options.map(({ value, label }) => (
        <Fragment key={value}>
          <Text tone="muted">{label}</Text>
          <Flex align="center" wrap>
            <Switch size={value}>开启通知</Switch>
          </Flex>
        </Fragment>
      ))}
    </Grid>
  );
}
```

展开代码

### 受控状态

通过 `checked` 控制状态，在 `onChange` 中从 `event.target.checked` 读取布尔值。


接收邮件邮件通知已开启

controlled.tsx

复制代码

```tsx lineNumbers file="../../src/examples/switch/controlled.tsx"
import { Flex, Switch, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function SwitchControlled() {
  const [checked, setChecked] = useState(true);
  return (
    <Flex direction="column" gap="md" align="start">
      <Switch checked={checked} onChange={(event) => setChecked(event.target.checked)}>
        接收邮件
      </Switch>
      <Text tone="muted" role="status">
        {checked ? '邮件通知已开启' : '邮件通知已关闭'}
      </Text>
    </Flex>
  );
}
```

展开代码

设置 `name` 后，已开启且未禁用的开关提交其 `value`；未开启、禁用或加载时不参与提交。非受控开关在表单重置时恢复 `defaultChecked`，受控开关需要同步重置应用状态。


## API

### Switch API

配置开关的选中状态、提交字段与交互状态。

支持 `name`、`value`、`required`、`form` 等原生 checkbox 属性。通过文字或 `aria-label` 提供名称；`className` 和 `style` 作用于标签容器。

| 属性               | 类型                                     | 默认值     | 说明                             |
| ---------------- | -------------------------------------- | ------- | ------------------------------ |
| `size`           | `'sm' \| 'md' \| 'lg'`                 | `'md'`  | 开关尺寸                           |
| `loading`        | `boolean`                              | `false` | 显示加载状态并禁用交互                    |
| `checked`        | `boolean`                              | —       | 受控的开关状态。                       |
| `defaultChecked` | `boolean`                              | —       | 非受控模式的初始开关状态。                  |
| `onChange`       | `ChangeEventHandler<HTMLInputElement>` | —       | 从 event.target.checked 读取开关状态。 |
| `disabled`       | `boolean`                              | `false` | 禁用交互。                          |
| `children`       | `ReactNode`                            | —       | 可点击的文字标签。                      |
| `ref`            | `Ref<HTMLInputElement>`                | —       | 开关引用                           |
