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

# Switch

数据录入`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

立即切换一个布尔设置，并展示当前开关状态。

## 何时使用

设置可立即生效且不需要额外提交时使用 Switch。

**推荐**

- 标签描述开启后的状态。
- 异步切换期间使用 loading。

**避免**

- 需要提交确认或选择多个值时不要使用 Switch。

## 代码演示


### 基础用法
```tsx preview
import { Stack, Switch } from '@rockshin/tao-ui';
import { useState } from 'react';

function SwitchExample() {
  const [enabled, setEnabled] = useState(true);

  return (
    <Stack direction="horizontal" gap="lg" align="center">
      <Switch checked={enabled} onChange={setEnabled} />
      <Switch checked loading />
      <Switch disabled />
    </Stack>
  );
}

export default SwitchExample;
```

### 标签与尺寸
```tsx preview
import { Stack, Switch } from '@rockshin/tao-ui';

function SwitchLabels() {
  return (
    <Stack direction="horizontal" gap="lg" align="center">
      <Switch size="small" defaultChecked />
      <Switch checkedChildren="ON" unCheckedChildren="OFF" defaultChecked />
      <Switch
        aria-label="接收通知"
        checkedChildren={
          <svg
            width="14"
            height="14"
            viewBox="0 0 16 16"
            fill="none"
            stroke="currentColor"
            strokeWidth="2"
            strokeLinecap="round"
            strokeLinejoin="round"
            aria-hidden="true"
            focusable="false"
          >
            <path d="m3 8 3 3 7-7" />
          </svg>
        }
        unCheckedChildren={
          <svg
            width="14"
            height="14"
            viewBox="0 0 16 16"
            fill="none"
            stroke="currentColor"
            strokeWidth="2"
            strokeLinecap="round"
            aria-hidden="true"
            focusable="false"
          >
            <path d="m4 4 8 8m0-8-8 8" />
          </svg>
        }
      />
    </Stack>
  );
}

export default SwitchLabels;
```

### 加载与禁用状态
```tsx preview
import { Stack, Switch } from '@rockshin/tao-ui';

function SwitchStates() {
  return (
    <Stack direction="horizontal" gap="lg" align="center">
      <Switch loading checked />
      <Switch disabled />
      <Switch checked disabled />
    </Stack>
  );
}

export default SwitchStates;
```

### 受控开关
onChange 返回布尔值，可直接与设置状态同步。
```tsx preview
import { useState } from 'react';
import { Switch, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [enabled, setEnabled] = useState(true);
  return (
    <Stack direction="vertical">
      <Switch
        aria-label="Notifications"
        checked={enabled}
        onChange={setEnabled}
      />
      <output>
        {enabled ? 'Notifications enabled' : 'Notifications disabled'}
      </output>
    </Stack>
  );
}
```

### 加载期间禁止重复切换
使用独立按钮切换 loading，观察开关的等待状态。
```tsx preview
import { useState } from 'react';
import { Switch, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [loading, setLoading] = useState(false);
  return (
    <Stack direction="vertical">
      <Switch aria-label="Sync" loading={loading} defaultChecked />
      <Button onClick={() => setLoading(!loading)}>
        {loading ? 'Finish loading' : 'Start loading'}
      </Button>
    </Stack>
  );
}
```

### 状态文字与尺寸
简短文字适合双态开关，大小尺寸都应保持完整可读。
```tsx preview
import { Switch, Stack } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Stack direction="vertical">
      <Switch
        aria-label="Access"
        checkedChildren="On"
        unCheckedChildren="Off"
        defaultChecked
      />
      <Switch
        size="small"
        aria-label="Compact access"
        checkedChildren="On"
        unCheckedChildren="Off"
        defaultChecked
      />
      <Switch
        aria-label="Locked access"
        checkedChildren="On"
        unCheckedChildren="Off"
        defaultChecked
        disabled
      />
    </Stack>
  );
}
```

### 共享尺寸与禁用
多个开关可继承配置，局部 disabled 可以覆盖。
```tsx preview
import { Switch, TaoProvider, Stack } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <TaoProvider size="small" disabled>
      <Stack>
        <Switch aria-label="Inherited disabled" defaultChecked />
        <Switch aria-label="Enabled override" disabled={false} />
      </Stack>
    </TaoProvider>
  );
}
```

## API


### [#](#switch)Switch



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| disabled | 是否禁用 | `boolean | undefined` | `-` |
| className | 节点类名 | `string | undefined` | `-` |
| style | 节点样式 | `CSSProperties | undefined` | `-` |

