代码演示
如何引入
import { Switch } from '@douyinfe/semi-ui';
基本
你可以通过 onChange
监听状态变化,通过 defaultChecked
或受控的 checked
制定选中状态。
通过 aria-label
描述该 Switch 开关的具体作用
import React from 'react';
import { Switch } from '@douyinfe/semi-ui';
() => (
<div>
<Switch onChange={(v, e) => console.log(v)} aria-label="a switch for demo"></Switch>
<br />
<Switch defaultChecked={true} onChange={(v, e) => console.log(v)} aria-label="a switch for semi demo"></Switch>
</div>
);
尺寸
你可以通过 size 指定尺寸
import React from 'react';
import { Switch } from '@douyinfe/semi-ui';
() => (
<div>
<Space style={{ marginBottom: 10, display: 'block' }}>
<Switch size="small" aria-label="a switch for demo"></Switch>
<Switch defaultChecked={true} size="small" aria-label="a switch for demo"></Switch>
<Switch size="small" loading aria-label="a switch for demo" />
<Switch size="small" loading defaultChecked={true} aria-label="a switch for demo" />
</Space>
<Space style={{ marginBottom: 10, display: 'block' }}>
<Switch></Switch>
<Switch defaultChecked={true} aria-label="a switch for demo"></Switch>
<Switch loading aria-label="a switch for demo" />
<Switch loading defaultChecked={true} aria-label="a switch for demo" />
</Space>
<Space>
<Switch size="large"></Switch>
<Switch defaultChecked={true} size="large"></Switch>
<Switch size="large" loading />
<Switch size="large" loading defaultChecked={true} />
</Space>
</div>
);
不可用
import React from 'react';
import { Switch } from '@douyinfe/semi-ui';
() => (
<div>
<Switch disabled aria-label="a switch for demo"></Switch>
<br />
<Switch disabled checked={true} aria-label="a switch for demo"></Switch>
</div>
);
带文本
可以通过 checkedText
与 uncheckedText
设置开关时的文本
注意:此项功能在最小的开关(即 size='small'时)无效
import React from 'react';
import { Switch } from '@douyinfe/semi-ui';
() => (
<div>
<Switch checkedText="开" uncheckedText="关" />
<Switch checkedText="|" uncheckedText="〇" style={{ marginLeft: 5 }} />
<br />
<br />
<Switch defaultChecked checkedText="开" uncheckedText="关" />
<Switch defaultChecked checkedText="|" uncheckedText="〇" style={{ marginLeft: 5 }} />
<br />
<br />
<Switch checkedText="开" uncheckedText="关" size="large" />
<Switch checkedText="|" uncheckedText="〇" size="large" style={{ marginLeft: 5 }} />
<br />
<br />
<Switch defaultChecked checkedText="开" uncheckedText="关" size="large" />
<Switch defaultChecked checkedText="|" uncheckedText="〇" size="large" style={{ marginLeft: 5 }} />
</div>
);
相比于通过 chekedText 与 uncheckedText 设置内嵌的文本,我们更推荐将文本说明放置在 Switch 外部
import React, { useState } from 'react';
import { Switch, Typography } from '@douyinfe/semi-ui';
() => {
const [open, setOpen] = useState();
const { Title } = Typography;
return (
<div style={{ display: 'flex', alignItems: 'center' }}>
<Title heading={6} style={{ margin: 8 }}>
{open ? '已开启' : '已关闭'}
</Title>
<Switch checked={open} onChange={setOpen} aria-label="a switch for demo" />
</div>
);
};
受控组件
组件是否选中完全取决于传入的 checked 值,配合 onChange 回调函数使用
import React from 'react';
import { Switch } from '@douyinfe/semi-ui';
() => {
const [checked, setChecked] = useState(true);
const onChange = checked => {
setChecked(checked);
};
return <Switch checked={checked} aria-label="a switch for demo" onChange={onChange} />;
};
加载中
version: >= 1.29.0
可以通过设置 loading="true" 开启加载中状态。
import React from 'react';
import { Switch } from '@douyinfe/semi-ui';
() => (
<div>
<Switch loading />
<br />
<Switch loading defaultChecked={true} />
</div>
);
API 参考
属性 | 说明 | 类型 | 默认值 | 版本 |
---|
aria-label | aria-label属性,用来给当前元素加上的标签描述, 提升可访问性 | string | | 2.2.0 |
aria-labelledby | aria-labelledby属性,表明某些元素的 id 是某一对象的标签。它被用来确定控件或控件组与它们标签之间的联系, 提升可访问性 | string | | 2.2.0 |
className | 类名 | string | | |
checked | 指示当前是否选中,配合 onChange 使用 | boolean | false | |
checkedText | 打开时展示的内容, size 为 small 时无效 | ReactNode | | |
defaultChecked | 初始是否选中 | boolean | false | |
disabled | 是否禁用 | boolean | false | |
loading | 设置加载状态 | boolean | false | 1.29.0 |
onChange | 变化时回调函数 | function(checked:boolean) | | |
onMouseEnter | 鼠标移入时回调 | function() | | |
onMouseLeave | 鼠标移出时回调 | function() | | |
size | 尺寸,可选值large ,default ,small | string | 'default' | |
style | 内联样式 | object | | |
uncheckedText | 关闭时展示的内容, size 为 small 时无效 | ReactNode | | |
Accessibility
ARIA
- Switch 具有
switch
role,当 checked 为 true 时,aria-checked
将被自动设置为 true,反之亦然 - 作为表单控件应该带有 Label,当你使用 Form.Switch 时会自动被带上
- 如果你单独使用 Switch,建议使用
aria-label
描述当前标签作用
键盘和焦点
- 键盘用户可以使用
Tab
及 Shift + Tab
切换焦点 - 聚焦时可以通过
Space
键切换开启或关闭状态
文案规范
- 开关描述
- 首字母大写,不需要标点符号
- 间接明了地说明该设置的开启或关闭状态
- 如果需要,解释给用户开启和关闭状态所代表的情况