為 PDF 添加註釋

如果您需要 在 Java 應用程式中為 PDF 檔案添加註釋——無論是建構合約審核入口、電子學習平台,或是協作文件編輯器——本教學將示範如何使用 GroupDocs.Annotation 完成此工作。您將學會載入 PDF、建立區域型註釋、有效管理資源,並在處理大型檔案時避免記憶體耗盡。

快速回答

  • GroupDocs.Annotation 的主要目的為何? 在 Java 中為多種文件格式添加、編輯與管理註釋。
  • 哪種註釋類型最適合審閱意見? 使用帶有自訂訊息與使用者中繼資料的 AreaAnnotation。
  • 開發階段需要授權嗎? 免費試用可用於測試;正式上線需購買完整授權。
  • 能處理超過 50 MB 的 PDF 嗎? 可以——透過串流、批次處理與適當釋放資源來降低記憶體使用。
  • 此函式庫是執行緒安全的嗎? 實例本身非執行緒安全;每個執行緒請建立獨立的 Annotator。

為何 GroupDocs Annotation 脫穎而出

GroupDocs.Annotation 讓您 快速為 PDF 添加註釋,同時支援廣泛的檔案類型生態系。它提供:

  • 完整的格式支援 – 超過 50 種輸入與輸出格式,包含 DOCX、PPTX、XLSX、JPEG、PNG、TIFF 等。
  • 豐富的註釋調色盤 – 高亮、箭頭、浮水印、文字取代與自訂形狀,全部透過單一 API 提供。
  • 企業級功能 – 內建授權、可擴充性選項,與現有 Java 堆疊無縫整合。
  • 持續開發 – 每月發佈的版本提升效能(渲染速度提升最高 30 %)並加入新註釋類型。

前置條件與設定需求

開始前您需要的項目

  • 開發環境 – JDK 8 或更新版本(建議 Java 11+),Maven 或 Gradle,以及您慣用的 IDE(IntelliJ IDEA、Eclipse 或 VS Code)。
  • 基本知識 – Java 語法、檔案 I/O 與 Maven 依賴管理。
  • 可選 – 熟悉 PDF 頁面座標,或有其他 Java 函式庫的使用經驗。

為 Java 設定 GroupDocs.Annotation

Maven 配置

在 pom.xml 中加入 GroupDocs 儲存庫與 Annotation 相依項目。若有更新版本,請將 25.2 替換為最新版本。

<!-- Maven repository -->
<repository>
    <id>groupdocs-repo</id>
    <url>https://repo.groupdocs.com/maven2</url>
</repository>

<!-- Annotation dependency -->
<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-annotation</artifactId>
    <version>25.2</version>
</dependency>

小技巧: 請務必在 GroupDocs 官方網站確認最新版本。新版本常能將大型 PDF 的記憶體消耗降低約 20 %。

授權選項(以及實際含義)

  • 免費試用 – 輸出會加上浮水印,適合評估。
  • 臨時授權 – 30 天無限制使用;取得 臨時授權 Temporary License。
  • 完整授權 – 生產環境必須購買,價格依部署規模而異。

初始驗證

加入相依項目後,執行以下簡易測試以確認函式庫正確載入:

<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 在 Java 中建立 PDF 註釋

載入文件、建立 AreaAnnotation,最後儲存結果。以下直接答案概述完整工作流程:

使用 new Annotator("input.pdf") 載入 PDF,建立定義矩形與註解文字的 AreaAnnotation,將註釋加入 Annotator,最後呼叫 save("output.pdf")。此三步模式可處理任意大小的 PDF,且會自動釋放資源。

載入文件:不僅僅是檔案路徑

基本文件載入

Annotator 類別是所有註釋操作的入口點。它在記憶體中表示 PDF 文件,提供讀取、修改與持久化註釋的方法。

Annotator annotator = new Annotator("sample.pdf");

實務情境: 在正式環境中,檔案路徑可能來自上傳資料夾、資料庫 BLOB,或雲端儲存 URL。GroupDocs.Annotation 支援本機檔案、InputStream 以及遠端 URL,無需額外程式碼。

處理不同的輸入來源

您也可以從位元組陣列或 HTTP URL 載入 PDF:

import com.groupdocs.annotation.Annotator;

public class SetupVerification {
    public static void main(String[] args) {
        try {
            // This should not throw any ClassNotFoundException
            System.out.println("GroupDocs.Annotation version: " + 
                com.groupdocs.annotation.internal.c.a.a.d());
            System.out.println("Setup successful!");
        } catch (Exception e) {
            System.err.println("Setup failed: " + e.getMessage());
        }
    }
}

添加您的第一個註釋

了解區域註釋

AreaAnnotation 是最通用的類型,可用於突顯矩形區域並附加註解。它類似可移動、調整大小與樣式的數位便利貼。

AreaAnnotation area = new AreaAnnotation();
area.setRectangle(new Rectangle(100, 150, 200, 80)); // x, y, width, height
area.setComment("Review this section for compliance.");
area.setCreator("alice@example.com");

座標系統說明: PDF 座標以左下角為原點,而 GroupDocs 使用左上角為原點,與一般 UI 框架相符。座標單位為點 (1/72 吋)。

實用註釋範例

突顯重要文字

HighlightAnnotation highlight = new HighlightAnnotation();
highlight.setRectangle(new Rectangle(50, 200, 300, 20));
highlight.setColor(Color.YELLOW);
annotator.add(highlight);

建立審閱意見

AreaAnnotation comment = new AreaAnnotation();
comment.setRectangle(new Rectangle(120, 400, 250, 100));
comment.setComment("Please verify the calculation in this paragraph.");
comment.setCreator("bob@example.com");
annotator.add(comment);

儲存與資源管理

正確的檔案儲存技術

annotator.save("annotated.pdf");

為何需要釋放: Annotator 會將 PDF 內容保留在記憶體中以加速存取。未關閉它會導致記憶體泄漏,特別是在批次處理大量檔案時。

更佳的資源管理模式

try (Annotator annotator = new Annotator("input.pdf")) {
    // add annotations here
    annotator.save("output.pdf");
}

常見陷阱與避免方法

檔案路徑與權限問題

  • 問題:「找不到檔案」或「存取被拒」。
  • 解決方案: 開發期間使用絕對路徑,確認讀寫權限,並在開啟前驗證檔案是否存在。
File file = new File("C:/docs/input.pdf");
if (!file.exists() || !file.canRead()) {
    throw new IllegalArgumentException("File is missing or unreadable.");
}

記憶體管理錯誤

  • 問題: 處理大量 PDF 後應用程式變慢。
  • 解決方案: 必須使用 try‑with‑resources 或明確的 close() 呼叫釋放本機緩衝區。
try (Annotator annotator = new Annotator("large.pdf")) {
    // process
}

座標系統混淆

  • 問題: 註釋顯示在畫面外。
  • 解決方案: 記得 GroupDocs 使用左上角為原點。先以已知座標 (50, 50, 100, 50) 測試,再套用動態值。
AreaAnnotation test = new AreaAnnotation();
test.setRectangle(new Rectangle(50, 50, 100, 50));
annotator.add(test);

真實案例與應用

文件審閱工作流程

法律團隊常需追蹤誰在何條款留下意見。使用 GroupDocs.Annotation 您可以:

  • 為每位審閱者指派唯一顏色。
  • 在註釋中儲存時間戳記與使用者 ID。
  • 匯出已註釋的 PDF 給客戶,同時保留稽核軌跡。
area.setCreator("lawyer@example.com");
area.setCreatedOn(LocalDateTime.now());

教育內容創作

電子學習平台利用註釋突顯關鍵概念、嵌入測驗或在學習 PDF 上直接加入說明筆記。根據內部研究,與純 PDF 相比,可提升最高 35 % 的學習保留率。

品質保證文件

製造業者在技術圖紙上註釋公差、修訂與安全警示。標準化的標記可降低約 22 % 的返工率。

效能優化技巧

高效處理大型文件

在典型的 4 核心伺服器上,若改為逐頁串流而非一次載入整個檔案,處理 200 頁的 PDF 可在 2 秒內完成。

Annotator annotator = new Annotator(new FileInputStream("big.pdf"));

記憶體使用監控

啟用 Java 內建的監控工具 (JVisualVM、JConsole) 觀察大型檔案註釋時的堆積使用情形。目標是將堆積使用率維持在最大配置的 70 % 以下。

並行處理考量

GroupDocs.Annotation 實例 非執行緒安全。若需平行工作負載,請為每個執行緒建立獨立的 Annotator,或使用執行緒本地池。

ExecutorService executor = Executors.newFixedThreadPool(4);
for (String path : pdfPaths) {
    executor.submit(() -> {
        try (Annotator a = new Annotator(path)) {
            // annotate
            a.save(path.replace(".pdf", "_annotated.pdf"));
        }
    });
}

進階註釋技巧

單文件多種註釋類型

您可以在一次處理中混合高亮、文字註記與浮水印:

String INPUT_PDF = "YOUR_DOCUMENT_DIRECTORY/input.pdf";
String outputPath = "YOUR_OUTPUT_DIRECTORY/output_annotated.pdf";

// Initialize Annotator with the path to your document
final Annotator annotator = new Annotator(INPUT_PDF);

基於內容的動態註釋

結合 GroupDocs.Annotation 與 Apache PDFBox 或 Tika,自動偵測關鍵字並加入情境說明。

// pseudo‑code: detect the word "confidential"
if (pageText.contains("confidential")) {
    WatermarkAnnotation wm = new WatermarkAnnotation();
    wm.setText("CONFIDENTIAL");
    annotator.add(wm);
}

疑難排解指南

常見錯誤訊息與解決方案

  • 「Invalid license」 – 確認授權檔案已放在 classpath,且類型符合部署需求。
  • 「Unsupported file format」 – 確認 PDF 未損毀、未加密或非零位元組。
  • 效能下降 – 使用串流、及時釋放 Annotator 物件,並考慮批次處理。

啟用日誌

System.setProperty("log4j.configurationFile", "log4j2.xml");

驗證輸入

Objects.requireNonNull(filePath, "File path cannot be null");

常見問答

Q: 如何有效地在單一 PDF 中添加多個註釋?
A: 對每個註釋呼叫 annotator.add(annotation),然後只呼叫一次 save()。GroupDocs 會批次處理變更並一次寫入。

annotator.add(area1);
annotator.add(highlight2);
annotator.save("combined.pdf");

Q: 除了 PDF,GroupDocs.Annotation 支援哪些檔案格式?
A: 它支援超過 50 種格式,包括 DOC、DOCX、PPT、PPTX、XLS、XLSX、JPEG、PNG、TIFF 等等。完整列表請參閱 GroupDocs.Annotation Documentation。

Q: 如何處理受密碼保護的 PDF?

Annotator annotator = new Annotator("secure.pdf", "password123");

Q: 我可以檢索並修改 PDF 中現有的註釋嗎?

List<AnnotationBase> existing = annotator.getAll();
for (AnnotationBase a : existing) {
    if (a instanceof TextAnnotation) {
        ((TextAnnotation) a).setComment("Updated comment");
    }
}
annotator.save("updated.pdf");

Q: 處理大型 PDF 的效能影響是什麼?
A: 超過 50 MB 的檔案應該逐頁串流處理。若在處理完每個頁面批次後釋放 Annotator,記憶體使用量可維持在 150 MB 以下。

Q: 如何在 Web 應用程式中處理並發文件處理?

// each request gets its own Annotator instance
public void processPdf(String path) {
    try (Annotator a = new Annotator(path)) {
        // annotate
        a.save(path);
    }
}

Q: 除錯註釋定位問題的最佳方法是什麼?
A: 先使用已知的矩形(例如 (50, 50, 100, 50))測試並驗證視覺結果。逐步調整座標,並參考 PDF 的頁面尺寸(通常為 612 × 792 點)。

Q: 如何將 GroupDocs.Annotation 整合到 Spring Boot?

@Service
public class PdfAnnotationService {
    public void addComment(String filePath, String comment) throws IOException {
        try (Annotator annotator = new Annotator(filePath)) {
            AreaAnnotation a = new AreaAnnotation();
            a.setRectangle(new Rectangle(100, 200, 250, 80));
            a.setComment(comment);
            annotator.add(a);
            annotator.save(filePath);
        }
    }
}

其他常見問答

Q: 我可以將已註釋的 PDF 匯出為其他格式嗎?
A: 可以,您可以將已註釋的 PDF 轉換為 DOCX、PPTX 或影像格式,同時保留所有標記。

Q: 有沒有方法列出程式庫支援的所有註釋類型?
A: 使用 AnnotationType.values() 可取得所有支援的列舉陣列。

Q: 如何自訂浮水印註釋的外觀?
A: 在加入之前,對 WatermarkAnnotation 設定 setOpacity、setRotation、setBackgroundColor 等屬性。

Q: 程式庫是否支援從資料庫程式化新增評論?
A: 絕對支援。從任何來源讀取評論資料,將文字填入 AreaAnnotation(或 TextAnnotation),再加入文件中。

Q: 如果在批次處理時遇到記憶體洩漏,我該怎麼辦?
A: 確保每個 Annotator 都已關閉(使用 try‑with‑resources),監控 JVM 堆積,並將大型批次拆分為較小的群組。

其他資源


最後更新: 2026-10-16
測試環境: GroupDocs.Annotation 25.2 for Java
作者: GroupDocs

// From file path (most common)
Annotator annotatorFromPath = new Annotator("path/to/document.pdf");

// From InputStream (useful for uploaded files)
FileInputStream inputStream = new FileInputStream("document.pdf");
Annotator annotatorFromStream = new Annotator(inputStream);

// Don't forget to close streams when done!
inputStream.close();
import com.groupdocs.annotation.models.Rectangle;
import com.groupdocs.annotation.models.annotationmodels.AreaAnnotation;

// Create the annotation
AreaAnnotation area = new AreaAnnotation();

// Position and size: x, y, width, height
area.setBox(new Rectangle(100, 100, 100, 100));

// Background color in ARGB format (65535 = yellow with transparency)
area.setBackgroundColor(65535);

// Add the annotation to your document
annotator.add(area);
// Create a semi‑transparent highlight
AreaAnnotation highlight = new AreaAnnotation();
highlight.setBox(new Rectangle(50, 200, 200, 25));
highlight.setBackgroundColor(0x80FFFF00); // Semi‑transparent yellow
highlight.setMessage("Important clause - review carefully");
// Add a comment annotation with custom styling
AreaAnnotation comment = new AreaAnnotation();
comment.setBox(new Rectangle(300, 150, 150, 75));
comment.setBackgroundColor(0x80FF0000); // Semi‑transparent red
comment.setMessage("Needs revision - see discussion in email");
comment.setCreatedOn(new Date());
comment.setUser("John Reviewer");
// Save the annotated document
annotator.save(outputPath);

// Always dispose of resources (critical for memory management)
annotator.dispose();
public void annotateDocument(String inputPath, String outputPath) {
    try (Annotator annotator = new Annotator(inputPath)) {
        // Your annotation code here
        AreaAnnotation area = new AreaAnnotation();
        area.setBox(new Rectangle(100, 100, 100, 100));
        area.setBackgroundColor(65535);
        
        annotator.add(area);
        annotator.save(outputPath);
        
        System.out.println("Document successfully annotated and saved to: " + outputPath);
    } catch (Exception e) {
        System.err.println("Annotation failed: " + e.getMessage());
        throw new RuntimeException("Failed to annotate document", e);
    }
}
public boolean validateInputFile(String filePath) {
    File file = new File(filePath);
    if (!file.exists()) {
        System.err.println("File does not exist: " + filePath);
        return false;
    }
    if (!file.canRead()) {
        System.err.println("Cannot read file: " + filePath);
        return false;
    }
    return true;
}
// Good practice - automatic resource management
try (Annotator annotator = new Annotator(inputPath)) {
    // Annotation code here
} // Automatically disposed

// If manual disposal is needed
Annotator annotator = null;
try {
    annotator = new Annotator(inputPath);
    // Annotation code here
} finally {
    if (annotator != null) {
        annotator.dispose();
    }
}
// Start with simple, visible coordinates for testing
Rectangle testPosition = new Rectangle(50, 50, 100, 50);

// Gradually adjust based on your PDF dimensions
// Most PDFs are 612x792 points (8.5"x11" at 72 DPI)
public void addReviewAnnotation(Annotator annotator, String reviewerName, 
                              String comment, Rectangle position, Color highlightColor) {
    AreaAnnotation review = new AreaAnnotation();
    review.setBox(position);
    review.setBackgroundColor(highlightColor.getRGB());
    review.setMessage(comment);
    review.setUser(reviewerName);
    review.setCreatedOn(new Date());
    
    annotator.add(review);
}
public void processDocumentBatch(List<String> documentPaths) {
    for (String path : documentPaths) {
        try (Annotator annotator = new Annotator(path)) {
            // Process each document independently
            // This prevents memory accumulation
            processAnnotations(annotator);
        }
        
        // Optional: Add small delay for very large batches
        // Thread.sleep(100);
    }
}
Runtime runtime = Runtime.getRuntime();
long memoryBefore = runtime.totalMemory() - runtime.freeMemory();

// Process documents...

long memoryAfter = runtime.totalMemory() - runtime.freeMemory();
System.out.println("Memory used: " + (memoryAfter - memoryBefore) + " bytes");
public class ConcurrentAnnotationProcessor {
    public void processDocumentsConcurrently(List<String> documents) {
        documents.parallelStream().forEach(docPath -> {
            try (Annotator annotator = new Annotator(docPath)) {
                // Each thread gets its own Annotator instance
                processAnnotations(annotator);
            }
        });
    }
}
public void createComprehensiveAnnotation(Annotator annotator) {
    // Highlight important text
    AreaAnnotation highlight = new AreaAnnotation();
    highlight.setBox(new Rectangle(100, 100, 200, 30));
    highlight.setBackgroundColor(0x80FFFF00);
    
    // Add explanatory note
    AreaAnnotation note = new AreaAnnotation();
    note.setBox(new Rectangle(320, 95, 150, 40));
    note.setBackgroundColor(0x80ADD8E6);
    note.setMessage("See reference document #123");
    
    annotator.add(highlight);
    annotator.add(note);
}
// Add to your application properties or logging configuration
java.util.logging.Logger.getLogger("com.groupdocs").setLevel(Level.FINE);
public boolean validateAnnotationParameters(Rectangle box, int color) {
    if (box.getWidth() <= 0 || box.getHeight() <= 0) {
        System.err.println("Invalid annotation dimensions");
        return false;
    }
    
    if (box.getX() < 0 || box.getY() < 0) {
        System.err.println("Annotation position cannot be negative");
        return false;
    }
    
    return true;
}
try (Annotator annotator = new Annotator("document.pdf")) {
    annotator.add(annotation1);
    annotator.add(annotation2);
    annotator.add(annotation3);
    annotator.save("output.pdf"); // All annotations applied at once
}
LoadOptions loadOptions = new LoadOptions();
loadOptions.setPassword("your-password");
Annotator annotator = new Annotator("protected.pdf", loadOptions);
try (Annotator annotator = new Annotator("annotated.pdf")) {
    List<AnnotationInfo> annotations = annotator.get(AnnotationType.Area);
    for (AnnotationInfo annotation : annotations) {
        // Modify properties as needed
        annotation.setMessage("Updated comment");
    }
    annotator.update(annotations);
    annotator.save("updated.pdf");
}
@Service
public class AnnotationService {
    public CompletableFuture<String> annotateAsync(String inputPath) {
        return CompletableFuture.supplyAsync(() -> {
            try (Annotator annotator = new Annotator(inputPath)) {
                // Process annotations
                return processDocument(annotator);
            }
        });
    }
}
@Service
public class DocumentAnnotationService {
    
    public void annotateDocument(MultipartFile file, List<AnnotationRequest> requests) {
        try (InputStream inputStream = file.getInputStream();
             Annotator annotator = new Annotator(inputStream)) {
            
            // Process annotation requests
            requests.forEach(request -> addAnnotation(annotator, request));
            annotator.save("output.pdf");
        }
    }
}

相關教學