如何使用 GroupDocs.Annotation for Java 保存已註釋的 PDF
在本教學中,您將學習如何使用 GroupDocs.Annotation for Java 以程式方式 保存已註釋的 PDF 文件。無論您需要標註法律條款、加入審閱意見,或在工程圖紙中嵌入圖形,下列步驟將帶您逐步完成從 Maven 設定、批次新增註釋到持久化最終檔案的全過程。完成後,您即可在任何 Java 應用程式中整合強大的 PDF 註釋功能。
快速解答
- GroupDocs.Annotation 的主要目的為何?
以程式方式在 Java 應用程式中建立、編輯並 保存已註釋的 PDF 文件。 - 我需要哪個 Maven 套件?
com.groupdocs:groupdocs-annotation(請參閱 Maven dependency 部分)。 - 我可以一次新增多個註釋嗎?
可以——您可以在單一次操作中 新增多個註釋,以減少 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 用於相依管理。
- IDE,例如 IntelliJ IDEA 或 Eclipse。
- 具備 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並釋放本機資源。 - 批次新增註釋(如功能 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 列舉值。 |
| 授權錯誤 | 核對授權檔案路徑是否正確,且授權版本與函式庫版本相符。 |
常見問答
Q: 我可以在形狀之外加入文字評論嗎?
A: 可以,GroupDocs.Annotation 支援 TextAnnotation 與 CommentAnnotation 類型——實例化相應模型並加入 annotator 的集合。
Q: 能編輯已存在的註釋嗎?
A: 當然可以。依據 ID 取得註釋,修改其屬性,然後呼叫 annotator.update(updatedAnnotation)。
Q: 如何移除不再需要的註釋?
A: 使用 annotator.delete(annotationId) 刪除特定註釋,或使用 annotator.clear(pageNumber) 清除頁面上的所有註釋。
Q: 此函式庫能處理受密碼保護的 PDF 嗎?
A: 能。建立 Annotator 實例時提供密碼:new Annotator(filePath, password)。
Q: 需要哪個版本的 Java?
A: 此函式庫相容於 Java 8 及以上版本;我們建議使用最新的 LTS 版本(Java 17)以獲得最佳效能與安全性。
最後更新: 2026-10-11
測試版本: GroupDocs.Annotation 25.2
作者: GroupDocs