OHIF 3.10 到 3.11 迁移指南其他变更详解测量服务、Viewport 与图像排序【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers本篇指南面向正在从 OHIF 3.10 升级到 3.11 的开发者聚焦迁移指南中“Other Changes”一节涉及的四类破坏性变更connectToolsToMeasurementService调用签名的调整、data-viewportId属性的 React 合规化重命名、ViewportGridService中setIsReferenceViewable的移除、以及JUMP_TO_MEASUREMENT_VIEWPORT/JUMP_TO_MEASUREMENT_LAYOUT事件合并为单一JUMP_TO_MEASUREMENT事件。此外本文还会深入讲解 3.11 中默认启用、按ImagePositionPatient排序的 ImageSet 新排序规则及其回退方案。读完本文你将掌握 3.11 中这些 API 与行为的精确变化并能在自己的扩展代码中完成对应改造。概览3.11 中的关键变更清单按照 迁移指南 的归纳3.11 版本中与既有扩展代码相关的“其他变更”共有以下四项变更项变更前3.10变更后3.11connectToolsToMeasurementService参数直接传入servicesManager单个参数改为传入包含servicesManager、commandsManager、extensionManager的对象参数data-viewportId属性名data-viewportId驼峰data-viewportid全小写以消除 React 告警视图跳转的可视性判定ViewportGridService.setIsReferenceViewable由 cornerstone 视口自身提供isReferenceViewable跳转到测量事件JUMP_TO_MEASUREMENT_VIEWPORT与JUMP_TO_MEASUREMENT_LAYOUT两个事件合并为单一JUMP_TO_MEASUREMENT事件且不再有 consume 事件除上述 API 变更外3.11 还调整了 ImageSet 的默认排序策略图像默认按ImagePositionPatient患者位置排序当该属性不可用时回退到InstanceNumber排序。下文将逐项说明这些变更的具体内容、背后的源码实现以及迁移操作方法。一、connectToolsToMeasurementService调用签名变更1.1 变更内容与迁移步骤ohif/cornerstone-extensions即本仓库中的extensions/cornerstone导出的connectToolsToMeasurementService函数在 3.11 中不再接收单一参数而是接收一个包含所有服务对象的参数对象。官方迁移步骤要求对所有调用点做如下改写// Before - connectToolsToMeasurementService(servicesManager); // After connectToolsToMeasurementService({ servicesManager, commandsManager, extensionManager });1.2 源码级的实现佐证在 initMeasurementService.ts 中可以看到新签名的实际定义函数从对象参数中解构出commandsManager、servicesManager与extensionManager并通过servicesManager.services获取measurementService、displaySetService、cornerstoneViewportService与customizationService随后调用initMeasurementService建立 cornerstone3D 工具与 OHIF 测量服务之间的映射关系并调用connectMeasurementServiceToTools完成事件的双向桥接。这意味着在 3.11 中connectToolsToMeasurementService已经不再只是一个“传入单一服务、单向绑定”的工具函数而是完整的测量服务初始化入口。因此如果你在自己的扩展中直接调用过该函数必须同步传入三个服务对象如果直接调用initMeasurementService则其参数列表measurementService, displaySetService, cornerstoneViewportService, customizationService保持不变。1.3 实际调用位置示例在 cornerstone 扩展自身的初始化流程中该函数的新签名调用方式位于 init.tsxthis.measurementServiceSource connectToolsToMeasurementService({ servicesManager, commandsManager, extensionManager, });这段代码可作为迁移后的标准调用范式参考三个服务对象均来自扩展初始化上下文直接按名称传入即可。二、data-viewportId重命名为data-viewportid2.1 变更原因与影响范围data-viewportId这个命名不符合 React 对 DOM 自定义属性的小写约定会在运行时产生 React 告警warning。3.11 中该属性被统一重命名为全小写的data-viewportid凡是引用了旧属性名的地方都需要同步修改。这一属性主要用于视口 DOM 元素上标记其所属 viewportId是页面对象模型如 Playwright 测试与 hover 事件处理定位视口的关键标识。受影响的文件包括 OHIFCornerstoneViewport.tsx、useViewportHover.ts 以及 DicomMicroscopyViewport.tsx 等。2.2 迁移操作建议全局搜索以下两种写法并统一替换- div>JUMP_TO_MEASUREMENT: event:jump_to_measurement,当用户执行“跳转到测量”操作时MeasurementService会通过内部方法见该文件中约 L737-L754 的jumpToMeasurement逻辑调用this._broadcastEvent(EVENTS.JUMP_TO_MEASUREMENT, event)向所有订阅者广播该事件。在 cornerstone 扩展侧init.tsx 中正是订阅了该事件并把测量信息转交到命令层处理measurementService.subscribe(measurementService.EVENTS.JUMP_TO_MEASUREMENT, evt { const { measurement } evt; const { uid: annotationUID } measurement; commandsManager.runCommand(jumpToMeasurementViewport, { measurement, annotationUID, evt }); });4.3 迁移操作建议如果你曾在扩展中同时订阅JUMP_TO_MEASUREMENT_VIEWPORT与JUMP_TO_MEASUREMENT_LAYOUT请将两处订阅合并为对JUMP_TO_MEASUREMENT的单一订阅在事件处理回调中依据evt.measurement的引用信息如displaySetInstanceUID、referencedImageId、视口类型等自行决定跳转目标视口必要时可结合上文提到的isReferenceViewable工具判断目标视口是否可展示该测量不再依赖任何 consume 事件来拦截或取消跳转。五、ImageSet 默认排序按患者位置ImagePositionPatient5.1 变更内容3.11 修改了 ImageSet 的排序行为默认情况下图像集按ImagePositionPatient图像位置排序当ImagePositionPatient不可用时排序回退到InstanceNumber实例号。这一变化直接影响多帧序列、重建序列等在视口中加载时的帧顺序属于运行时行为变更不涉及代码 API 破坏。5.2 源码实现该排序逻辑位于 ImageSet.ts 的sort(customizationService)方法中其优先级如下优先读取customizationService.getCustomization(instanceSortingCriteria)获取自定义排序配置若配置中指定了可用的排序函数defaultSortFunctionName对应的sortFunctions中存在该函数则直接使用该自定义排序函数否则当图像集不可重建!this.isReconstructable或图像缺少可用于位置排序的ImagePositionPatient/ImageOrientationPatient!isValidForPositionSort(this.images)时回退为instancesSortCriteria.sortByInstanceNumber其余情况默认执行sortImagesByPatientPosition(this.images)即按患者位置排序。可以看到“优先用自定义排序 → 无位置信息则按实例号 → 否则按患者位置”正是迁移指南所述行为的完整实现。5.3 如何回退到旧的排序方式如果你希望恢复 3.10 及之前“按 InstanceNumber 排序”的旧行为可以像迁移指南给出的示例那样通过customizationService.setCustomizations注册名为instanceSortingCriteria的自定义项并将其defaultSortFunctionName指向defaultcustomizationService.setCustomizations({ instanceSortingCriteria: { $set: { defaultSortFunctionName: default }, }, });该配置对应的默认结构定义在 instanceSortingCriteriaCustomization.tsexport default { instanceSortingCriteria: { sortFunctions: {}, defaultSortFunctionName: , }, };从ImageSet.sort的代码可以看出combinedSortFunctions是把内置的instancesSortCriteria与自定义项中的sortFunctions合并得到的因此当defaultSortFunctionName设为default时会命中合并后的默认排序函数即按 InstanceNumber 排序。设置后请确保该自定义项在 ImageSet 构建/排序之前生效通常可以在应用初始化阶段或扩展的getCustomizationModule中注册。六、迁移后的验证建议完成上述 API 改造后建议进行以下验证确保升级到 3.11 后功能正常测量创建与编辑闭环在视口中创建、拖动、删除测量确认ANNOTATION_ADDED / COMPLETED / MODIFIED / REMOVED / SELECTION_CHANGE等事件仍能正确同步到MeasurementService对应 initMeasurementService.ts 中的事件订阅。跳转测量行为在不同视口类型stack 与 volume、MPR之间点击测量跳转确认单一JUMP_TO_MEASUREMENT事件能被正确路由到对应视口。排序行为加载一组同时具备ImagePositionPatient与InstanceNumber的序列确认默认按患者位置排序随后移除位置信息或配置instanceSortingCriteria确认回退逻辑生效。控制台检查确认不再出现与data-viewportId相关的 React 属性告警。以上所有变更均可在本仓库的源码中找到对应实现迁移过程中如遇问题可对照文中给出的文件路径进一步查看上下文细节。【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考