Switch 开关
受控开关,用于切换开启与关闭状态。圆形滑块使用系统玻璃材质,轨道仍以灰色与主题主色表达开关状态。
代码演示
下方通过平台解析渲染 Switch.web.tsx;native 使用 Switch.tsx 的 Reanimated 动画,Web 使用受 reduced-motion 控制的 CSS transition。
状态
默认外观取自 src/components/ui/Switch/styles.ts 和 Switch.tsx。
| 状态 | 视觉 |
|---|---|
| 关 | 32×20 灰底 c.surfaceContainerHighest,16×16 系统材质滑块在左 |
| 开 | 32×20 主色底 c.primary,16×16 系统材质滑块在右 |
| 禁用 | 44×44 outer frame 保留,仅语义轨道 opacity: 0.5;材质滑块不淡化,handler 被移除 |
滑块复用 GlassLayer,原生默认不额外设置染色;Android、旧 iOS 或系统减少透明度时使用主题 surface 实色。Web 使用 CSS 近似材质,无 CSS 模糊能力且未启用减少透明度时使用主题渐变。轨道与滑块是同一 visual frame 下的兄弟节点,禁用反馈不会降低材质及其祖先的整体透明度。
默认开关在 44×44 的透明命中框中居中呈现 32×20 轨道。传入 stateLabels={{ off: '正常', on: '异常' }} 时,轨道按当前文案和字号扩展,文字始终在滑块另一侧,命中区宽高均至少为 44。空白的状态文案沿用默认轨道。保留简短的状态文字,控件用途交给 accessibilityLabel。
默认滑块从 x=2 移到 x=14。带标签时滑块移到轨道另一端,动画时长沿用 motion.base(200ms)。native 走 Reanimated;系统开启 reduced motion 时先取消旧动画,再同步写入 0/1 终值。Web 开启 reduced motion 时直接更新稳态值,并且完全不输出 transitionProperty、transitionDuration 或 transitionTimingFunction。
用法
import { Switch, Cell, List } from '@unif/react-native-design';
{
/* 独立使用 */
}
<Switch value={enabled} onChange={setEnabled} accessibilityLabel="启用通知" />;
{
/* 设置场景 — 配 Cell 使用,Switch 作为 extra */
}
<List>
<Cell
title="拜访提醒"
desc="按计划自动推送提醒"
extra={{
kind: 'control',
node: (
<Switch
value={notify}
onChange={setNotify}
accessibilityLabel="拜访提醒"
/>
),
}}
/>
<Cell
title="语音输入"
desc="长按说话输入消息"
extra={{
kind: 'control',
node: (
<Switch
value={voice}
onChange={setVoice}
accessibilityLabel="语音输入"
/>
),
}}
/>
</List>;
API
来源:src/components/ui/Switch/types.ts、Switch.tsx。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
value | boolean | — | 当前状态(受控,必填) |
onChange | (value: boolean) => void | — | 切换回调(必填) |
accessibilityLabel | string | — | 控件名称始终必填,状态文字通过 accessibilityValue 提供 |
stateLabels | { off: string; on: string } | — | 在滑块旁显示当前状态的短文案,轨道随文字宽度和字号调整。 |
disabled | boolean? | — | 禁用时移除 handler、上报 disabled 并半透明 |
testID | string? | — | outer frame 定位;自动派生 ${testID}-visual / -track / -thumb 后代 |
无障碍(a11y)
来源:src/components/ui/Switch/Switch.tsx、Switch.web.tsx、types.ts(native 与 web 两份实现 a11y 完全一致)。
- 默认
accessibilityRole:包裹的<Pressable>上硬编码'switch'。 - accessible name:
accessibilityLabel是类型必填且运行时会 trim;空白值移除 handler/action 语义并在 effect 诊断。即使视觉文字位于相邻 Cell / FormRow,也必须显式传入非空名称。 - 放在 Cell 行尾时必须使用
extra={{ kind: 'control', node: <Switch ... /> }};Cell 外层保持普通View,Switch 是唯一交互与 a11y owner。 - 状态语义:
accessibilityState={{ checked: value, disabled: !!disabled }}——checked直接映射必填的value,disabled映射disabledprop。 - 禁用语义:同时传
disabled={true}与onPress={undefined}。 - visual frame 是本地 RN
View,复用共享A11Y_HIDDEN_PROPS隐藏整个展示子树;该 wrapper 再包住 native 的第三方Animated.View,隐藏 props 不会透传给第三方。
// accessibilityLabel 始终必填;checked 由 value 自动上报
<Switch value={enabled} onChange={setEnabled} accessibilityLabel="拜访提醒" />
Native / Web 人工测量
在 runtime harness 的选择控件区用 Inspector 测量:
| 节点 | testID | 预期布局 |
|---|---|---|
| outer RNGH Pressable | selection-switch | 默认 44×44;内显文案时至少 44×44,透明、无 hitSlop |
| 本地 visual wrapper | selection-switch-visual | 默认尺寸为 r(32) × r(20),位于 outer 正中央;Web 与 402pt RN harness 实测应为 32×20,其他 native window 按实际 r() 结果验证 |
打开系统 reduced motion 后反复切换:native 必须取消进行中的动画并立即到终值。Web
展开 visual wrapper,分别检查 selection-switch-track 与
selection-switch-thumb:前者和后者的 inline style 都不得存在任何
transition* property。关闭偏好后,track 恢复 background-color transition,
thumb 恢复 transform transition,两端恢复 200ms 动画。
使用注意
- ❌ 不要换其它颜色——开必须是主橙(这是品牌一致性)
- ❌ 不要省略
accessibilityLabel——相邻 Cell / FormRow 的视觉 label 不会替代控件自身的 required name - ❌ 不要做"中间态"——Switch 只有开/关,三态用 Radio