semi-design/content/input/switch/index.md

---

localeCode: zh-CN order: 30 category: 输入类 title: Switch 开关 icon: doc-switch width: 60%

brief: 开关是用于切换两种互斥状态的交互形式

代码演示

如何引入

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 键切换开启或关闭状态

文案规范

• 开关描述

  • 首字母大写，不需要标点符号
  • 间接明了地说明该设置的开启或关闭状态

  • 如果需要，解释给用户开启和关闭状态所代表的情况

    设计变量