如何在 Java 中從帶註釋的文件保存特定頁面

簡介

是否曾在大量帶註釋的文件中苦苦尋找，只想要幾頁特定內容？使用 try with resources java，您可以透過 GroupDocs.Annotation 高效地抽取所需頁面。無論是法律合約、技術手冊或研究論文，只取出相關頁面即可節省儲存空間、加快處理速度，並讓工作流程更整潔。

在本指南中，我們將一步步說明從設定函式庫到進階效能技巧，確保您的 Java 應用程式順暢運行。

學完本章您將掌握：

正確在 Java 專案中設定 GroupDocs.Annotation
使用乾淨、可維護的程式碼實作選擇性頁面保存
避免大多數開發者常犯的陷阱
為大文件處理優化效能
在問題發生前先行排除故障

快速回答

「try with resources java」的作用是什麼？ 它會自動關閉 Annotator，避免檔案鎖定與記憶體洩漏。
哪個函式庫負責頁面範圍保存？ GroupDocs.Annotation 提供 SaveOptions，可使用 setFirstPage / setLastPage。
可以在 Spring Boot 服務中使用嗎？ 可以——請參考「Spring Boot 文件服務整合」章節。
需要授權嗎？ 開發階段可使用免費試用版；正式上線需購買正式授權。
對於大型 PDF（1000+ 頁）安全嗎？ 使用僅載入註釋頁面與批次處理，可保持低記憶體使用量。

為什麼要保存特定頁面？（實務情境）

在談技術細節之前，先說明此功能為何是改變遊戲規則的關鍵：

儲存效能：一份 500 頁的手冊，只在 20 頁上有註釋？與其保存全部 500 頁，不如抽出相關 20 頁，檔案大小可減少 96 %。

更快的處理：檔案變小即代表上傳、下載與處理速度提升。您的使用者（以及伺服器）都會感受到好處。

更佳的使用者體驗：沒有人願意捲動上百頁才找到註釋區段。直接提供所需內容即可。

合規與安全：在受規範限制的產業，可能只能分享文件的特定章節。選擇性保存讓合規更簡單。

前置條件與設定

您需要的環境

Java Development Kit (JDK)：8 版或以上（建議使用 JDK 11+）
Maven 或 Gradle：用於相依管理
GroupDocs.Annotation for Java：版本 25.2 或更新
基本的 Java 知識：了解檔案 I/O 與 OOP

設定 GroupDocs.Annotation for Java

Maven 設定

將以下內容加入 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>

Gradle 設定（如果您是 Gradle 團隊）

repositories {
    maven {
        url "https://releases.groupdocs.com/annotation/java/"
    }
}

dependencies {
    implementation 'com.groupdocs:groupdocs-annotation:25.2'
}

取得授權

以下是大多數教學不會提到的重點：先使用免費試用版。真的很簡單，別把事情想得太複雜。

免費試用：適合測試與開發，從 GroupDocs releases 取得
臨時授權：需要更長時間評估？可取得 temporary license
正式授權：要上線生產環境？請前往 Purchase here

小技巧：試用版雖有些限制，但足以完成本教學並建立概念驗證。

核心實作：保存特定頁面範圍

基本做法（從這裡開始）

先從最簡單的實作入手，這能滿足 90 % 的使用情境：

步驟 1：設定檔案路徑管理

先建立一個工具類別，負責處理檔案路徑（日後變更目錄時會感謝您）：

import org.apache.commons.io.FilenameUtils;

public class FilePathConfiguration {
    public String getOutputFilePath(String inputFile) {
        return "YOUR_OUTPUT_DIRECTORY/SavingSpecificPageRange" + "." + FilenameUtils.getExtension(inputFile);
    }
}

為什麼這樣寫？ 可將路徑邏輯集中管理，便於測試。使用 FilenameUtils 可自動保留原始副檔名。

步驟 2：實作頁面範圍保存

以下是核心程式碼：

import com.groupdocs.annotation.Annotator;
import com.groupdocs.annotation.options.export.SaveOptions;

public class SaveSpecificPageRange {
    public void run(String inputFile) {
        String outputPath = new FilePathConfiguration().getOutputFilePath(inputFile);
        
        try (final Annotator annotator = new Annotator(inputFile)) {
            SaveOptions saveOptions = new SaveOptions();
            saveOptions.setFirstPage(2);  // Start from page 2
            saveOptions.setLastPage(4);   // End at page 4
            
            annotator.save(outputPath, saveOptions);
        }
    }
}

程式說明：

使用 try‑with‑resources java 區塊 (try ( … ))，讓 Annotator 自動關閉，避免檔案鎖定問題。
setFirstPage(2) 與 setLastPage(4) 定義包含式範圍（第 2‑4 頁）。
此範圍在兩端皆為包含，是許多開發者常忽略的細節。

進階檔案路徑設定

在正式環境中，您可能需要更彈性的路徑處理：

public class FilePathConfiguration {
    private final String baseOutputDirectory;
    
    public FilePathConfiguration(String baseOutputDirectory) {
        this.baseOutputDirectory = baseOutputDirectory;
    }
    
    public String getInputFilePath(String filename) {
        return "YOUR_DOCUMENT_DIRECTORY/" + filename;
    }
    
    public String getOutputFilePath(String inputFile, String suffix) {
        String baseName = FilenameUtils.getBaseName(inputFile);
        String extension = FilenameUtils.getExtension(inputFile);
        return String.format("%s/%s_%s.%s", baseOutputDirectory, baseName, suffix, extension);
    }
}

現在可以自動產生 contract_pages_2-4.pdf 等檔名。

常見陷阱與避免方法

陷阱 #1：頁碼索引混淆

問題：誤以為頁碼從 0 開始（實際不是）。

解決方案：頁碼從 1 起算，與實際文件相同。第 1 頁即為第一頁，而非第 0 頁。

// Wrong - this tries to start from page 0 (doesn't exist)
saveOptions.setFirstPage(0);

// Right - this starts from the actual first page
saveOptions.setFirstPage(1);

陷阱 #2：資源洩漏

問題：未正確關閉 Annotator，導致檔案鎖定與記憶體洩漏。

解決方案：始終使用 try‑with‑resources java 或手動關閉：

// Good - automatic resource management
try (final Annotator annotator = new Annotator(inputFile)) {
    // your code here
} // automatically closes

// Also acceptable - manual closing
Annotator annotator = null;
try {
    annotator = new Annotator(inputFile);
    // your code here
} finally {
    if (annotator != null) {
        annotator.dispose();
    }
}

陷阱 #3：無效的頁面範圍

問題：指定的頁面範圍超出文件實際頁數。

解決方案：先驗證範圍是否合法：

public void savePageRangeWithValidation(String inputFile, int firstPage, int lastPage) {
    try (final Annotator annotator = new Annotator(inputFile)) {
        // Get document info to check page count
        DocumentInfo documentInfo = annotator.getDocument().getDocumentInfo();
        int totalPages = documentInfo.getPageCount();
        
        // Validate range
        if (firstPage < 1 || firstPage > totalPages) {
            throw new IllegalArgumentException("First page out of range: " + firstPage);
        }
        if (lastPage < firstPage || lastPage > totalPages) {
            throw new IllegalArgumentException("Last page out of range: " + lastPage);
        }
        
        SaveOptions saveOptions = new SaveOptions();
        saveOptions.setFirstPage(firstPage);
        saveOptions.setLastPage(lastPage);
        
        String outputPath = new FilePathConfiguration().getOutputFilePath(inputFile);
        annotator.save(outputPath, saveOptions);
    }
}

效能優化技巧

大文件的記憶體管理

處理 100 + 頁的大文件時，記憶體使用尤為重要：

public class OptimizedPageRangeSaver {
    public void saveWithOptimization(String inputFile, int firstPage, int lastPage) {
        // Configure for lower memory usage
        LoadOptions loadOptions = new LoadOptions();
        loadOptions.setLoadOnlyAnnotatedPages(true); // Only load pages with annotations
        
        try (final Annotator annotator = new Annotator(inputFile, loadOptions)) {
            SaveOptions saveOptions = new SaveOptions();
            saveOptions.setFirstPage(firstPage);
            saveOptions.setLastPage(lastPage);
            
            // Optional: Enable compression for smaller output files
            saveOptions.setAnnotationsOnly(false); // Set to true if you only want annotations
            
            String outputPath = new FilePathConfiguration().getOutputFilePath(inputFile);
            annotator.save(outputPath, saveOptions);
        }
    }
}

關鍵優化策略

setLoadOnlyAnnotatedPages(true) 可減少記憶體佔用。
setAnnotationsOnly(true) 產生僅包含註釋層的輕量檔案。
若需處理多個檔案，請分批執行。

批次處理多個文件

在需要一次處理大量文件的生產環境中：

public class BatchPageRangeSaver {
    public void processBatch(List<String> inputFiles, int firstPage, int lastPage) {
        for (String inputFile : inputFiles) {
            try {
                savePageRangeWithValidation(inputFile, firstPage, lastPage);
                System.out.println("Successfully processed: " + inputFile);
            } catch (Exception e) {
                System.err.println("Failed to process " + inputFile + ": " + e.getMessage());
                // Log the error and continue with next file
            }
        }
    }
}

與常見框架的整合

Spring Boot 文件服務整合

以下是一個簡易的 Spring Boot 服務，用於頁面範圍保存（請注意 spring boot document service 的說明）：

@Service
public class DocumentPageRangeService {
    
    @Value("${app.document.output-directory}")
    private String outputDirectory;
    
    public String savePageRange(String inputFile, int firstPage, int lastPage) {
        try (final Annotator annotator = new Annotator(inputFile)) {
            SaveOptions saveOptions = new SaveOptions();
            saveOptions.setFirstPage(firstPage);
            saveOptions.setLastPage(lastPage);
            
            String outputPath = generateOutputPath(inputFile, firstPage, lastPage);
            annotator.save(outputPath, saveOptions);
            
            return outputPath;
        } catch (Exception e) {
            throw new DocumentProcessingException("Failed to save page range", e);
        }
    }
    
    private String generateOutputPath(String inputFile, int firstPage, int lastPage) {
        String baseName = FilenameUtils.getBaseName(inputFile);
        String extension = FilenameUtils.getExtension(inputFile);
        return String.format("%s/%s_pages_%d-%d.%s", 
                            outputDirectory, baseName, firstPage, lastPage, extension);
    }
}

實務應用與案例

法律文件處理

律師事務所常需抽取合約或法院文件的特定段落：

public class LegalDocumentProcessor {
    public void extractEvidencePages(String caseFile, List<Integer> evidencePages) {
        // Group consecutive pages for efficient processing
        List<PageRange> ranges = groupConsecutivePages(evidencePages);
        
        for (PageRange range : ranges) {
            String outputFile = String.format("evidence_%d_%d-to-%d.pdf", 
                                            getCaseNumber(caseFile), range.start, range.end);
            savePageRange(caseFile, range.start, range.end, outputFile);
        }
    }
}

教育內容管理

教師為學生作業抽取教科書特定章節：

public class EducationalContentExtractor {
    public void createAssignmentPacket(String textbook, int chapterStart, int chapterEnd) {
        try (final Annotator annotator = new Annotator(textbook)) {
            SaveOptions saveOptions = new SaveOptions();
            saveOptions.setFirstPage(chapterStart);
            saveOptions.setLastPage(chapterEnd);
            
            String assignmentFile = generateAssignmentFileName(textbook, chapterStart, chapterEnd);
            annotator.save(assignmentFile, saveOptions);
        }
    }
}

品質保證審查

僅抽取含有審查意見的頁面，以便集中修訂：

public class QAReviewExtractor {
    public void extractReviewedPages(String document) {
        try (final Annotator annotator = new Annotator(document)) {
            // Get pages with annotations
            List<Integer> annotatedPages = getAnnotatedPageNumbers(annotator);
            
            if (!annotatedPages.isEmpty()) {
                int firstPage = Collections.min(annotatedPages);
                int lastPage = Collections.max(annotatedPages);
                
                SaveOptions saveOptions = new SaveOptions();
                saveOptions.setFirstPage(firstPage);
                saveOptions.setLastPage(lastPage);
                
                String reviewFile = document.replace(".pdf", "_review_comments.pdf");
                annotator.save(reviewFile, saveOptions);
            }
        }
    }
}

最佳實踐摘要

務必驗證輸入參數——在處理前檢查頁面範圍。
使用 try‑with‑resources java——防止資源洩漏與檔案鎖定。
實作完善的錯誤處理——避免單一壞檔案導致整批失敗。
考量記憶體使用——大型文件請使用 setLoadOnlyAnnotatedPages(true)。
測試多種檔案類型——PDF、Word、PowerPoint 可能行為不同。
監控效能——留意處理時間與記憶體使用情況。

常見問題排除

問題：「File is locked」錯誤

症狀：保存時拋出檔案鎖定例外。

原因：

前一次操作未正確關閉 Annotator。
檔案仍被其他程式開啟。
權限不足。

解決方式：

// Ensure proper cleanup
try (final Annotator annotator = new Annotator(inputFile)) {
    // ... your code ...
} // Automatically releases file handles

// Verify file accessibility before processing
File file = new File(inputFile);
if (!file.canRead()) {
    throw new IllegalArgumentException("Cannot read input file: " + inputFile);
}
if (!file.getParentFile().canWrite()) {
    throw new IllegalArgumentException("Cannot write to output directory");
}

問題：記憶體不足錯誤

症狀：處理大型文件時出現 OutOfMemoryError。

解決方式：

增加 JVM 堆積大小，例如 -Xmx2g。
使用前述的最佳化載入選項。
將文件分批處理。

問題：註釋未保留

症狀：輸出檔案不包含原始註釋。

解決方式：確保未在保存過程中剝除註釋：

SaveOptions saveOptions = new SaveOptions();
saveOptions.setAnnotationsOnly(false); // Keep both content and annotations
saveOptions.setFirstPage(firstPage);
saveOptions.setLastPage(lastPage);

常見問答

Q: 能否一次保存非連續頁面（例如第 1、3、7 頁）？
A: 單次操作無法直接完成。需要分別保存每個範圍，或在之後合併結果。

Q: 這能處理受密碼保護的文件嗎？
A: 能，只要在建立 Annotator 時提供密碼，例如 new Annotator(inputFile, loadOptions.setPassword("your_password"))。

Q: 支援哪些檔案格式？
A: PDF、Microsoft Word、Excel、PowerPoint 等多種格式。完整列表請參考 official documentation。

Q: 能否只保存註釋而不包含原始內容？
A: 完全可以——設定 saveOptions.setAnnotationsOnly(true) 即可產生僅含註釋的檔案。

Q: 如何處理極大型文件（1000+ 頁）？
A: 使用 setLoadOnlyAnnotatedPages(true)，分塊處理，必要時增大 JVM 堆積。

Q: 有沒有辦法在保存前預覽頁面？
A: GroupDocs.Annotation 主要聚焦於處理而非檢視，但您可以取得文件資訊（頁數、註釋位置）來協助決定要抽取的範圍。

資源

文件說明： GroupDocs.Annotation for Java Docs
API 參考： Complete API Documentation
下載： Latest Releases
購買： License Options
免費試用： Try It Now
臨時授權： Get Evaluation License
支援： Community Forum

最後更新： 2026-01-10
測試環境： GroupDocs.Annotation 25.2 (Java)
作者： GroupDocs