使用 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 码

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 发货 ID
医疗同意书从最终同意页提取 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 码时)

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
}

常见问答

问:可以在一次调用中搜索多种条形码格式吗?
答:可以。BarcodeSearchOptions 默认搜索所有受支持的格式。若只需特定类型,可通过 getEncodeType() 过滤结果。

问:如何处理同时包含条形码和图像签名的文档?
答:分别执行搜索——使用 BarcodeSignature.class 查找条形码,使用 ImageSignature.class 查找图像签名,然后根据需要合并结果。

问:搜索所有页面与特定页面的性能差异如何?
答:对 50 页 PDF 全页扫描可能需要 3–5 秒。限制为首页+末页通常在 1 秒以内完成。

问:这对扫描的 PDF(光栅图像)有效吗?
答:仅当条形码作为数字签名对象添加时有效。对于仅包含光栅图像的条形码,需要使用基于图像的条形码识别器(如 GroupDocs.Barcode)。

问:如何验证条形码签名未被篡改?
答:在条形码负载中嵌入哈希或数字签名,然后对原始数据重新计算哈希并比较。此过程需要原始签名密钥或证书。


最后更新: 2026-06-21
测试环境: GroupDocs.Signature 23.12 for Java
作者: GroupDocs

相关教程