跳到正文

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

名称类型默认值说明版本
valuestring | number | booleanundefined受控时的当前值。未发布
defaultValuestring | number | booleanuncheckedValue非受控时的初始值。未发布
onUpdateValue(value) => voidundefined切换时以新值调用。未发布
checkedValuestring | number | booleantrue表示打开的值。未发布
uncheckedValuestring | number | booleanfalse表示关闭的值。未发布
sizesmall | medium | largemedium轨道和滑块的大小。未发布
roundbooleantrue胶囊形轨道和圆形滑块。未发布
disabledbooleanfalse禁用开关。未发布
loadingbooleanfalse在滑块里显示加载圈,并忽略点击。未发布
rubberBandbooleantrue按住时拉长滑块。未发布
checkedContentReactNodeundefined打开时显示在轨道里。未发布
uncheckedContentReactNodeundefined关闭时显示在轨道里。未发布
iconReactNodeundefined两种状态下都显示在滑块里。未发布
checkedIconReactNodeundefined打开时显示在滑块里,覆盖 icon。未发布
uncheckedIconReactNodeundefined关闭时显示在滑块里,覆盖 icon。未发布

Switch 也接受原生 button 属性和 ref。轨道和滑块里的内容用 checkedContent、uncheckedContent、icon、checkedIcon、uncheckedIcon 属性设置,样式通过 --r-switch-* token 调整轨道和滑块的样式。