如何使用 GroupDocs.Annotation for Java 保存带注释的 PDF
在本教程中,您将学习保存带注释的 PDF文档的编程方法。无论您需要突出显示法律条款、添加审阅评论,还是在工程图纸中嵌入形状,以下步骤将带您逐步完成整个过程——从 Maven 设置到批量添加注释再到持久化最终文件。完成后,您即可在任何 Java 应用程序中集成强大的 PDF 注释功能。
快速答案
- GroupDocs.Annotation 的主要目的是什么?
在 Java 应用程序中以编程方式创建、编辑和 保存带注释的 PDF 文档。 - 我需要哪个 Maven 构件?
com.groupdocs:groupdocs-annotation(参见 Maven 依赖 部分)。 - 我可以一次添加多个注释吗?
是的——您可以在一次操作中 添加多个注释,从而减少 I/O 开销。 - 如何初始化 annotator?
使用教程中展示的 initialize annotator 模式;它会加载 PDF 并为注释任务准备 API。 - 关键的最佳实践提示是什么?
遵循 annotation best practices 检查表,以进行内存管理、批处理和优化文件大小。
什么是 “如何注释 PDF”?
GroupDocs.Annotation 是一个 Java 库,允许您将可视化备注——高亮、评论、形状和印章——直接嵌入 PDF 文件。该库抽象了底层 PDF 操作,使您能够专注于业务逻辑而非 PDF 内部细节。它支持多种注释类型,提供针对大文档的流式 API,并且可以轻松集成到现有的 Java 项目中,是任何基于 PDF 工作流的多功能解决方案。
为什么使用 GroupDocs.Annotation for Java?
GroupDocs.Annotation 提供了一整套功能,简化 PDF 注释任务,同时实现高性能和可扩展性。该库可在任何支持 Java 的操作系统上运行,能够处理高达 500 MB 的文档而无需将整个文件加载到内存中,并且内置超过 15 种注释类型。其 API 为开发者而设计,只需几行代码即可添加、编辑和删除注释,并为试用和生产环境提供强大的授权选项。
- 跨平台支持 – 在 Windows、Linux 和 macOS 上运行,覆盖 100 % 的 Java 兼容环境。
- 丰富的注释类型 – 超过 15 种内置类型,包括文本、区域、椭圆和自定义印章。
- 无需外部 PDF 编辑器 – 所有操作均在您的 Java 代码中完成,消除第三方依赖。
- 企业级可扩展性 – 可处理高达 500 MB 的 PDF,并在不将整个文件加载到内存中的情况下处理数百页文档,这得益于流式 API。
前提条件
- Java 8 或更高(建议使用 JDK 11 或更高)。
- 用于依赖管理的 Maven。
- 如 IntelliJ IDEA 或 Eclipse 等 IDE。
- 熟悉 Java 集合和异常处理的基础知识。
Maven 依赖 GroupDocs
将 GroupDocs 仓库和注释库添加到您的 pom.xml 中:
<repositories>
<repository>
<id>repository.groupdocs.com</id>
<name>GroupDocs Repository</name>
<url>https://releases.groupdocs.com/annotation/java/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.groupdocs</groupId>
<artifactId>groupdocs-annotation</artifactId>
<version>25.2</version>
</dependency>
</dependencies>
许可证获取
- 免费试用 – 下载 30 天试用版以评估 API。
- 临时许可证 – 请求 7 天评估密钥以获取全部功能。
- 正式许可证 – 购买永久许可证,实现无限部署。
如何在 Java 中初始化 annotator
Annotator 是 GroupDocs.Annotation 的核心类,用于加载 PDF 并提供创建、编辑和保存注释的方法。正确初始化它是实现可靠工作流的第一步,使用 try‑with‑resources 可确保本机资源自动释放。您只需将文件路径(以及可选的受保护 PDF 密码)传递给构造函数即可创建实例,随后 annotator 即可进行后续操作。
import com.groupdocs.annotation.Annotator;
public class Feature1 {
public void loadAnnotator(String fileName) {
try (final Annotator annotator = new Annotator(fileName)) {
// Ready to use!
}
}
}
功能 1:加载并初始化 annotator
此功能演示如何使用文件路径创建 Annotator 实例,并可选地为受保护的 PDF 传递密码。
import com.groupdocs.annotation.Annotator;
public class Feature1 {
public void loadAnnotator(String fileName) {
try (final Annotator annotator = new Annotator(fileName)) {
// Annotator initialized and ready.
}
}
}
如何创建注释
创建注释包括实例化特定的注释模型、配置其属性,然后将其添加到 annotator 的集合中。
功能 2:创建区域注释
AreaAnnotation 表示 PDF 页面上的矩形高亮区域。它用于标记需要关注的文本或图像部分。
import com.groupdocs.annotation.models.Rectangle;
import com.groupdocs.annotation.models.annotationmodels.AreaAnnotation;
public class Feature2 {
public AreaAnnotation createAreaAnnotation() {
AreaAnnotation area = new AreaAnnotation();
area.setBox(new Rectangle(100, 100, 100, 100));
area.setBackgroundColor(65535);
area.setPageNumber(1);
return area;
}
}
功能 3:创建椭圆注释
EllipseAnnotation 定义了可以放置在页面上的圆形或椭圆形状,用于强调徽标、图表或其他任何视觉元素。
import com.groupdocs.annotation.models.Rectangle;
import com.groupdocs.annotation.models.annotationmodels.EllipseAnnotation;
public class Feature3 {
public EllipseAnnotation createEllipseAnnotation() {
EllipseAnnotation ellipse = new EllipseAnnotation();
ellipse.setBox(new Rectangle(100, 100, 100, 100));
ellipse.setBackgroundColor(123456);
ellipse.setPageNumber(2);
return ellipse;
}
}
如何添加多个注释
addAnnotations 方法允许您一次性将一组注释对象添加到文档中,从而通过减少文件系统写入和内存波动来提升性能。通过批量添加注释,您可以最小化 I/O 操作并保持 JVM 堆使用量低,尤其在处理大型 PDF 时。
import com.groupdocs.annotation.Annotator;
import java.util.ArrayList;
import java.util.List;
import com.groupdocs.annotation.models.AnnotationBase;
import com.groupdocs.annotation.models.annotationmodels.AreaAnnotation;
import com.groupdocs.annotation.models.annotationmodels.EllipseAnnotation;
public class Feature4 {
public void addAnnotations(Annotator annotator) {
AreaAnnotation area = new AreaAnnotation();
area.setBox(new Rectangle(100, 100, 100, 100));
area.setBackgroundColor(65535);
area.setPageNumber(1);
EllipseAnnotation ellipse = new EllipseAnnotation();
ellipse.setBox(new Rectangle(100, 100, 100, 100));
ellipse.setBackgroundColor(123456);
ellipse.setPageNumber(2);
List<AnnotationBase> annotations = new ArrayList<>();
annotations.add(area);
annotations.add(ellipse);
annotator.add(annotations);
}
}
如何保存带注释的 PDF
SaveOptions 让您在持久化 PDF 时指定要应用的注释类型和输出设置。加载 PDF,添加所需的注释,然后使用包含要持久化的注释类型的 SaveOptions 对象调用 save 方法。此一步操作将更改写回磁盘,同时保留原始文档结构。
public class Feature5 {
public String getOutputPath(String fileName) {
return "YOUR_OUTPUT_DIRECTORY" + "/filtered_output.pdf";
public void saveAnnotatedDocument(Annotator annotator, String outputPath) {
SaveOptions saveOptions = new SaveOptions();
saveOptions.setAnnotationTypes(AnnotationType.ELLIPSE);
annotator.save(outputPath, saveOptions);
}
}
Java 注释最佳实践
- 使用 try‑with‑resources 自动关闭
Annotator并释放本机资源。 - 批量添加注释(如 Feature 4 所示)以最小化 I/O 开销。
- 在
SaveOptions中仅指定所需的注释类型,以控制输出文件大小。 - 在保存后从内存中释放大型文档,以避免泄漏;完成后调用
annotator.dispose()。
实际应用
- 法律文档审阅 – 高亮条款、附加评论并跟踪审阅者更改。
- 教育资源 – 为教科书或讲义幻灯片添加注释,以供协作学习小组使用。
- 技术手册 – 将备注、警告和修订标记直接嵌入工程图纸。
性能考虑因素
- 限制对大于 300 MB 的 PDF 进行并发注释操作,以避免堆内存压力。
- 使用推荐的 annotation best practices 将内存使用保持在 200 MB 以下,以适应典型企业工作负载。
- 如果发现延迟峰值,请使用 Java Flight Recorder 或 VisualVM 对应用程序进行性能分析。
常见问题及解决方案
| 问题 | 解决方案 |
|---|---|
| OutOfMemoryError 在加载大型 PDF 时 | 以流模式加载文档 (new Annotator(stream)) 或增加 JVM 堆大小 (-Xmx2g)。 |
| 保存后注释未显示 | 确保 SaveOptions 包含正确的 AnnotationType 枚举值。 |
| 许可证错误 | 验证许可证文件路径是否正确,以及许可证版本是否与库版本匹配。 |
常见问答
问:我可以在形状之外添加文本评论吗?
答:是的,GroupDocs.Annotation 支持 TextAnnotation 和 CommentAnnotation 类型——实例化相应的模型并将其添加到 annotator 的集合中。
问:是否可以编辑已有的注释?
答:当然可以。通过其 ID 检索注释,修改其属性,然后调用 annotator.update(updatedAnnotation)。
问:如何删除不再需要的注释?
答:使用 annotator.delete(annotationId) 删除特定注释,或使用 annotator.clear(pageNumber) 清除页面上的所有注释。
问:该库是否支持受密码保护的 PDF?
答:是的。在构造 Annotator 实例时提供密码:new Annotator(filePath, password)。
问:需要哪个版本的 Java?
答:该库兼容 Java 8 及以上版本;我们建议使用最新的 LTS 版本(Java 17),以获得最佳性能和安全性。
最后更新: 2026-10-11
测试版本: GroupDocs.Annotation 25.2
作者: GroupDocs