Ordo UI
组件Controls

Switch

@mox-hub/ui 组件 · Controls · canonical

switch@mox-hub/uiControlscanonicalsrc/components/switch.tsx
变体演示switch

Props API

Prop类型默认值说明
className*string | ((state: SwitchRootState) => string)——
size*"default" | "sm""default"—
onChange*(event: { target: { checked: boolean; }; }) => void——
onCheckedChange*(checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element; }) => void——
style*CSSProperties | ((state: SwitchRootState) => CSSProperties)——

源码

packages/ui/src/components/switch.tsx
"use client"

import * as React from "react"
import { Switch as SwitchPrimitive } from "@base-ui/react/switch"
import { useDirection } from "@base-ui/react/direction-provider"

import { cn } from "../lib/utils"

// 兼容层:onChange({ target: { checked } })(历史 API)映射为 onCheckedChange
function Switch({
  className,
  size = "default",
  onChange,
  onCheckedChange,
  style,
  ...props
}: SwitchPrimitive.Root.Props & {
  size?: "sm" | "default"
  onChange?: (event: { target: { checked: boolean } }) => void
}) {
  const direction = useDirection()
  return (
    <SwitchPrimitive.Root
      data-slot="switch"
      data-size={size}
      style={
        {
          ...style,
          // 位移量按书写方向取符号:RTL 下 checked 要向左移,且只声明一次,
          // 避免与 translate 工具类在样式表顺序上打架(审计 P1-04c)。
          "--switch-x":
            direction === "rtl"
              ? "calc(-100% + var(--switch-inset, 2px))"
              : "calc(100% - var(--switch-inset, 2px))",
        } as React.CSSProperties
      }
      className={cn(
        "peer group/switch relative inline-flex shrink-0 items-center rounded-full border border-transparent shadow-xs transition-[color,background-color,border-color,box-shadow] duration-fast outline-none group-has-[:focus-visible]/field-label:border-transparent group-has-[:focus-visible]/field-label:ring-0 after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 data-[size=default]:h-5 data-[size=default]:w-8 [[data-contrast=high]_&]:[--switch-inset:4px] data-[size=sm]:h-3.5 data-[size=sm]:w-6 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-checked:bg-primary data-unchecked:bg-input dark:data-unchecked:bg-input/80 data-disabled:cursor-not-allowed data-disabled:opacity-50",
        className
      )}
      onCheckedChange={
        onCheckedChange ??
        (onChange ? (checked: boolean) => onChange({ target: { checked } }) : undefined)
      }
      {...props}
    >
      <SwitchPrimitive.Thumb
        data-slot="switch-thumb"
        className="pointer-events-none block rounded-full bg-background ring-0 transition-transform duration-fast group-data-[size=default]/switch:size-4 group-data-[size=sm]/switch:size-3 group-data-[size=default]/switch:data-checked:translate-x-(--switch-x) group-data-[size=sm]/switch:data-checked:translate-x-(--switch-x) dark:data-checked:bg-primary-foreground group-data-[size=default]/switch:data-unchecked:translate-x-0 group-data-[size=sm]/switch:data-unchecked:translate-x-0 dark:data-unchecked:bg-foreground"
      />
    </SwitchPrimitive.Root>
  )
}

export { Switch }

可访问性与 RTL

  • 键盘:交互件保留:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。
  • RTL:间距、对齐与方向性图标使用逻辑属性 (ms-* /text-start /rtl:-scale-x-100);通过 ThemeProvider 或I18nProvider 的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。
  • 文案:优先用组件labels /translate /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

开关,受控用 checked 与 onCheckedChange;即时生效的设置项使用,提交型表单用 checkbox。