Semi Design 中的 Switch 开关组件详解

Semi Design 中的 Switch 开关组件详解

【免费下载链接】semi-design 🚀A modern, comprehensive, flexible design system and React UI library. 🎨 Provide more than 2800+ Design Tokens, easy to build your design system. Make Semi Design to Any Design. 🧑🏻‍💻 Design to Code in one click 项目地址: https://gitcode.com/gh_mirrors/se/semi-design

什么是 Switch 开关组件

Switch 开关是 Semi Design 提供的一种用于切换两种互斥状态的交互组件。它类似于现实生活中的物理开关，用户可以通过点击来快速在"开"和"关"两种状态间切换。这种组件在设置界面中非常常见，特别适合用于启用/禁用某项功能或配置。

基本用法

使用 Switch 组件非常简单，首先需要引入组件：

import { Switch } from '@douyinfe/semi-ui';

然后就可以在代码中使用：

<Switch onChange={(v, e) => console.log(v)} />

受控与非受控模式

Switch 组件支持两种使用模式：

1. 非受控模式：使用 defaultChecked 设置初始状态

   <Switch defaultChecked={true} />
   

2. 受控模式：使用 checked 属性完全控制状态

   const [checked, setChecked] = useState(true);
   <Switch checked={checked} onChange={setChecked} />
   

组件特性详解

1. 尺寸选择

Switch 提供三种尺寸供选择：

• small：小型开关，适合紧凑布局
• default：默认尺寸（中等大小）
• large：大型开关，更显眼

<Switch size="small" />
<Switch size="default" />
<Switch size="large" />

2. 禁用状态

通过 disabled 属性可以禁用开关交互：

<Switch disabled />
<Switch disabled checked={true} />

3. 加载状态

从 1.29.0 版本开始，Switch 支持加载状态：

<Switch loading />
<Switch loading defaultChecked={true} />

4. 带文本的开关

可以通过 checkedText 和 uncheckedText 为开关添加状态文本：

<Switch checkedText="开" uncheckedText="关" />

注意：文本功能在 size="small" 时无效

5. 无障碍访问

为了提升可访问性，建议：

1. 使用 aria-label 描述开关用途

   <Switch aria-label="启用夜间模式" />
   

2. 或者使用 aria-labelledby 关联标签

   <span id="dark-mode-label">夜间模式</span>
   <Switch aria-labelledby="dark-mode-label" />
   

最佳实践

1. 标签位置：建议将说明文本放在 Switch 外部而非内部

   <div style={{ display: 'flex', alignItems: 'center' }}>
     <span>夜间模式</span>
     <Switch />
   </div>
   

2. 状态反馈：当开关状态改变时，提供清晰的视觉反馈

3. 键盘操作：确保可以通过 Tab 键聚焦，Space 键切换状态

设计规范

1. 文案规范：

   • 首字母大写
   • 简洁明了地描述开关功能
   • 避免使用标点符号

2. 交互状态：

   • 正常状态
   • 悬停状态
   • 聚焦状态
   • 禁用状态
   • 加载状态

常见问题

Q: 为什么小尺寸开关不支持文本？

A: 小尺寸开关空间有限，显示文本会影响可读性和美观性。建议在小尺寸下使用图标或外部标签。

Q: 如何实现异步操作后的状态回滚？

A: 可以在 onChange 中处理异步操作，操作失败时手动设置回原状态：

const [checked, setChecked] = useState(false);

const handleChange = async (newChecked) => {
  try {
    const result = await someAsyncOperation();
    setChecked(newChecked);
  } catch (error) {
    // 操作失败，保持原状态
  }
};

<Switch checked={checked} onChange={handleChange} />

Switch 组件是 Semi Design 中一个简单但功能完善的交互组件，合理使用可以大大提升用户界面的友好性和易用性。

【免费下载链接】semi-design 🚀A modern, comprehensive, flexible design system and React UI library. 🎨 Provide more than 2800+ Design Tokens, easy to build your design system. Make Semi Design to Any Design. 🧑🏻‍💻 Design to Code in one click 项目地址: https://gitcode.com/gh_mirrors/se/semi-design