辅助函数、Hooks 与常量
本指南介绍支撑 UI 层的工具模块（helpers/）、Vue 组合式函数（hooks/）和注册表（constants/）。
辅助函数 — src/helpers/
| 文件 | 用途 |
|---|---|
device.js | 设备/浏览器检测（详见下文）。 |
hotkeysManager.js | 极简键盘快捷键管理器：register(combo, handler)、unregister(combo)、initialize()、destroy()。尚未接入应用。 |
loadDocument.js | core.loadDocument(src, options, docNum) 的便捷封装，将引擎的 progress 回调连接到 useDocument.setLoadingProgress。可直接使用的辅助函数（DocumentContainer.vue 中的实际加载路径直接调用 core.loadDocument）。 |
initDocument.js | 实际启动：从 lib/webview.min.js 构造 new ComPDFKitViewer(options)，再 core.setDocumentViewer(1, documentViewer)。 |
setupI18n.js | i18next 初始化参考（声明 Languages[] 目录 + languageRules）。 |
getHashParameters.js | 将 window.location.hash 解析为键/值对象（含布尔类型强转）。 |
getPopupPosition.js | 计算批注弹出菜单的屏幕坐标。 |
loadScript.js | loadScript(src, warning) —— 注入 <script> 到 <head> 的 Promise 包装。还导出 loadConfig(initOptions)（iframe↔父窗口配置握手）。 |
renderStampPreview.js | 跟随鼠标显示印章图片的浮动 .stamp-preview div。 |
utils.js | uploadFile(extension)、hslToRgb、convertColor、areColorsSimilar(c1, c2, threshold=10)。 |
annotationPermissions.js | canCopyAnnotations({ isReadOnly, isUserAdmin, currentAuthor, annotations })。 |
device.js
模块加载时从 navigator.userAgent 和 window.innerWidth 计算一次的布尔值/函数：
- 布局断点：
isDesktop()（> 900）、isTabletOrMobile()（<= 900）、isMobile/isMobileSize()（< 640）。 - 系统：
isMac、isWindows、isIOS（含 iOS 13 MacIntel+touch）、isAndroid、isHarmonyOSMobile、isiPad。 - 移动端聚合：
isMobileDevice（iOS || Android || HarmonyOS || webOS/BlackBerry/IEMobile/Opera Mini）和isMobileDeviceFunc()。 - 浏览器：
isChrome、isSafari、isChromeOniOS、isFirefoxOniOS、isFirefox、isIEEdge、isIEEdgeChromium、isIE11、isIE、isIEEdgeLegacy。
device.js 被约 27 个组件/store 引用；isMobileDevice / isiPad 驱动 setActiveToolMode / setToolbarGroup 的移动端守卫。
getPopupPosition.js
getAnnotationPopupPositionBasedOn(rect, pageNumber, popup, documentViewerKey=1, position='right') → { left, top }。流程：通过 core.pageToWindow 将页面空间 rect 角点转为窗口坐标；读取 popup.getBoundingClientRect()；夹取 left（居中或右对齐，BOUNDARY_PADDING=4）和 top（优先批注下方 annotBottom + ANNOTATION_PADDING，回退到上方，再到空间更多的一侧）。
Hooks — src/hooks/
| 文件 | 状态 | 用途 |
|---|---|---|
useSearch.js | 功能完整、自包含 | 返回响应式搜索状态（searchQuery、searchResults、currentIndex、searching、currentResult）以及 search()、setActiveResult()、clear() 方法，委托给 core.search / core.setActiveSearchResult / core.clearSearchResults。不触碰全局 document store，因此不会与 store 驱动的搜索面板冲突。 |
useOnAnnotationPopupOpen.js | 功能正常，无消费者 | 返回 { selectedAnnotation } ref；注册 annotationSelected / annotationDeselected，并通过 onScopeDispose 移除，使监听器在所属作用域销毁时清理。 |
两个 hook 当前均为孤立（grep 未发现消费者）。可直接使用；搜索也可选择基于 store 的方式。
常量 — src/constants/
dataElements.js
集中化的 UPPER_SNAKE_CASE → camelCase/kebab-case 映射，包含每个 dataElement 标识符——是 store 的 activeElements / disabledElements / activeElementsTab / headers 键的唯一真实来源。分节：工具栏/头部按钮、批注工具、弹出操作、裁剪弹出、密文、表单工具、测量工具、内容编辑、对比、文档操作、面板、对话框、仅可禁用外壳，以及标签常量（ThumbnailsButton、OutlinesButton、AnnotationButton、LayersButton、SignatureButton、SearchButton、General、Appearance、Preference、Standard、Dynamic、Custom、Keyboard、Trackpad 等）。
toolNames.js
三个导出：
ToolNames—— 每个工具名的UPPER_SNAKE → camelCase映射（视图、批注、表单、测量、内容编辑、签名、安全）。DataElementToToolName—— 从DataElements.*_BUTTON到ToolNames.*的反向映射。map——{ [toolName]: { tool, toolName? } }查找表，供document.js#setToolState使用。register(tool)—— 向map添加自定义工具。
panel.js
panelNames——{ pageModePanel, stampPanel }（懒渲染面板）。noLazyPanelNames——{ stylePanel, leftPanel, rightPanel, linkPanel, colorSeparationPanel, contentEditorPanel, redactionPanel }（即时渲染面板）。
API 辅助 — src/api_helpers/
| 文件 | 用途 |
|---|---|
createEncapsulatedStore.js | 包装 Pinia store，仅暴露 dispatch(action)(args) 和 getState(key)（深拷贝）。供弹出 API、getPassword、getPanels 使用。 |
createPopupAPI.js | 为给定弹出 data-element 构建 UI.Popup 接口（add / update / getItems）。 |