如何在 PDF 文档中创建条形码签名 Java

介绍

在本教程中，您将学习如何使用 GroupDocs.Signature create barcode signature Java 为 PDF 文件添加条形码签名。无论是需要在合同中嵌入产品代码、审计 ID，还是任何结构化数据，条形码签名都可以让您添加可机器读取的信息，立即扫描，同时保持文档的加密安全性。我们将逐步演示设置、代码、定制以及最佳实践技巧，让您在几分钟内开始向 PDF 添加条形码签名。

快速答案

  • 什么库在 Java 中添加条形码签名？ GroupDocs.Signature for Java.
  • 哪种条形码类型最适合零售？ GS1CompositeBar (industry‑standard for product tracking).
  • 我需要生产环境的许可证吗？ 是 – 需要购买 GroupDocs 许可证。
  • 我可以同时添加数字签名和条形码签名吗？ 当然；可以将它们组合使用，以实现安全性和可扫描性。
  • 代码兼容 Java 11 及更高版本吗？ 是的，API 支持 JDK 8+。

什么是 create barcode signature java？

create barcode signature java 指的是使用 Java 代码以编程方式将条形码嵌入 PDF 的过程。GroupDocs.Signature 提供了简洁的 API，能够生成条形码图像、定位到页面并在一次无缝操作中保存签名文档。

为什么使用条形码签名？

条形码签名为合法签署的 PDF 提供 机器可读的元数据。它们实现即时可视化验证，简化供应链扫描，并让下游系统在不打开文件的情况下提取结构化数据。支持超过 60 种条形码格式，GS1CompositeBar 可在单个紧凑符号中编码产品标识、序列号和批次码——非常适合零售、医疗和金融等行业。

前置条件

  • Java 开发工具包： JDK 8 或更高（Java 11、17、21 都可）。
  • 构建工具： Maven 或 Gradle – 任选其一。
  • IDE： IntelliJ IDEA、Eclipse 或 VS Code。
  • GroupDocs.Signature 库： 按下文添加依赖。
  • 许可证： 开发阶段可使用免费试用版，生产环境需购买许可证。

将 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 提供免费试用版，适合测试和开发。您可以从其 releases page 下载。准备投产时，需要购买许可证或从 GroupDocs website 申请临时许可证。详细的 API 用法请参阅 API Reference，步骤请查看 Developer Guide，如有疑问可在 GroupDocs Forum 提问。同一购买链接也列在 purchase page。

如何在 Java 中设置 GroupDocs.Signature？

Signature 类代表文档，并提供应用签名、搜索内容和管理资源的方法。创建 Signature 实例以打开 PDF 并准备签署。Signature 类是 GroupDocs.Signature 的核心组件，负责文档加载、资源处理和签署工作流，确保所有操作安全高效。

import com.groupdocs.signature.Signature;

// Point to your PDF file
Signature signature = new Signature("path/to/your/document.pdf");

重要提示： 使用完毕后务必释放 Signature 对象——这会关闭文件句柄并释放内存。

如何配置条形码签名选项？

BarcodeSignOptions 类定义了即将嵌入的条形码的所有细节，从数据负载到视觉样式。它是所有条形码相关设置的容器，包括类型、尺寸、颜色和位置。下面的最小配置创建了一个包含 GTIN 和序列号的 GS1CompositeBar 条形码，并演示了如何设置边距和背景色以获得最佳可读性。

import com.groupdocs.signature.options.sign.BarcodeSignOptions;
import com.groupdocs.signature.domain.barcodes.BarcodeTypes;

// Create barcode with GS1 format data
BarcodeSignOptions options = new BarcodeSignOptions("(01)03212345678906/(21)A1B2C3D4E5F6G7H8");
options.setEncodeType(BarcodeTypes.GS1CompositeBar);

字符串 "(01)03212345678906/(21)A1B2C3D4E5F6G7H8" 符合 GS1 标准：

  • (01) = GTIN（全球产品标识符）
  • 03212345678906 = 实际产品代码
  • (21) = 序列号标识符
  • A1B2C3D4E5F6G7H8 = 唯一序列号

您可以将其替换为 QR 码、Code128、DataMatrix 等任意文本。支持超过 60 种条形码类型——完整列表请参阅 GroupDocs 文档。

如何定位和自定义条形码？

位置和样式通过同一个 BarcodeSignOptions 对象控制。使用 setTop、setLeft、setWidth、setHeight 定义精确坐标和尺寸。setAllPages(true) 会自动在每页添加条形码，setPageNumber(1) 则定位到特定页。还可以旋转条形码、添加背景色或调整边距，确保条形码不与现有内容重叠。

// Set position and apply to all pages
options.setTop(200); // Set vertical position
options.setAllPages(true);

如需更精确的布局，还可以将条形码锚定到特定页面、旋转或添加背景色：

options.setLeft(100);        // 100 pixels from left edge
options.setTop(200);         // 200 pixels from top
options.setWidth(300);       // Barcode width in pixels
options.setHeight(100);      // Barcode height in pixels
options.setPageNumber(1);    // Only sign page 1 (removes setAllPages)

通过额外属性可进行视觉定制（前景/背景颜色、边距、文本标签）：

options.setMargin(new Padding(10));           // Add padding around barcode
options.setBackground(new Background());       // Set background color
options.setForeColor(Color.BLACK);            // Barcode color
options.setBackgroundColor(Color.WHITE);      // Background color

如何使用条形码签署文档？

Signature 实例的 sign 方法会应用配置好的选项并将签署后的文档写入磁盘。它返回一个 SignResult 对象，告知已应用的签名数量以及是否出现警告。该方法封装了所有低层 PDF 操作，您无需直接使用 PDF 库。

try {
    SignResult signResult = signature.sign(outputPath, options);
    System.out.println("Document signed successfully!");
    System.out.println("Signed document saved to: " + outputPath);
} finally {
    if (signature != null) {
        signature.dispose();
    }
}

外围的 try‑finally 块确保即使出现异常也会释放 Signature 对象，防止文件句柄泄漏。

您可以检查 SignResult 以确认成功：

if (signResult.getSucceeded().size() > 0) {
    System.out.println("Successfully added " + signResult.getSucceeded().size() + " signature(s)");
}

完整工作示例

将所有步骤整合在一起，下面的单个方法演示了加载 PDF、添加 GS1CompositeBar 条形码并保存签名文件：

import com.groupdocs.signature.Signature;
import com.groupdocs.signature.options.sign.BarcodeSignOptions;
import com.groupdocs.signature.domain.barcodes.BarcodeTypes;

public class BarcodeSigningExample {
    
    public void signPdfWithBarcode(String inputPath, String outputPath) {
        Signature signature = null;
        
        try {
            // Initialize signature
            signature = new Signature(inputPath);
            
            // Configure barcode
            BarcodeSignOptions options = new BarcodeSignOptions(
                "(01)03212345678906/(21)A1B2C3D4E5F6G7H8"
            );
            options.setEncodeType(BarcodeTypes.GS1CompositeBar);
            options.setTop(200);
            options.setAllPages(true);
            
            // Sign and save
            SignResult result = signature.sign(outputPath, options);
            
            System.out.println("Signing completed: " + result.getSucceeded().size() + " signature(s) added");
            
        } catch (Exception e) {
            System.err.println("Error signing document: " + e.getMessage());
            e.printStackTrace();
        } finally {
            if (signature != null) {
                signature.dispose();
            }
        }
    }
}

该方法已具备生产就绪能力：验证输入、管理资源并报告结果。

如何同时添加数字签名和条形码签名？

为获得最高安全性，先添加加密数字签名，再在其上层叠加条形码。数字签名保证文档完整性，条形码提供快速可视化验证和机器可读数据。使用 DigitalSignOptions 完成第一步，然后如上使用 BarcodeSignOptions。

// First, add digital signature
DigitalSignOptions digitalOptions = new DigitalSignOptions("certificate.pfx");
digitalOptions.setPassword("cert_password");
signature.sign(outputPath, digitalOptions);

// Then, add barcode on top
BarcodeSignOptions barcodeOptions = new BarcodeSignOptions("DATA");
barcodeOptions.setEncodeType(BarcodeTypes.QR);
signature.sign(outputPath, barcodeOptions);

生成的 PDF 既具法律约束力（数字签名），又可通过任何条形码扫描仪即时读取。

使用不同条形码类型

切换条形码格式只需更改一个枚举值。下面的示例将 GS1CompositeBar 替换为 QR 码：

// Define barcode sign options with sample text
BarcodeSignOptions options = new BarcodeSignOptions("Sample Text");

// Assign specific barcode type
options.setEncodeType(BarcodeTypes.GS1CompositeBar);

同样的更改用于 Code128 线性条形码：

options.setEncodeType(BarcodeTypes.QR);           // QR code
options.setEncodeType(BarcodeTypes.Code128);      // Code 128
options.setEncodeType(BarcodeTypes.DataMatrix);   // Data Matrix

请记住，每种条形码类型都有自己的数据容量限制——QR 码可容纳数千字符，而 Code39 仅限字母数字。

实际使用案例

供应链管理

在装运清单上嵌入 GS1CompositeBar，可让仓库人员在不打开 PDF 的情况下扫描订单号、目的地和批次码。

BarcodeSignOptions options = new BarcodeSignOptions(
    "(01)" + gtin + "/(21)" + serialNumber + "/(10)" + batchNumber
);
options.setEncodeType(BarcodeTypes.GS1CompositeBar);

医疗文档

在同意书上使用 QR 码，可自动将文档归档到对应患者记录中。

String patientData = "PATIENT_ID:" + patientId + "|DOC_TYPE:CONSENT|DATE:" + dateString;
BarcodeSignOptions options = new BarcodeSignOptions(patientData);
options.setEncodeType(BarcodeTypes.QR);

金融服务

将交易 ID 编码为条形码，审计员只需扫描即可验证合规性。

String complianceData = "TXN:" + transactionId + "|AGENT:" + agentId + "|BRANCH:" + branchCode;
BarcodeSignOptions options = new BarcodeSignOptions(complianceData);
options.setEncodeType(BarcodeTypes.PDF417);

制造质量控制

包含批次号和检查员 ID 的条形码签名检查报告，使根本原因分析瞬间完成。

String qcData = "BATCH:" + batchNumber + "|INSPECTOR:" + inspectorId + "|RESULT:" + passFailStatus;
BarcodeSignOptions options = new BarcodeSignOptions(qcData);
options.setEncodeType(BarcodeTypes.DataMatrix);

常见实现问题

问题 1：“文件已被占用” 异常

答案： 如果之前的 Signature 实例未释放，文件会保持锁定。请始终在 try‑finally 块中包装签名代码，并调用 signature.dispose()。

Signature signature = null;
try {
    signature = new Signature(filePath);
    // ... your code ...
} finally {
    if (signature != null) {
        signature.dispose();
    }
}

问题 2：条形码未出现在 PDF 上

答案： 检查 setTop/setLeft 是否在页面范围内，增大条形码的宽高，并确保前景/背景颜色与页面背景形成对比。

// Make sure dimensions are reasonable
options.setTop(100);      // Not 10000
options.setLeft(100);
options.setWidth(300);    // At least 200 pixels for readability
options.setHeight(100);

// Ensure contrast
options.setForeColor(Color.BLACK);
options.setBackgroundColor(Color.WHITE);

问题 3：“无效的条形码数据” 异常

答案： GS1 条形码要求严格的括号表示法。使用正确的应用标识符（如 (01)、(21)），并避免使用不受支持的字符。

// Correct:
"(01)03212345678906/(21)ABC123"

// Incorrect:
"03212345678906ABC123"

问题 4：大型 PDF 导致 OutOfMemoryError

答案： 增加 JVM 堆内存 (-Xmx4G) 并考虑对大型文档逐页签名，而不是使用 setAllPages(true)。

java -Xmx2G -jar your-application.jar

问题 5：条形码扫描失败

答案： 确保条形码至少为 200 × 100 px，使用高对比度颜色，并避免因 PDF 压缩导致的失真。

// Increase size
options.setWidth(400);
options.setHeight(150);

// Maximize contrast
options.setForeColor(Color.BLACK);
options.setBackgroundColor(Color.WHITE);

// Add quiet zone (blank space around barcode)
options.setMargin(new Padding(10));

安全性与验证

条形码签名安全吗？

单独的条形码并未加密保护，任何人都可以生成新的条形码。将其与数字签名配合使用，可同时保证真实性和可扫描性。双签名模式（先数字后条形码）提供法律强制力和运营便利。

验证条形码数据

扫描后，先验证文档的数字签名仍然有效，再检查条形码负载是否符合预期模式。可使用 GroupDocs 的 search() API 与 BarcodeSearchOptions 自动提取并验证条形码内容。

public boolean validateScannedBarcode(String scannedData, String documentPath) {
    // Verify digital signature first
    if (!verifyDigitalSignature(documentPath)) {
        return false;
    }
    
    // Validate barcode format
    if (!scannedData.matches("(01)\\d{14}/(21)[A-Z0-9]+")) {
        return false;
    }
    
    // Check against database
    String productId = extractProductId(scannedData);
    return database.productExists(productId);
}

性能考虑

资源管理

每次操作后务必释放 Signature 对象，以避免内存泄漏：

signature.dispose();

在处理大量文件时，为每个文档创建并释放新的 Signature：

for (String filePath : documentPaths) {
    Signature signature = null;
    try {
        signature = new Signature(filePath);
        // ... signing logic ...
    } finally {
        if (signature != null) {
            signature.dispose();
        }
    }
}

批处理

对于小批量（< 100 个文件），顺序处理最为简单：

for (String path : paths) {
    signDocument(path);
}

对于大规模工作负载，可采用并行处理以提升速度——但需监控 I/O 压力并将线程数限制在 4‑8 条：

paths.parallelStream().forEach(path -> signDocument(path));

大型 PDF 的内存优化

增大堆内存，逐页处理，并在每步后清除引用，防止 50 MB 以上文档出现 OutOfMemoryError。

缓存条形码选项

如果在多个文件中复用相同的条形码配置，可缓存 BarcodeSignOptions 实例：

// Create once, reuse many times
private static BarcodeSignOptions createStandardBarcodeOptions(String data) {
    BarcodeSignOptions options = new BarcodeSignOptions(data);
    options.setEncodeType(BarcodeTypes.GS1CompositeBar);
    options.setTop(200);
    options.setAllPages(true);
    return options;
}

高级功能

单文档多签名

通过多次调用 sign 并传入不同的选项对象，可在同一文档上添加多个条形码（或混合数字签名）：

// Add QR code in top-left
BarcodeSignOptions qrOptions = new BarcodeSignOptions("https://example.com");
qrOptions.setEncodeType(BarcodeTypes.QR);
qrOptions.setTop(50);
qrOptions.setLeft(50);
signature.sign(outputPath, qrOptions);

// Add GS1 barcode in bottom-right
BarcodeSignOptions gs1Options = new BarcodeSignOptions("(01)03212345678906");
gs1Options.setEncodeType(BarcodeTypes.GS1CompositeBar);
gs1Options.setTop(700);
gs1Options.setLeft(400);
signature.sign(outputPath, gs1Options);

动态条形码内容

可根据文档元数据、时间戳或数据库查询生成条形码数据：

// Extract data from PDF or database
String orderId = extractOrderIdFromPdf(filePath);
String timestamp = LocalDateTime.now().format(DateTimeFormatter.ISO_DATE_TIME);
String barcodeData = String.format("ORDER:%s|TIME:%s", orderId, timestamp);

BarcodeSignOptions options = new BarcodeSignOptions(barcodeData);

与 Spring Boot 集成

提供一个 REST 端点，接收 PDF、添加条形码并返回签名文件：

@Service
public class DocumentSigningService {
    public void signWithBarcode(MultipartFile file, String barcodeData) {
        // ... implementation ...
    }
}

REST API 示例

一个最小化的控制器，将请求委托给签名服务：

@PostMapping("/sign-document")
public ResponseEntity<byte[]> signDocument(
    @RequestParam("file") MultipartFile file,
    @RequestParam("barcode") String barcodeData
) {
    // Sign document and return as byte array
}

常见问题

Q: 什么是 GS1CompositeBar 条形码？
A: GS1CompositeBar 将线性和 2D 组件组合在一起，能够在单个可扫描符号中存储产品 ID、序列号等数据，广泛用于零售和物流。

Q: 我可以使用除 GS1CompositeBar 之外的其他条形码类型吗？
A: 可以——GroupDocs.Signature 支持超过 60 种类型，包括 QR、Code128、DataMatrix、PDF417 和 Aztec。只需更改 setEncodeType() 的值即可切换格式。

Q: 生产环境需要许可证吗？
A: 生产部署必须使用有效的 GroupDocs 许可证。开发和测试阶段可使用免费试用版。

Q: 条形码扫描仪能读取已签名 PDF 中的条形码吗？
A: 完全可以，只要条形码尺寸至少为 200 × 100 px，且颜色对比度足够。手机扫描应用可在屏幕上读取，硬件扫描仪可读取打印稿。

Q: 如何处理签名过程中的错误？
A: 将代码放在 try‑catch 块中，记录完整堆栈，并在 finally 块中始终调用 signature.dispose() 以释放资源。

Q: 我可以签署其他文档格式吗？
A: 可以——GroupDocs.Signature 同样支持 DOCX、XLSX、PPTX、图像等多种格式。只需更改输入文件扩展名，API 使用方式保持不变。

Q: 有文件大小限制吗？
A: 没有硬性限制，但超过 50 MB 的文档可能需要更大的 JVM 堆并采用逐页处理以保持内存效率。

Q: 如何签署存储在云端的 PDF？
A: 将文件下载到临时本地路径，完成签名后再上传回云存储，并在完成后清理临时文件。

结论

现在您已经掌握了针对 PDF 文档的 create barcode signature Java 的完整、可投入生产的指南。通过将加密数字签名与机器可读的条形码相结合，您可以在供应链、医疗、金融和制造等场景中实现法律约束力和运营效率的双重提升。请尝试不同的条形码类型，将代码集成到现有服务中，并探索大规模批处理以满足企业级需求。

Last Updated: 2026-05-21
Tested With: GroupDocs.Signature 23.10 for Java
Author: GroupDocs

String filePath = "YOUR_DOCUMENT_DIRECTORY" + "/sample.pdf";
String fileName = new java.io.File(filePath).getName();
String outputPath = "YOUR_OUTPUT_DIRECTORY" + "/SignedWithBarcodeGS1CompositeBar/" + fileName;

String documentDir = System.getenv("DOCUMENT_DIR");
String outputDir = System.getenv("OUTPUT_DIR");

Signature signature = new Signature(filePath);

相关教程