0 Fork 0

Files

T

2026-10-09 17:32:14 +08:00

2.6 KiB

Raw Blame History

title, description

title	description
Switch 开关	用于切换单个状态的即时开关

Switch 开关

Switch 表示「开 / 关」两态，通常立即生效（不需要点保存）。

何时使用

设置项里即时生效的开关（启用通知、公开可见）；
表格行内的状态切换；
需要注意：Switch 不是复选框的替代品。多个选项之间互不排斥、需要一起提交时用 Checkbox。

基础用法

v-model 绑定 boolean；change 回传新值与原生事件。

禁用态

与表单一起使用

放入 G3FormItem 时，label 与校验由表单负责，Switch 只提供值。

关于「异步切换」

组件本身不做 loading/回滚，因为「乐观切换 + 失败回滚」的业务语义差异很大。推荐在 change 里显式处理：

async function onChange(next: boolean) {
  const previous = !next
  try {
    await api.update(next)
  } catch {
    enabled.value = previous // 失败回滚
    G3Message.error('保存失败')
  }
}

API

Props

名称	类型	默认值	说明
`modelValue`	`boolean`	`false`	双向绑定的开关状态
`disabled`	`boolean`	`false`	禁用态

Events

名称	参数	说明
`update:modelValue`	`(value: boolean)`	状态变化
`change`	`(value: boolean, event: MouseEvent)`	同上，附带原生点击事件

Slots

名称	参数	说明
`default`	—	开关旁的文案（可点击切换）

类型定义

export interface SwitchProps {
  modelValue?: boolean
  disabled?: boolean
}

样式变量

变量	默认值	说明
`--g3-switch-width`	`32px`	轨道宽
`--g3-switch-height`	`18px`	轨道高
`--g3-switch-thumb-size`	`14px`	滑块直径
`--g3-switch-thumb-offset`	`2px`	滑块内边距
`--g3-color-primary`	`#18181b`	开启态轨道色

实现说明

没有原生的 <input type="switch">，因此用 <button type="button" role="switch" aria-checked> 承载语义：Enter / Space 由原生按钮自动转为 click；
aria-checked 会跟随 modelValue 更新，屏幕阅读器能播报「开 / 关」；
滑块的位移由固定变量计算（宽度 - 滑块 - 内边距×2），因此改 --g3-switch-* 变量后滑块位置依然正确，不需要改代码；
文字部分也在按钮内，因此点击文字同样可以切换（按钮整体是一个目标区域，触屏上更好点）。

2.6 KiB Raw Blame History Unescape Escape