OHIF Viewport Grid Service 详解:透视查看器网格布局、状态管理与事件机制
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)或被移除的视口 IdremovedViewportIds,见 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 会依次按以下优先级挑选新的活跃视口:
- 若原活跃视口已不存在,取新视口列表的第一个;
- 否则在新视口中按"方向(orientation)是否与原活跃视口一致"排序;
- 再按"是否展示与原活跃视口相同的 DisplaySet UID"排序;
- 取排序结果的第一名作为活跃视口。
挂片协议中的真实调用
在应用侧,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)中使用该服务时,可以遵循以下最佳实践:
-
获取服务实例:通过
servicesManager.services.viewportGridService访问(类型可从AppTypes.ViewportGridService获得)。 -
切换活跃视口:调用
setActiveViewportId(viewportId),无需手动广播事件——服务会自动异步发布ACTIVE_VIEWPORT_ID_CHANGED;如果 Id 未变化则不会重复触发。 -
给视口绑定显示集:优先使用批量接口
setDisplaySetsForViewports([...])(或单视口的便捷方法setDisplaySetsForViewport),入参结构为{ viewportId, displaySetInstanceUIDs, viewportOptions?, displaySetOptions? }。这是当前推荐方式,规避了旧版单视口更新存在的渲染竞态。 -
切换布局:调用
setLayout({ numCols, numRows, layoutOptions?, layoutType?, activeViewportId?, findOrCreateViewport?, isHangingProtocolLayout? })。常规布局切换时保持isHangingProtocolLayout: false,由挂片协议驱动时置为true。 -
监听网格变化:订阅
GRID_STATE_CHANGED与LAYOUT_CHANGED,事件载荷中包含最新state与被移除视口 Id 列表,可用于驱动缩略图面板、左侧序列列表等 UI 的同步刷新;在视口渲染完成后调用setViewportIsReady(viewportId, true),并可在全部就绪后通过publishViewportsReady()广播VIEWPORTS_READY。 -
模式退出清理:在模式(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 中进一步研读。