OHIF Viewport Grid Service 详解:透视查看器网格布局、状态管理与事件机制

原创2026-09-18 12:28:401,762 阅读
文章标签:医疗健康前端图像处理PWA

OHIF Viewport Grid Service 详解:透视查看器网格布局、状态管理与事件机制

导读

Viewport Grid Service 是 OHIF(zero-footprint DICOM viewer)在 @ohif/core 中提供的一个 UI 服务,它统一管理查看器(Viewer)中视口网格(viewport grid)的布局与配置:从活跃视口的选中、DisplaySet 与视口的绑定,到行列布局的切换,所有变更都会通过事件广播通知整个应用。本文以 viewport-grid-service.md 文档为核心骨架,并结合仓库中 @ohif/core 的服务实现与 @ohif/ui-next 的 Provider 源码,完整讲解该服务的四类事件、九个核心 API、状态结构以及它在 OHIF 应用中的实际注入与消费链路。读完本文,你将能够理解并在自己的 OHIF 扩展(Extension)或模式(Mode)中正确使用 ViewportGridService 完成布局管理、活跃视口切换与显示集绑定。

Overview:一个专门管理网格布局的 UI 服务

在 OHIF 的平台架构中,服务(Service)通过 servicesManager 统一注册,供扩展和模式调用。Viewport Grid Service 正是其中一个新增的 UI 服务,其职责可以概括为:

  • 维护整个视口网格的布局结构(行数、列数、布局类型);
  • 维护每个网格单元(viewport)与 DisplaySet(显示集) 的绑定关系;
  • 追踪并切换活跃视口(active viewport);
  • 在布局或状态发生变化时,发布事件供 UI 组件(如工具栏、挂片协议、上下文菜单)订阅响应。

服务本身不直接渲染任何界面,它是一层"状态 + 事件总线"的抽象:状态由 ViewportGridProvider 持有,事件由继承自 PubSubService 的广播机制向外发布。从源码看,服务在 @ohif/core 中的注册名为 viewportGridService(别名 ViewportGridService),见 ViewportGridService.ts:

public static REGISTRATION = {
  name: 'viewportGridService',
  altName: 'ViewportGridService',
  create: ({ configuration = {}, servicesManager }) => {
    return new ViewportGridService({ servicesManager });
  },
};

需要说明的是:原文档描述为"seven events",但文档表格只展开了四个事件,且以当前仓库源码为准,服务中实际定义了 6 个事件常量,本文第 2 节会逐一列出并说明其真实触发时机。

事件机制:网格状态变化的广播中枢

ViewportGridService 继承自 PubSubService,事件常量定义在 ViewportGridService.ts 的 EVENTS 静态属性中:

事件常量 事件字符串 触发时机(依据源码)
ACTIVE_VIEWPORT_ID_CHANGED event::activeviewportidchanged 活跃视口 Id 发生变化时触发
LAYOUT_CHANGED event::layoutChanged 网格布局(行列)变化时触发
GRID_STATE_CHANGED event::gridStateChanged 整个网格状态被改变时触发
GRID_SIZE_CHANGED event::gridSizeChanged 网格尺寸变化时触发(通过 setViewportGridSizeChanged())
VIEWPORTS_READY event::viewportsReady 网格中的视口准备就绪时触发(通过 publishViewportsReady())
VIEWPORT_ONDROP_HANDLED event::viewportOnDropHandled 拖放(drag & drop)处理完成时触发(通过 publishViewportOnDropHandled())

事件发布的关键细节

  • 异步广播:setActiveViewportId、setLayout、set 等方法在修改状态后,都会通过 setTimeout(..., 0) 延迟发布事件。源码注释明确说明这是为了让状态先完成更新,再广播事件("Use queueMicrotask to delay the event broadcast"),例如 ViewportGridService.ts:
public setActiveViewportId(id: string) {
  if (id === this.getActiveViewportId()) {
    return;
  }
  this.serviceImplementation._setActiveViewport(id);

  setTimeout(() => {
    this._broadcastEvent(this.EVENTS.ACTIVE_VIEWPORT_ID_CHANGED, {
      viewportId: id,
    });
  }, 0);
}

注意这里还有一个去重逻辑:如果传入的 id 与当前活跃视口相同,则直接返回、不触发事件。

  • setLayout 双事件广播:布局变化时会依次广播 LAYOUT_CHANGED(携带 numCols、numRows)和 GRID_STATE_CHANGED(携带完整的新状态 state 以及被移除的视口 Id 列表 removedViewportIds),见 ViewportGridService.ts。移除视口的判定逻辑是对比布局变化前后的 viewport Id 集合取差集。

  • setDisplaySetsForViewports 的状态广播:批量更新视口绑定后广播 GRID_STATE_CHANGED,事件载荷包含更新后的 state、发生变化的 viewports 列表,以及被清空(displaySetInstanceUIDs 长度为 0)或被移除的视口 Id removedViewportIds,见 ViewportGridService.ts。

如何订阅事件

服务通过 _broadcastEvent(继承自 PubSubService)发布事件,应用层可通过 servicesManager.services.viewportGridService 拿到服务实例,再使用 subscribe(event, callback) 订阅,例如:

const { viewportGridService } = servicesManager.services;

viewportGridService.subscribe(
  viewportGridService.EVENTS.ACTIVE_VIEWPORT_ID_CHANGED,
  ({ viewportId }) => {
    // 响应活跃视口切换,例如更新左侧面板高亮
  }
);

仓库中 useToolbar.tsx、useActiveViewportDisplaySets.ts 以及 StudyPrefetcherService.ts 都订阅了这些事件,可作为参考实现。

核心接口:服务提供的 API 成员

原文档给出的 API 表格是使用 ViewportGridService 的"操作手册",以下逐项结合源码说明其真实签名与行为:

API 成员 文档描述 源码补充说明
setActiveViewportId(viewportId) 在应用中设置活跃视口 Id 若 Id 与当前活跃视口相同则直接返回;否则调用实现层 _setActiveViewport 并延迟广播 ACTIVE_VIEWPORT_ID_CHANGED
getState() 获取视口状态(见下文 State 一节) 委托给 serviceImplementation._getState(),返回 AppTypes.ViewportGrid.State
setDisplaySetsForViewport({ viewportId, displaySetInstanceUID }) 基于 DisplaySet Id 为视口设置显示集 底层是单视口场景的便捷方法,内部转调 setDisplaySetsForViewports([props])(批量方法)
setLayout({numCols, numRows, ...}) 设置行列数;当总视口数减少时,可选保留额外/离屏视口 实际签名支持 layoutOptions、layoutType(默认 'grid')、activeViewportId、findOrCreateViewport、isHangingProtocolLayout,见下文第 5 节
reset() 重置为默认状态 委托给 _reset,在 Provider 中对应 RESET reducer,直接恢复 DEFAULT_STATE
getNumViewportPanes() 获取可见视口面板数量 Provider 实现为 Math.min(viewports.size, numCols * numRows),即"实际视口数"与"行列格子数"的较小值
getLayoutOptionsFromState(gridState) 根据传入状态生成 ViewportLayoutOptions 工具方法 遍历 state.viewports(Map),提取每个视口的 x/y/width/height 返回数组
getActiveViewportId() 返回网格中活跃视口的 Id 直接读取 state.activeViewportId
getActiveViewportOptionByKey(key) 获取活跃视口的指定选项字段 Provider 实现:state.viewports.get(activeViewportId)?.viewportOptions?.[key],常用于读取如 viewportType、toolGroupId 等字段

源码中还提供了哪些补充方法

除了文档表格列出的方法,实际服务还包含以下对扩展开发十分有用的成员(可在 ViewportGridService.ts 中确认):

  • getViewportState(viewportId):返回单个视口的完整状态对象;
  • setViewportIsReady(viewportId, isReady):标记视口渲染就绪状态;
  • setDisplaySetsForViewports(viewportsToUpdate):批量更新多个视口的 DisplaySet 绑定,避免逐个更新带来的竞态问题(Provider reducer 注释明确提到旧的单视口更新存在部分渲染竞态导致异常的隐患);
  • getDisplaySetsUIDsForViewport(viewportId):获取某视口当前绑定的 DisplaySet Instance UID 数组;
  • getPresentationIds({ viewport, viewports }) / addPresentationIdProvider(id, provider):与"呈现 Id"(presentationIds)相关的注册与获取机制,用于跨会话保存视口显示参数;
  • setViewportGridSizeChanged():主动广播 GRID_SIZE_CHANGED;
  • publishViewportsReady() / publishViewportOnDropHandled(eventData):主动广播对应事件;
  • onModeExit():模式退出时调用,将视口网格恢复为标准/干净状态。源码注释建议:若要实现网格状态的保存/恢复,应在模式或扩展的 onModeExit 中存储状态,并在 onModeEnter 中恢复。

服务实现的可替换设计

ViewportGridService 采用"接口 + 实现注入"(serviceImplementation)模式:服务本体定义 API 与事件广播,而真正的状态读写由 setServiceImplementation({...}) 注入的具体实现承担(见 ViewportGridService.ts)。setActiveViewportId、getState、setDisplaySetsForViewports、setLayout、reset、onModeExit、set、getNumViewportPanes、setViewportIsReady、getViewportState 均可被替换。这使服务既能被 ViewportGridProvider 这类 React 实现消费,也能被其他宿主环境替换实现。

状态结构:从文档示例到源码类型

文档中的 DEFAULT_STATE

原文档给出了服务的默认状态示例(numRows、numCols 初始为 null,等待挂片协议定义行列数;viewports 为数组;activeViewportId 为 null):

const DEFAULT_STATE = {
  numRows: null,
  numCols: null,
  viewports: [
    /*
     * {
     *    displaySetInstanceUID: string,
     * }
     */
  ],
  activeViewportId: null,
};

源码中的真实默认状态

文档示例是早期形态的简化示意。在当前仓库中,真正的默认状态定义在 ViewportGridProvider.tsx,结构已经演进为:

const DEFAULT_STATE: AppTypes.ViewportGrid.State = {
  activeViewportId: null,
  layout: {
    numRows: 0,
    numCols: 0,
    layoutType: 'grid',
  },
  // 该标志用于判断当前是否为挂片协议布局,
  // 以便决定是否继承上一个状态的视口选项。
  // 例如在 MPR 挂片协议下切换到 1x1 布局后,
  // 需要通过该标志恢复常规布局,避免拖放时始终继承
  // 挂片协议布局的选项(如 volume viewport)。
  isHangingProtocolLayout: false,
  // 视口结构已从数组/下标(viewportIndex)改为 Map,
  // 每个视口拥有全局唯一的 viewportId。
  viewports: new Map(
    Object.entries({
      default: {
        viewportId: 'default',
        displaySetInstanceUIDs: [],
        isReady: false,
        viewportOptions: { viewportId: 'default' },
        displaySetSelectors: [],
        displaySetOptions: [{}],
        x: 0, // left
        y: 0, // top
        width: 100,
        height: 100,
        viewportLabel: null,
      },
    })
  ),
};

类型定义的完整视图

对应的 TypeScript 类型定义位于 ViewportGridType.ts,其中每个关键字段的语义如下:

  • GridViewport:单个网格视口对象,包含 viewportId、displaySetInstanceUIDs(该视口绑定的显示集 UID 数组)、viewportOptions(视口选项,见下)、displaySetSelectors、displaySetOptions、x/y/width/height(归一化布局坐标,0~1 区间)、viewportLabel、isReady;
  • GridViewportOptions:视口选项,包括 viewportType、toolGroupId、orientation、flipHorizontal、rotation、background、syncGroups、initialImageOptions、presentationIds、displayArea、viewReference、customViewportProps 等;
  • Layout:{ numRows, numCols, layoutType },其中 layoutType 默认 'grid';
  • ViewportGridState:{ activeViewportId, layout, isHangingProtocolLayout, viewports };
  • SetDisplaySetsForViewportsProps:批量更新视口绑定的入参结构,支持为每个视口指定 viewportOptions 以及一组 displaySetOptions(其中可包含 voi 窗宽窗位、blendMode、slabThickness、colormap、displayPreset 等)。

这些类型均通过 AppTypes.ViewportGrid 命名空间暴露,可在 AppTypes.ts 中查看汇总。

布局切换:setLayout 的工作机制与 findOrCreateViewport

setLayout 是服务中最复杂的方法,也是挂片协议(Hanging Protocol)与手动布局选择器的共同入口。其完整签名(来自源码)为:

public async setLayout({
  numCols,
  numRows,
  layoutOptions,
  layoutType = 'grid',
  activeViewportId = undefined,
  findOrCreateViewport = undefined,
  isHangingProtocolLayout = false,
})

各参数说明:

参数 说明
numCols / numRows 网格的行列数
layoutOptions 每个网格位置的布局选项数组(含 x/y/width/height 归一化坐标、positionId 等);未提供时按 1/numCols、1/numRows 等分计算
layoutType 布局类型,默认 'grid'
activeViewportId 布局变化后要设为活跃的视口 Id;缺省时由 determineActiveViewportId 自动推断
findOrCreateViewport 工厂函数 (position, positionId, options) => viewport,决定每个网格位置放入哪个视口对象。options 是临时状态存储,可用来记录哪些 DisplaySet 已在视图中,以便按序补充未展示的显示集
isHangingProtocolLayout 标记该布局是否来自挂片协议,影响后续视口选项是否继承

自动推断活跃视口

当未显式指定 activeViewportId 时,Provider 中的 determineActiveViewportId 会依次按以下优先级挑选新的活跃视口:

  1. 若原活跃视口已不存在,取新视口列表的第一个;
  2. 否则在新视口中按"方向(orientation)是否与原活跃视口一致"排序;
  3. 再按"是否展示与原活跃视口相同的 DisplaySet UID"排序;
  4. 取排序结果的第一名作为活跃视口。

挂片协议中的真实调用

在应用侧,ViewportGrid.tsx 展示了挂片协议驱动 setLayout 的典型用法——从协议 stage 的 viewportStructure.properties 中取出行列数与 layoutOptions,并由 findOrCreateViewport 根据协议匹配结果(viewportMatchDetails)为每个位置生成带 displaySetInstanceUIDs、displaySetOptions、viewportOptions 的视口对象:

viewportGridService.setLayout({
  numRows,
  numCols,
  layoutType,
  layoutOptions,
  findOrCreateViewport,
  isHangingProtocolLayout: true,
});

布局过程中自动生成 viewportId

在 SET_LAYOUT reducer 中(ViewportGridProvider.tsx),若 findOrCreateViewport 返回的视口未带 viewportId,Provider 会用 utils.uuidv4().substring(0, 8) 生成形如 viewport-xxxxxxxx 的随机 Id(viewport-${randomUID}),并同步更新 x/y/width/height 归一化坐标与 isReady: false。这解释了为什么 viewports 必须用 Map<string, GridViewport> 而非数组——每个视口以全局唯一 Id 为键,与"视口索引"彻底解耦。

实现与消费:ViewportGridProvider 与应用的接入

Provider 注入

ViewportGridProvider 是 ViewportGridService 在 @ohif/ui-next 中的官方实现,位于 ViewportGridProvider.tsx。文档中"Baked into Dialog Provider"的表述在演进后的版本中已由应用根组件直接注入:在 App.tsx 中,viewportGridService 从 servicesManager 取出后作为 prop 传入 ViewportGridProvider:

[ViewportGridProvider, { service: viewportGridService }],

Provider 通过 useEffect 调用 service.setServiceImplementation({...}) 将 reducer 实现注入服务(ViewportGridProvider.tsx),从而建立"服务 API → React state"的桥接。

消费侧:useViewportGrid Hook

UI 组件通过 useViewportGrid() Hook 获取 [state, api] 二元组:

const [viewportGrid, viewportGridService] = useViewportGrid();
const { layout, activeViewportId, viewports, isHangingProtocolLayout } = viewportGrid;
const { numCols, numRows } = layout;

API 对象(ViewportGridProvider.tsx)中除了服务的方法外,还暴露了:

  • isReferenceViewable(viewportId, viewRef, options?):判断某个视口引用是否可查看;
  • getGridViewportsReady():检查所有"已绑定 DisplaySet 的视口"是否都处于 isReady 状态(用于决定何时发布 VIEWPORTS_READY);
  • getActiveViewportOptionByKey(key):读取活跃视口的某个选项字段;
  • getDisplaySetsUIDsForViewport(viewportId):读取某视口的 DisplaySet UID 列表。

reducer 与状态流转

Provider 内部用 useReducer 管理网格状态,action 类型包括 SET_ACTIVE_VIEWPORT_ID、SET_DISPLAYSETS_FOR_VIEWPORTS、SET_LAYOUT、RESET、SET、VIEWPORT_IS_READY。其中两个值得注意的设计:

  • SET_DISPLAYSETS_FOR_VIEWPORTS 会清理一次性使用的 initialImageOptions(useOnce 标志),并通过 lodash.merge 合并新旧 viewportOptions,实现"只更新 DisplaySet、保留其余视口选项";
  • 当 updatedViewport 未提供 viewportOptions 且当前不是挂片协议布局时,reducer 会将 viewportOptions 收敛为仅含 viewportId,从而避免拖放操作意外继承挂片协议布局的选项(如 toolGroupId、viewportType)。

实战要点:在扩展与模式中使用 ViewportGridService

综合文档与源码,开发者在自定义扩展(Extension)或模式(Mode)中使用该服务时,可以遵循以下最佳实践:

  1. 获取服务实例:通过 servicesManager.services.viewportGridService 访问(类型可从 AppTypes.ViewportGridService 获得)。

  2. 切换活跃视口:调用 setActiveViewportId(viewportId),无需手动广播事件——服务会自动异步发布 ACTIVE_VIEWPORT_ID_CHANGED;如果 Id 未变化则不会重复触发。

  3. 给视口绑定显示集:优先使用批量接口 setDisplaySetsForViewports([...])(或单视口的便捷方法 setDisplaySetsForViewport),入参结构为 { viewportId, displaySetInstanceUIDs, viewportOptions?, displaySetOptions? }。这是当前推荐方式,规避了旧版单视口更新存在的渲染竞态。

  4. 切换布局:调用 setLayout({ numCols, numRows, layoutOptions?, layoutType?, activeViewportId?, findOrCreateViewport?, isHangingProtocolLayout? })。常规布局切换时保持 isHangingProtocolLayout: false,由挂片协议驱动时置为 true。

  5. 监听网格变化:订阅 GRID_STATE_CHANGED 与 LAYOUT_CHANGED,事件载荷中包含最新 state 与被移除视口 Id 列表,可用于驱动缩略图面板、左侧序列列表等 UI 的同步刷新;在视口渲染完成后调用 setViewportIsReady(viewportId, true),并可在全部就绪后通过 publishViewportsReady() 广播 VIEWPORTS_READY。

  6. 模式退出清理:在模式(Mode)的 onModeExit 钩子中调用 viewportGridService.onModeExit() 恢复干净状态;如需保存/恢复用户布局,则按服务源码注释的建议在 onModeExit 存储状态、在 onModeEnter 恢复。

小结

Viewport Grid Service 是 OHIF 查看器中"网格布局"与"视口状态"的唯一权威来源:它以 PubSubService 事件机制对外广播活跃视口、布局与网格状态的变化;以 serviceImplementation 注入模式实现与 React 端 ViewportGridProvider 的解耦;以 Map<viewportId, GridViewport> 承载与索引解耦的视口状态。本文所涉及的完整实现可从 ViewportGridService.ts、ViewportGridProvider.tsx、类型定义 ViewportGridType.ts 以及应用侧消费示例 ViewportGrid.tsx 中进一步研读。

登录后查看全文
Viewers