Annotations

批注

本页介绍 PDF 批注的创建、读取、搜索和扁平化。Page 为每种批注子类型公开一个 Add*() 方法，返回一个实时的 Annotation 句柄；Annotation 基类及其子类型（TextAnnotation、StampAnnotation、MarkupAnnotation 等）公开批注的属性，以便读取和编辑。

创建标记、注释和链接批注

四个文本标记方法 — Page.AddHighlight()、Page.AddUnderline()、Page.AddSquiggly() 和 Page.AddStrikeOut() — 接受一个 quads 数组（/QuadPoints），并返回一个 MarkupAnnotation。Page.AddLink() 创建一个带有 URI 或内部操作的可点击区域，Page.AddTextNote() 添加一个粘贴便签图标，打开一个显示 contents 文本的弹出框，返回一个 TextAnnotation。

page.AddHighlight({ quads, color: [1, 1, 0], contents: 'Yellow highlight' });
page.AddUnderline({ quads, color: [0, 0, 1] });
page.AddStrikeOut({ quads, color: [1, 0, 0] });

page.AddLink({
  rect: [100, 700, 220, 716],
  action: { type: 'uri', uri: 'https://example.com' },
  border: 0,
});

page.AddTextNote({
  rect: [x, y, x + 20, y + 20], icon: 'Note', author: 'Reviewer',
  contents: 'This is a sticky-note annotation.',
});

Page 还公开形状和自由手绘方法 — AddSquare()、AddCircle()、AddLine()、AddPolygon()、AddPolyline()、AddInk()、AddFreeText()、AddCaret() 和 AddStamp() — 每个方法返回对应子类型的批注句柄，并自动生成其 /AP 外观。

读取和列出批注

page.Annotations 是页面上每个 Annotation 的数组。每个批注，无论子类型如何，都公开 Subtype、Rect、Color、Contents、Name、Layer、ModDate、Flags、Print、Hidden 和 Opacity；子类型会添加自己的字段，例如 StampAnnotation.StampName 或 MarkupAnnotation.QuadPoints。

const freeText = page.Annotations.find((a) => a.Subtype === 'FreeText');
if (freeText) {
  freeText.Contents = 'Updated note text';
}

搜索注释文本

Page.SearchAnnotationText() and Page.SearchAnnotations() 是故意分开的。 SearchAnnotationText() 在文本中查找匹配的注释 carries 而不是绘制 — 笔记的 /Contents，其作者 (/T），或其主题 (/Subj） — 并返回 AnnotationTextMatch[] ({ annot, key, value, text }). SearchAnnotations() 在文本中查找匹配的注释 draws，例如一个 FreeText的可见文字，并返回 AnnotationMatch[] ({ annot, text, quads }).

// A sticky note's /Contents text — found by SearchAnnotationText, not SearchAnnotations.
const textHits = page.SearchAnnotationText('body secret');
console.log(textHits[0].key, textHits[0].value); // 'Contents' 'body secret'

// A FreeText's rendered words — found by SearchAnnotations, not SearchAnnotationText.
const drawnHits = page.SearchAnnotations('bravo');

扁平化注释

Annotation.Flatten() 将注释的 /AP 外观直接烘焙进页面的内容流，在其 /Rect 处，然后从 /Annots 中移除。结果是永久的、静态的内容——不再是观众可以点击、编辑或隐藏的独立注释。

const note = page.AddTextNote({
  rect: [72, 660, 92, 680], icon: 'Comment', contents: 'Reviewed and approved.',
});
note.Flatten();

技巧与最佳实践

• 在由 Add*() 调用直接返回的对象上调用 Flatten() ——随后通过重新读取 page.Annotations 获得的注释是另一个对象引用。
• SearchAnnotationText() 和 SearchAnnotations() 覆盖不同的文本：如果需要查找短语，无论它是被键入到笔记中还是绘制在页面上，都应同时运行两者。
• 这四种标记方法（AddHighlight、AddUnderline、AddSquiggly、AddStrikeOut）会自动生成它们的 /AP 外观 —— 无需手动绘制内容流。
• 加密在往返过程中仍然有效：在 Document.Save() 之前使用 encrypt 选项添加的注释，在文档重新打开并解密后仍然有效。

常见问题

FAQ

SearchAnnotationText 和 SearchAnnotations 有什么区别？

SearchAnnotationText() 匹配文本的注释 carries — /Contents, /T (author)，或 /Subj —— 如便签的正文。 SearchAnnotations() 匹配文本和注释 draws 在页面上，例如一个 FreeText的可见词。两者是互斥的：在一个中的匹配不会出现在另一个中。

如何使注释成为永久且不可交互的？

对由 Add*() 方法创建并返回的 Annotation 句柄调用 Flatten()。这会将其外观烘焙到页面的内容流中，并将其从 /Annots 中移除。

支持哪些注释子类型？

Page 提供文本标记（AddHighlight、AddUnderline、AddSquiggly、AddStrikeOut）、注释和提示（AddTextNote、AddFreeText、AddCaret）、链接（AddLink）、形状（AddSquare、AddCircle、AddLine、AddPolygon、AddPolyline）、手写墨迹（AddInk）、印章（AddStamp）以及文件附件（AddFileAttachment）。

我如何列出页面上已有的所有注释？

读取 page.Annotations，它是一个 Annotation 句柄的数组。每个句柄都公开 Subtype、Rect、Color、Contents 以及其他共享属性，这样您就可以使用标准数组方法对它们进行筛选或检查。

API Reference 摘要

另请参阅

• Aspose.PDF — Enterprise Documentation