输入
Switch
用于在开/关两种状态之间切换的开关组件
开关（Switch）用于在两种互斥状态之间切换，常见于设置面板中的功能启停。基于 Radix UI Switch 封装，支持主题颜色、多种尺寸和无障碍键盘操作。
import {
Switch,
SwitchRoot,
SwitchThumb
} from '@skyroc/web-ui';何时使用
- 需要在"开"和"关"两种状态之间切换时。
- 设置面板、偏好配置等需要即时生效的布尔选项。
- 需要清晰表达当前状态，并允许用户立即改变状态。
- 如果需要从一组选项中多选，使用 Checkbox；如果状态需要提交后才生效，优先使用 Checkbox 或表单控件组合。
基础用法
通过 defaultChecked 设置非受控初始状态。Switch 本身没有可见文本，建议始终提供 aria-label 或配合外部文本说明。
Preview
Code
Loading...
<Switch
defaultChecked
aria-label="Enable notifications"
/>受控模式
使用 checked 和 onCheckedChange 管理开关状态。onCheckedChange 会返回新的布尔值。
Preview
Code
Loading...
const [checked, setChecked] = useState(false);
<Switch checked={checked} onCheckedChange={setChecked} aria-label="开启通知" />颜色
通过 color 控制开关打开时的颜色，支持全部 8 种语义色。
Preview
Code
Loading...
<Switch color="primary" defaultChecked />
<Switch color="success" defaultChecked />
<Switch color="warning" defaultChecked />
<Switch color="info" defaultChecked />
<Switch color="destructive" defaultChecked />
<Switch color="carbon" defaultChecked />
<Switch color="secondary" defaultChecked />
<Switch color="accent" defaultChecked />尺寸
通过 size 调整开关大小，从 xs 到 2xl 共 6 个尺寸。
Preview
Code
Loading...
| 尺寸 | 轨道尺寸 | 滑块尺寸 | 适用场景 |
|---|---|---|---|
xs | 28×16px | 12px | 紧凑列表、表格内嵌 |
sm | 32×18px | 14px | 侧边栏设置项 |
md | 36×20px | 16px | 常规场景（默认） |
lg | 40×22px | 18px | 强调设置项 |
xl | 44×24px | 20px | 大号设置面板 |
2xl | 52×28px | 24px | 首屏重要开关 |
<Switch size="xs" defaultChecked />
<Switch size="sm" defaultChecked />
<Switch size="md" defaultChecked />
<Switch size="lg" defaultChecked />
<Switch size="xl" defaultChecked />
<Switch size="2xl" defaultChecked />禁用
设置 disabled 后，开关变为不可交互状态。
Preview
Code
Loading...
<Switch disabled />
<Switch disabled defaultChecked />自定义样式
通过 classNames 分别控制 root（轨道）和 thumb（滑块）的样式。
Preview
Code
Loading...
<Switch
classNames={{
root: 'data-[state=checked]:bg-gradient-to-r data-[state=checked]:from-pink-500 data-[state=checked]:to-violet-500',
thumb: 'bg-white'
}}
/>API
Switch
通用属性参考：组合 SwitchRoot 和 SwitchThumb 的主组件。支持 Radix Switch Root 的常用属性和原生 button 属性。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| checked | 受控模式下的开关状态 | boolean | - |
| defaultChecked | 非受控模式下的默认开关状态 | boolean | - |
| onCheckedChange | 开关状态变化时触发 | (checked: boolean) => void | - |
| color | 打开状态的主题颜色 | 'primary' | 'destructive' | 'success' | 'warning' | 'info' | 'carbon' | 'secondary' | 'accent' | 'primary' |
| size | 尺寸，影响轨道和滑块大小 | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'md' |
| children | 滑块内部内容，会渲染到 SwitchThumb 内 | ReactNode | - |
| disabled | 是否禁用开关 | boolean | false |
| required | 是否必填（表单场景） | boolean | - |
| name | 表单字段名称 | string | - |
| value | 表单提交时的值 | string | 'on' |
| className | 轨道的自定义 class；传入有效值时优先于 classNames.root | ClassValue | - |
| classNames | 各 slot 的自定义 class（root / thumb） | ClassNames | - |
| asChild | 将渲染委托给子元素 | boolean | false |
SwitchRoot
底层轨道组件，基于 Radix Switch Root 封装。适合需要自行组合 thumb 时使用。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| color | 打开状态的主题颜色 | 'primary' | 'destructive' | 'success' | 'warning' | 'info' | 'carbon' | 'secondary' | 'accent' | 'primary' |
| size | 尺寸，影响轨道大小 | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'md' |
| checked | 受控模式下的开关状态 | boolean | - |
| defaultChecked | 非受控模式下的默认开关状态 | boolean | - |
| onCheckedChange | 开关状态变化时触发 | (checked: boolean) => void | - |
| disabled | 是否禁用开关 | boolean | false |
| className | 轨道自定义 class | ClassValue | - |
SwitchThumb
底层滑块组件，基于 Radix Switch Thumb 封装。主组件会自动创建 thumb；只有自定义结构时才需要直接使用。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| size | 尺寸，影响滑块大小和位移距离 | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'md' |
| children | 滑块内部内容，例如图标 | ReactNode | - |
| className | 滑块自定义 class | ClassValue | - |
类型
SwitchProps
主组件属性。继承 SwitchRootProps，并增加 classNames 配置；children 会渲染到 SwitchThumb 内。
| 字段 | 类型 | 说明 |
|---|---|---|
| checked | boolean | 受控开关状态。 |
| className | ClassValue | 轨道 class。 |
| classNames | ClassNames | 各 slot 的自定义 class。 |
| color | 'primary' | 'destructive' | 'success' | 'warning' | 'info' | 'carbon' | 'secondary' | 'accent' | 主题颜色。 |
| children | ReactNode | 滑块内部内容。 |
| defaultChecked | boolean | 非受控默认状态。 |
| disabled | boolean | 是否禁用。 |
| name | string | 表单字段名称。 |
| onCheckedChange | (checked: boolean) => void | 状态变化回调。 |
| required | boolean | 是否必填。 |
| size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 组件尺寸。 |
| value | string | 表单提交时的值。 |
SwitchRootProps
轨道组件属性。继承 Radix Switch Root 的常用状态、表单和无障碍属性，并增加主题颜色和尺寸。
| 字段 | 类型 | 说明 |
|---|---|---|
| checked | boolean | 受控开关状态。 |
| defaultChecked | boolean | 非受控默认状态。 |
| onCheckedChange | (checked: boolean) => void | 状态变化回调。 |
| color | 'primary' | 'destructive' | 'success' | 'warning' | 'info' | 'carbon' | 'secondary' | 'accent' | 主题颜色。 |
| size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 轨道尺寸。 |
| disabled | boolean | 是否禁用。 |
| required | boolean | 是否必填。 |
| name | string | 表单字段名称。 |
| value | string | 表单提交时的值。 |
| className | ClassValue | 轨道 class。 |
| asChild | boolean | 将渲染委托给子元素。 |
| ...buttonProps | button element props | 其他 Radix Switch Root / button 属性。 |
SwitchThumbProps
滑块组件属性。继承 Radix Switch Thumb 属性，并增加尺寸和自定义 class。
| 字段 | 类型 | 说明 |
|---|---|---|
| children | ReactNode | 滑块内部内容。 |
| size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 滑块尺寸和选中态位移。 |
| className | ClassValue | 滑块 class。 |
| asChild | boolean | 将渲染委托给子元素。 |