批注

批注是用户添加到 PDF 的标记对象——高亮、形状、自由文本、印章、签名、密文等。本指南介绍 UI 侧批注功能及导入/导出 API。

批注渲染、数据模型和 PDF 空间坐标处理位于闭源 Core 引擎（packages/core/src/annotation/）。此处文档化的 UI 层通过 core 桥接层驱动引擎，并在 document Pinia store 中镜像批注状态。

批注类型

类别	类型
文本标记	高亮、下划线、删除线、波浪线
形状	矩形（square）、圆、线、箭头、折线、多边形、云形、弧、曲线
自由文本	Freetext、Callout
绘图	Ink
印章与图片	Stamp、Image
链接	Link
表单	Textfield、Checkbox、Radiobutton、Listbox、Combobox、Pushbutton、Signature（见 表单）
安全	Redaction、Remove（见内容编辑/安全）

类型别名

部分类型共享引擎实现：

• 无测量的 circle → square
• 有测量的 ink → curve
• 带弧点的 ink → arc

UI API

启用/禁用导入导出

UI.disableAnnotationExport();   // useViewer.setAnnotationExport(false)
UI.enableAnnotationExport();    // useViewer.setAnnotationExport(true)
UI.disableAnnotationImport();   // useViewer.setAnnotationImport(false)
UI.enableAnnotationImport();    // useViewer.setAnnotationImport(true)

切换 viewer store 中的 annotation.isAnnotationExport / annotation.isAnnotationImport 标志，控制 UI 是否提供批注导入/导出。

作者/用户

UI.setCurrentUser('alice');     // 回退到 'Guest'
UI.setAnnotator('alice');       // 与 setCurrentUser 相同的 store action
UI.setAuthor('alice');          // 为假时为空字符串
UI.setHighlightLink(true);      // 切换链接高亮

批注弹出菜单

批注右键菜单可定制——见 弹出菜单。

Core 桥接层（批注接口）

core 桥接层（src/core/）在 instance.Core 上暴露引擎的批注 API：

函数	用途
getAnnotationsList	列出批注。
getAnnotationManager	获取批注管理器。
getAnnotationHistoryManager	获取撤销/重做历史管理器。
importAnnotations / exportAnnotations	XFDF/JSON 导入导出。
exportXfdf / saveAnnotations	保存批注数据。
removeAllAnnotations	清除所有批注。
selectAnnotation / jumpToAnnotation	选择与导航。
setAnnotationStyles	更新批注样式。
addAnnotationImage	添加图片批注。
handleReplyAnnotation	回复线程。
setUnselectableAnnotationTypes / getUnselectableAnnotationTypes	选择控制。
enableAutoSelectOnCreate / disableAutoSelectOnCreate	创建时自动选中。
updateViewWithColorIndex	颜色索引视图更新。
showPopup / handlePopup	弹出控制。
setAnnotator	在引擎中设置批注者名称。
getDynamicStampPreview / getStampRect / handleStamp	印章辅助。
setHighlightLink / setHighlightForm	高亮切换。

UI 中的批注状态

document store 为 UI 镜像批注状态：

• annotations —— 数组（通过 initAnnotations 包装为 shallowReactive），按页索引管理。
• selectedAnnotation / selected —— 当前选中批注。
• annotationsCount —— 计数（由 getAnnotationsCount getter 格式化为 "N annotation(s)"）。
• getAllAnnotations getter —— 按页索引分组批注，按类型白名单过滤并排除回复。
• propertyPanel —— 选中批注/表单字段的属性面板模型。

initAnnotations / setAnnotations(annotation, type) 按页索引管理数组（增/删/改）。store 将变更推送到引擎——例如 setActiveToolColor 写入颜色并调用 core.setTool。

权限检查

helpers/annotationPermissions.js 暴露 canCopyAnnotations({ isReadOnly, isUserAdmin, currentAuthor, annotations })：

• 只读时返回 false。
• 用户为管理员时返回 true。
• 否则要求每个批注的作者等于 currentAuthor。

示例

禁用批注导出并设置作者

UI.disableAnnotationExport();
UI.setAuthor('alice');

通过桥接层导出批注

const xfdf = await instance.Core.exportXfdf();

列出批注

const annotations = instance.Core.getAnnotationsList();

相关

• 工具 — 创建批注。
• 弹出菜单 — 批注右键菜单。
• 签名 — 签名批注。
• 印章 — 印章批注。
• Core 桥接层