OHIF Viewer 报告保存对话框深度解析:目标序列选择、序列命名与版本化机制
OHIF Viewer 报告保存对话框深度解析:目标序列选择、序列命名与版本化机制
本文以 OHIF Viewer 行为文档 report-dialog-save-destinations.md 为主线,结合 extensions/default 与 extensions/cornerstone-dicom-seg 的实际源码与测试,完整剖析保存对话框(Report Dialog)的工作原理。你将掌握:Save to current / Save as new / Replace existing 三种保存目标的判定逻辑、predecessorImageId 与 PredecessorSequence 的底层机制、新序列的四种命名候选及其记忆历史、新序列编号的计算规则,以及如何通过 ohif.createReportDialog 自定义替换整个对话框。
一、概述:保存对话框解决什么问题
当用户需要把一次编辑的成果写回 DICOM 存储时,OHIF Viewer 会弹出一个报告保存对话框(Report Dialog)。它可以存储三类对象:
- 分割(Segmentation,SEG)
- 轮廓集(Contour Set / RTSTRUCT)
- 测量报告(Measurement Report / SR)
对话框向用户提出两个核心问题:对象写入哪个序列(Series),以及这个序列叫什么名字。两者看似简单,背后却牵涉到版本化语义、前驱引用链与记忆历史三个设计维度。
该功能横跨多个模块,实现位置如下:
- 对话框本体与
ohif.createReportDialog定制点:reportDialogCustomization.tsx - 对话框的 Prompt 封装(输入输出契约):createReportDialogPrompt.tsx
- 序列描述记忆历史:seriesDescriptionHistory.ts
- SEG / RTSTRUCT 的保存调用方(
storeSegmentation):commandsModule.ts - 测量报告的保存调用方:promptSaveReport.tsx
- 前驱实例读取(
PredecessorSequenceprovider):位于文档所引用的 adapters 包libs/@cornerstonejs/packages/adapters/src/utilities/referencedMetadataProvider.ts
此外,配套的迁移指南 report-dialog.md 记录了 3.13 → 3.14 版本中该对话框从"单一下拉框"演进为"三种明确目标"的完整过程,可作为行为文档的延伸阅读。
二、核心语义:一次保存只存一个对象
在深入三个目标之前,必须先理解保存对话框的基础语义:
每次保存都把当前的全部数据作为一个对象写入目标序列,对话框不做任何合并。
这意味着:
- 保存进一个已有数据的序列时,不会先读取该序列的旧数据——旧对象不会与新对象融合;
- 当前数据也不会被遗漏任何一部分——保存的是服务中选定的全量数据(测量服务中的全部测量、分割服务中的全部分段);
- 目标序列决定了新对象取代哪一个旧实例——
predecessorImageId指向的实例被"继承"(supersede),旧实例仍然保留在序列中,但新实例成为该序列被默认加载的对象。
从源码看,reportDialogCustomization.tsx 中的 Destination 类型注释明确写道:三种目标存储的是同一个对象,对话框不合并任何内容("All three store the same object, and the dialog merges nothing")。
三、三种保存目标:Save to current / Save as new / Replace existing
3.1 三种目标一览
| 目标 | 对象去向 | 对话框何时提供该目标 |
|---|---|---|
Save to current |
视口加载数据来源的那个序列 | 数据的 predecessorImageId 指向一个已加载的序列 |
Save as new |
新建一个序列,编号与描述均可编辑 | 始终可用 |
Replace existing |
用户选择的、同模态(modality)的其他已加载序列 | 视口还持有至少一个此类序列 |
默认选择规则:
- 当
Save to current可用时,它是默认选择; - 否则默认选择
Save as new; Save to current与Replace existing都保留目标序列原有的编号与描述,因此对话框对这两项只读展示、不允许用户编辑。
在 UI 上,这三个目标以分段控件(Segmented Control)的形式呈现在 Series 行上,控件下方有一行帮助文字,保存按钮上也重复了所选目标的措辞。源码中这三个目标的文案定义在 reportDialogCustomization.tsx 的 DESTINATIONS 数组中:
- Save to current:帮助文字为 "Adds a new version to this series as the new default. Earlier versions are kept."(向该序列添加一个新版本作为新的默认对象,旧版本保留);不可用时提示 "This data has not been saved to a series yet"(这些数据尚未保存到任何序列)。
- Save as new:帮助文字为 "Creates a separate series."(创建独立序列)。
- Replace existing:帮助文字为 "Choose a series to replace. The current data becomes the default and earlier versions are kept."(选择一个要替换的序列,当前数据成为默认,旧版本保留);不可用时提示 "No other series of this type is loaded"(没有加载其他同类序列)。
3.2 三个目标的源码实现
reportDialogCustomization.tsx 中:
existingSeries:从displaySetService.getDisplaySetCache()中筛选出同模态的显示集,映射为ExistingSeries结构(value即predecessorImageId,作为写入目标;seriesNumber用于计算下一个可用编号),并过滤掉没有predecessorImageId的条目与重复值;currentSeries:existingSeries中value === predecessorImageId的那一个,即Save to current的写入目标;数据从未被存储过时它为null;replaceableSeries:existingSeries中排除currentSeries的其余部分,即Replace existing的可选项。
对话框打开时,useState<Destination>(currentSeries ? 'current' : 'new') 决定默认选中的标签页。只有当 Replace existing 目标被选中但尚未选择具体序列时,保存与下载按钮才会被禁用(isIncomplete 判断)。
四、哪些序列会被对话框提供为目标
4.1 两个硬性条件
对话框把某个已加载序列作为目标,必须同时满足两个条件:
- 序列持有同类型的对象——即与本次保存的模态(modality)一致(保存 SEG 时只考虑 SEG 序列);
- 序列具有
predecessorImageId值。
predecessorImageId 命名的是"上次有人保存进该序列的那个直接前驱实例(immediate prior object)"。本次保存将取代(supersede)这一个实例。adapter 通过 PredecessorSequence provider,借助这个值解析出对应的序列与实例编号。
4.2 为什么不回退到 SeriesInstanceUID
对话框不会回退到显示集的 SeriesInstanceUID 值。原因在于类型语义:
- UID 命名的是序列而不是实例,因此它不指向任何前驱对象;
- UID 也不是 image id,
PredecessorSequenceprovider 无法为 UID 找到任何实例; - 结果就是:若以 UID 作为"前驱",provider 找不到实例,保存会新建一个序列,而不是扩展所选的序列。
迁移文档 report-dialog.md 补充说明:旧版本的行为正是把 SeriesInstanceUID 当作序列值塞给 provider,导致 provider 抛出 TypeError——这正是行为文档中"provider 对 UID 找不到实例"这一规则的由来。
4.3 本地 id 是合法值
一个本地 id(local id),例如 dicomfile:3,是完全合法的 predecessorImageId。机制如下:
- 用户上传的实例(uploaded instance)在注册时被赋予一个本地 id;
- provider 能够解析本地 id;
- 因此用户可以多次针对同一个上传实例执行保存(例如先存
Save as new,之后再次保存时通过本地 id 定位到它)。
4.4 下载但未存储的序列
一个被下载(download)却从未写回存储的显示集,没有 predecessorImageId 值,因此对话框不会提供该显示集作为保存目标。
但要注意:新建序列的编号计算仍然会计入这类序列。因为编号来自该模态的全部已加载序列,而不仅仅是"被提供的那些"。源码见 reportDialogCustomization.tsx:defaultNewSeriesNumber 遍历 modalityDisplaySets(同模态全部显示集)取最大 SeriesNumber 再加一,而非基于 existingSeries 或 replaceableSeries。
五、新序列叫什么:四种命名候选
5.1 四名候选的优先级
Save as new 提供四种候选名称,描述字段从第一个非空名称开始填充:
| 优先级 | 名称来源 | 说明 |
|---|---|---|
| 1 | itemName |
用户为该项目选择的名称。保存前的重命名会反映到该字段 |
| 2 | 加载来源序列的描述 | 即该数据上一次保存时使用的序列名 |
| 3 | 该类型项目以前用过的描述 | 最近使用的最靠前(详见"记住的描述") |
| 4 | defaultSeriesDescription |
没有任何其他名称时的兜底名称 |
仓库内三个内置调用方传入的 defaultSeriesDescription 分别为:Segmentation(SEG)、Contours(RTSTRUCT)与 Measurements(测量报告)。
5.2 itemName 与 labelIsGenerated 的微妙关系
itemName 必须是"用户选择过的名称"。以 storeSegmentation 为例,commandsModule.ts 中:
const { label, predecessorImageId, labelIsGenerated } = segmentation;
// 只有用户选择的名称才进入 itemName,对话框将其放在第一位;
// 生成的名称则进入 defaultSeriesDescription,放在最后。
const chosenLabel = labelIsGenerated ? '' : label || '';
const defaultSeriesDescription =
(labelIsGenerated && label) || (modality === 'RTSTRUCT' ? 'Contours' : 'Segmentation');
这里的关键在于 labelIsGenerated 标记:
- 分割服务(Segmentation Service)为新分割自动生成一个名称(例如
Segmentation 3),并给分割打上labelIsGenerated标记; - 一个仍带着该标记的标签,会被归入
defaultSeriesDescription而非itemName——因为生成的名称不能压过(outrank)用户记住的描述; - 重命名会清除该标记。此后即使用户手动输入一个与自动生成名一模一样的字符串(例如真的输入了
Segmentation 3),保存时也不会做字符串比对,该名称仍会以itemName的身份进入候选第一位。
迁移文档还补充了 labelIsGenerated 的完整生命周期:Segmentation.labelIsGenerated 是 @cornerstonejs/tools 中的新字段,由 SegmentationPublicInput.config 携带;创建者发明标签时传入 labelIsGenerated: true;不带标签的创建者同样会得到该标记;而携带 label 但未带 labelIsGenerated 的更新操作会清除标记(即重命名)。
5.3 下拉列表的去重与回退规则
四种名称按上述顺序放入下拉列表(pull-down),并遵循以下规则:
- 空白名称与纯空格名称会被剔除,防止其"藏住"后面的名称;
- 对话框忽略大小写比较名称,列表中每个名称只出现一次;
- 字段被清空时,回退到列表的第一个名称。
源码实现见 reportDialogCustomization.tsx:descriptionOptions 先对 [itemName, currentSeries?.description, ...remembered, defaultSeriesDescription] 逐一 trim() 并过滤空值,再用 toLowerCase() 去重。
5.4 没有 itemName 的调用方
没有可编辑名称的调用方不传 itemName。例如测量报告(measurement report)没有此类名称,因此其描述字段直接从"加载来源序列的描述"或"最近使用的名称"开始。
5.5 键盘交互
用户可以通过三种方式使用该列表(源码见 reportDialogCustomization.tsx):
- 点击下拉按钮:展示全部候选名称;
- 键入文字:列表被过滤为"当前输入可以补全(complete)"的名称子集;
- Tab:补全为过滤后列表的第一个名称(若与当前输入不同则阻止默认 Tab 行为);
- 方向键 + Enter:在列表中上下移动并选中一项;
- Escape:关闭列表。
六、记住的描述(Remembered Descriptions)
6.1 什么时候被记住
- 用户创建新序列并使用该描述时,此描述被记住;下载(download)也算一次保存,同样触发记忆;
- 保存进一个已存在的序列时,不记住任何东西——因为该序列保留自己的描述;
- 使用
defaultSeriesDescription的保存不进入历史:调用方每次保存都会提供该名称,对话框无论如何都会提供它,记住它只会污染历史。
由此产生一个重要推论:自动生成的分割标签(如 Segmentation 1)落在 defaultSeriesDescription 上,因此不会进入历史,对话框也就不会把 Segmentation 1 当作后来某个无关分割的名称来推荐。
6.2 两个配置项
| 配置项 | 含义 | 默认值 |
|---|---|---|
itemType |
描述被记住时使用的键(key) | 模态(modality),即 SEG / RTSTRUCT / SR 各自独立 |
rememberedDescriptionCount |
每种类型记住多少条描述 | 5 |
特别地,rememberedDescriptionCount: 0 会完全关闭该功能:不记忆、不提供,列表只剩一个名称,对话框也不渲染下拉按钮,退化为普通文本输入框。对于不允许向 localStorage 持久化任何内容的部署,应显式传入 rememberedDescriptionCount: 0。
6.3 存储实现
历史数据存放在浏览器 localStorage 中,键名为 ohif.seriesDescriptionHistory,结构为 Record<string, string[]>(按 itemType 分组、最近使用在前)。核心实现在 seriesDescriptionHistory.ts:
getSeriesDescriptionHistory(itemType, maxCount):读取并返回该类型最近使用的描述,最多maxCount条(第 39-52 行);rememberSeriesDescription(itemType, description, maxCount):把描述记为最近使用,移除更早的同名条目(大小写不敏感,isSameDescription用toLowerCase()比较),并截断到maxCount条(第 58-82 行);readHistory():由于 localStorage 在某些浏览器配置下不可用、内容也可能被污染,所有读取都是防御性的,失败仅意味着"没有历史"(第 20-29 行)。
6.4 测试用例佐证
reportDialogCustomization.test.ts 中对记忆历史的断言非常直观,例如:
remembers the description that was used, per type of item:输入Right kidney保存后,storedHistory()等于{ SEG: ['Right kidney'] };remembers nothing for the name that the caller provides:直接用生成的Segmentation 1保存后,storedHistory()等于{};remembers nothing when the typed name is the provided one:即使输入带空格变体的contours,也不会被记住;remembers nothing when an existing series is stored into:存入已有序列不触发记忆。
七、新序列的序列号(Series Number)
7.1 计算规则
Save as new 提供的序列号 = 该模态全部已加载序列的最高序列号 + 1,且至少为 minSeriesNumber。用户可以直接编辑该数字;若数字为空或非法,则回退到对话框最初提供的数字。
源码见 reportDialogCustomization.tsx 与 parsedSeriesNumber 的解析逻辑(第 279-282 行)。
7.2 minSeriesNumber 的模态默认值
minSeriesNumber 由 createReportDialogPrompt.tsx 按模态计算,仅当调用方未显式传入时生效:
minSeriesNumber ||=
(modality === 'SR' && 3000) ||
(modality === 'SEG' && 3100) ||
(modality === 'RTSTRUCT' && 3200) ||
4000;
即:SR 为 3000、SEG 为 3100、RTSTRUCT 为 3200,其他模态一律 4000。同时在 reportDialogCustomization.tsx 中,对话框组件自身的 minSeriesNumber 默认值为 3000。
7.3 返回值:seriesNumber 与 priorSeriesNumber
createReportDialogPrompt 返回 seriesNumber,同时返回 priorSeriesNumber(比 seriesNumber 小 1)。这是为了兼容旧调用方:凡是按 1 + priorSeriesNumber 计算编号的调用方,都能得到对话框当前显示(可能被用户编辑过)的数字。
迁移文档给出了明确的版本差异:
- 3.13(旧):调用方自己算
SeriesNumber: 1 + priorSeriesNumber,无法感知用户的编辑; - 3.14(新):直接使用
SeriesNumber: seriesNumber(对话框已返回最终值),priorSeriesNumber从"该模态最高现有编号"变为"seriesNumber - 1",旧式1 + priorSeriesNumber依然可用。
7.4 存储端的优先级
一个容易被忽略的细节:当设置了 predecessorImageId 时,SeriesDescription 和 SeriesNumber 会被忽略,因为生成的实例会应用前驱实例的序列数据——这正是对话框在扩展已有序列时把编号与描述显示为只读的原因。这在 commandsModule.ts 的 storeSegmentation 中有直接体现:
const args = {
segmentationId,
options: {
dataSource: dataSourceName,
SeriesDescription: series ? undefined : reportName || label || defaultSeriesDescription,
SeriesNumber: series ? undefined : seriesNumber,
predecessorImageId: series,
},
};
当 series(即 predecessorImageId)存在时,SeriesDescription 与 SeriesNumber 均为 undefined。
八、保存之后:被存储的对象成为新前驱
要让"第二次保存默认 Save to current"成立,保存动作本身必须把本次写入的实例登记为新的前驱。核心机制是 registerStoredInstanceImageId:从 viewer 存储的实例,会像从数据源加载的实例一样被识别——它获得一个"重新加载该实例时会用到的 imageId",并在加入元数据存储前把这个 imageId 映射到它的 UIDs。因此,由存储实例生成的显示集自带 predecessorImageId。
两类对象的登记路径不同:
- 分割与轮廓(SEG / RTSTRUCT):保存会移除内存中的分割并展示存储下来的那个,因此重新加载的分割通过正常加载路径从显示集取得前驱;
- 测量(Measurements):测量不会从存储的报告重新加载,因此新增的
recordMeasurementsPredecessor命令(在CORNERSTONE命令模块中)直接把前驱记录在测量及其派生的标注上,确保之后编辑测量不会丢失该引用。
在 promptSaveReport.tsx 中可以看到测量路径的完整闭环:storeMeasurements 执行后,从新显示集取 predecessorImageId,再调用 recordMeasurementsPredecessor 写回测量数据。
实际效果:同一份数据第二次保存时,默认选中 Save to current 并指向第一次保存所创建的序列。
九、如何自定义或替换对话框
ohif.createReportDialog 是正式的定制点(customization)。任何自定义组件只要注册到该键名下即可整体替换内置对话框。替换时需遵循的输入输出契约如下:
9.1 输入 props
内置 ReportDialog 组件接收(见 reportDialogCustomization.tsx):
dataSources:可写入的数据源列表(多数据源导出开启时显示选择器);modality:本次保存的模态,用于筛选可写序列;predecessorImageId:数据加载来源的 image id,决定Save to current是否可用;minSeriesNumber:新序列编号的下限;itemName:用户为该对象选择的名称(如分割名),新序列首选它;生成的名称应放入defaultSeriesDescription;defaultSeriesDescription:无其他名称时的兜底名;itemType:记忆历史的键,默认取模态;rememberedDescriptionCount:记忆条数,0 关闭;enableDownload:是否显示 Download 按钮。
9.2 输出 onSave
onSave 负载包含:reportName(序列描述)、dataSource、series(以 predecessorImageId 值引用目标序列,新建序列时为 null)、seriesNumber(对话框显示并可能被编辑过的最终编号)以及 priorSeriesNumber。3.14 起新增 seriesNumber 字段;一个只创建新序列的自定义对话框可以直接传 series: null 与自定义的 seriesNumber。
9.3 复用记忆历史
描述记忆是对话框自身的职责。自定义对话框若想复用该行为,应直接调用 seriesDescriptionHistory.ts 导出的 getSeriesDescriptionHistory 与 rememberSeriesDescription;不想使用的对话框忽略 itemType 与 rememberedDescriptionCount 即可。
9.4 配套的样式与行为细节
- 对话框标题为 Save Segmentation、Save Contours、Save Measurements(3.14 前为 Store/Create Report 措辞),调用方可通过
title或模式的defaultSaveTitle覆盖; - 底部操作区为
FooterAction:左侧Download、右侧Cancel与主保存按钮; - 对话框打开时默认焦点会落在"系列目标"分段控件上,但当目标是
Save as new时,代码通过useEffect把光标移到描述输入框,便于用户直接键入命名(第 436-442 行)。
十、测试验证与行为契约
reportDialogCustomization.test.ts 用 701 行测试完整锁定了本文描述的全部行为,是理解行为契约的最佳入口。测试通过模拟多个显示集验证:
- 目标可用性:无前驱时
current禁用并提示;无其他同模态序列时replace禁用;默认选中标签页随数据是否被保存过而切换(第 186-215 行); - Save to current:展示目标序列只读的编号与描述,
onSave携带该序列的predecessorImageId与序列号(第 217-235 行); - Save as new:编号为最高现有编号 + 1;没有同模态序列时用
minSeriesNumber;不提供的序列(无前驱的下载序列)仍然计入编号计算;空字段回退到提供的值(第 237-301 行); - Replace existing:选择前禁用保存按钮;不重复提供当前序列;无描述的序列以
Series 3103形式命名;带本地 id(dicomfile:3)的上传序列可被选中并可重复保存(第 303-384 行)。
十一、相关阅读
- 行为文档本体:platform/docs/docs/behaviours/report-dialog-save-destinations.md
- 3.13 → 3.14 迁移指南(含输入输出契约与版本差异详解):platform/docs/docs/migration-guide/3p13-to-3p14/report-dialog.md
- 测量保存的调用方与
recordMeasurementsPredecessor流程:extensions/default/src/utils/promptSaveReport.tsx - 分割保存的调用方:extensions/cornerstone-dicom-seg/src/commandsModule.ts
掌握这套"目标判定 + 命名候选 + 前驱链"的机制后,无论是排查保存行为、扩展新的保存对象类型,还是整体替换保存对话框,都能准确对齐 OHIF Viewer 既有的数据版本化语义,避免在自定义过程中破坏"旧版本保留、新版本成为默认"的核心契约。