在 PDF 中使用 GroupDocs.Signature Java 添加条形码签名

在现代文档中心的应用程序中，add barcode signature是一种快速、可靠的方式，使 PDF 同时具有人类可读和机器可扫描的特性。本教程将逐步指导您——从 Maven 配置、条形码样式设置，到处理大文件的边缘情况——帮助您自信地在 Java 项目中集成条形码签名。

快速答案

  • 开始签名的第一行代码是什么？ Signature signature = new Signature("sample.pdf");
  • 我需要哪个 Maven 构件？ com.groupdocs:groupdocs-signature:23.10 (replace with the latest version)
  • 我可以签署受密码保护的 PDF 吗？ Yes—pass the password when creating the Signature object.
  • 支持多少种条形码格式？ Over 30, including Code128, QR, DataMatrix, and Aztec.
  • 针对 100 MB PDF 推荐的堆大小是多少？ At least -Xmx2g (2 GB) to avoid OutOfMemoryError.

什么是条形码签名？

条形码签名是一种嵌入 PDF 的机器可读条形码，充当防篡改标记，并且可以携带自定义数据，如 ID、时间戳或 URL。它将可视化验证与自动扫描相结合，是库存管理、合规性以及高吞吐量工作流自动化的理想选择。

为什么使用 GroupDocs.Signature Java 添加条形码签名？

GroupDocs.Signature 支持 50+ 种输入和输出格式，能够在不将整个文件加载到内存的情况下处理数百页的 PDF，并提供流畅的 Java API，让您可以微调条形码的每个视觉细节。在基准测试中，对 150 页 PDF 添加 Code128 条形码的签名在标准 2 vCPU 云实例上 不到 1.2 秒。

先决条件

在开始之前，请确认您具备以下条件：

  • Java 开发工具包 (JDK) 8 或更高（建议使用 JDK 11 或 17 以获得长期支持）
  • IDE （IntelliJ IDEA、Eclipse 或带有 Java 扩展的 VS Code）
  • 构建工具 （Maven 3.6+ 或 Gradle 7.0+）
  • GroupDocs.Signature Java 库（下面将展示 Maven 与 Gradle 的设置）
  • 基本熟悉 Java 面向对象概念以及 Maven/Gradle 项目结构

必需的库和依赖项

GroupDocs.Signature 可平滑集成到 Maven 或 Gradle。请选择您已经在使用的构建工具：

Maven 设置

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

Gradle 设置

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

如果您更喜欢手动处理 JAR，请从 GroupDocs.Signature for Java releases 下载最新发布版并将其添加到类路径中。

获取许可证的步骤

GroupDocs 提供三种授权模式：

  • 免费试用 – 完全功能访问 30 天（已签署的 PDF 会添加水印）
  • 临时许可证 – 延长试用期且无功能限制（适用于开发流水线）
  • 正式许可证 – 生产就绪，包含优先支持且无水印

在 GroupDocs Licensing 获取相应的许可证。即使在试用期间也可以在本地运行代码；只需记得在上线前将试用密钥替换为永久密钥。

如何使用 GroupDocs.Signature Java 为 PDF 添加条形码签名？

Signature 类是使用 GroupDocs.Signature 处理文档的主要入口。
BarcodeSignOptions 类用于指定条形码的数据、类型和视觉外观。

使用 new Signature("source.pdf") 加载源 PDF，配置包含所需数据和视觉样式的 BarcodeSignOptions 对象，然后调用 signature.sign("output.pdf", options)。这种三步模式在一次线程安全的调用中处理文件 I/O、条形码生成和 PDF 写入，适用于从几千字节到数百兆字节的 PDF。

步骤 1：初始化 Signature 对象

Signature 类是 GroupDocs.Signature 所有签名操作的入口。它在内存中表示单个 PDF 文档，并提供惰性加载以降低内存使用。

```java
import com.groupdocs.signature.Signature;

public class InitializeSignature {
    public static void main(String[] args) {
        Signature signature = new Signature("YOUR_DOCUMENT_DIRECTORY/sample.pdf");
        System.out.println("GroupDocs.Signature initialized successfully.");
    }
}

说明：

  • filePath 指向您想要签名的源 PDF。
  • outputFilePath 是保存已签名 PDF 的位置，保留原始文件。
  • try‑catch 块确保对 I/O 错误、文件缺失或权限问题进行优雅处理。

步骤 2：配置条形码签名选项

BarcodeSignOptions 允许您定义条形码的每个属性——类型、数据、位置、颜色、边框，甚至是否返回原始条形码图像。

```java
import com.groupdocs.signature.Signature;
import com.groupdocs.signature.exception.GroupDocsSignatureException;
import java.nio.file.Paths;
import java.io.File;

public class Feature1 {
    public static void run() throws Exception {
        String filePath = "YOUR_DOCUMENT_DIRECTORY/sample.pdf";
        String outputFilePath = new File("YOUR_OUTPUT_DIRECTORY", "SignedOutputSample.pdf").getPath();

        try {
            Signature signature = new Signature(filePath);
            System.out.println("Signature initialized and paths set.");
        } catch (Exception e) {
            throw new GroupDocsSignatureException(e.getMessage());
        }
    }
}

关键设置分解：

  • Data & Type – "12345678" 是负载；BarcodeTypes.Code128 适用于字母数字字符串，且被扫描仪广泛支持。
  • Positioning – setLeft(100) 和 setTop(100) 将条形码相对于左上角偏移 100 像素；VerticalAlignment.Top + HorizontalAlignment.Right 根据这些偏移调整对齐方式。
  • Margins & Padding – Padding 对象添加 20 像素的缓冲，以避免页面边缘被裁剪。
  • Styling – 边框、字体和背景刷均可完全自定义；在生产环境中可能会去掉渐变以提升渲染速度。
  • Return Content – 启用 setReturnContent(true) 可将条形码作为 byte[] 返回，便于将图像存入数据库或在 UI 中显示。

最小化生产就绪配置

对于干净的法律文档，通常只需要一个黑底白字的简洁条形码，无需额外边框：

```java
import com.groupdocs.signature.domain.enums.*;
import com.groupdocs.signature.domain.Padding;
import com.groupdocs.signature.domain.Border;
import com.groupdocs.signature.domain.DashStyle;
import com.groupdocs.signature.domain.extensions.LinearGradientBrush;
import com.groupdocs.signature.domain.font.SignatureFont;
import java.awt.Color;
import com.groupdocs.signature.options.sign.BarcodeSignOptions;

public class Feature2 {
    public static void configureBarcodeOptions() throws Exception {
        BarcodeSignOptions signOptions = new BarcodeSignOptions("12345678");
        signOptions.setEncodeType(BarcodeTypes.Code128);
        signOptions.setLeft(100);
        signOptions.setTop(100);
        signOptions.setVerticalAlignment(VerticalAlignment.Top);
        signOptions.setHorizontalAlignment(HorizontalAlignment.Right);

        Padding padding = new Padding();
        padding.setLeft(20);
        padding.setTop(20);
        signOptions.setMargin(padding);

        Border border = new Border();
        border.setColor(Color.GREEN);
        border.setDashStyle(DashStyle.DashLongDashDot);
        border.setWeight(2);
        border.setTransparency(0.5);
        border.setVisible(true);
        signOptions.setBorder(border);

        signOptions.setForeColor(Color.RED);
        SignatureFont font = new SignatureFont();
        font.setSize(12);
        font.setFamilyName("Comic Sans MS");
        signOptions.setFont(font);

        signOptions.setCodeTextAlignment(CodeTextAlignment.Above);

        Background background = new Background();
        background.setColor(Color.GREEN);
        background.setTransparency(0.5);
        background.setBrush(new LinearGradientBrush(Color.GREEN, Color.DARK_GRAY, 0));
        signOptions.setBackground(background);

        signOptions.setReturnContent(true);
        signOptions.setReturnContentType(FileType.PNG);
    }
}

步骤 3：签署文档

sign 方法将配置好的条形码应用到 PDF 并将结果写入目标路径。

```java
signOptions.setEncodeType(BarcodeTypes.QR); // QR codes for more data
signOptions.setForeColor(Color.BLACK);
signOptions.setBackgroundColor(Color.WHITE);
// Remove border and fancy styling for professional appearance

内部实现：

  • signature.sign(outputFilePath, signOptions) 将条形码写入 PDF，同时保持源文件不变。
  • SignResult 报告添加了多少签名、哪些页面被修改以及产生的任何警告。
  • 对于批处理任务，可将此调用包装在 ExecutorService 中，以在 CPU 核心之间并行执行。

常见问题及解决方案

问题 1：初始化时出现 FileNotFoundException

症状： 在创建 Signature 对象时，应用程序抛出 FileNotFoundException。

根本原因：

  • 文件路径不正确（相对路径 vs 绝对路径）
  • 缺少读取权限
  • 文件被其他进程锁定（例如在 Acrobat 中打开）

修复：

```java
import com.groupdocs.signature.Signature;
import com.groupdocs.signature.exception.GroupDocsSignatureException;
import com.groupdocs.signature.options.sign.BarcodeSignOptions;
import com.groupdocs.signature.domain.BaseSignature;

public class Feature3 {
    public static void signDocument(String filePath, BarcodeSignOptions signOptions) throws Exception {
        Signature signature = new Signature(filePath);
        String outputFilePath = filePath.replace(".pdf", "_Signed.pdf");

        try {
            com.groupdocs.signature.domain.signatures.SignResult signResult = signature.sign(outputFilePath, signOptions);
            System.out.println("Document signed successfully.");
        } catch (Exception e) {
            throw new GroupDocsSignatureException(e.getMessage());
        }
    }
}

确保路径使用正斜杠（C:/Docs/sample.pdf）或对反斜杠进行转义（C:\\Docs\\sample.pdf）。检查操作系统权限并关闭可能锁定文件的程序。

问题 2：输出中未出现条形码

症状： 签名完成且没有错误，但条形码不可见。

常见原因：

  • 位置将条形码放在可打印区域之外。
  • 透明度设置为 1.0（完全透明）。
  • 字体大小设置为 0。

解决方案：

  • 将 setLeft/setTop 的值保持在页面尺寸范围内（标准 A4 为 0‑600 像素）。
  • 使用介于 0.0（不透明）和 0.9 之间的透明度值。
  • 设置可读的字体大小，例如 12pt。

问题 3：处理大文档时出现内存不足错误

症状： 处理大于约 50 MB 的 PDF 时出现 OutOfMemoryError。

解决办法：

  • 增加 JVM 堆：-Xmx2g 或更高，具体取决于文档大小。
  • 使用 Signature 的流式 API 按页处理 PDF。
  • 在每次操作后显式关闭 Signature 实例以释放本机资源。
```java
import java.nio.file.Files;
import java.nio.file.Path;

Path filePath = Path.of("YOUR_DOCUMENT_DIRECTORY/sample.pdf");
if (!Files.exists(filePath)) {
    throw new IllegalArgumentException("PDF file not found: " + filePath);
}
if (!Files.isReadable(filePath)) {
    throw new SecurityException("Cannot read PDF file: " + filePath);
}
// Now safe to initialize
Signature signature = new Signature(filePath.toString());

问题 4：无效的条形码数据错误

症状： API 抛出异常，提示不支持的字符。

原因： 不同的条形码标准接受不同的字符集。Code128 允许字母数字；QR 可以处理 Unicode；某些 1D 条形码仅接受数字。

解决方案： 选择与数据集匹配的条形码类型，或在将字符串赋给 BarcodeSignOptions 前进行清理。

```java
String barcodeData = "ABC123"; // Your data
BarcodeTypes type = BarcodeTypes.Code128; // Alphanumeric support

// For numeric-only barcodes, validate first:
if (type == BarcodeTypes.EAN13 && !barcodeData.matches("\\d+")) {
    throw new IllegalArgumentException("EAN13 requires numeric data only");
}

生产环境最佳实践

1. 在签名之前验证 PDF

始终确认文件是格式良好的 PDF，以避免运行时解析错误。

```java
try (Signature signature = new Signature(filePath)) {
    // If this succeeds, file is valid
    signature.getDocumentInfo();
} catch (Exception e) {
    // Handle invalid PDF
}

2. 对高吞吐量工作负载使用异步处理

将签名任务卸载到后台线程池；这可以防止 UI 卡顿并提升吞吐量。

```java
ExecutorService executor = Executors.newFixedThreadPool(4);
List<String> pdfFiles = Arrays.asList("doc1.pdf", "doc2.pdf", "doc3.pdf");

pdfFiles.forEach(file -> {
    executor.submit(() -> {
        try {
            signDocument(file, signOptions);
        } catch (Exception e) {
            // Log error
        }
    });
});
executor.shutdown();

3. 实施结构化日志记录

记录每个签名请求的输入路径、输出路径、条形码数据以及任何异常。这能显著加快事后分析速度。

```java
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

private static final Logger logger = LoggerFactory.getLogger(YourClass.class);

try {
    SignResult result = signature.sign(outputFilePath, signOptions);
    logger.info("Document signed successfully: {}", outputFilePath);
    logger.debug("Signatures added: {}", result.getSucceeded().size());
} catch (Exception e) {
    logger.error("Failed to sign document: {}", filePath, e);
}

4. 为速度优化条形码设置

  • 除非需要单独获取图像，否则禁用 setReturnContent(true)。
  • 优先使用实色背景刷而非渐变。
  • 对于简单的追踪使用场景，省略边框。

5. 优雅地处理临时许可证过期

License 类用于加载并验证 GroupDocs 的许可证文件。
在每次签名操作前检查许可证状态，并在过期时回退到只读模式或提醒管理员。

```java
try {
    License license = new License();
    license.setLicense(licensePath);
} catch (Exception e) {
    logger.warn("License validation failed. Using trial mode.");
    // Continue with trial limitations
}

何时使用条形码签名

理想场景

  • 库存与物流： 在装运清单、装箱单或资产标签上附加可扫描的条形码。
  • 监管合规： 如制药等行业需要机器可读的审计轨迹。
  • 自动化文档流水线： 将条形码签名与 OCR 结合，实现端到端处理，无需人工录入数据。
  • 高吞吐量批处理作业： 与加密数字签名相比，扫描大量纸质档案时条形码的验证更快。

何时更倾向于使用其他签名类型

  • 法律合同： 使用基于 PKI 的数字签名（如 X.509）以实现不可否认性。
  • 面向客户的 PDF： QR 码在移动设备上更易识别。
  • 超高安全文档： 将条形码与加密数字签名配合使用，实现分层安全。

专业提示： 您可以在同一 PDF 中嵌入多种签名类型——添加条形码用于追踪，同时添加数字证书以实现法律强制力。

常见问题

Q: 如何在 Java 中不使用外部依赖为 PDF 添加条形码签名？
A: GroupDocs.Signature for Java 是自包含的；在添加 Maven/Gradle 构件后，您即可获得完整的条形码生成和 PDF 渲染功能，无需任何第三方库。

Q: 我可以在 Java 中配置条形码签名选项以生成 QR 码吗？
A: 当然可以。将 BarcodeTypes 枚举切换为 QRCode 并根据需要调整尺寸参数。

```java
signOptions.setEncodeType(BarcodeTypes.QR);

Q: 生产环境推荐的 Maven 设置是什么？
A: 在 pom.xml 中锁定确切版本（例如 23.10.0），以避免意外升级，并启用 Maven shade 插件生成单个可执行 JAR。

```xml
<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-signature</artifactId>
    <version>23.12</version> <!-- Don't use LATEST -->
</dependency>

Q: 该库是否支持受密码保护的 PDF？
A: 支持。在构造 Signature 对象时提供密码，然后照常进行签名。

```java
LoadOptions loadOptions = new LoadOptions();
loadOptions.setPassword("your_pdf_password");
Signature signature = new Signature(filePath, loadOptions);

Q: 一次操作可以签署多少页？
A: GroupDocs.Signature 可以一次性处理 PDF 的所有页面，或通过 setPageNumber() 定位特定页面。性能呈线性增长；在典型云 VM 上，200 页 PDF 的签名约需 2 秒。

Q: 除了 Code128 之外还有哪些条形码格式可用？
A: 超过 30 种格式，包括 QR、DataMatrix、Aztec、UPC‑A、EAN‑13、PDF417 等。完整列表请参阅 BarcodeTypes 枚举。

Q: 条形码数据长度是否有限制？
A: 长度限制取决于条形码类型；对于 Code128，实际限制约为 80 个字符，而 QR 码可存储最多 4 KB 数据。

Q: 我可以在签名后获取生成的条形码图像吗？
A: 设置 setReturnContent(true) 和 setReturnContentType(FileType.PNG)；SignResult 将包含一个 byte[]，您可以将其写入磁盘或数据库。

最后更新： 2026-07-25
测试环境： GroupDocs.Signature 23.10 for Java
作者： GroupDocs

相关教程