Skip to main content

开关 Switch

Radix UI 封装的开关组件，支持可访问性、键盘导航、焦点样式和状态样式，适用于二元状态切换（如开关、启用/禁用）。

📦 引入方式​

import { Switch } from '@npmqg/react-ui-core';

🧩 使用示例​

📚 非受控用法（默认状态）​

📚 受控用法​

const [enabled, setEnabled] = React.useState(false);

<Switch checked={enabled} onCheckedChange={setEnabled} />;

📚 禁用状态​

📚 搭配表单标签使用​

🧩 Props​

属性类型默认值描述
checkedboolean—控制组件是否为选中状态（受控）
defaultCheckedboolean—初始是否为选中状态（非受控）
onCheckedChange(checked: boolean) => void—状态切换时的回调
disabledbooleanfalse是否禁用
classNamestring—自定义 class 样式
其他React.ComponentPropsWithoutRef<typeof SwitchPrimitives.Root>—其他传递给根元素的原生属性

✅ 可访问性支持​

  • 支持键盘导航（Tab、空格键）
  • 支持屏幕阅读器识别状态
  • 使用 focus-visible 提供可视焦点环样式

💡 开发建议​

  • 若需设置颜色风格，可通过类名控制 bg-* 与 ring-* 等样式。
  • 你可以结合 label 或 aria-label 提供更好的可访问体验。
  • 推荐搭配 form 表单库（如 React Hook Form）实现表单值同步。