Skip to content

PDF 生成模板编辑器

开源可视化 PDF 生成引擎,支持自定义模板,并提供面向开发者的 API,灵活构建文档生成流程。

查看 GitHub

Header 与工具栏 ​

Header 和工具栏由模块化组件构建。本指南介绍它们的结构以及修改它们的 API。

UI API ​

UI.getModularHeader(dataElement) ​

返回 Header 对象。可以用 getItems() 读取其中的项,用 setItems(items) 替换。

javascript
/**
 * @method UI.getModularHeader
 * @param {string} dataElement Header,例如 'default-top-header' 或 'tools-header'。
 * @returns {UI.Components.ModularHeader}
 */
const header = UI.getModularHeader('default-top-header');
console.log(header.getItems().map(item => item.dataElement));

Header 对象还提供 getGroupedItems()、setGap(gap)、setJustifyContent(value)、setMaxWidth(width)、setMaxHeight(height) 和 setStyle(style)。UI.getModularHeaderList() 返回所有 Header。

Header 与组件 ​

API用途
UI.getModularHeader(id) / UI.getModularHeaderList()获取一个 / 全部 Header。
UI.addModularHeaders(headers)添加用 UI.Components.ModularHeader(或 TopHeader、BottomHeader、LeftHeader、RightHeader)创建的 Header。
UI.setModularHeaders(headers)替换全部 Header。
UI.getGroupedItems(id)获取工具分组组件,用 setItems(items) 修改。
UI.getRibbonGroup(id)获取功能区组,用 setItems(items) 修改。
UI.exportModularComponents() / UI.importModularComponents(data, functionMap)以数据形式导出 / 导入整个模块化 UI。

UI.setToolbarGroup(group) ​

切换当前功能区(选中的功能区项,以及 tools-header 中显示的工具)。

javascript
/**
 * @method UI.setToolbarGroup
 * @param {string} group UI.ToolbarGroup 中的值,例如 'toolbarGroup-Annotate'。
 */
UI.setToolbarGroup('toolbarGroup-Annotate');

有效的功能区:toolbarGroup-View、toolbarGroup-Annotate、toolbarGroup-Forms、toolbarGroup-Measure、toolbarGroup-FillAndSign、toolbarGroup-Security、toolbarGroup-Redact、toolbarGroup-Compare、toolbarGroup-EditText、toolbarGroup-Document、toolbarGroup-Separation,以及自定义功能区 toolbarGroup-Shapes、toolbarGroup-Insert 和 toolbarGroup-Edit。功能区变化时触发 UI.Events.TOOLBAR_GROUP_CHANGED。

工具栏结构 ​

Header内容
default-top-headerleftPanelButton、fullscreenButton、selectToolsButton、panToolButton、zoom-container、snippingToolButton、textSelectToolButton、功能区组 default-ribbon-group、searchPanelToggle,以及 menuButton(打开 MainMenuFlyout)。
tools-header当前功能区的工具分组。
page-editor-header页面编辑器中显示的 Header(取消、保存、另存为)。
compare-header文档对比中显示的 Header。

功能区项与工具分组 ​

default-ribbon-group 中的每个功能区项指定一个功能区以及它显示的工具分组:

功能区项工具分组
toolbarGroup-View—
toolbarGroup-AnnotateannotateGroupedItems
toolbarGroup-FormsformsGroupedItems
toolbarGroup-MeasuremeasureGroupedItems
toolbarGroup-FillAndSignfillAndSignGroupedItems
toolbarGroup-SecuritysecurityGroupedItems
toolbarGroup-RedactredactionGroupedItems
toolbarGroup-Compare—
toolbarGroup-EditTexteditTextGroupedItems
toolbarGroup-Document—
toolbarGroup-Separation—

功能区放不下时,放不下的项会收进“···”菜单。

项的类型 ​

项通过 instance.UI.Components 中的类创建:

类type渲染为
CustomButtoncustomButton执行 onClick 的按钮。
ToolButtontoolButton激活工具 toolName 的按钮。
ToggleElementButtontoggleButton打开/关闭 toggleElement 的按钮。
StatefulButtonstatefulButton有多个状态的按钮。
PresetButtonpresetButton内置按钮(UI.PRESET_BUTTON_TYPES),例如 downloadButton 或 printButton。
GroupedItemsgroupedItems一组项。
RibbonGroup / RibbonItemribbonGroup / ribbonItem功能区切换条及其项。
Flyout / MainMenuflyout下拉菜单。
Zoom、PageControls、ViewControls、Labelzoom、pageControls、viewControls、label内置控件和文字标签。
CustomElementcustomElementrender() 返回的任意元素。
Dividerdivider竖向分隔线。

每个项都可以设置 hidden:true 表示始终隐藏,屏幕尺寸数组(desktop、tablet、mobile、small-mobile)表示只在这些尺寸下隐藏。grow: 1 的空 GroupedItems 可作为间隔器,把后面的项推到另一侧。

各类项的属性参见自定义导航栏。

setItems 的内部工作方式 ​

Header、工具分组、功能区组及其项都以普通数据的形式保存在 viewer store 中,以 dataElement 为键。setItems(items) 按 dataElement 保存每个项(替换 dataElement 相同的项),并把 dataElement 列表写回 Header 或分组。Header 组件根据 store 重新渲染。工具分组只在处于激活状态或 alwaysVisible 为 true 时渲染。

示例 ​

按 data-element 删除按钮 ​

javascript
const header = UI.getModularHeader('default-top-header');
header.setItems(header.getItems().filter(item => item.dataElement !== 'snippingToolButton'));

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

javascript
const header = UI.getModularHeader('default-top-header');
const items = header.getItems();
const index = items.findIndex(item => item.dataElement === 'searchPanelToggle');
items.splice(index, 0, new UI.Components.CustomButton({
  dataElement: 'myAction',
  label: '我的操作',
  onClick: () => console.log('clicked'),
}));
header.setItems(items);

替换整个功能区的项 ​

javascript
const { Components } = UI;
UI.getGroupedItems('annotateGroupedItems').setItems([
  new Components.ToolButton({ dataElement: 'highlightToolButton', toolName: 'AnnotationCreateTextHighlight' }),
  new Components.ToolButton({ dataElement: 'rectangleToolButton', toolName: 'AnnotationCreateRectangle' }),
]);

添加自定义功能区 ​

javascript
const { Components } = UI;
const myTools = new Components.GroupedItems({
  dataElement: 'myGroupedItems',
  items: [
    new Components.ToolButton({ dataElement: 'myRectangleButton', toolName: 'AnnotationCreateRectangle', img: 'RectangleTool' }),
  ],
});
const toolsHeader = UI.getModularHeader('tools-header');
toolsHeader.setItems([...toolsHeader.getItems(), myTools]);

const ribbonGroup = UI.getRibbonGroup('default-ribbon-group');
ribbonGroup.setItems([
  ...ribbonGroup.items,
  new Components.RibbonItem({
    dataElement: 'toolbarGroup-Shapes',
    label: '形状',
    toolbarGroup: 'toolbarGroup-Shapes',
    groupedItems: ['myGroupedItems'],
  }),
]);
UI.setToolbarGroup('toolbarGroup-Shapes');

向主菜单添加一项 ​

javascript
const mainMenu = UI.Flyouts.getFlyout('MainMenuFlyout');
mainMenu.setItems([
  ...mainMenu.items,
  { dataElement: 'aboutButton', label: '关于', onClick: () => alert('ComPDFKit WebViewer') },
]);

相关 ​