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

介紹

曾經花了好幾個小時手動驗證數百份文件中的簽章嗎?你並不孤單。無論你是要建置合約管理系統、自動化發票處理,或是保護醫療紀錄,手動追蹤與驗證條碼簽章既繁瑣又容易出錯。

在本指南中,我們將示範 如何以程式方式在文件中搜尋特定頁面的條碼,使用 Java 與 GroupDocs.Signature。完成後,你將能在指定頁面偵測簽章、即時監控搜尋進度,並處理各種條碼格式,全部以乾淨且易於維護的程式碼實現。

您將學習

  • 在 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,抽象掉低階的條碼解碼、頁面渲染與文件格式處理。它原生支援 PDF、DOCX、XLSX 等多種格式,讓你專注於業務邏輯,而不必自行解析檔案。

前置條件

  • JDK 8+ 已安裝
  • MavenGradle 用於相依管理
  • 具備 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 download page 取得最新發行版本。

取得授權

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

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

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 位數字

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

如何搜尋特定頁面的條碼

我們將實作分為三個重點功能。

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

為何重要

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

實作

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%。

實作

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");
  • 比對類型 讓你微調文字搜尋(ContainsExactStartsWithEndsWith)。
  • 調整 setAllPagesPagesSetup,即可 僅搜尋特定頁面的條碼

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

為何此步驟重要

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

實作

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

針對特定頁面的搜尋可大幅縮短處理時間。

問題 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-01-29
測試環境: GroupDocs.Signature 23.12 for Java
作者: GroupDocs