UI 定制

ComPDFKit WebViewer UI 完全可定制。本页是常见定制任务的枢纽，每个链接的指南都包含 API 签名和示例的深入说明。

查看器初始化后，公共定制接口位于 instance.UI：

const { UI } = window.instance;

定制一览

任务	API	指南
添加/移除/重排工具栏按钮	UI.setHeaderItems(callback)	头部与工具栏
切换当前工具栏分组	UI.setToolbarGroup(group)	头部与工具栏
添加自定义左/右面板	UI.addPanel(panel)	面板
替换所有面板	UI.setPanels(panels)	面板
打开/关闭面板或对话框	UI.openElement / UI.closeElement	显示/隐藏元素
隐藏/显示按钮（从 DOM 卸载）	UI.disableElements / UI.enableElements	显示/隐藏元素
切换主题	UI.setTheme('dark')	主题与样式
注入自定义 CSS	UI.setCustomStyle(css)	主题与样式
切换语言	UI.setLanguage('zh-CN')	本地化
添加语言	UI.addLanguage(lang)	本地化
注册自定义弹窗	UI.addCustomModal(options)	自定义弹窗
定制右键菜单	UI.annotationPopup、UI.textPopup 等	弹出菜单
激活工具	UI.setActiveTool(dataElement)	工具
注册自定义工具	UI.registerTool(tool, options)	工具

元素模型

UI 中几乎每个可见部件——面板、对话框、工具栏按钮——都由一个 data-element 字符串标识。这些标识符集中定义在 packages/webview/src/constants/dataElements.js，并作为键贯穿 Pinia store（activeElements、disabledElements、activeElementsTab）。

这意味着有三类 API 控制可见性：

• 打开/关闭（openElement、closeElement）——切换元素当前是否显示（例如打开左面板）。
• 启用/禁用（enableElements、disableElements）——将元素从 DOM 中挂载或完全卸载。禁用工具栏按钮会移除它，但不会禁用底层功能。
• 活动标签页（setActiveElementTab）——切换带标签页元素内的活动子标签（例如显示左面板的哪个标签）。

详见 显示/隐藏元素。

工具栏模型

工具栏在 viewer store 的 headers 状态中声明式定义——一个 工具栏分组 → 项数组的映射。分组包括 default（主顶部栏）以及 toolbarGroup-View、toolbarGroup-Annotation、toolbarGroup-Form、toolbarGroup-Measurement、toolbarGroup-Sign、toolbarGroup-Security、toolbarGroup-Redaction、toolbarGroup-Compare、toolbarGroup-Editor、toolbarGroup-Document 和 toolbarGroup-Separation。

每一项是一个描述符，含 type（toolButton、actionButton、toggleElementButton、statefulButton、customElement、divider、spacer）、dataElement、icon 和 onClick(viewerStore, documentStore) 处理函数。UI.setHeaderItems(callback) 交给你一个可变的 Header 对象，提供链式 DSL（get、getHeader、insertBefore、insertAfter、delete、push、pop、unshift、shift、update）来修改这些数组。

详见 头部与工具栏。

面板模型

面板通过通用的 Panel.vue 外壳渲染，并在 viewer store 的 genericPanels 列表中声明。默认集合包括 leftPanel、rightPanel、stylePanel、pageModePanel、stampPanel、linkPanel、contentEditorPanel、colorSeparationPanel 和 redactionPanel。通过 UI.addPanel 添加的自定义面板通过相同外壳渲染，其 render 函数返回一个 HTMLElement。

详见 面板。

常见配方

隐藏打印和下载按钮

UI.disableElements(['printButton', 'downloadButton']);

打开左面板并切换到缩略图标签

UI.openElement('leftPanel');
UI.setActiveElementTab('leftPanel', 'ThumbnailsButton'); // THUMBS 标签

添加自定义工具栏按钮

UI.setHeaderItems(header => {
  header.getHeader('default').push({
    type: 'actionButton',
    dataElement: 'my-export-btn',
    label: 'Export',
    onClick: () => { /* … */ },
  });
});

切换到深色主题和中文

UI.setTheme('dark');
UI.setLanguage('zh-CN');

添加自定义右侧面板

UI.addPanel({
  dataElement: 'myPanel',
  location: 'right',
  render: () => {
    const el = document.createElement('div');
    el.textContent = 'Hello from my panel';
    return el;
  },
});
UI.openElement('myPanel');

高级定制

由于完整 UI 源码开源，你可以超越运行时 API：fork 仓库并直接修改组件、store 或工具栏定义。组件 和 状态管理 指南描述了你会接触到的内部结构。

下一步

• 头部与工具栏
• 面板
• 显示/隐藏元素
• 主题与样式
• 本地化