OHIF v3 Toolbar 模块开发指南：组件注册、评估器（Evaluator）与工具箱（Toolbox）实战-开发者社区

OHIF v3 Toolbar 模块开发指南：组件注册、评估器（Evaluator）与工具箱（Toolbox）实战

【免费下载链接】ViewersOHIF zero-footprint DICOM viewer and oncology specific Lesion Tracker, plus shared extension packages项目地址: https://gitcode.com/GitHub_Trending/vi/Viewers

本文以 OHIF 官方文档《Module: Toolbar》为主线，结合当前仓库中@ohif/extension-default、@ohif/extension-cornerstone以及@ohif/core的 ToolbarService 源码，系统讲解 Toolbar Module 的注册机制、evaluate评估器的返回值契约与组合策略、按钮 Section 的组织方式，以及useToolbarHook 与Toolbox组件的二次开发实战。读完本文，你将能够为自己的扩展注册自定义按钮组件、编写三态等高级评估器，并在 Mode 中把工具栏按钮装配到主工具栏或任意自定义面板中。

在 OHIF v3 的扩展体系中，Toolbar Module（工具栏模块）是扩展对外提供"按钮外观"与"按钮状态判定逻辑"的标准出口。它与 ToolbarService（负责按钮注册、Section 组织与命令执行）以及 Mode（模式）（负责消费这些按钮）三者配合，构成了完整的工具栏闭环。理解 Toolbar Module 是进行 OHIF 二次开发、定制自己医学影像工作流 UI 的第一步。

一、Toolbar Module 是什么：`getToolbarModule`导出契约

一个扩展通过定义getToolbarModule方法来注册 Toolbar Module。@ohif/extension-default（默认扩展）提供了若干内置按钮uiTypes，其中最基础的三种为：

ohif.radioGroup：可点击的简单按钮（radio 型按钮）；
ohif.splitButton：带下拉菜单的按钮；
ohif.divider：简单的分隔线。

在当前仓库中，默认扩展的实际实现位于 extensions/default/src/getToolbarModule.tsx，它注册的uiTypes已扩充为：

ohif.toolButton、ohif.toolButtonList、ohif.row、ohif.toolBoxButtonGroup、ohif.toolBoxButton（新版按钮系列）；
ohif.layoutSelector（布局选择器）、ohif.progressDropdown（进度下拉）、ohif.Toolbar（整体工具栏容器）；
以及evaluate.cine（Cine 播放评估器，依据cineService.getState().isCineEnabled返回开关样式）。

值得注意的是，Toolbar Module 返回的每一项既可以是组件定义（defaultComponent），也可以是评估器定义（evaluate）。两者混排在同一个数组中，由 ToolbarService 统一登记。

二、注册按钮组件（Components）

Toolbar Module 返回一个objects数组。最简单的注册方式如下：

export default function getToolbarModule({ commandsManager, servicesManager }) { return [ { name: 'ohif.radioGroup', defaultComponent: ToolbarButton, clickHandler: () => {}, }, { name: 'ohif.splitButton', defaultComponent: ToolbarSplitButton, clickHandler: () => {}, }, { name: 'ohif.layoutSelector', defaultComponent: ToolbarLayoutSelector, clickHandler: (evt, clickedBtn, btnSectionName) => {}, }, { name: 'ohif.toggle', defaultComponent: ToolbarButton, clickHandler: () => {}, }, ]; }

自定义组件（Custom Components）

你完全可以创建自己的扩展，并注册全新的按钮外观（例如将 split tool 从垂直改为水平方向）。只需在扩展中加入getToolbarModule，并在返回对象中把defaultComponent指向自己的 React 组件：

import myToolComponent from './myToolComponent'; export default function getToolbarModule({ commandsManager, servicesManager }) { return [ { name: 'new-tool-type', defaultComponent: myToolComponent, clickHandler: () => {}, }, ]; }

组装自有组件时，可以直接复用@ohif/ui提供的IconButton、Icon、Tooltip、ToolbarButton等基础部件。组件被消费的具体流程是：在 ToolbarService.ts 的_mapButtonToDisplay中，服务会通过_getButtonUITypes()汇总所有扩展的toolbarModule注册项，然后根据按钮定义里的uiType找到对应的defaultComponent并挂到按钮上；若找不到组件会输出警告Neither button type nor a component found for button: ${id}。这一查找逻辑与文档描述一致：Toolbar Module 只负责"提供"，真正把按钮组装到工具栏上是在 Mode 中完成的。

三、评估器（Evaluators）：按钮状态的"裁判"

按钮可以配备评估器（evaluator）——它们是 ToolbarService 调用、用于评估按钮状态的函数，必须返回一个包含{ className }的对象，并可附带更多字段。评估器的核心价值在于：根据当前视口（viewport）动态决定按钮是否可用。

典型的场景包括：当 displaySet 不可重建（not reconstructable）时限制用户点击 MPR 相关按钮；或某些按钮与特定 toolGroup 绑定，在特定视口下应保持不激活。下面以 cornerstone 扩展中最常用的evaluate.cornerstoneTool为例（完整实现见 extensions/cornerstone/src/getToolbarModule.tsx）：

{ name: 'evaluate.cornerstoneTool', evaluate: ({ viewportId, button, toolNames, disabledText }) => { const toolGroup = toolGroupService.getToolGroupForViewport(viewportId); if (!toolGroup) { return; } const toolName = toolbarService.getToolNameForButton(button); if (!toolGroup || (!toolGroup.hasTool(toolName) && !toolNames)) { return getDisabledState(disabledText); // { disabled: true, disabledText } } const isPrimaryActive = toolNames ? toolNames.includes(toolGroup.getActivePrimaryMouseButtonTool()) : toolGroup.getActivePrimaryMouseButtonTool() === toolName; return { disabled: false, isActive: isPrimaryActive, }; }, },

该评估器的工作方式是：先通过toolGroupService.getToolGroupForViewport(viewportId)拿到视口对应的工具组，再通过toolbarService.getToolNameForButton(button)解析按钮要激活的工具名（优先读取命令commandOptions.toolName，回退到按钮 id，见 ToolbarService.ts 的getToolNameForButton），最后检查工具是否存在于工具组、以及是否是主鼠标键当前激活的工具。

3.1 评估器可返回的字段

评估器可以返回多种信息，ToolbarService 在刷新逻辑refreshToolbarState中会将评估结果合并进按钮 props：

字段	说明
`disabled`	布尔值，表示按钮是否应被禁用
`disabledText`	当`disabled`为`true`时显示的文字/提示
`visible`	布尔值，是否显示按钮；是基于自定义逻辑强制隐藏按钮的便捷手段
`isActive`	布尔值，按钮当前是否处于激活状态
`className`	添加到按钮组件上的自定义 CSS 类名

3.2 内置评估器清单

OHIF 与 cornerstone 扩展合计提供了以下内置评估器（前五项出自官方文档，evaluate.viewport.supported、evaluate.modality.supported等在 cornerstone 扩展源码中有完整实现）：

evaluate.cornerstoneTool：按钮随当前视口的 toolGroup 状态变化，例如工具不在工具组中时禁用；
evaluate.cornerstoneTool.toggle：面向具有开关行为的工具（如参考线、图像叠加层的显示/隐藏）。实现上通过_evaluateToggle检查工具模式是否为Disabled/Passive，并借助utils.getToggledClassName生成开关样式（源码位置）；
evaluate.cornerstone.synchronizer：依据视口的同步器（synchronizer）状态判断按钮是否处于"已同步"状态（源码位置）；
evaluate.viewportProperties.toggle：针对视口可切换属性（invert、flip、rotate 等），按钮外观随当前视口属性动态变化（源码位置）；
evaluate.mpr：MPR 专用评估器，需要检查 displaySet 是否可重建（当前仓库中以evaluate.displaySetIsReconstructable形式实现，见 extensions/cornerstone/src/getToolbarModule.tsx）；
evaluate.viewport.supported与evaluate.modality.supported：见下一节。

3.3 视口类型与模态（Modality）支持评估

工具栏系统现在采用更稳健的方式，基于视口类型与模态评估按钮状态。

视口类型支持（evaluate.viewport.supported）：禁用特定视口类型上的按钮。其实现会读取cornerstoneViewportService.getCornerstoneViewport(viewportId)的viewport.type，与unsupportedViewportTypes比对（源码位置）：

{ name: 'evaluate.viewport.supported', unsupportedViewportTypes: ['volume3d', 'video', 'sm'], }

模态支持（evaluate.modality.supported）：按模态控制按钮状态。实现会取视口内所有 displaySet 的Modality字段做包含/排除判断（源码位置）：

{ name: 'evaluate.modality.supported', supportedModalities: ['CT', 'MR'], // 仅在这些模态下启用 // 或者 unsupportedModalities: ['US'], // 在这些模态下禁用 }

注意：unsupportedModalities是"排除式"匹配（displaySet 中存在任一模态即禁用），supportedModalities是"包含式"匹配（存在任一支持的模态即启用）；两者可同时使用，默认禁用文案为'Buttons:Tool not available for this modality'。

3.4 组合评估器（Composing Evaluators）

一个按钮可以挂多个评估器，这在需要按多种条件联合判定时非常有用。例如防止 Cine 播放器出现在 3D 视口上：

evaluate: [ 'evaluate.cine', { name: 'evaluate.viewport.supported', unsupportedViewportTypes: ['volume3d'], }, ],

当evaluate是数组时，ToolbarService 的handleEvaluate会逐个解析每个条目（字符串按名字查找，对象则取出name并把其余字段作为选项混入评估参数），把所有评估结果用 reduce 合并成一个对象；只要有一个评估器返回disabled: true，最终按钮即为禁用态。

还可以组合出更复杂的评估器。tmtv 模式的RectangleROIStartEndThreshold工具使用的就是：

evaluate: [ 'evaluate.cornerstone.segmentation', // 必须把 disabledText 放在最后一个评估器，因为每个评估器的文本会被合并进最终结果 { name: 'evaluate.cornerstoneTool', disabledText: 'Select the PT Axial to enable this tool', }, ],

这里第一个评估器evaluate.cornerstone.segmentation确保已经创建了分割（segmentation），第二个evaluate.cornerstoneTool确保工具在当前视口可用。由于多个评估器的disabledText会合并进最终结果，必须把disabledText放在最后一个评估器上。

当多个按钮复用一个评估器但参数不同时，可以采用对象形式传入额外属性。例如分割剪刀类工具：

{ name: 'evaluate.cornerstone.segmentation', toolNames: ['CircleBrush', 'SphereBrush'], }

3.5 组评估器（Group Evaluators）

Split 按钮（如何定义见 ToolbarService 文档）可以配备组评估器（group evaluator），用于决定用户交互后哪个按钮应被提升到 primary 区。官方提供两个，也支持自定义：

evaluate.group.promoteToPrimaryIfCornerstoneToolNotActiveInTheList：检查 cornerstone 工具状态，若该工具未在按钮列表中激活，则把按钮提升到 primary 区；
evaluate.group.promoteToPrimary：忽略 cornerstone 工具状态，无条件把按钮提升到 primary 区。

若未指定组评估器，则不会有任何动作，按钮将停留在 secondary 区。

3.6 自定义评估器

你可以自由编写自己的评估器。文档给出的典型例子是设计"三态按钮"——例如视口叠加层（Overlay）的 "Show All / Show Some / Show None" 三种状态。实现方式是在自己的getToolbarModule中返回一个{ name, evaluate }对象，之后即可像内置评估器一样通过name在按钮定义中引用；在 ToolbarService 中，若按名字找不到评估函数，会抛出Evaluate function not found for name: ...错误，并提示可通过扩展的getToolbarModule注册。

四、在 Mode 中消费按钮：注册与 Section 组织

只提供组件是不够的，还需要把按钮加入 ToolbarService，并决定每个 Section 使用哪些按钮。下面是一个简化版的longitudinal（basic viewer）模式示例——通过ToolBarService.addButtons(toolbarButtons)添加按钮，toolbarButtons是toolDefinitions数组：

function modeFactory({ modeConfiguration }) { return { id: 'viewer', displayName: 'Basic Viewer', onModeEnter: ({ servicesManager, extensionManager }) => { const { toolBarService } = servicesManager.services; toolbarService.addButtons([...toolbarButtons, ...moreTools]); toolbarService.createButtonSection('primary', [ 'MeasurementTools', 'Zoom', 'info', 'WindowLevel', 'Pan', 'Capture', 'Layout', 'Crosshairs', 'MoreTools', ]); }, routes: [ { path: 'longitudinal', layoutTemplate: ({ location, servicesManager }) => { return { /* */ }; }, }, ], }; }

API 演进提示：当前仓库中addButtons与createButtonSection已标记为deprecated（会输出控制台警告），官方推荐使用register()与updateSection()替代（见 ToolbarService.ts 与 ToolbarService.ts）。新版register(buttons, replace)还支持buttonSection: true的快捷写法——当按钮 props 中buttonSection为布尔值true时，服务会自动把该属性替换为按钮自身的 id（源码位置）。

实际上，@ohif/extension-default的默认布局（extensions/default/src/ViewerLayout/index.tsx）在所有 Mode 中都会使用一个 Toolbar 组件来创建primarySection，这正是上面示例创建primarySection 的原因。布局同样可定制：你可以在自己的扩展中实现getLayoutTemplateModule模块并供 Mode 使用。默认情况下使用@ohif/extension-default.layoutTemplateModule.viewerLayout，它提供：

Header（左侧 Logo、中间工具栏、右侧用户菜单）；
左侧面板；
主视口网格区域；
右侧面板。

以当前仓库的 basic 模式为参考，其内部通过 modes/basic/src/modeCustomization.ts 中的registerModeToolbar把按钮列表注册进 toolbarService，并按toolbarSections配置逐个调用updateSection；按钮清单与 Section 配置本身来自 cornerstone 扩展的定制数据cornerstone.toolbarButtons/cornerstone.toolbarSections（见 modes/basic/src/index.tsx），具体按钮定义在 extensions/cornerstone/src/customizations/toolbarButtonsCustomization.ts。

五、替代工具栏 Section：`useToolbar`Hook 与`Toolbox`组件

除了主工具栏，你还可以在自定义 UI 组件（如面板）中引入一个"工具栏 Section 模板"，之后再往里面添加按钮。只需使用useToolbarHook 即可保证按钮被正确添加、正确响应交互、正确评估状态。该 Hook 暴露onInteraction函数和toolbarButtons数组，你可以按需定制 UI（完整实现见 platform/core/src/hooks/useToolbar.tsx）：

function myCustomPanel({ servicesManager }) { const { onInteraction, toolbarButtons } = useToolbar({ servicesManager, buttonSection: 'myCustomSectionName', }); // 把按钮映射到 UI return ( <div> {toolbarButtons.map((button, index) => { return ( <button key={index} onClick={() => onInteraction(button)}> {button.label} </button> ); })} </div> ); }

useToolbar内部会订阅TOOL_BAR_MODIFIED与TOOL_BAR_STATE_MODIFIED事件刷新按钮列表，并监听ACTIVE_VIEWPORT_ID_CHANGED、VIEWPORTS_READY、LAYOUT_CHANGED等视口网格事件，在活跃视口变化时调用toolbarService.refreshToolbarState({ viewportId })重估所有按钮；onInteraction则最终路由到toolbarService.recordInteraction（见 platform/core/src/hooks/useToolbar.tsx）。

OHIF 还提供了一个通用的Toolbox容器组件，用于承载一组工具栏工具。它配合useToolbarHook，通过 Context API 管理工具状态、处理用户交互并记忆选项。Toolbox集成非常简单，只需传入服务与配置参数（buttonSectionId、title）：

function MyApplication({ servicesManager, commandsManager }) { // 工具箱容器配置 const config = { servicesManager, commandsManager, buttonSectionId: 'customButtonSection', title: 'My Toolbox', }; return <Toolbox {...config} />; }

随后在 Mode 中即可向该 Section 注入工具：

onModeEnter: ({ servicesManager, extensionManager }) => { const { toolBarService } = servicesManager.services; toolbarService.addButtons([...toolbarButtons, ...moreTools]); toolbarService.createButtonSection('customButtonSection', [ 'MeasurementTools', 'Zoom', 'info', ]); },

5.1 典型场景：点击按钮弹出工具选项 Modal

另一个常见需求是点击按钮后弹出一个 Modal 展示工具选项。首先在 Mode 中定义按钮：

// Mode 中的 ToolbarButton { id: 'Others', uiType: 'ohif.radioGroup', props: { icon: 'info-action', label: 'Others', commands: 'showOthersModal', }, },

在 Mode factory 中把按钮加入 Section：

// 把 'Others' 按钮加入 primary 区 toolbarService.createButtonSection('primary', [ 'Others', // --------> 这里 ]); // 把 shapes 按钮加入 'other' 区 toolbarService.createButtonSection('other', ['Shapes']);

这里使用了showOthersModal命令，它定义在扩展的 commandsModule 中：

// 在扩展的 commandsModule 内 showOthersModal: () => { const { uiModalService } = servicesManager.services; uiModalService.show({ content: OthersModal, title: 'Others', customClassName: 'w-8', movable: true, contentProps: { onClose: uiModalService.hide, servicesManager, commandsManager, }, containerDimensions: 'h-[125px] w-[300px]', contentDimensions: 'h-[125px] w-[300px]', }); },

Modal 内容组件内部放置Toolbox（从@ohif/ui导入），并将buttonSectionId指向other：

// Others modal import { Toolbox } from '@ohif/ui'; function OthersModal({ servicesManager, commandsManager }) { return ( <div className="px-2"> <Toolbox buttonSectionId={'other'} commandsManager={commandsManager} servicesManager={servicesManager} title={'other'} useCollapsedPanel={false} ></Toolbox> </div> ); }

最终效果是：点击Others按钮后弹出一个内含工具箱的 Modal，且其状态会自动与 ToolbarService 同步（运行效果即前文第一张配图）。

六、Toolbox 带选项（Toolbox With Options）

工具箱中的按钮可以携带选项（options），这对需要调整参数的进阶工具非常有用——例如笔刷（brush）需要切换笔刷大小或 2D/3D 模式。

注意：带选项的 Toolbox 会在组件挂载（mount）时执行选项命令（commands），这有助于设置工具箱的初始状态。

目前支持三种选项类型。

6.1 Radio 选项（单选）

用于分割形状工具，让用户在三种裁剪模式间选择：

{ id: 'Shapes', uiType: 'ohif.radioGroup', props: { label: 'Shapes', evaluate: { name: 'evaluate.cornerstone.segmentation', toolNames: ['CircleScissor', 'SphereScissor', 'RectangleScissor'], }, icon: 'icon-tool-shape', options: [ { name: 'Shape', type: 'radio', value: 'CircleScissor', id: 'shape-mode', values: [ { value: 'CircleScissor', label: 'Circle' }, { value: 'SphereScissor', label: 'Sphere' }, { value: 'RectangleScissor', label: 'Rectangle' }, ], commands: 'setToolActiveToolbar', }, ], }, },

6.2 Range 选项（滑块）

用于笔刷半径调整：

{ id: 'Brush', icon: 'icon-tool-brush', label: 'Brush', evaluate: { name: 'evaluate.cornerstone.segmentation', toolNames: ['CircularBrush', 'SphereBrush'], disabledText: 'Create new segmentation to enable this tool.', }, options: [ { name: 'Radius (mm)', id: 'brush-radius', type: 'range', min: 0.5, max: 99.5, step: 0.5, value: 25, commands: { commandName: 'setBrushSize', commandOptions: { toolNames: ['CircularBrush', 'SphereBrush'] }, }, }, ], },

6.3 Custom 选项（自定义组件）

tmtv 模式的RectangleROIThreshold使用了该模式，通过字符串引用扩展注册的自定义选项组件：

{ id: 'RectangleROIStartEndThreshold', uiType: 'ohif.radioGroup', props: { icon: 'tool-create-threshold', label: 'Rectangle ROI Threshold', commands: setToolActiveToolbar, evaluate: { name: 'evaluate.cornerstoneTool', disabledText: 'Select the PT Axial to enable this tool', }, options: 'tmtv.RectangleROIThresholdOptions', }, },

注意：你有责任在扩展的getToolbarModule中提供tmtv.RectangleROIThresholdOptions这个选项组件定义。其解析逻辑在 ToolbarService 的handleEvaluate中：当options是字符串时，服务会到_getButtonUITypes()中按该名字查找defaultComponent并设置为optionComponent。选项变更时，服务会调用选项的commands并携带{ ...option, value, options, servicesManager, commandsManager }运行（见 ToolbarService.ts 的createEnhancedOptions）。

七、根据 Hanging Protocol 动态切换工具栏

如果你希望工具栏随挂片协议（hanging protocol）变化，可以订阅hangingProtocolService的PROTOCOL_CHANGED事件，在回调中重建按钮 Section：

const { unsubscribe } = hangingProtocolService.subscribe( hangingProtocolService.EVENTS.PROTOCOL_CHANGED, () => { toolbarService.createButtonSection('primary', [ 'MeasurementTools', 'Zoom', 'WindowLevel', ]); } );

这样当协议切换时，primary 区会立即按新配置重组。ToolbarService 还提供了updateSection（合并追加，不重复添加同 id 按钮）与clearButtonSection（清空 Section）等配套 API，可组合出更灵活的协议级工具栏策略（见 ToolbarService.ts 与 ToolbarService.ts）。

八、源码级补充：ToolbarService 的状态流转机制

最后从源码层面总结一下工具栏的状态流转闭环（核心代码均在 platform/core/src/services/ToolBarService/ToolbarService.ts）：

注册：register(buttons)/addButtons(buttons)将按钮定义写入state.buttons，并广播TOOL_BAR_MODIFIED事件；
组织：updateSection(key, buttons)/createButtonSection(key, buttons)将按钮 id 分组写入state.buttonSections；
交互：用户点击按钮 →recordInteraction(interaction, options)运行按钮的commands（通过commandsManager.run），随后触发refreshToolbarState({ viewportId, itemId })重估所有按钮（ToolbarService.ts）；
评估：refreshToolbarState遍历按钮，将evaluate（函数 / 字符串名 / 对象 / 数组）统一解析为函数执行，合并返回的disabled、disabledText、visible、isActive、className，并通过hideWhenDisabled（在evaluateProps或 props 层均可设置）决定隐藏逻辑（ToolbarService.ts）；
渲染：getButtonSection(sectionId)经_mapButtonToDisplay把按钮 id 映射为{ id, Component, componentProps }供useToolbar/Toolbox/ 主工具栏渲染。

这套机制保证了"一个按钮出现在多个 Section 中时状态完全同步"（得益于统一的评估系统），也解释了文档中的一条建议：不要忘记正确配置 toolGroups——按钮只是视觉界面，交互时执行命令，评估器则在交互后判定其状态，二者都以 toolGroup 的配置为前提。

OHIF v3 Toolbar 模块开发指南：组件注册、评估器（Evaluator）与工具箱（Toolbox）实战