使用 Java 搜尋文件中特定頁面的條碼

介紹

曾經花了好幾個小時手動驗證數百份文件中的簽名嗎？你並不孤單。無論你是在構建合約管理系統、自動化發票處理，或是保護醫療記錄，手動追蹤並驗證條碼簽名既繁瑣又容易出錯。在本教學中，你將學會如何使用 GroupDocs.Signature 於 Java 搜尋條碼頁面，從而以程式方式僅針對關鍵頁面、即時監控進度，並僅用幾行 Java 程式碼處理各種條碼格式。

你將學到

  • 在 Java 專案中設定 GroupDocs.Signature（≈5 分鐘）
  • 訂閱搜尋事件以即時追蹤進度
  • 設定智慧搜尋選項以鎖定特定頁面
  • 高效執行搜尋並處理結果

快速回答

  • 哪個函式庫可協助搜尋特定條碼頁面？ GroupDocs.Signature for Java
  • 典型設定時間？ 約 5 分鐘即可加入 Maven/Gradle 相依性並套用授權
  • 我可以將搜尋限制在首頁與末頁嗎？ 可以 – 使用 PagesSetup 指定精確頁碼
  • 支援哪些條碼格式？ QR Code、Code128、Code39、DataMatrix、EAN/UPC 等多種
  • 生產環境需要付費授權嗎？ 生產環境必須使用完整授權；試用版可用於評估

什麼是「搜尋條碼特定頁面」？

搜尋條碼特定頁面是指指示簽名引擎只在你關心的頁面上（例如首頁、末頁或任何自訂範圍）尋找條碼簽名。此聚焦方式可加快處理速度、降低記憶體使用，並讓你建立即時回饋的 UI。

為什麼要使用 GroupDocs.Signature 完成此任務？

GroupDocs.Signature 提供高階 API，抽象掉低階的條碼解碼、頁面渲染與文件格式處理。它支援 超過 20 種條碼格式，且能在 不將整個檔案載入記憶體 的情況下處理 數百頁的文件，讓你專注於業務邏輯，而非檔案解析。

前置條件

  • 已安裝 JDK 8+
  • Maven 或 Gradle 以管理相依性
  • 具備 Java 類別、方法與例外處理的基本概念
  • 取得 GroupDocs.Signature 授權（試用或正式）

為 Java 設定 GroupDocs.Signature

Maven 設定

將相依性加入 pom.xml：

<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-signature</artifactId>
    <version>23.12</version>
</dependency>

Gradle 設定

或在 build.gradle 中加入：

implementation 'com.groupdocs:groupdocs-signature:23.12'

想手動下載？可直接從 GroupDocs 下載頁面 取得最新發行版。

取得授權

  • 免費試用 – 立即開始，無需承諾
  • 臨時授權 – 完整功能供評估使用
  • 正式授權 – 生產環境就緒，無使用限制

使用以下簡易初始化程式碼驗證安裝：

import com.groupdocs.signature.Signature;

public class SignatureSetup {
    public static void main(String[] args) {
        // Initialize the Signature instance with the document path
        Signature signature = new Signature("YOUR_DOCUMENT_PATH");
        
        System.out.println("GroupDocs.Signature for Java initialized successfully.");
    }
}

專業提示： 把 "YOUR_DOCUMENT_PATH" 替換為實際的 PDF、DOCX 或 XLSX 檔案。若主控台印出成功訊息，即表示已可使用。

了解條碼簽名類型

條碼在文件中嵌入機器可讀的資料。與手寫簽名不同，條碼可儲存 ID、時間戳、URL 或 JSON 負載，十分適合自動驗證。

條碼類型最適用途典型資料長度
QR Code高密度資料、URL、 多行文字最多 4,296 個字元
Code128字母數字追蹤編號可變長度
Code39簡易舊式代碼最多 43 個字元
DataMatrix小標籤、醫療記錄最多 2,335 個字元
EAN/UPC商品識別、零售8‑13 位數字

當你需要快速機器讀取、結構化資料或防篡改簽名時，條碼往往是最佳選擇。

如何在 Java 中搜尋條碼頁面？

Signature 是代表待處理文件的主要類別。使用 new Signature("file.pdf") 載入文件，BarcodeSearchOptions 定義搜尋條碼簽名的參數，並設定目標頁面，最後呼叫 signature.search(options)。search 方法會根據提供的選項執行搜尋，並回傳 BarcodeSignature 物件清單，內含頁碼、解碼文字與幾何座標——一次完成所有工作，免除額外的影像抽取或自訂解碼程式。

了解整體流程後，接下來深入三個核心功能的實作。

功能 1：訂閱文件搜尋事件

為何重要

在處理大量批次時，即時回饋（例如進度條）可提升使用者體驗，並協助及早偵測卡住的情況。

定義錨點

Signature 代表文件，提供事件訂閱功能。

實作

Signature signature = new Signature("YOUR_DOCUMENT_PATH");

signature.SearchStarted.add(new ProcessStartEventHandler() {
    public void invoke(Signature sender, ProcessStartEventArgs args) {
        System.out.println("Search process started at " + args.getStarted()
            + " with " + args.getTotalSignatures() + " total signatures to be put in document");
    }
});

signature.SearchProgress.add(new ProcessProgressEventHandler() {
    public void invoke(Signature sender, ProcessProgressEventArgs args) {
        System.out.println("Search progress. Processed " + args.getProcessedSignatures()
            + " signatures. Time spent " + args.getTicks() + " mlsec");
    }
});

signature.SearchCompleted.add(new ProcessCompleteEventHandler() {
    public void invoke(Signature sender, ProcessCompleteEventArgs args) {
        System.out.println("Search process completed at " + args.getCompleted()
            + " with " + args.getTotalSignatures() + " total signatures. Process took "
            + args.getTicks() + " mlsec");
    }
});

這三個處理器分別提供開始時間、即時進度與最終統計資訊，適合用於日誌或 UI 更新。

功能 2：為特定頁面設定條碼搜尋選項

為何需要細粒度控制

掃描 200 頁合約的每一頁會浪費大量 CPU。僅針對首頁與末頁即可將執行時間縮短 最高 80 %。

定義錨點

PagesSetup 指定搜尋作業包含哪些頁面。

實作

import com.groupdocs.signature.domain.enums.TextMatchType;
import com.groupdocs.signature.options.search.BarcodeSearchOptions;

BarcodeSearchOptions options = new BarcodeSearchOptions();

options.setAllPages(false); // Opt‑in selective page searching
options.setPageNumber(1);   // Starting page (optional)

import com.groupdocs.signature.options.PagesSetup;

PagesSetup pagesSetup = new PagesSetup();
pagesSetup.setFirstPage(true);   // Include first page
pagesSetup.setLastPage(true);    // Include last page
pagesSetup.setOddPages(false);   // Skip odd pages
pagesSetup.setEvenPages(false);  // Skip even pages
options.setPagesSetup(pagesSetup);

options.setMatchType(TextMatchType.Contains);
options.setText("12345");
  • 匹配類型 讓你微調文字搜尋（Contains、Exact、StartsWith、EndsWith）。
  • 調整 setAllPages 與 PagesSetup 即可 僅搜尋條碼特定頁面。

功能 3：執行搜尋並處理結果

為何此步驟關鍵

找到條碼只是第一步，你還必須對資料進行驗證、儲存或觸發工作流程。

定義錨點

BarcodeSignature 代表偵測到的條碼，包含頁碼、解碼文字等屬性。

實作

import java.util.List;
import com.groupdocs.signature.domain.signatures.BarcodeSignature;

try {
    List<BarcodeSignature> signatures = signature.search(BarcodeSignature.class, options);
    System.out.println("Source document contains following signatures.");
    
    for (BarcodeSignature barcodeSignature : signatures) {
        System.out.println("Barcode signature found at page " + barcodeSignature.getPageNumber()
            + " with type " + barcodeSignature.getEncodeType() + " and text " + barcodeSignature.getText());
    }
} catch (Exception e) {
    throw new RuntimeException(e.getMessage(), e);
}

現在你已取得 BarcodeSignature 物件清單，每個物件提供：

  • getPageNumber() – 條碼所在頁碼
  • getEncodeType() – QR、Code128 等類型
  • getText() – 解碼後的負載
  • 位置 (getLeft()、getTop()) 與尺寸 (getWidth()、getHeight())

範例：僅處理最後一頁的 QR Code

for (BarcodeSignature barcodeSignature : signatures) {
    if (barcodeSignature.getPageNumber() == lastPageNumber 
        && barcodeSignature.getEncodeType().equals("QRCode")) {
        // Process only QR codes from the final page
        processApprovalCode(barcodeSignature.getText());
    }
}

真實案例應用

情境條碼特定頁面搜尋的幫助
合約驗證在簽名頁自動驗證 QR 編碼的憑證雜湊
供應鏈追蹤在清單的首頁/末頁定位 Code128 出貨編號
醫療同意書從最終同意頁提取 DataMatrix 病患 ID
發票自動化在發票任意位置找尋「APPR‑」前綴條碼，然後路由處理

常見問題與解決方案

問題 1 – 雖有條碼卻無結果

// Ensure you are not limiting pages too aggressively
options.setAllPages(true);

若條碼以點陣圖形式嵌入，請考慮使用 GroupDocs.Image 進行影像基礎的偵測。

問題 2 – 大檔案效能緩慢

PagesSetup pagesSetup = new PagesSetup();
pagesSetup.setLastPage(true);  // Most signatures are on the last page
pagesSetup.setFirstPage(true);
options.setPagesSetup(pagesSetup);

針對特定頁面可大幅降低處理時間；將 150 頁 PDF 的搜尋時間由約 4 秒降至 <1 秒，只要限制在兩頁內。

問題 3 – TextMatchType 找不到預期條碼

String searchText = "12345".trim().toLowerCase();
options.setText(searchText);
options.setMatchType(TextMatchType.StartsWith); // Try a more permissive mode

問題 4 – 長時間迴圈導致記憶體泄漏

try (Signature signature = new Signature("document.pdf")) {
    List<BarcodeSignature> signatures = signature.search(BarcodeSignature.class, options);
    // Process signatures
}

使用 try‑with‑resources 區塊可自動釋放 Signature 實例。

生產環境最佳實踐

強韌的錯誤處理

try {
    List<BarcodeSignature> signatures = signature.search(BarcodeSignature.class, options);
} catch (com.groupdocs.signature.exception.GroupDocsSignatureException e) {
    logger.error("GroupDocs error: " + e.getMessage());
} catch (Exception e) {
    logger.error("Unexpected error: " + e.getMessage(), e);
}

文件不可變時快取結果

Map<String, List<BarcodeSignature>> cache = new ConcurrentHashMap<>();

public List<BarcodeSignature> getCachedSignatures(String docId) {
    return cache.computeIfAbsent(docId, id -> performSearch(id));
}

使用進度事件提供 UI 回饋

signature.SearchProgress.add(new ProcessProgressEventHandler() {
    public void invoke(Signature sender, ProcessProgressEventArgs args) {
        int percent = (args.getProcessedSignatures() * 100) / args.getTotalSignatures();
        updateProgressBar(percent);
    }
});

驗證條碼負載

for (BarcodeSignature barcodeSignature : signatures) {
    String text = barcodeSignature.getText();
    if (!text.matches("APPR-\\d{4}-\\d{3}")) {
        logger.warn("Invalid format: " + text);
        continue;
    }
    if (!validateChecksum(text)) {
        logger.error("Checksum failed for: " + text);
        flagForManualReview(document);
    }
}

依文件類型最佳化頁面選擇

PagesSetup contractsSetup = new PagesSetup();
contractsSetup.setLastPage(true); // Contracts usually signed on last page
options.setPagesSetup(contractsSetup);

搜尋後依條碼類型過濾（若只需 QR Code）

for (BarcodeSignature sig : signatures) {
    if ("QRCode".equals(sig.getEncodeType())) {
        // Process QR code
    }
}

取得條碼影像尺寸（若需渲染）

for (BarcodeSignature sig : signatures) {
    int width = sig.getWidth();
    int height = sig.getHeight();
    // Use dimensions for overlay or thumbnail generation
}

常見問答

Q: 可以一次呼叫搜尋多種條碼格式嗎？
A: 可以。BarcodeSearchOptions 預設會搜尋所有支援的格式。若只需特定類型，可於結果中以 getEncodeType() 篩選。

Q: 若文件同時包含條碼與影像簽名，該如何處理？
A: 分別執行搜尋 – 使用 BarcodeSignature.class 處理條碼，ImageSignature.class 處理影像簽名，然後依需求合併結果。

Q: 搜尋全部頁面與僅搜尋特定頁面的效能差異為何？
A: 以 50 頁 PDF 為例，完整掃描需 3–5 秒；限定首頁＋末頁通常在 1 秒以內完成。

Q: 這能用於掃描版 PDF（點陣圖）嗎？
A: 只有條碼以數位簽名物件形式加入時才可。若僅為點陣圖條碼，需使用影像式條碼辨識器（例如 GroupDocs.Barcode）。

Q: 如何驗證條碼簽名未被竄改？
A: 在條碼負載中嵌入雜湊或數位簽章，然後對原始資料重新計算雜湊並比對。此作法需要原始簽署金鑰或憑證。

最後更新： 2026-06-21
測試環境： GroupDocs.Signature 23.12 for Java
作者： GroupDocs

相關教學