跳到主要内容

Switch 开关Switch

打开或关闭一个立即生效的设置,比如“深色模式”“接收通知”。需要点“保存”才生效的选项用 Checkbox。

基本用法

children 是开关旁的文字,点文字同样可以切换。按住时滑块会拉伸,松开弹到另一侧。

没有可见文字

只有开关本身时必须给 aria-label,或者放进带标签的 Field(标签在上、开关在下,提示文字会一并关联)。

每周一早上发到邮箱

禁用

禁用后轨道只剩描边、滑块变灰;开着的保留淡强调色,仍能看出状态。

受控用法

onChange 的参数是新的布尔值。

已关闭

规格

尺寸
54 × 32 · 滑块 32 × 26
按住
滑块宽 32 → 38 · 150ms
切换
位移走弹簧
禁用
轨道只剩描边、滑块变灰;开着的保留淡强调色

API

属性

属性类型默认值说明
checkedboolean—是否打开(受控)。
defaultCheckedbooleanfalse初始是否打开(非受控)。
onChange(checked: boolean) => void—状态变化时触发,参数是新状态。
childrenReactNode—开关旁的文字。
disabledboolean—禁用。
name / valuestring—原生属性:放在表单里时,打开才会提交。
rootClassName / rootStylestring / CSSProperties—外层 <label> 的类名与样式。className / style 同样落在 <label> 上。
…restInputHTMLAttributes—其余原生属性和 ref 落在 <input> 上。

无障碍

  • 是真的 <input type="checkbox" role="switch">,读屏读作“开关,开 / 关”。
  • Tab 聚焦,Space 切换。
  • 必须有可读名称:写 children、给 aria-label,或放进带标签的 Field。
  • 开关表示“立即生效”。切换后如果有异步请求,失败时要把状态拨回去并说明原因。
  • 状态除了颜色还有滑块位置这第二种提示。