从 CHANGELOG 到源码：@ohif/ui-next 组件库演进全解析与定制实践
从 CHANGELOG 到源码ohif/ui-next 组件库演进全解析与定制实践【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers导读ohif/ui-next是 OHIF Viewer 新一代 UI 组件库以 shadcn/ui 与 Radix UI 为基础构建承载了 WorkList 检查列表、SmartScrollbar 切片滚动条、可调整侧边栏等新一代界面能力。本文以 platform/ui-next/CHANGELOG.md 记录的约一年版本演进为主线结合 platform/ui-next/src/components 下的 70 余个组件实现梳理 ui-next 的架构定位、关键功能落地方式与定制化接口帮助读者理解 OHIF 界面层从旧 ui 到 ui-next的迁移脉络并掌握其可复用的组件定制方法。ui-next 的定位OHIF 的下一代 UI 组件库在 OHIF 仓库中platform/ui是上一代组件库而platform/ui-next则是其继任者。从 platform/ui-next/package.json 的包描述可以看到它的自我定位Next version of OHIF Viewers UI, more customizable using shadcn/ui这意味着 ui-next 不是简单重写而是把可定制性作为首要设计目标——底层直接采用 shadcn/ui 的风格化组件体系。包当前版本为3.14.0-beta.29与整个 OHIF monorepo 的版本节奏保持一致所有子包通过 lerna 同步发布CHANGELOG 中大量条目仅标注 Version bump only for package ohif/ui-next 即为此机制的体现。技术栈一览从 package.json 的依赖可以清晰还原其技术底座类别依赖作用交互基座radix-ui/react-*约 21 个子包无障碍原语组件Dialog、DropdownMenu、Tooltip、Select、Slider、Tabs 等样式方案tailwindcsstailwindcss-animateclass-variance-authoritytailwind-merge原子化样式与组件变体variants管理表格tanstack/react-tableWorkList/StudyList 数据表格的无头表格引擎图标lucide-react与radix-ui/react-icons统一图标集动画framer-motion组件进出场动画通知sonner轻量 toast 通知体系引导shepherd.js应用内 Tours 引导流程布局react-resizable-panels可拖拽调整的面板布局日期date-fnsreact-day-picker检查列表日期过滤框架react18.3.1React 18 并发特性其中值得注意的两点一是React 18 迁移与shadcn/ui 基座是同一次提交引入的CHANGELOG 3.9.0-beta.22 记录 move to React 18 and base for using shadcn/ui二是构建工具采用rspack并在 3.10.0-beta.55 进一步迁移到rsbuild以加速开发move to rsbuild for dev - faster。对外导出面src/index.ts 展示了包的整体导出结构components全部组件、contextProviders上下文提供器、types类型命名空间、utils含cn、formatDICOMDate、formatDICOMTime、parseStudyDateTimestamp等工具以及hooksuseSessionStorage、useDynamicMaxHeight。任何使用方只需import { ToolButton } from ohif/ui-next即可接入。版本演进脉络从 3.9 到 3.14 的四阶段CHANGELOG 的 5045 行记录完整覆盖了ohif/ui-next从 2024 年 5 月至 2026 年 6 月的演进可以划分为四个阶段第一阶段3.9.x2024-05 ~ 2024-08奠基与设计3.9.0-beta.22引入 React 18 与 shadcn/ui 基座这是 ui-next 的起点3.9.0-beta.73完成 ui-next 的设计规范并落地核心组件Created design and added core components for ui-next3.9.0-beta.83新增基于 ui-next 的实验性 Study 面板New OHIF study panel - under experimental flag这是后续 WorkList 的前身3.9.0-beta.101新检查面板默认对非缩略图序列使用列表视图、默认筛选改为 All并给缩略图增加 更多 菜单与 DICOM Tag 浏览器入口。这一阶段还有大量 Tailwind 构建错误修复beta.75、beta.70 的border-border类清理说明组件库样式体系正在从旧 ui 向新规范过渡。第二阶段3.10.x2024-11 ~ 2025-04能力爆发期3.10 是功能密度最高的版本段CHANGELOG 记录了多项架构级变更图标体系迁移migrate icons to ui-nextbeta.24以及配套的addIcon双库同步机制3.9.0-beta.111定制服务升级new customization service apibeta.71随后Migrate hotkeys to customization servicebeta.106快捷键从此可通过定制文件覆盖布局能力左右侧边栏可选可调整大小beta.68、侧边栏拖拽手柄的交互反馈beta.78、多显示器支持beta.58、响应式缩略图beta.70工具箱重构Toolbar/Toolbox 支持 sections 分组beta.117、action corner API 简化3.11.0-beta.33 实际落于 3.11 前段渲染相关DICOM 缩略图多策略渲染beta.28、字体本地打包不再依赖 Google CDNbeta.121、Cornerstone3D 3.0 适配beta.114。第三阶段3.11.x ~ 3.12.x2025-04 ~ 2026-02细分领域深耕这一阶段围绕分割、测量、数据叠加做大量 UI 增强分割分段统计、labelmap 插值、分段双向测量3.10.0-beta.126AI 与一键分割工具3.10.0-beta.144分割工具预览与选择3.10.0-beta.131分段标签改进beta.113分割表下拉菜单增强beta.10数据叠加DataOverlay 前景/背景控制、方向切换与 RTDOSE 支持beta.243D 相关scoord3d 支持beta.115通知与引导add custom notification component support3.12.0-beta.100、Tours 版本冻结与许可文档beta.94界面细节工具设置 tooltipbeta.93、窗口级操作菜单修复beta.123、Orientation 菜单增加 Reformat 选项beta.85。第四阶段3.13.x2026-02 ~ 2026-06收敛与整合3.13.0-beta.52新增SmartScrollbar组件OHIF-25583.13.0-beta.61将ViewportSliceProgressScrollbar与 customizations 集成并补文档3.13.0-beta.67为ToolButton增加 toggle 状态并附带 Crosshair 示例3.13.0-beta.85WorkList 正式落地——New Study List (WorkList based on ui-next); old study list renamed to LegacyWorklist。这是 ui-next 全面接管检查列表的标志性事件旧的检查列表被重命名为 LegacyWorklist新列表完全基于 ui-next。核心组件体系与源码佐证基础原语Radix shadcn 风格化src/components 下的基础组件Button、Input、Select、Dialog、DropdownMenu、Tooltip、Slider、Switch、Tabs、Accordion 等均是对 Radix 原语的 shadcn 风格封装通过class-variance-authority提供变体系统并通过cntailwind-merge封装合并自定义类名——这是可定制的第一层任意组件都能用 Tailwind 类覆盖默认样式。领域组件医学影像特有的 UI 抽象ui-next 不只是一套通用组件还沉淀了医学影像工作流特有的组件StudyList / WorkList基于tanstack/react-table的检查列表。源码位于 src/components/StudyList其中 columns/defaultColumns.tsx 定义了COLUMN_IDS、FILTERABLE_COLUMN_IDS、TEXT_FILTER_COLUMN_IDS及默认列构造器textColumn说明列与筛选是可配置的数据驱动结构components/Layout.tsx 则通过Layout复合组件组织列表、预览与筛选区域SegmentationTable分割面板管理分段列表、可见性、锁定、颜色与操作菜单SmartScrollbar智能滚动条复合组件模式见 SmartScrollbar/SmartScrollbar.tsx其内部定义SmartScrollbarIndicatorConfig类型、SmartScrollbarLayoutContext/SmartScrollbarScrollContext上下文并要求SmartScrollbarIndicator作为子组件通过DEFAULT_INDICATOR_CONFIG提供默认配置——这种配置对象 上下文 复合组件的设计让滚动条指示器可以被按需定制Viewport 系列Viewport、ViewportDialog、ContextMenuViewport、OHIFToolSettings、OHIFToolbox、CinePlayer、ProgressLoadingBar 等覆盖影像显示与工具栏交互测量与报告MeasurementTable、DataTable、DataRow、LineChart支持分组 findings 表格值 自定义分组函数3.10.0-beta.132。布局与主题SidePanel、Resizable基于react-resizable-panels、OHIFPanels、ThemeWrapper、NavBar、Header构成应用骨架ThemeWrapper与next-themes配合支持主题切换。关键能力深挖CHANGELOG 重要条目的源码视角WorkListui-next 全面接管检查列表CHANGELOG 3.13.0-beta.85 是 ui-next 历史上最重要的里程碑之一。它意味着以 ui-next 组件StudyList、StudyBrowser、StudyItem、StudyBrowserSort、StudyBrowserViewOptions构建的新检查列表成为默认旧实现被保留为LegacyWorklist以兼容存量配置从 3.9.0-beta.83 的实验性 Study 面板到 3.13 正式落地经历了约一年半的迭代。对于开发者的实操意义若你使用旧版 OHIF 配置并希望在升级后保留旧列表外观需要关注LegacyWorklist相关配置若使用新 WorkList则可利用 StudyList/columns/defaultColumns.tsx 中暴露的COLUMN_IDS与筛选常量定制列。SmartScrollbar 与切片进度滚动条3.13.0-beta.52 新增 SmartScrollbar3.13.0-beta.61 将其以ViewportSliceProgressScrollbar的形式与 customization 机制打通。从源码看SmartScrollbar 通过mapRawIndicatorDataToConfig之类的映射函数见 SmartScrollbar.tsx 的SmartScrollbarIndicatorConfig把原始数据记录转换为指示器配置再通过布局/滚动两个 Context 在复合组件间共享状态。这套抽象让滚动切片时显示进度指示器成为可插拔功能也解释了为何它能与 customizations 无缝集成。可调整侧边栏与多显示器3.10.0-beta.68 使左右侧边栏可选可调整基于react-resizable-panels3.10.0-beta.58 加入在新窗口打开另一项研究的多显示器能力。两者共同支撑了诊断工作流中的第二屏对比阅读场景。通知与热键一切皆可定制3.12.0-beta.100 支持自定义 notification 组件底层由sonner提供 toast 机制Sonner/目录即其封装3.10.0-beta.106 把 hotkeys 迁移到 customization service。结合 3.10.0-beta.71 的新 customization service APIui-next 组件如 ToolButton、ActionMenu的快捷键、显示文本、甚至组件本身都可通过定制覆盖不再需要 fork 源码。ToolButton 的 toggle 状态3.13.0-beta.67 为 ToolButton 增加 toggle 状态。对于需要按下/弹起语义的工具如 Crosshair、翻转、反色工具栏按钮现在可以在激活时保持高亮这是交互可感知性的重要改进OHIFToolbox 正是由一系列带状态的 ToolButton 组成。分割面板的持续打磨CHANGELOG 中分割相关修复数量最多映射到 src/components/SegmentationTable 的持续演进分段列表手动滚动与自动滚动到活动分段3.12.0-beta.71、未加载分割在切换 hanging protocol 时仍可显示3.11.0-beta.67、panelSegmentation.disableEditing时锁定所有再水合分段3.12.0-beta.68、opacity/border 输入校验3.13.0-beta.24、3D 视图列出表面表示3.12.0-beta.122。这些修复共同指向一个目标分割作为临床标注核心其面板必须在大体量分段、跨视图、再水合等边界场景下保持稳定。从 Bug Fix 看工程实践与安全治理CHANGELOG 的 Bug Fixes 部分同样是理解 ui-next 的重要素材可归纳出几条工程主线错误边界工程化ErrorBoundary 支持生产环境展示详情3.12.0-beta.67、修复 console 错误并改进日志3.12.0-beta.24、堆栈溢出可滚动3.10.0-beta.6安全治理依赖改为精确版本号3.12.0-beta.59、移除tar-fs依赖并剔除 storybook/sharp3.12.0-beta.33、Babel 漏洞补丁3.11.0-beta.78主题令牌化硬编码黑色替换为背景色 token3.13.0-beta.13、旧色值批量替换为 ui-next 色值3.13.0-beta.11配合 Tailwind 主题配置文件实现整体换肤交互细节tooltip 改为 portal 渲染避免裁剪3.11.0-beta.108、复制失败时的剪贴板图标反馈3.12.0-beta.98、context menu 重定位逻辑下沉到 Dialog 组件3.11.0-beta.38、窗口级菜单二次点击问题3.12.0-beta.123本地化工具栏工具名的 i18n 翻译补全3.12.0-beta.30、俄语语言包3.11.0-beta.26。延伸与仓库其他模块的协同关系ui-next 并非孤立组件库它与平台层协同工作platform/app 中的应用通过 customization 机制把 ui-next 组件与 platform/core 的 Service如 MeasurementService、ToolbarService绑定extensions/cornerstone 的 Viewport 与 ui-next 的 Viewport 组件配合实现影像渲染与 UI 解耦检查列表数据来自 platform/core 的 DataSource 层ui-next 只负责展示。若要深入实践建议按此顺序阅读仓库先通读 platform/ui-next/CHANGELOG.md 建立版本全貌再逐个研读 platform/ui-next/src/components 下的组件源码最后通过 platform/app/public/config 下的模式配置观察组件如何在真实应用中被组装与定制。【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考