Switch 开关
Switch 用来打开或关闭一项设置。它是一个 role="switch" 的按钮:打开时滑块滑到轨道另一端,轨道换成主色填充。
演示
基础用法
给开关加 aria-label,或者和文字一起包在 label 里,这样点文字也能切换。
尺寸
形状
轨道默认是胶囊形;round={false} 使用主题的圆角。
加载中
loading 在滑块里显示加载圈,并忽略点击。适合在保存改动时使用,保存完成后再更新 value。
禁用
轨道内容
checkedContent 和 uncheckedContent 在滑块旁边的轨道里显示文字或图标。轨道会按较长的那一个撑开。
滑块图标
icon 在两种状态下都显示在滑块里;checkedIcon、uncheckedIcon 分别覆盖某一状态的图标。
自定义值
checkedValue 和 uncheckedValue 替换 true 和 false,开关可以在任意两个字符串或数字之间切换。
橡皮筋效果
按住时滑块会朝另一端拉长。rubberBand={false} 关闭这个效果;滑块里有图标或加载圈时也不会拉长。
受控
传入 value 和 onUpdateValue 自己管理状态。
无障碍
开关是带 role="switch" 和 aria-checked 的原生 button,空格和回车都能切换。用 aria-label、aria-labelledby 或外层 label 给它命名。轨道里的内容只是装饰,对辅助技术隐藏。loading 时开关带 aria-busy。
Props
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
value | string | number | boolean | undefined | 受控时的当前值。 | 未发布 |
defaultValue | string | number | boolean | uncheckedValue | 非受控时的初始值。 | 未发布 |
onUpdateValue | (value) => void | undefined | 切换时以新值调用。 | 未发布 |
checkedValue | string | number | boolean | true | 表示打开的值。 | 未发布 |
uncheckedValue | string | number | boolean | false | 表示关闭的值。 | 未发布 |
size | small | medium | large | medium | 轨道和滑块的大小。 | 未发布 |
round | boolean | true | 胶囊形轨道和圆形滑块。 | 未发布 |
disabled | boolean | false | 禁用开关。 | 未发布 |
loading | boolean | false | 在滑块里显示加载圈,并忽略点击。 | 未发布 |
rubberBand | boolean | true | 按住时拉长滑块。 | 未发布 |
checkedContent | ReactNode | undefined | 打开时显示在轨道里。 | 未发布 |
uncheckedContent | ReactNode | undefined | 关闭时显示在轨道里。 | 未发布 |
icon | ReactNode | undefined | 两种状态下都显示在滑块里。 | 未发布 |
checkedIcon | ReactNode | undefined | 打开时显示在滑块里,覆盖 icon。 | 未发布 |
uncheckedIcon | ReactNode | undefined | 关闭时显示在滑块里,覆盖 icon。 | 未发布 |
Switch 也接受原生 button 属性和 ref。轨道和滑块里的内容用 checkedContent、uncheckedContent、icon、checkedIcon、uncheckedIcon 属性设置,样式通过 --r-switch-* token 调整轨道和滑块的样式。