PDF 注释（C++）——文本备注、链接、高亮和印章

介绍

PDF 注释覆盖了广泛的交互式和视觉元素，这些元素层叠在页面内容之上：粘性文本备注、超链接、突出显示或删除线文本、几何形状、墨迹、文件附件以及批准印章。Aspose.PDF FOSS for C++ 将这些全部表示为 Annotation 的具体子类，因此遍历页面注释的代码可以针对基类进行通用操作，同时在需要时仍能访问子类型特有的成员——例如 TextAnnotation 的 Icon() 或 LinkAnnotation 的 Action()——。

库的 Annotations::AnnotationType 枚举列举了它识别的子类型：Text、Link、FreeText、Line、Square、Circle、Polygon、PolyLine、Highlight、Underline、Squiggly、StrikeOut、Stamp、Caret、Ink、Popup、FileAttachment、Sound、Movie、Widget、Screen、PrinterMark、Watermark、Redaction、RichMedia 等等。每个值对应一个具体类——用于形状标记的 CircleAnnotation、SquareAnnotation、PolygonAnnotation、PolylineAnnotation 和 LineAnnotation；用于自由文本和手绘笔画的 FreeTextAnnotation 与 InkAnnotation；用于嵌入内容的 FileAttachmentAnnotation、SoundAnnotation、MovieAnnotation、ScreenAnnotation 与 RichMediaAnnotation；以及用于 AcroForm 字段外观的 WidgetAnnotation。

本文介绍了 Annotation 和 AnnotationCollection 基础 API，包括添加文本备注和链接、在加载已有文档时检测注释类型，以及读取或更新标记元数据和印章。Aspose.PDF FOSS for C++ 是一个基于 C++20 的库，除标准库外没有运行时依赖；头文件直接从 aspose/pdf/annotations/ 目录引入，库以 CMake 目标的形式构建。

包含内容

Annotation 与 AnnotationCollection

Annotation 是所有注释子类型的基类。它公开了共享属性：Rect() / Rect(value) 用于获取或设置注释的边界矩形，Contents() 用于关联的文本，Name()、Color()、Flags()（一个 AnnotationFlags 位掩码——Print、Hidden、Invisible、NoZoom、ReadOnly 等），Border()、Width() / Height()、AnnotationType() 和 PageIndex()。AnnotationCollection 保存单页上的注释，可通过 Page.Annotations() 访问。

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/annotation_collection.hpp>
#include <iostream>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc("reviewed.pdf");
AnnotationCollection& annots = doc.Pages()[1].Annotations();

std::cout << "Annotation count: " << annots.Count() << "\n";
for (int i = 0; i < annots.Count(); ++i) {
    Annotation& a = annots[i];
    std::cout << "  " << a.Name() << ": " << a.Contents() << "\n";
}

AnnotationCollection 还提供了 Add(annotation)、Add(annotation, considerRotation)、Delete(index)、Delete(annotation)、Clear()、Remove(annotation)、Contains(annotation) 和 IsReadOnly() 等方法。

带有 TextAnnotation 的文本注释

TextAnnotation 代表常见的粘性便签评论。除基类 Annotation 的成员外，它还新增了 Open() / Open(value) 用于控制便签是否展开，以及 Icon() / Icon(value)（一个 TextIcon 值，如 Note、Comment、Key、Help 或 Check）用于选择图标形状。

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/text_annotation.hpp>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc("input.pdf");

TextAnnotation note{doc};
note.Rect(Rectangle{100.0, 700.0, 200.0, 720.0, false});
note.Contents("Reviewed by QA");
note.Icon(TextIcon::Comment);
note.Open(true);

doc.Pages()[1].Annotations().Add(note);
doc.Save("annotated.pdf");

带有 LinkAnnotation 的链接和操作

LinkAnnotation 将可点击区域附加到页面。它由所属的 Page 和一个 Rectangle 构造，并通过 Action(value) 设置行为——可以是任何 PdfAction 子类，包括 NamedAction（如 PredefinedAction::LastPage 之类的预定义导航）、GoToAction、GoToURIAction 或 JavascriptAction。Destination() 读取链接的 IAppointment 目标，Highlighting() / Highlighting(value) 设置链接激活时使用的 HighlightingMode（None、Invert、Outline、Push、Toggle）。

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/link_annotation.hpp>
#include <aspose/pdf/annotations/named_action.hpp>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc;
Page page = doc.Pages().Add();

LinkAnnotation link{page, Rectangle{0.0, 0.0, 100.0, 20.0, false}};
link.Action(NamedAction{PredefinedAction::LastPage});
link.Highlighting(HighlightingMode::Push);

page.Annotations().Add(link);

加载时检测注释类型

当文档打开时，现有的注释已在每页的 AnnotationCollection 中填充，AnnotationType() 用于识别每个条目对应的具体子类型。这使得调用代码可以根据枚举值进行分支，而无需预先知道给定 PDF 包含哪些注释类型。

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/annotation_type.hpp>
#include <iostream>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc("mixed-annotations.pdf");
auto& annots = doc.Pages()[1].Annotations();

for (int i = 0; i < annots.Count(); ++i) {
    switch (annots[i].AnnotationType()) {
        case AnnotationType::Text:      std::cout << "Text note\n"; break;
        case AnnotationType::Link:      std::cout << "Link\n"; break;
        case AnnotationType::Circle:    std::cout << "Circle shape\n"; break;
        case AnnotationType::Square:    std::cout << "Square shape\n"; break;
        case AnnotationType::Highlight: std::cout << "Highlight\n"; break;
        case AnnotationType::Stamp:     std::cout << "Stamp\n"; break;
        default: break;
    }
}

Markup Annotation 元数据

MarkupAnnotation 是携带审阅者元数据的注释的基类：Title()（作者）、Subject()、用于格式化评论文本的 RichText()，以及用于与页面内容混合的 Opacity()。InReplyTo() 和 Popup() 将标记注释与其所属的评论线程关联，ClearState() / SetReviewState(state, userName) 管理其审阅状态。HighlightAnnotation、UnderlineAnnotation、StrikeOutAnnotation 和 SquigglyAnnotation 是位于文本之上的标记子类型；它们共享的 TextMarkupAnnotation 基类添加了 QuadPoints() 用于定义覆盖的四边形区域，以及 GetMarkedText() 用于读取其下方的文本。

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/markup_annotation.hpp>

using namespace Aspose::Pdf::Annotations;

for (int i = 0; i < annots.Count(); ++i) {
    if (auto* markup = dynamic_cast<MarkupAnnotation*>(&annots[i])) {
        markup->Title("QA Reviewer");
        markup->Subject("Layout issue");
        markup->Opacity(0.6);
    }
}

使用 StampAnnotation 创建印章注释

StampAnnotation 在页面上放置预定义或自定义的印章。Icon() / Icon(value) 选择一个 StampIcon 值——Approved、Draft、Confidential、Final、Expired、NotApproved、ForComment、TopSecret 等——而 Image() / Image(value) 则提供自定义印章外观的原始图像字节，以替代内置图标。

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/stamp_annotation.hpp>

using namespace Aspose::Pdf::Annotations;

for (int i = 0; i < annots.Count(); ++i) {
    if (auto* stamp = dynamic_cast<StampAnnotation*>(&annots[i])) {
        stamp->Icon(StampIcon::Approved);
    }
}

快速入门

将库作为 CMake 子目录添加，并链接到 aspose_pdf_foss 目标：

add_subdirectory(aspose.pdf-foss-for-cpp)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)

打开文档，添加文本注释，并读取注释计数：

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/text_annotation.hpp>
#include <iostream>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

int main() {
    Document doc("input.pdf");

    TextAnnotation note{doc};
    note.Rect(Rectangle{100.0, 700.0, 200.0, 720.0, false});
    note.Contents("Reviewed by QA");
    note.Icon(TextIcon::Comment);

    doc.Pages()[1].Annotations().Add(note);
    doc.Save("annotated.pdf");

    std::cout << "Annotations on page 1: "
              << doc.Pages()[1].Annotations().Count() << "\n";
}

支持的格式

格式	扩展	读取	写入
BMP	.bmp	—	✓
JPEG	.jpg	—	✓
TIFF	.tiff	—	✓
Text	.txt	—	✓
SVG	.svg	✓	—

格式支持适用于文档级别的页面渲染和加载选项；这些条目反映了已确认的导出（BmpDevice、JpegDevice、TiffDevice、TextDevice）和导入（SvgLoadOptions）路径，而非特定于批注的序列化。

开源与许可

Aspose.PDF FOSS for C++ 在 MIT 许可证下发布。源代码可在 https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Cpp 获取，且该库可在商业和开源项目中使用，无需许可费用。

介绍

包含内容

Annotation 与 AnnotationCollection

带有 TextAnnotation 的文本注释

带有 LinkAnnotation 的链接和操作

加载时检测注释类型

Markup Annotation 元数据

使用 StampAnnotation 创建印章注释

快速入门

支持的格式

开源与许可

快速开始

相关资源

介绍#

包含内容#

Annotation 与 AnnotationCollection#

带有 TextAnnotation 的文本注释#

带有 LinkAnnotation 的链接和操作#

加载时检测注释类型#

Markup Annotation 元数据#

使用 StampAnnotation 创建印章注释#

快速入门#

支持的格式#

开源与许可#

快速开始#

相关资源#

介绍

包含内容

Annotation 与 AnnotationCollection

带有 TextAnnotation 的文本注释

带有 LinkAnnotation 的链接和操作

加载时检测注释类型

Markup Annotation 元数据

使用 StampAnnotation 创建印章注释

快速入门

支持的格式

开源与许可

快速开始

相关资源