OHIF Viewers 3.13 迁移指南：`formatDICOMDate` options 对象化改造与实战适配

OHIF Viewers 3.13 迁移指南formatDICOMDateoptions 对象化改造与实战适配【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/ViewersformatDICOMDate是ohif/ui-next中负责将 DICOM 原始日期字符串如20180916、2018.09.16格式化为本地化展示文本的核心工具广泛用于工作列表WorkList的 Study Date 列、旧版工作列表以及视口 Overlay 的日期显示。本文以 OHIF Viewers 的 3.12 到 3.13 迁移文档为骨架结合ui-next源码与测试用例完整讲解该函数从「位置参数」到「options 对象」的签名变化、三个可用选项的语义与优先级、底层严格/宽松解析机制并给出仓库内真实调用方的迁移对照帮助你在升级到 3.13 时零遗漏地完成适配。迁移依据文档位于 platform/docs/docs/migration-guide/3p12-to-3p13/format-dicom-date.md。迁移背景从位置参数到 options 对象在 OHIF Viewers 3.12 及更早版本中formatDICOMDate的第二个参数是位置参数直接传入一个格式化模板字符串// Before (3.12) formatDICOMDate(date, YYYY-MM-DD);从 3.13 开始可选参数被收拢为单个 options 对象// After (3.13) formatDICOMDate(date, { strFormat: YYYY-MM-DD });这一改动消除了「第二个参数含义随调用位置变化」的隐患并为后续新增的fallbackFormat、invalidFallback两个选项提供了可扩展的载体。函数签名在源码中的定义如下platform/ui-next/src/utils/formatDICOMDate.tsexport function formatDICOMDate(date: string, options: FormatDICOMDateOptions {}): stringoptions是可选的默认{}因此只传date一个参数的调用完全不受影响——包括把formatDICOMDate直接作为formatDate格式化器传入视口 Overlay 的用法。options 对象全参数详解三个可用选项及其语义如下表所示选项类型作用默认值strFormatstring显式指定输出格式一旦提供将覆盖当前 locale 的Common:localDateFormat未提供时使用 locale 键fallbackFormatstring仅当当前激活的 locale未定义Common:localDateFormat时生效的输出格式MMM D, YYYYinvalidFallbackstring当date为空或完全无法解析时返回的值省略时保留旧版宽松解析行为无见下文行为说明对应的类型定义见 platform/ui-next/src/utils/formatDICOMDate.tsexport interface FormatDICOMDateOptions { /** 显式输出格式。提供时覆盖 locale 的 Common:localDateFormat省略时使用 locale 键。 */ strFormat?: string; /** 仅当当前 locale 未定义 Common:localDateFormat 时使用的格式约 8 个内置 locale 未定义。默认 MMM D, YYYY。 */ fallbackFormat?: string; /** date 为空或无法解析时返回的值。省略时保留旧行为宽松 moment 解析结果无法解析时为 Invalid date。 */ invalidFallback?: string; }strFormat显式格式的优先权strFormat的优先级最高一旦指定就直接作为输出模板不再查询 locale。在格式解析逻辑中它的优先级链是formatDICOMDate.tsconst format strFormat ?? i18n.t(Common:localDateFormat, fallbackFormat);即strFormat缺失时才读取Common:localDateFormat翻译键且该键缺失时回退到fallbackFormat。fallbackFormatlocale 缺失时的兜底fallbackFormat只在激活 locale 没有提供Common:localDateFormat时被使用。实际上仓库自带的 28 个 locale 中确实有部分未定义该键源码注释明确提到 shipped locales 中有 8 个未定义。已定义该键的 locale 示例platform/i18n/src/locales/en-US/Common.json、fr/Common.json、zh/Common.json// en-US localDateFormat: DD-MMM-YYYY // fr localDateFormat: DD MMM YYYY // zh localDateFormat: YYYY-MM-DD可见不同语言的默认日期形态差异很大英文为DD-MMM-YYYY中文为YYYY-MM-DD。fallbackFormat的价值在于当某个 locale 没有提供该键时仍能保证输出一个确定、可读的日期而不是返回空字符串。invalidFallback兜底返回值与「宽松解析」的取舍invalidFallback是最能体现本次改造意图的选项。理解它需要先了解函数内部的两段式解析逻辑const parsed moment(date, [YYYYMMDD, YYYY.MM.DD], true);严格解析使用 moment 的 strict 模式第三个参数true仅接受YYYYMMDD与YYYY.MM.DD两种 DICOM 规范形态。宽松兜底严格解析失败时若未提供invalidFallback则退化为moment(date).locale(locale).format(format)的宽松解析——DICOM 格式之外的、moment 能识别的日期串仍会被格式化彻底无法解析的输入则会得到 moment 的Invalid date。invalidFallback提供了一条「纪律性」路径只要显式传入它严格解析一旦失败就直接返回该值完全跳过宽松解析让输出在异常输入下保持可控。三种输入情形下的行为汇总输入未传invalidFallback传了invalidFallback空字符串 /undefined返回返回invalidFallback合法的 DICOM 日期20180916、2018.09.16正常格式化正常格式化非 DICOM 但 moment 可解析如2018-09-16宽松解析出结果返回invalidFallback完全无法解析如garbage返回Invalid date返回invalidFallback源码级验证测试用例逐条对照仓库为本次改造配备了完整的单元测试platform/ui-next/src/utils/formatDICOMDate.test.ts每个选项的行为都有可执行断言是升级后回归验证的最佳参考。合法 DICOM 日期formatDICOMDate(20180916) // Sep 16, 2018默认 fallbackFormat formatDICOMDate(2018.09.16) // Sep 16, 2018支持点分变体 formatDICOMDate(20180916, { fallbackFormat: MMM-DD-YYYY }) // Sep-16-2018 formatDICOMDate(20180916, { strFormat: YYYY-MM-DD }) // 2018-09-16覆盖 locale空输入formatDICOMDate() // 默认返回空串 formatDICOMDate(undefined as unknown as string) // formatDICOMDate(, { invalidFallback: N/A }) // N/A非法输入宽松解析行为保留验证formatDICOMDate(2018-09-16) // Sep 16, 2018宽松解析仍生效 formatDICOMDate(garbage) // Invalid date旧行为 formatDICOMDate(garbage, { invalidFallback: N/A }) // N/A formatDICOMDate(2018-09-16, { invalidFallback: N/A }) // N/AinvalidFallback 短路宽松解析最后一个用例尤其值得注意即使2018-09-16能被 moment 宽松解析但只要严格 DICOM 解析失败且显式提供了invalidFallback返回值就是invalidFallback而非解析结果——这正是「显式兜底优先于历史宽松行为」的设计印证。仓库内的实际调用方升级对照与范例迁移后仓库自身的调用方就是最标准的 options 用法范例升级时可直接对照。新 ui-next 工作列表的 Study Date 列platform/ui-next/src/components/StudyList/columns/defaultColumns.tsx 中的日期列同时使用了fallbackFormat与invalidFallbackconst date formatDICOMDate(r.date ?? , { fallbackFormat: MMM-DD-YYYY, invalidFallback: , }); if (!date) { return ; // 日期无效时整格留空即使存在 time 也不拼接 } const time formatDICOMTime(r.time ?? , { invalidFallback: }); return time ? ${date} ${time} : date;这里invalidFallback: 配合if (!date)的判断实现了「无有效日期就整格不显示」的产品语义fallbackFormat则保证了无论激活 locale 是否提供localDateFormat日期列都有稳定的MMM-DD-YYYY形态。该列的时间过滤与排序分别基于原始date字符串和 parseStudyDateTimestamp 生成的毫秒时间戳完成与显示格式化互不干扰。旧版工作列表 LegacyWorkListplatform/app/src/routes/LegacyWorkList/LegacyWorkList.tsx 采用了完全一致的写法const studyDate formatDICOMDate(date, { fallbackFormat: MMM-DD-YYYY, invalidFallback: }); const studyTime formatDICOMTime(time, { invalidFallback: });视口 Overlay单参数调用无需改动formatDICOMDate在 cornerstone 扩展的 Overlay 系统中被直接用作formatDate格式化器extensions/cornerstone/src/Viewport/Overlays/utils.ts 从ohif/ui-next引入并对外 re-exportextensions/cornerstone/src/Viewport/Overlays/CustomizableViewportOverlay.tsx 与 同文件 L219 将其作为formatDate/formatters.formatDate传给 Overlay 渲染。这类用法只传date一个参数在 3.13 下行为完全不变无需任何迁移动作——这也是迁移文档中明确保证的兼容性边界。导出路径确认formatDICOMDate同时从 utils 聚合入口platform/ui-next/src/utils/index.ts和 ui-next 主入口platform/ui-next/src/index.ts导出升级后import { formatDICOMDate } from ohif/ui-next的导入路径保持不变。无需迁移的场景清单根据迁移文档与源码以下调用不受本次破坏性变更影响无需修改只传date一个参数的调用等价于formatDICOMDate(date, {})将formatDICOMDate直接作为formatDate函数引用传递给 Overlay、表格列等消费方函数引用本身不触发第二个参数任何依赖「空输入返回空串」「非法输入返回Invalid date」这一历史宽松行为的现有逻辑——未提供invalidFallback时行为逐字节保持。迁移核对清单升级到 3.13 时按以下清单排查formatDICOMDate的调用点即可完成适配全局搜索formatDICOMDate(逐一检查第二参数是否为字符串字面量将formatDICOMDate(date, FORMAT)改写为formatDICOMDate(date, { strFormat: FORMAT })对需要稳定展示形态的场景如工作列表日期列补充fallbackFormat以规避部分 locale 缺少localDateFormat的问题对「空值/脏数据需展示占位符」的场景显式传入invalidFallback如N/A或若希望完整保留 3.12 的宽松解析行为则不要传入该选项运行formatDICOMDate.test.ts所在的ui-next测试套件回归验证默认格式、locale 覆盖、宽松解析三类行为。顺带一提同为ohif/ui-next导出的formatDICOMTime也采用了相同的 options 对象签名见 platform/ui-next/src/utils/formatDICOMTime.ts选项语义一一对应strFormat/fallbackFormat默认hh:mm A/invalidFallback且其在时间解析失败时不进行宽松重解析、直接返回invalidFallback ?? ——适配时可以一并核对。【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考