福昕开发者文档中心

基本操作 ​

本文介绍如何用 PDFPage 和 Annot 读取、创建、修改、删除和扁平化注释。注释类型见 注释概述。

相关接口包括：

  • PDFPage.getAnnots()、PDFPage.getAnnotCountAsync()、PDFPage.getAnnotsByRect()：读取页面注释。
  • PDFPage.addAnnot()：在页面上创建注释。
  • PDFPage.removeAnnotById()、PDFPage.removeAnnotByObjectNumber()、PDFDoc.removeAllAnnots()：删除注释。
  • PDFPage.flatten()、PDFPage.flattenAnnot()：扁平化注释或表单控件。
  • Annot.getType()、Annot.getRect()、Annot.setRect()、Annot.getContent()、Annot.setContent()、Annot.getFlags()、Annot.setFlags()：读取或修改注释通用属性。
  • PDFPage.getAnnotIdAtDevicePoint()：按设备坐标命中注释。

读取页面注释 ​

javascript
const page = await pdfDoc.getPageByIndex(0);
const annots = await page.getAnnots();

annots.forEach((annot) => {
    console.log(annot.getType(), annot.getRect());
});

如果只需要数量，可使用：

javascript
const count = await page.getAnnotCountAsync();

按矩形获取注释 ​

PDFPage.getAnnotsByRect(rect, tolerance?) 返回与矩形相交的注释。rect 为 PDF 坐标；tolerance 默认 8，有效范围约 0–30。

javascript
const page = await pdfDoc.getPageByIndex(0);
const annots = await page.getAnnotsByRect(
    { left: 0, bottom: 0, right: 200, top: 200 },
    8
);

创建注释 ​

PDFPage.addAnnot(annotJson) 用于创建注释。不同注释类型需要的属性不同，常见字段包括 type、rect、contents、color、coords 等。

javascript
const annots = await page.addAnnot({
    type: 'note',
    rect: {
        left: 100,
        right: 130,
        top: 700,
        bottom: 670
    },
    contents: '请确认这里的内容'
});

const note = annots[0];

文本标记注释通常需要基于文本选区或搜索结果生成 coords。如果使用完整 UI，可优先使用内置文本选择工具。

粘贴时使用当前用户作为作者 ​

pdfViewer.setCurrentUserAsAnnotationAuthor(true) 开启后，粘贴生成的注释以当前用户为作者。请先设置当前用户身份。

修改注释属性 ​

javascript
const annot = annots[0];

await annot.setContent('更新后的注释内容');
await annot.setRect({
    left: 120,
    right: 180,
    top: 720,
    bottom: 680
});

修改注释属性后，如需保存到文件，应按文档保存流程导出 PDF。

多选批量缩放 ​

构造参数 enableBatchAnnotResize 默认为 false。设为 true 后，可对多选注释拖拽缩放框等比缩放并保持相对位置。ink、方形、圆形、文本框、区域高亮、screen 等类型支持该操作；备注、图章、铅笔等可能不适用。

javascript
const pdfViewer = new PDFViewCtrl.PDFViewer({
    enableBatchAnnotResize: true
});

不可选中权限见 注释权限管理器 · selectable。

删除和扁平化注释 ​

javascript
const annotId = annot.getUniqueID();
await page.removeAnnotById(annotId);

删除全部注释 ​

PDFDoc.removeAllAnnots() 删除文档中的全部注释，返回按页索引到已删除注释对象号数组的映射。该操作需要注释编辑权限。

javascript
const removed = await pdfDoc.removeAllAnnots();

扁平化会把注释外观写入页面内容，注释对象本身将不再作为可编辑注释存在。

javascript
await page.flattenAnnot(annot);

注意事项 ​

  • 注释坐标通常使用 PDF 坐标，和 Viewer 的 device pixels 不同。
  • 创建、修改、删除或扁平化注释通常需要相应文档权限。
  • 如果需要保存注释变更，应在操作完成后导出或保存 PDF 文件。