头部与工具栏

头部是查看器的顶部栏。它包含主工具栏（default 分组）、工具栏分组切换器（Ribbons）、二级上下文工具栏（ToolsHeader），以及若干模式专属栏（表单面板、签名校验栏、安全应用栏）。本指南说明其结构与定制 API。

UI API

UI.setHeaderItems(headerCallback)

通过在回调中修改 Header 辅助对象来定制头部/工具栏分组。

/**
 * @method UI.setHeaderItems
 * @param {UI.headerCallback} headerCallback 对 {UI.Header} 实例进行操作的回调。
 */
UI.setHeaderItems(header => {
  header.getHeader('default')         // 选择要编辑的分组
    .push({ type: 'actionButton', dataElement: 'myBtn', /* … */ });
});

回调接收一个 UI.Header 实例——所有头部数组的可变工作副本。回调返回后，每个被修改的分组写回 viewer store，触发工具栏的响应式重新渲染。

UI.Header — 链式 DSL

方法	签名	用途
get(dataElement)	(dataElement: string) => Header	按 data-element 选中按钮，供后续 insertBefore / insertAfter / delete 使用。
getItems()	() => Array<object>	返回当前分组的项列表。
getHeader(group)	(group: string) => Header	切换正在编辑的活动分组。
insertBefore(item)	(item: object) => Header	在选中按钮前插入。
insertAfter(item)	(item: object) => Header	在选中按钮后插入。
delete(id?)	(id?: number|string|Array) => Header	按索引、data-element、当前选中按钮（无参）或数组删除。
shift()	() => Header	移除第一个按钮。
unshift(...items)	(...items) => Header	在头部添加按钮。
push(...items)	(...items) => Header	在末尾添加按钮。
pop()	() => Header	移除最后一个按钮。
update(items)	(items: Array<object>) => Header	替换整个分组的项列表。

UI.setToolbarGroup(group)

切换当前工具栏分组。

/**
 * @method UI.setToolbarGroup
 * @param {string} groupDataElement 取值之一：
 *   toolbarGroup-View、toolbarGroup-Annotation、toolbarGroup-Form、
 *   toolbarGroup-Measurement、toolbarGroup-Sign、toolbarGroup-Security、
 *   toolbarGroup-Redaction、toolbarGroup-Compare、toolbarGroup-Editor、
 *   toolbarGroup-Document、toolbarGroup-Separation
 */
UI.setToolbarGroup('toolbarGroup-Annotation');

内部会设置活动工具栏分组、活动头部分组和活动工具模式。旧版 toolMenu-* 名称会被接受并映射为 toolbarGroup-*，同时发出弃用警告。

UI.setActiveToolMode 和 UI.setActiceToolMode（拼写错误）是 setToolbarGroup 的弃用别名，会发出 [ComPDF] "..." is deprecated... 警告。

工具栏结构

头部分组

viewer store 中的 headers 状态是分组名 → 项数组的映射。主要分组：

分组	内容
default	主顶部头部：左面板切换、全屏、手形工具、缩放覆盖、裁剪页面、Ribbons（分组切换器）、搜索等。
small-mobile-more-buttons	小移动屏幕上的溢出按钮。
toolbarGroup-View	视图工具。
toolbarGroup-Annotation	批注工具。
toolbarGroup-Form	表单字段创建工具。
toolbarGroup-Measurement	测量工具。
toolbarGroup-Sign	签名工具。
toolbarGroup-Security	安全/加密工具。
toolbarGroup-Redaction	密文与移除工具。
toolbarGroup-Compare	文档对比工具。
toolbarGroup-Editor	内容编辑工具。
toolbarGroup-Document	页面编辑工具。
toolbarGroup-Separation	分色工具。

相关状态：rightHeaders（打开文件、搜索、页面模式、下载、扁平化、打印、主题、设置）、toolItems（安全/密文子项）、documentEditorHeaders。

项类型

每个项描述符含 type 字段，由 HeaderItems.vue 渲染器分派：

type	渲染为
toolButton	<ToolButton> — 激活一个工具。
actionButton	<ActionButton> — 执行 onClick。
toggleElementButton	<ToggleElementButton> — 打开/关闭元素。
statefulButton	<StatefulButton> — 带开/关状态的按钮。
customElement	在 componentMap 中查找的组件（Ribbons、ZoomOverlay、LeftPanelButton、Dropdown、SignatureToolBar、SecurityToolbar、RedactionToolbar、ComparedToolbar、FillForm、SelectToolsButton），或用于用户 render 函数的通用 <CustomElement>。
divider / spacer	空的 flex <div> 分隔符。

二级栏

• Ribbons（components/Ribbons/）——渲染在 default 头部内的工具栏分组切换器。列出已启用的 toolbarGroup-* data-element，标记活动分组，溢出折叠为 "···" 菜单。
• ToolsHeader（components/ToolsHeader/）——主头部下方的二级工具栏行。通过 getToolbarGroupItems(currentToolbarGroup) 渲染活动 toolbarGroup-* 的项。视图/文档/分色/未完成对比模式下隐藏。
• FormBoard、SignatureVerifyBar、SecurityApplyBar ——由 Header.vue 按模式条件渲染的专属栏。

setHeaderItems 内部原理

apis/setHeaderItems.js 通过 Object.create(Header).initialize(store, headerGroups) 构建 Header 对象——headers、rightHeaders、tools、toolItems 和 documentEditorHeaders 的工作副本。用户回调修改此副本。回调返回后，API 将每个工作副本数组写回 store.headers[group]，触发 HeaderItems.vue 的响应式重渲染。

HeaderItems.vue 计算 visibleItems（按移动/PC 标志和 isElementDisabled 隐藏项）并应用响应式隐藏类（hide-in-desktop、hide-in-tablet、hide-in-mobile、hide-in-small-mobile、always-hide）。挂载时连接 createHeaderItemsListener，使工具栏按钮与选择/工具状态保持同步（无相关选择时禁用属性面板按钮）。

示例

按 data-element 移除按钮

UI.setHeaderItems(header => {
  header.getHeader('default').delete('downloadButton');
});

在已有按钮前插入自定义按钮

UI.setHeaderItems(header => {
  header.getHeader('default')
    .get('printButton')
    .insertBefore({
      type: 'actionButton',
      dataElement: 'myAction',
      label: 'My Action',
      onClick: () => console.log('clicked'),
    });
});

替换整个分组的项

UI.setHeaderItems(header => {
  header.getHeader('toolbarGroup-View').update([
    { type: 'toolButton', dataElement: 'handToolButton', /* … */ },
    { type: 'toolButton', dataElement: 'zoomOverlayButton', /* … */ },
  ]);
});

添加右侧头部按钮

右侧按钮位于 rightHeaders 数组。可同样在选择后 push；注意 getHeader 接受分组键——右侧头部使用对应分组，或在 store 暴露时通过 store 操作 rightHeaders。

相关

• 显示/隐藏元素 — 用 disableElements 隐藏按钮而无需重构工具栏。
• 组件 — 内部 Header / HeaderItems 组件树。
• API 参考 — 完整的 setHeaderItems / setToolbarGroup 签名。