面板
面板是查看器左右两侧的滑入式侧栏。本指南介绍内置面板、通用 Panel 外壳，以及添加、替换和查看面板的 API。
UI API
UI.addPanel(panel)
向左或右添加自定义面板。
/**
* @method UI.addPanel
* @param {Object<PanelProperties>} panel
* @param {string} panel.dataElement 唯一 id。
* @param {string} panel.location 'left' | 'right'
* @param {string | UI.renderCustomPanel} panel.render 预定义面板名或 () => HTMLElement
*/
UI.addPanel({
dataElement: 'myPanel',
location: 'right',
render: () => {
const el = document.createElement('div');
el.textContent = 'My panel';
return el;
},
});render 可以是预定义面板名（见 UI.Panels），也可以是返回 HTMLElement 的函数（通过通用 CustomElement 宿主渲染）。addPanel 接受 Panel 实例（调用 toObject()）或普通对象，然后追加到 store 的 genericPanels 列表。
UI.setPanels(panelList)
替换整个面板列表。
/**
* @method UI.setPanels
* @param {array} panelList UI 中使用的新面板列表。
*/
UI.setPanels([ /* PanelProperties[] */ ]);每个条目若是 Panel 实例则通过 Panel.toObject() 归一化。
UI.getPanels()
返回当前面板。
/**
* @method UI.getPanels
* @return {Array<UI.Components.Panel | UI.Components.TabPanel>}
*/
const panels = UI.getPanels();返回深拷贝条目，包装为 UI.Components.Panel 实例。
UI.Components.Panel 类
| 成员 | 签名 | 用途 |
|---|---|---|
dataElement | string（读/写） | 面板的 data-element；setter 同步 store。 |
render | string|function（读/写） | 渲染规格；setter 同步 store。 |
location | 'left'|'right'（读/写） | 侧；非法值 → 'right'；setter 同步 store。 |
setLocation(location) | (location: string) => void | 显式设置侧。 |
delete() | () => void | 从 store 移除面板。 |
每次修改会调用 store 的 resetPanels() 再 setGenericPanels(panels)。
内置面板
默认 genericPanels 列表（9 个）：
dataElement | 位置 | 用途 |
|---|---|---|
leftPanel | 左（全高） | 带标签侧栏：缩略图、书签、批注、图层、签名、搜索。 |
rightPanel | 右 | 表单字段属性（General / Appearance / Preferences 标签）。 |
stylePanel | 右 | 批注与测量属性。 |
pageModePanel | 右 | 页面显示模式（单/双页、滚动方向）。 |
stampPanel | 右 | 印章选择器（Standard / Dynamic / Custom）。 |
linkPanel | 右 | 链接批注属性。 |
contentEditorPanel | 右 | 内容编辑器选择属性。 |
colorSeparationPanel | 右 | 分色视图。 |
redactionPanel | 右 | 密文标记属性。 |
左面板标签
通过 UI.setActiveElementTab('leftPanel', tab) 切换：
| 标签常量 | 内容 |
|---|---|
ThumbnailsButton（THUMBS） | 页面缩略图——.thumbnail-view 挂载目标传给 core.initializeViewer。 |
OutlinesButton（OUTLINE） | 书签/目录树。 |
AnnotationButton（ANNOTATION_TAB） | 批注列表（头部+内容）。 |
LayersButton（LAYER） | PDF 图层可见性。 |
SignatureButton（SIGNATURE_TAB） | 签名列表。 |
SearchButton（SEARCH_TAB） | 查找栏。 |
右面板标签
UI.setActiveElementTab('rightPanel', tab)：
| 标签常量 | 内容 |
|---|---|
General | 字段名、按钮文本、可见性、必填/指示符标志。 |
Appearance | 填充色、字体颜色/族/样式/大小（签名字段隐藏）。 |
Preference | 对齐、默认值、多行、按钮样式、选项（签名字段隐藏）。 |
通用 Panel 外壳
所有面板通过 components/Panel/Panel.vue 渲染——一个固定定位的滑入容器（.left / .right、.mobile、.full、.closed 使用 translateX/translateY）。它从 useViewer.isElementOpen / isElementDisabled(dataElement) 读取 isOpen / isDisabled，预留 panelSpace（某侧有打开面板时为 260px）以便 DocumentContainer 收缩，桌面端宽 260px，移动端 100vw。
挂载策略
根 App/index.vue 通过 v-for 渲染 useViewer.getGenericPanels 的每个面板，包装在 Panel 外壳中。内部组件以三种方式解析：
- 即时加载（
NoLazyComponents）：stylePanel、leftPanel、rightPanel、linkPanel、colorSeparationPanel、contentEditorPanel、redactionPanel。 - 懒加载（
LazyLoadComponents，defineAsyncComponent）：pageModePanel、stampPanel和CustomModal。 <CustomElement>：用于任何用户render函数（自定义面板）。
即时/懒加载名定义在 constants/panel.js（noLazyPanelNames / panelNames）。
示例
添加并打开自定义左面板
UI.addPanel({
dataElement: 'commentsPanel',
location: 'left',
render: () => {
const el = document.createElement('div');
el.className = 'comments';
el.innerHTML = '<h3>Comments</h3><ul><li>None yet</li></ul>';
return el;
},
});
UI.openElement('commentsPanel');将面板移到另一侧
const [panel] = UI.getPanels().filter(p => p.dataElement === 'myPanel');
panel.setLocation('left');移除面板
const [panel] = UI.getPanels().filter(p => p.dataElement === 'myPanel');
panel.delete();替换所有面板
UI.setPanels([
{ dataElement: 'leftPanel', location: 'left', render: 'leftPanel' },
{ dataElement: 'myPanel', location: 'right', render: () => myEl },
]);