输入类 · Switch
开关
开关是用于切换两种互斥状态的交互形式

代码演示

如何引入

基本

你可以通过 onChange 监听状态变化,通过 defaultChecked 或受控的 checked 制定选中状态。
通过 aria-label 描述该 Switch 开关的具体作用

尺寸

你可以通过 size 指定尺寸

不可用

带文本

可以通过 checkedTextuncheckedText 设置开关时的文本
注意:此项功能在最小的开关(即 size='small'时)无效
相比于通过 chekedText 与 uncheckedText 设置内嵌的文本,我们更推荐将文本说明放置在 Switch 外部

受控组件

组件是否选中完全取决于传入的 checked 值,配合 onChange 回调函数使用

加载中

version: >= 1.29.0
可以通过设置 loading="true" 开启加载中状态。

API 参考

属性说明类型默认值版本
aria-labelaria-label属性,用来给当前元素加上的标签描述, 提升可访问性string2.2.0
aria-labelledbyaria-labelledby属性,表明某些元素的 id 是某一对象的标签。它被用来确定控件或控件组与它们标签之间的联系, 提升可访问性string2.2.0
className类名string
checked指示当前是否选中,配合 onChange 使用booleanfalse
checkedText打开时展示的内容, size 为 small 时无效ReactNode
defaultChecked初始是否选中booleanfalse
disabled是否禁用booleanfalse
loading设置加载状态booleanfalse1.29.0
onChange变化时回调函数function(checked:boolean)
onMouseEnter鼠标移入时回调function()
onMouseLeave鼠标移出时回调function()
size尺寸,可选值large,default,smallstring'default'
style内联样式object
uncheckedText关闭时展示的内容, size 为 small 时无效ReactNode

Accessibility

ARIA

  • Switch 具有 switch role,当 checked 为 true 时,aria-checked 将被自动设置为 true,反之亦然
  • 作为表单控件应该带有 Label,当你使用 Form.Switch 时会自动被带上
  • 如果你单独使用 Switch,建议使用 aria-label 描述当前标签作用

键盘和焦点

  • 键盘用户可以使用 TabShift + Tab 切换焦点
  • 聚焦时可以通过 Space 键切换开启或关闭状态

文案规范

  • 开关描述
    • 首字母大写,不需要标点符号
    • 间接明了地说明该设置的开启或关闭状态
    • 如果需要,解释给用户开启和关闭状态所代表的情况

设计变量