跳到主要内容

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。

参数类型默认值说明
valueboolean—当前状态(受控,必填)
onChange(value: boolean) => void—切换回调(必填)
accessibilityLabelstring—控件名称始终必填,状态文字通过 accessibilityValue 提供
stateLabels{ off: string; on: string }—在滑块旁显示当前状态的短文案,轨道随文字宽度和字号调整。
disabledboolean?—禁用时移除 handler、上报 disabled 并半透明
testIDstring?—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 映射 disabled prop。
  • 禁用语义:同时传 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 Pressableselection-switch默认 44×44;内显文案时至少 44×44,透明、无 hitSlop
本地 visual wrapperselection-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