使用 HIBC 在 Java 中对 PDF 进行条形码签名

如果您正在构建制药或医疗保健物流软件，可能已经遇到纸质跟踪、签名丢失和审计噩梦的难题。在 PDF 上使用条形码签名——尤其是 HIBC 数据矩阵或 QR 码——可以创建防篡改、机器可读的痕迹，能够经受打印、扫描和监管审查。在本教程中，您将看到如何使用 GroupDocs.Signature for Java 将数据矩阵和 QR 条形码同时添加到 PDF 中。

快速答案

  • 什么库在 Java 中处理 HIBC 条形码？ GroupDocs.Signature for Java。
  • 哪种条形码格式最紧凑？ Data Matrix – 适用于小标签。
  • 我可以在同一个 PDF 中同时添加 QR 和 Data Matrix 吗？ 是的，只需创建单独的 QrCodeSignOptions。
  • 运行时需要互联网连接吗？ 不需要，库在安装后可完全离线工作。
  • 推荐使用哪个 Java 版本？ Java 11+ 以获得生产级性能。

什么是 HIBC 条形码 PDF 签名？

Signature 是 GroupDocs.Signature 的核心类，代表 PDF 文档并支持嵌入数字签名。GroupDocs.Signature for Java 中的 Signature 类提供将 HIBC 条形码作为数字签名嵌入的方法。通过使用 HIBC 条形码对 PDF 进行签名，您可以创建可验证、防篡改的记录，供应链中的任何环节都可以扫描。

为什么要同时使用 Data Matrix 和 QR 码？

Data Matrix 提供最小的占用空间，同时可容纳多达 2,335 个字母数字字符，非常适合密集的标签区域。QR 码则支持多达 4,296 个字符，并且可以被智能手机普遍读取。将两者结合，可在空间效率和数据容量之间取得最佳平衡，确保从仓库扫描仪到移动应用的所有利益相关者都能读取所需信息。

前提条件

  • JDK 11 或更高（Java 8 也可运行，但推荐使用 Java 11+ 以获得最佳性能）。
  • IDE，如 IntelliJ IDEA、Eclipse 或带有 Java 扩展的 VS Code。
  • Maven 或 Gradle 用于依赖管理（示例见下）。
  • 示例 PDF（例如 sample.pdf）用于测试实现。
  • 有效的 GroupDocs.Signature 许可证（开发阶段免费试用，生产环境需付费许可证）。

为 Java 设置 GroupDocs.Signature

Maven 配置

将依赖添加到您的 pom.xml：

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

Gradle 配置

对于 Gradle 项目，将以下内容添加到您的 build.gradle：

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

直接下载选项

您也可以直接从 GroupDocs.Signature for Java 发布 下载 JAR 文件，并手动将其添加到项目的类路径中。这种方式在受限网络环境下效果良好。

获取许可证

向 GroupDocs 申请免费试用或临时许可证，以去除水印并解锁所有功能。生产部署需要购买许可证。

基本初始化

Signature 是所有签名操作的入口。它加载 PDF，应用条形码，并写入签名文件。

import com.groupdocs.signature.Signature;

class InitializeSignature {
    public static void main(String[] args) {
        Signature signature = new Signature("sample.pdf");
        // Proceed with signing operations...
    }
}

如何使用 HIBC 条形码创建 Data Matrix PDF？

实例化 Signature 并提供源 PDF，将 QrCodeSignOptions 设置为 Data Matrix 格式，提供正确格式的 HIBC 字符串，然后调用 sign()。库会将签名后的 PDF 写入目标位置，保持布局并将条形码嵌入为防篡改签名。

QrCodeSignOptions 指定签名的条形码类型、内容、大小和放置位置。

  1. 导入所需的类 – 这些类提供签名引擎和 Data Matrix 选项的访问。
import com.groupdocs.signature.Signature;
import com.groupdocs.signature.options.sign.QrCodeSignOptions;
import com.groupdocs.signature.domain.qrcodes.QrCodeTypes;
  1. 实例化 Signature 对象，使用源文件和目标文件的绝对路径。
String sourceFilePath = "YOUR_DOCUMENT_DIRECTORY";
String destinFilePath = "YOUR_OUTPUT_DIRECTORY/SignWithHIBCLICQR.pdf";

final Signature signature = new Signature(sourceFilePath);
  1. 配置 Data Matrix 选项 – 设置 HIBC 字符串，选择 QrCodeTypes.HIBCLICDataMatrix，并定义放置坐标。QrCodeTypes 列举了 HIBC 签名支持的条形码格式。
QrCodeSignOptions hibcLic_QR = new QrCodeSignOptions("A123PROD30917/75#422011907#GP293", QrCodeTypes.HIBCLICQR);
hibcLic_QR.setLeft(1); // Set the position from left
hibcLic_QR.setTop(1);   // Set the position from top
hibcLic_QR.setReturnContent(true); // Return content after signing
hibcLic_QR.setReturnContentType(FileType.PNG); // Specify return content type as PNG
  1. 将签名应用 到 PDF。
signature.sign(destinFilePath, hibcLic_QR);
  1. 释放资源，以关闭文件句柄并避免内存泄漏。
finally {
    if (signature != null) signature.dispose();
}

完整工作示例

以下是单块完整流程（占位符代表您从前面代码片段中复制的确切代码）：

import com.groupdocs.signature.Signature;
import com.groupdocs.signature.options.sign.QrCodeSignOptions;
import com.groupdocs.signature.domain.qrcodes.QrCodeTypes;

public class HibcQrSigning {
    public static void main(String[] args) {
        String sourceFilePath = "sample.pdf";
        String destinFilePath = "output/SignWithHIBCLICQR.pdf";
        
        Signature signature = null;
        try {
            signature = new Signature(sourceFilePath);
            
            QrCodeSignOptions hibcLic_QR = new QrCodeSignOptions(
                "A123PROD30917/75#422011907#GP293", 
                QrCodeTypes.HIBCLICQR
            );
            hibcLic_QR.setLeft(1);
            hibcLic_QR.setTop(1);
            hibcLic_QR.setReturnContent(true);
            hibcLic_QR.setReturnContentType(FileType.PNG);
            
            signature.sign(destinFilePath, hibcLic_QR);
            System.out.println("PDF signed successfully with HIBC QR code");
            
        } catch (Exception e) {
            System.err.println("Error signing PDF: " + e.getMessage());
            e.printStackTrace();
        } finally {
            if (signature != null) signature.dispose();
        }
    }
}

直接答案（40–70 字）

要 创建 Data Matrix PDF，实例化 Signature 并提供源 PDF，将 QrCodeSignOptions 设置为 QrCodeTypes.HIBCLICDataMatrix 并提供正确格式的 HIBC 字符串，然后调用 signature.sign(outputPath, options)。库会将签名后的 PDF 写入目标位置，保持布局并将条形码嵌入为防篡改签名。

如何使用 GroupDocs.Signature 向 PDF 添加 QR 码？

加载 PDF，配置 QrCodeSignOptions 为 QR 格式，然后调用 sign()。库会缩放 QR 图像以提高可读性，并根据您设置的坐标进行定位，避免与现有内容重叠。这确保条形码在打印后仍可扫描，并符合 HIBC 标准。

QrCodeSignOptions 定义 QR 条形码的内容、大小和位置。

  1. 导入 QR 专用类
QrCodeSignOptions hibcLic_AZ = new QrCodeSignOptions("A123PROD30917/75#422011907#GP293", QrCodeTypes.HIBCLICAztec);
hibcLic_AZ.setLeft(1); // Set the position from left
hibcLic_AZ.setTop(200); // Set the position from top
hibcLic_AZ.setReturnContent(true); // Return content after signing
hibcLic_AZ.setReturnContentType(FileType.PNG); // Specify return content type as PNG
  1. 创建并配置 QR 选项 – 注意使用 QrCodeTypes.HIBCLICQR。
signature.sign(destinFilePath, hibcLic_AZ);
  1. 签署文档
QrCodeSignOptions hibcLic_DM = new QrCodeSignOptions("A123PROD30917/75#422011907#GP293", QrCodeTypes.HIBCLICDataMatrix);
hibcLic_DM.setLeft(1); // Set the position from left
hibcLic_DM.setTop(400); // Set the position from top
hibcLic_DM.setReturnContent(true); // Return content after signing
hibcLic_DM.setReturnContentType(FileType.PNG); // Specify return content type as PNG

直接答案： 在 QrCodeSignOptions 中使用 QrCodeTypes.HIBCLICQR，设置 HIBC 内容字符串，使用 setLeft() 和 setTop() 定位代码，然后调用 signature.sign(outputPath, options)。QR 条形码会立即嵌入，随时可供智能手机或扫描仪捕获。

常见错误避免

1. 忘记释放资源

错误：

Signature signature = new Signature("sample.pdf");
signature.sign(destinFilePath, options);
// Oops, no dispose() call

修复： 将 Signature 用法放入 try‑with‑resources 块中，或在 finally 子句中显式调用 close()。

2. 使用不正确的 HIBC 格式字符串

错误： 使用诸如 “12345” 的通用字符串。
修复： 遵循 HIBCC 标准（例如 A123PROD30917/75#422011907#GP293）。使用 HIBCC 在线验证器 进行验证。

3. 硬编码文件路径

错误：

String sourceFilePath = "C:/Users/John/Documents/test.pdf";

修复： 将路径存储在配置文件或环境变量中，并在运行时读取。

4. 忽视条形码位置冲突

将条形码放置在现有文本或签名之外。使用 PDF 坐标（原点在左下角），并使用打印样本进行测试。

5. 未使用真实扫描仪进行测试

打印签名后的 PDF，并使用工作流中实际使用的硬件进行扫描。验证在不同打印质量下的可读性。

医疗保健中的实际应用

场景推荐条形码适用原因
药品分销QR Code高数据容量，智能手机广泛扫描。
库存管理Data Matrix占用空间小，适用于密集的货架标签。
合规监管（FDA 21 CFR Part 11）QR + Data Matrix双格式提供冗余和可审计性。
医疗器械追踪Aztec Code紧凑尺寸适用于空间受限的包装。

性能考虑因素与最佳实践

批处理模式

List<String> filesToSign = getFileList();
for (String filePath : filesToSign) {
    Signature signature = null;
    try {
        signature = new Signature(filePath);
        // Sign and save
    } finally {
        if (signature != null) signature.dispose();
    }
}
  • 为每个文件创建新的 Signature 实例，以保持内存使用低。
  • 使用固定线程池（Executors.newFixedThreadPool(Runtime.getRuntime().availableProcessors() - 1)）进行并行处理，但要监控堆大小，因为每个 Signature 会在内存中保存完整的 PDF。

保持库更新

GroupDocs 的更新可将处理速度提升至 20 %，并添加新的 HIBC 合规功能。建议每季度进行依赖检查。

缓存模板

一次加载 PDF 模板，针对每种条形码变体进行克隆并签名这些克隆。这样可减少 I/O 并加快大批量工作流的速度。

常见问题解答

Q: GroupDocs.Signature 能签署除 PDF 之外的文件类型吗？
A: 可以，它同样支持 DOCX、XLSX、PPTX、PNG、JPEG 和 TIFF，使用相同的条形码签名 API。

Q: 如何排查 “Invalid barcode content” 错误？
A: 确认您的 HIBC 字符串严格遵循 HIBCC 语法，使用在线验证器，并确保为所选格式使用正确的 QrCodeTypes 常量。

Q: 每种 HIBC 格式的最大数据容量是多少？
A: QR ≈ 4,296 个字母数字字符，Aztec ≈ 3,832 个数字 / 3,067 个字母数字，Data Matrix ≈ 3,116 个数字 / 2,335 个字母数字。为获得最佳扫描可靠性，建议将代码长度保持在 200 字符以下。

Q: 能在同一个 PDF 中嵌入多种条形码类型吗？
A: 完全可以。为不同位置创建单独的 QrCodeSignOptions 对象，并对每个调用 signature.sign()。只需确保它们不重叠。

Q: 运行时签名是否需要互联网连接？
A: 不需要。将 JAR 放入类路径并激活许可证后，所有操作均在本地完成。

其他资源

最后更新： 2026-09-15
测试环境： GroupDocs.Signature 23.12 for Java
作者： GroupDocs

相关教程