组件

UI 是以 App/index.vue 为根的 Vue 3 组件树。本指南映射组件目录结构与关键区域，便于 fork 或扩展 UI 时定位。

挂载链

main.js  →  createApp(App = components/Suspenser.vue)
         →  setupStore(app) + i18n(app)
         →  mount('#app')

Suspenser.vue  →  <Suspense> fallback="loading…" → <App/>
App/index.vue  →  实际的查看器根

Suspenser.vue 将 App/index.vue 包裹在 <Suspense> 中，因为 App 使用顶层 await（i18nextPromise、loadConfig）。

根 App/index.vue

渲染外壳并连接引擎：

• 在 #outerContainer 上应用深色主题类。
• 渲染 <Header />（禁用 header 时隐藏），然后是包含文档区 + 侧面板 + 覆盖层的 .content 行。
• 挂载 PDF 界面：<DocumentContainer />、<CompareDocumentContainer />，以及条件渲染的 <DocumentEditorContainer />（仅在 document 工具模式）。
• 通过 v-for 渲染 useViewer.getGenericPanels 的每个面板，包裹在通用 <Panel> 外壳中。内部组件通过 NoLazyComponents（即时）、LazyLoadComponents（懒）或 <CustomElement>（用户 render）解析。
• 挂载全局遮罩：下载加载/错误遮罩、<SignCreatePanel>、<SignCreateDialog>、<CustomStamp>。
• setup 时：initDocument、defineWebViewerInstanceUIAPIs、加载 hash 参数（css、theme、header）、向 window.parent 发送 viewerLoaded。定义 window.instance.changeFile。

关键组件目录

目录	用途
App/	根应用组件。
Header/	顶部栏（Header.vue）。
HeaderItems/	通用工具栏渲染器（HeaderItems.vue）+ HeaderItemsListener.js 同步中心。
Ribbons/	工具栏分组切换器。
ToolsHeader/	二级上下文工具栏行。
FormBoard/	表单字段创建面板。
DocumentContainer/	PDF 渲染界面 + 文档级覆盖层（最大组件，约 31k）。
CompareDocumentContainer/	对比模式查看器（注册实例 2 和 3）。
DocumentEditorContainer/	页面编辑器（插入/删除/旋转/提取/合并/移动/裁剪）。
LeftPanel/	带标签左栏（缩略图、书签、批注、图层、签名、搜索）。
RightPanel/	表单字段属性（General/Appearance/Preferences）。
Panel/	通用滑入面板外壳。
StylePanel/	批注与测量属性。
StampPanel/	印章选择器。
LinkPanel/、ContentEditorPanel/、RedactionPanel/、ColorSeparationPanel/、RightPanelPageMode/	其他内置面板。
Popups/	AnnotationPopup、TextPopup、FreetextPopup、CropPagePopup、ContentEditorPopup。
Dialogs/	模态对话框（页面操作、签名、对比、测量、印章、密文、设置）。
Signatures/	SignCreatePanel、SignCreateDialog、DigitalSignCreatePanel、DigitalKeyboardCreatePanel。
SignatureContainer/	左面板签名标签。
Icon/	约 270 个 SVG-as-Vue 图标组件，按名字字符串引用。
Button/、CustomButton/、Dropdown/、CustomElement/	HeaderItems 与 Popups 使用的基础组件。
Message/	全局 toast（window.$message）。
AnnotationContainer/、Outlines/、LayerContainer/、SearchContainer/	左面板标签内容。
MeasurementBoard/、MeasureCurveGuide/、MeasurePanel/	测量工具。
Password/	密码输入/设置对话框。
SecurityToolbar/、SignatureToolBar/、ComparedToolbar/、FillForm/	模式专属工具栏。
LazyLoadWrapper/	异步组件 + Suspense 包装器及面板注册表。
CustomModal/、ModalContainer/	UI.addCustomModal 机制。
PageNavOverlay/、ZoomOverlay/	浮动覆盖层。

Header / HeaderItems

Header.vue 渲染 <HeaderItems :items="useViewer.getActiveHeaderItems" />（activeHeaderGroup 对应的数组）。HeaderItems.vue 按 item.type 分派（toolButton、toggleElementButton、actionButton、statefulButton、customElement、spacer、divider），计算 visibleItems（移动/PC + isElementDisabled）并应用响应式隐藏类。HeaderItemsListener.js 使工具栏按钮与选择/工具状态保持同步。

DocumentContainer

.document-container 根据 panelSpace 和 topSpace 调整尺寸。内部 .document div 是 PDF 渲染界面，连接了 click/touch/mousedown/dblclick/contextmenu 处理器，分派到 core.eventBus()。initViewer() 调用 core.initializeViewer({ container, viewer, thumbnailView, outlineView, findbarView, toggleButton }) 并注册引擎事件监听器。它还托管全部五个 Popups 和大多数文档级对话框。

Popups

五个浮动、位置计算的弹出菜单（通过 helpers/getPopupPosition），由 useViewer.getPopupItems(<key>) 驱动并按 isElementDisabled 过滤。详见 弹出菜单。

图标库

components/Icon/ 含约 270 个单一用途的 SVG-as-Vue 渲染函数图标组件，按名字字符串（如 icon: 'Pantool'）在头部项描述符和弹出项中引用，而非在调用处直接导入。

组件层的定制钩子

• 工具栏：UI.setHeaderItems(cb) 修改 store 中的 headers；HeaderItems.vue 重新渲染。
• 面板：UI.addPanel 追加到 genericPanels；根 App 通过 Panel.vue + <CustomElement> 渲染。
• 弹出菜单：UI.annotationPopup / textPopup / contentEditorPopup / cropPagePopup 修改弹出项数组。
• 弹窗：UI.addCustomModal 追加到 customModals；CustomModal + ModalContainer 渲染。
• 元素状态：openElement / closeElement / disableElements 通过 store 的 activeElements / disabledElements 映射驱动可见性。

相关

• 头部与工具栏
• 面板
• 状态管理