React 组件

UGSwitch 开关

用于立即切换两个互斥状态，支持受控与非受控、尺寸、标签、加载、切换守卫和原生表单提交。

导入方式

按需从包入口导入组件，并在应用入口引入一次样式文件。

tsx

import { UGSwitch } from '@ug666/ui-react'

标签与控件形成同一点击区域；没有标签时应提供 aria-label。

启用自动保存

根据表单排版将标签放在轨道左侧或右侧。

邮件通知短信通知

状态文本可放在轨道两侧或内部；图标和滑块动作内容分别承担说明与反馈。

使用真实尺寸属性，不通过 transform 缩放控件。

小号默认大号

禁用和加载会阻止重复切换；aria-invalid 同步无障碍语义和可见错误边框。

禁用正在保存必须开启同步_workspace_notification_channel_20260805 的所有状态变更

beforeChange 适合权限确认或保存前校验；成功后才提交新状态。

同步到工作区

设置 name 后以原生 checkbox 语义提交；reset 恢复 defaultChecked。

属性	类型	默认值	说明
checked / defaultChecked	boolean	— / false	受控状态或非受控初始状态。
onCheckedChange	(checked: boolean) => void	—	状态成功切换后触发。
beforeChange	(next) => boolean \| Promise<boolean>	—	切换前守卫；返回 false 或抛错会取消切换。
loading	boolean	false	显示处理中状态并阻止重复操作。
label	string	—	可点击的开关标签。
labelPlacement	'left' \| 'right'	'right'	标签位置。
width	number \| string	随尺寸计算	设置轨道宽度，并保留可操作的最小宽度。
activeText / inactiveText	string	—	在轨道两侧或内部显示开启、关闭状态文本。
activeIcon / inactiveIcon	ReactNode	—	状态图标，存在时覆盖同状态文本。
inlinePrompt	boolean	false	将当前状态文本或图标放入轨道。
activeAction / inactiveAction	ReactNode	—	自定义滑块内部的开启与关闭内容。
size	'sm' \| 'default' \| 'lg'	全局配置 / default	开关尺寸。
disabled	boolean	全局配置 / false	禁用切换。
aria-invalid	原生 ARIA 属性	—	表单校验失败时同步无障碍语义和危险色轨道边框。
name / value / form	原生表单属性	— / on / —	将开关状态同步为原生 checkbox 提交。
原生属性 / ref	ButtonHTMLAttributes / Ref<HTMLButtonElement>	—	透传到 role=switch 的真实按钮。