企业官网建设流程全解析

• 医疗健康
• 前端
• 音视频

OHIF Viewer 在 3.10 版本中完成了 UI 组件库的换代：全新的@ohif/ui-next取代了沿用多年的@ohif/ui。本文以 3.9 → 3.10 迁移指南中的 Switch 章节（platform/docs/versioned_docs/version-3.11/migration-guide/3p9-to-3p10/3-UI/4a-Migration-3p10-Switch.md）为骨架，结合仓库中 Switch 组件的真实实现与文档站示例，完整讲解如何把旧的SwitchButton迁移为新的Switch。读完本文，你将掌握导入路径替换、label/onChange两个破坏性变更的处理方式，以及新组件的受控/非受控用法、无障碍（a11y）规范与 Tailwind 布局技巧。

迁移背景：为什么需要从SwitchButton换成Switch

OHIF 3.10 之前，开关类控件由@ohif/ui包中的SwitchButton组件承担，它内置了label文案与onChange事件语义。在向@ohif/ui-next迁移的过程中，SwitchButton被一个标准化、基于 Radix UI 原语 的Switch组件取代，组件设计理念发生了三点根本变化：

• 职责分离：文案标签不再由组件内部渲染，而是交给外层Label组件或原生 HTML 元素负责；
• 事件命名统一：回调属性从onChange改为onCheckedChange，语义更精确；
• 样式完全交由 Tailwind：组件不再暴露内部结构或样式 prop，统一通过className与 Tailwind 工具类定制。

这是一次"单向破坏性变更"——所有引用SwitchButton的代码都必须跟随迁移，无法平滑兼容。迁移指南将其总结为三条关键变更：

迁移步骤详解

迁移指南给出了三步走的标准操作，下面结合仓库源码逐条展开。

第一步：更新导入语句

把组件导入从@ohif/ui切换到@ohif/ui-next，并重命名组件。如果需要使用配套的Label组件，一并导入：

- import { SwitchButton } from '@ohif/ui'; + import { Switch } from '@ohif/ui-next'; + import { Label } from '@ohif/ui-next'; // Optional: If using the Label component

@ohif/ui-next中Switch的导出位于 platform/ui-next/src/components/Switch/index.tsx，与其余组件一样从@ohif/ui-next包顶层统一导出。

第二步：替换组件用法，标签改为外部实现

旧组件的labelprop 已被移除，需要把文案放到Switch之外，并用布局工具类（如flex）摆好标签与开关的相对位置。迁移指南给出了完整的对照 diff：

- <SwitchButton - label="Enable Feature" - checked={isFeatureEnabled} - onChange={handleToggle} - /> + + <div className="flex items-center space-x-2"> + <Switch + id="feature-toggle" // It's good practice to add an id + checked={isFeatureEnabled} + onCheckedChange={handleToggle} + /> + <Label htmlFor="feature-toggle">Enable Feature</Label> {/* Or use a <span> */} + </div>

这里的两个细节值得注意：

• 无障碍关联：Label的htmlFor属性通过Switch上的id把它们绑定在一起。点击标签文字即可切换开关，屏幕阅读器也能正确朗读出"开关所代表的含义"；
• 布局编排：<div>上的flex items-center space-x-2负责垂直居中对齐并在开关与标签之间留出 2 个单位（0.5rem）的间距。

仓库的组件文档站（platform/docs/src/pages/components/switch-toggle.tsx）给出了同样的推荐模式：

import { Switch } from '@ohif/ui-next'; import { Label } from '@ohif/ui-next'; <div className="flex items-center space-x-2"> <Switch id="sync" defaultChecked /> <Label htmlFor="sync">Sync viewports</Label> </div>

对于"设置项列表"这种常见场景，还可以用flex items-center justify-between把标签放在左侧、开关放在右侧，例如"Show overlay / Show annotations / Invert colors"三行设置的排列方式。

第三步：更新事件处理 prop

把onChange重命名为onCheckedChange，并确保处理函数正确接收新的布尔状态作为参数：

- onChange={checked => setIsEnabled(checked)} + onCheckedChange={checked => setIsEnabled(checked)}

回调的函数签名（接收boolean类型的checked状态）与旧版常见写法一致，可直接沿用。迁移指南特别提示了一类需要留意的边界情况：如果你的旧onChange并不接收 checked 状态（例如只是简单地翻转现有状态），那么需要稍微调整处理逻辑，因为onCheckedChange直接提供的是"最新状态"而非"翻转动作"。

新Switch组件 API 一览

仓库组件文档站（platform/docs/src/pages/components/switch-toggle.tsx）为Switch维护了一份精确的 Props 表，可直接作为迁移时的对照参考：

注意两点：

1. 受控与非受控双模式：需要完全掌控状态时使用checked+onCheckedChange（受控）；仅需要默认状态时使用defaultChecked（非受控）。文档站示例中"Sync changes in all viewports"即使用了defaultChecked的非受控写法；
2. 所有原生属性透传：由于组件基于@radix-ui/react-switch的Root原语实现并展开...props，id、aria-label等标准 HTML/ARIA 属性都可以直接传递。

组件的源码级实现

Switch的实现非常精简，完整代码位于 platform/ui-next/src/components/Switch/Switch.tsx：

const Switch = React.forwardRef< React.ElementRef<typeof SwitchPrimitives.Root>, React.ComponentPropsWithoutRef<typeof SwitchPrimitives.Root> >(({ className, ...props }, ref) => ( <SwitchPrimitives.Root className={cn( 'focus-visible:ring-ring focus-visible:ring-offset-background>赞分享