如何使用 GroupDocs.Annotation for Java 為 PDF 加註

提升 Java 應用程式的文件加註功能，是改善協作、合規與使用者體驗的強大方式。在本指南中，您將學習 如何為 PDF 加註，從設定 Maven 依賴、建立多筆加註，到遵循加註最佳實踐。讓我們一步步操作，讓您能自信地將此功能整合至專案中。

快速回答

GroupDocs.Annotation 的主要目的為何？
在 Java 應用程式中以程式方式建立、編輯，以及 儲存已加註的 PDF 文件。
我需要哪個 Maven 套件？
com.groupdocs:groupdocs-annotation（請參考 Maven dependency 章節）。
我可以一次加入多個加註嗎？
可以——您可以在單一次操作中 加入多個加註。
我要如何初始化加註器？
使用教學中示範的 initialize annotator 模式。
關鍵的最佳實踐提示是什麼？
遵循 annotation best practices 清單，以管理記憶體與效能。

什麼是「如何為 PDF 加註」？

為 PDF 加註是指將視覺備註—如標記、評論、圖形與其他標記—永久寫入檔案，使任何開啟文件的人都能看到這些變更。GroupDocs.Annotation 提供簡易的 API，讓您以程式方式完成此任務。

為何使用 GroupDocs.Annotation for Java？

跨平台支援 – 可在任何執行 Java 的作業系統上運作。
豐富的加註類型 – 從簡單的高亮到複雜的橢圓形圖形皆可使用。
不需外部 PDF 編輯器 – 所有操作皆在您的 Java 程式碼內完成。
企業級可擴充 – 適用於法律、教育與技術文件等工作流程。

前置條件

已在機器上安裝 Java SDK（JDK 8 或更新版本）。
使用 Maven 進行相依管理。
具備 IntelliJ IDEA 或 Eclipse 等 IDE。
具備基本的 Java 程式設計知識。

Maven dependency 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>

取得授權

免費試用： 下載試用版以測試 GroupDocs.Annotation。
臨時授權： 取得臨時授權以在評估期間完整使用功能。
購買正式授權： 取得正式授權以供正式環境使用。

初始化 Annotator（Java）

第一步是 初始化加註器，並指定要處理的文件。以下為基本的初始化範例：

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，為加註任務做好 Java 應用程式的前置設定。

import com.groupdocs.annotation.Annotator;

public class Feature1 {
    public void loadAnnotator(String fileName) {
        try (final Annotator annotator = new Annotator(fileName)) {
            // Annotator initialized and ready.
        }
    }
}

建立加註

功能 2：建立區域加註（Area Annotation）

區域加註可用於標示矩形區域。依照以下步驟建立：

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：建立橢圓形加註（Ellipse Annotation）

橢圓形加註適合用於圓形或橢圓形的標示。

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;
    }
}

加入多筆加註

您可以在一次呼叫中 加入多個加註，此方式可提升效能並讓程式碼更簡潔。

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

當加註完成後，您只需 儲存已加註的 PDF，並可選擇只保留特定類型的加註。

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);
    }
}

Annotation Best Practices（Java）

使用 try‑with‑resources 以自動關閉 Annotator 並釋放記憶體。
批次加入加註（如功能 4 所示）以減少 I/O 開銷。
在 SaveOptions 中 僅指定所需的加註類型，以保持檔案大小最小。
儲存後 釋放大型文件，避免記憶體洩漏。

實務應用

法律文件審閱： 為條款加上高亮並附加評論，供律師使用。
教育資源： 為教科書加註，供學習小組討論。
技術手冊： 在工程圖上標註說明與警示。

效能考量

限制在極大型 PDF 上同時執行的加註數量。
使用建議的 annotation best practices 以有效管理記憶體。
若發現效能下降，可使用 Java Flight Recorder 進行效能分析。

常見問題與解決方案

問題	解決方案
OutOfMemoryError 在載入大型 PDF 時發生	以串流模式載入文件，或增大 JVM 堆積大小。
加註儲存後未顯示	確認 `SaveOptions` 包含正確的 `AnnotationType`。
授權錯誤	核對試用或正式授權檔案是否正確引用。

常見問答

Q: 我可以同時加入文字評論與圖形嗎？
A: 可以，GroupDocs.Annotation 支援 TextAnnotation 與 CommentAnnotation 類型——只需實例化相應模型並加入清單即可。

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 版本以獲得最佳效能。

結論

現在您已掌握使用 GroupDocs.Annotation for Java 為 PDF 加註 的完整端對端解決方案。依循上述步驟——設定 Maven 依賴、初始化加註器、建立並加入多筆加註，以及遵循加註最佳實踐，您即可為任何 Java 應用程式注入強大的文件標註功能。

最後更新： 2026-03-24
測試版本： GroupDocs.Annotation 25.2
作者： GroupDocs