如何使用 Java 在 PDF 中创建条形码签名

在本教程中，您将学习如何使用 Java 和 GroupDocs.Signature 创建条形码签名 于 PDF 文件中。条形码签名嵌入机器可读的标识符，既防篡改又易于扫描——非常适合合同、证书、发票以及任何需要可靠验证的文档。

快速答案

什么是条形码签名？ 嵌入在 PDF 中的条形码，存储结构化数据，可被扫描仪或软件读取。
推荐使用哪种条形码类型？ Code128，因为它能够紧凑地处理字母数字数据。
我需要许可证吗？ 免费试用可用于测试；生产环境需要完整许可证。
我可以在任何页面尺寸上放置条形码吗？ 可以——使用基于百分比的定位实现自动缩放。
条形码是矢量的吗？ 是的，它只会向 PDF 添加几千字节，并且在任何分辨率下都保持清晰。

为什么条形码签名对您的 PDF 很重要

您可能已经遇到过这样的挑战：需要在 PDF 中添加既可机器读取又防篡改的唯一标识符。也许您正在开发文档管理系统、处理证书，或处理需要后续验证的合同。

这时条形码签名就派上用场了。与普通文字水印不同，条形码可以嵌入结构化数据，扫描仪（以及您的软件）能够即时读取。此外，将其与 GroupDocs.Signature for Java 的 PDF 签名结合使用，您即可在无需复杂数据库查询的情况下，实现对文档的强大跟踪和验证。

在本指南中，您将学习如何在 Java PDF 中实现条形码签名——从基础设置到具备灵活定位的生产就绪代码。无论您是构建发票系统、证书生成器还是合同管理平台，阅读完本指南后您都将掌握所需的一切。

您将掌握的内容：

在几分钟内设置 GroupDocs.Signature for Java
创建 Code128 条形码签名（以及为何它们通常是最佳选择）
使用基于百分比的布局定位条形码，适用于任何 PDF 尺寸
避免常见的开发者陷阱
正确测试您的实现

开始之前您需要准备的内容

确保您已准备好以下必需品：

必需库：

GroupDocs.Signature for Java（建议使用 23.12 或更高版本）

开发环境：

已安装 JDK 8 或更高版本
您喜欢的 IDE（IntelliJ IDEA、Eclipse 或带有 Java 扩展的 VS Code）
用于依赖管理的 Maven 或 Gradle

您的技能水平： 您应熟悉基本的 Java 语法并了解文件操作。如果您能够创建一个简单的 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.Signature for Java releases 下载 JAR 并将其添加到类路径中。

获取许可证

在投入生产之前，您需要处理许可证：

免费试用： 适合测试——可从 GroupDocs 网站获取，以探索核心功能
临时许可证： 需要更多评估时间？申请 30 天临时许可证
完整许可证： 准备投入生产？购买无限使用的许可证

以下是快速检查，以确保一切正常工作：

import com.groupdocs.signature.Signature;

public class QuickTest {
    public static void main(String[] args) {
        try {
            Signature signature = new Signature("test-document.pdf");
            System.out.println("GroupDocs.Signature is ready to go!");
        } catch (Exception e) {
            System.err.println("Setup issue: " + e.getMessage());
        }
    }
}

如果运行没有错误，您就可以开始了！

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

现在进入有趣的部分——让我们使用条形码为 PDF 签名。我们将把过程拆分为一步步的小步骤，以便您清楚每个阶段的具体操作。

步骤 1：初始化 Signature 对象

首先，您需要告诉 GroupDocs 您正在处理哪个 PDF：

String filePath = "YOUR_DOCUMENT_DIRECTORY/sample.pdf";
Signature signature = new Signature(filePath);

此处的作用： Signature 对象将您的 PDF 加载到内存中并准备进行修改。确保文件路径正确——常见错误是在 Windows 上使用单个反斜杠而未进行转义（使用 \\ 或直接使用正斜杠，跨平台均可）。

步骤 2：配置条形码选项（如何添加条形码）

现在让我们使用您的数据创建条形码签名：

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

BarcodeSignOptions options = new BarcodeSignOptions("12345678");
options.setEncodeType(BarcodeTypes.Code128);

拆解说明：

"12345678" 是您的条形码数据——可以是订单号、证书编号或任何您需要的标识符
Code128 是编码类型（下面会详细说明如何选择合适的类型）

专业提示： Code128 能处理数字和字母，适用于大多数场景。如果您只需要数字，Code39 可能更简单，但 Code128 提供了更大的灵活性。

步骤 3：定位条形码（如何使用条形码签署 PDF）

这正是 GroupDocs 发光之处——基于百分比的定位使您的条形码在任何 PDF 大小上都表现良好：

import com.groupdocs.signature.domain.enums.MeasureType;
import com.groupdocs.signature.domain.Padding;

// Use percentages instead of fixed pixels
options.setLocationMeasureType(MeasureType.Percents);
options.setLeft(5);  // 5% from the left edge
options.setTop(5);   // 5% from the top

// Size it proportionally too
options.setSizeMeasureType(MeasureType.Percents);
options.setWidth(10);  // 10% of page width
options.setHeight(5);  // 5% of page height

// Add some breathing room with margins
Padding margins = new Padding();
margins.setLeft(1);
margins.setTop(1);
margins.setRight(1);
options.setMargin(margins);

为何使用百分比很重要： 想象一下您需要在 A4 文档和法律尺寸表单上签名。使用百分比定位，条形码会自动按比例缩放，在两种尺寸上保持一致。若使用固定像素值，则在大文档上条形码会太小，在小文档上则会太大。

实际示例： 在 A4 页面（595 × 842 points）上，宽度为 10% 的条形码约为 60 points。在法律页面（612 × 1008 points）上约为 61 points——自动保持比例。

步骤 4：签名并保存文档（如何添加条形码 PDF）

现在是实际应用签名并保存的时刻：

String outputFilePath = "YOUR_OUTPUT_DIRECTORY/SignWithPercents/sample_signed.pdf";
signature.sign(outputFilePath, options);

重要提示： 输出目录必须在运行代码前已存在。GroupDocs 不会为您创建嵌套目录，请先创建目录或在代码中处理：

Path outputPath = Paths.get(outputFilePath);
Files.createDirectories(outputPath.getParent());
signature.sign(outputFilePath, options);

如果出现错误怎么办？ 将其包装在 try‑catch 块中：

try {
    signature.sign(outputFilePath, options);
    System.out.println("PDF signed successfully at: " + outputFilePath);
} catch (Exception e) {
    System.err.println("Signing failed: " + e.getMessage());
    e.printStackTrace();
}

为您的需求选择合适的条形码类型（code128 pdf 条形码）

GroupDocs 支持多种条形码格式，选择合适的类型很重要。以下是实用对比：

Code128（我们的默认选择）：

最佳用途： 混合字母数字数据（如 “INV2024-001” 的 ID）
容量： 最多 128 个 ASCII 字符
优势： 紧凑、广泛支持，能够处理字母和数字
使用场景： 需要灵活性且不确定要编码的数据类型时

Code39：

最佳用途： 简单的字母数字码
容量： 43 个字符（A‑Z、0‑9 以及部分符号）
考虑因素： 老旧扫描仪通常更好支持
使用场景： 与遗留系统配合或对数据密度要求不高、简洁更重要时

QR Code：

最佳用途： 大量数据（URL、JSON 负载）
容量： 最多约 3 KB 数据
优势： 可存储复杂数据结构，内置纠错
使用场景： 需要嵌入结构化数据或 URL 时

EAN/UPC：

最佳用途： 产品识别
容量： 固定长度数字码（8‑13 位）
使用场景： 零售或库存系统

快速决策指南：

需要字母和数字？ → Code128
仅数字，保持简洁？ → Code39
大量数据或 URL？ → QR Code
零售/产品码？ → EAN/UPC

常见陷阱及规避方法

以下是开发者最常遇到的问题（帮助您避免）：

问题 1：条形码定位不正确

症状： 条形码出现在意外位置或被截断。

常见原因：

在不同页面尺寸上使用像素值
忘记 PDF 坐标系起点在左下角，而非左上角
边距导致内容超出可视区域

解决方案：
始终使用基于百分比的定位以保持一致性：

options.setLocationMeasureType(MeasureType.Percents);
options.setLeft(5);  // 5% from left works on any page width

问题 2：条形码文本不可读

症状： 编码文本可见，但扫描仪无法读取。

原因：

条形码尺寸相对于数据量过小
数据使用了错误的编码类型
分辨率低或对比度差

解决方案：
根据数据长度匹配条形码尺寸。对于 10‑15 字符的 Code128，宽度至少应占页面宽度的 8‑10%：

options.setWidth(10);  // Give it room to breathe
options.setHeight(5);  // Maintain proper aspect ratio

问题 3：文件路径异常

症状： FileNotFoundException 或类似错误。

原因：

硬编码的 Windows 路径使用单个反斜杠
输出目录不存在
文件权限问题

解决方案：
使用正斜杠（通用适用），并先创建目录：

String filePath = "documents/sample.pdf";  // Works on Windows, Mac, Linux
Files.createDirectories(Paths.get("output/signed"));

问题 4：大 PDF 的内存问题

症状： 处理大文档时出现内存不足错误。

解决方案：
完成后关闭 Signature 对象以释放资源：

try (Signature signature = new Signature(filePath)) {
    signature.sign(outputFilePath, options);
} // Automatically closes and releases memory

测试您的条形码实现

在部署之前，请确保条形码实际可用。以下是实用的测试清单：

1. 目视检查测试

打开已签名的 PDF 并检查：

条形码是否可见且定位正确？
是否清晰（无模糊或像素化）？
周围是否有足够的留白？

2. 扫描测试

使用手机上的条形码扫描应用（如 “Barcode Scanner” 或 “QR & Barcode Reader”）进行验证：

扫描器能够读取条形码
解码数据与您编码的内容匹配
在不同角度和距离下均能正常工作

3. 跨平台测试

在不同设备上打开 PDF：

Windows（Adobe Reader、Chrome）
Mac（Preview、Chrome）
移动设备（iOS、Android）

确保条形码在所有平台上均能正确渲染。

4. 自动化测试代码

以下是您可以运行的简单测试代码：

import org.junit.Test;
import static org.junit.Assert.*;

public class BarcodeSignatureTest {
    
    @Test
    public void testBarcodeSigning() {
        String testPdf = "test-data/sample.pdf";
        String output = "test-output/signed.pdf";
        
        try (Signature signature = new Signature(testPdf)) {
            BarcodeSignOptions options = new BarcodeSignOptions("TEST123");
            options.setEncodeType(BarcodeTypes.Code128);
            
            signature.sign(output, options);
            
            // Verify output file exists
            assertTrue(new File(output).exists());
            
            // Verify file size increased (signature was added)
            long originalSize = new File(testPdf).length();
            long signedSize = new File(output).length();
            assertTrue(signedSize > originalSize);
            
        } catch (Exception e) {
            fail("Signing should not throw exception: " + e.getMessage());
        }
    }
}

条形码签名的真实场景应用

让我们看看此技术在生产系统中的实际亮点：

1. 证书生成与验证

场景： 您正在构建一个发放结业证书的培训平台。
实现方式： 生成唯一的证书 ID（例如 “CERT‑2024‑00123”），并将其作为 Code128 条形码嵌入右下角。扫描条形码即可让您的 API 立即获取证书详情，省去手动录入。

2. 发票跟踪系统

场景： 您的公司每月处理数千份发票。
实现方式： 将发票号和到期日作为 QR 码放置在便于扫描设备读取的位置。自动分拣系统可在无需人工干预的情况下路由发票，将处理时间从数小时缩短至数分钟。

3. 法律合同管理

场景： 律师事务所需要跟踪合同版本和修订。
实现方式： 为每个合同版本分配包含合同 ID、版本号和签署日期的唯一条形码标识符。审计时扫描即可自动调出完整的版本历史。

4. 医疗记录安全

场景： 医院希望防止未授权的记录访问。
实现方式： 在条形码中嵌入患者 ID 和记录创建时间戳。只有经过认证的设备才能解码并访问完整记录，每次扫描都会生成审计日志以满足合规要求。

性能优化技巧

在签署大量 PDF 时，性能至关重要。以下是保持顺畅运行的一些技巧：

批量处理策略

与其一次签署一个文档，不如批量处理：

List<String> pdfFiles = Arrays.asList("doc1.pdf", "doc2.pdf", "doc3.pdf");

for (String pdfFile : pdfFiles) {
    try (Signature signature = new Signature(pdfFile)) {
        BarcodeSignOptions options = createBarcodeOptions(); // Reuse options
        signature.sign(getOutputPath(pdfFile), options);
    }
}

为何有效： 重用 options 对象并正确关闭资源可防止内存泄漏。

内存管理

针对非常大的 PDF（50 + MB）：

逐个顺序处理，而不是一次加载多个
使用 try‑with‑resources 确保清理
监控堆大小，并在需要时调整 JVM 参数，例如 -Xmx2g

缓存策略

如果您反复使用相同的条形码进行签名：

// Create options once, reuse many times
BarcodeSignOptions templateOptions = createStandardBarcodeOptions();

// For each document, clone and customize
BarcodeSignOptions documentOptions = templateOptions.clone();
documentOptions.setText(uniqueDocumentId);

何时使用条形码签名（以及何时不适用）

理想场景：

需要机器可读的文档标识符
文档将被自动扫描或处理
想要防篡改的追踪而无需数字证书
与现有条形码基础设施集成

不适用的情况：

需要具有法律约束力的数字签名（应使用数字证书）
文档仅供人工查看（简单文字水印即可）
文档极小，条形码会占据页面大部分
安全要求需要加密（条形码是可见且可被任何人扫描的）

可以结合使用吗？ 当然可以！许多系统同时使用条形码签名进行追踪和数字签名以满足法律有效性。

常见问题

问：我可以在同一个 PDF 中使用不同的条形码类型吗？
答：可以！对每种条形码类型调用 signature.sign() 多次并使用不同的 BarcodeSignOptions。只需确保它们不重叠即可。

问：如何处理包含特殊字符的条形码？
答： Code128 能很好地处理大多数 ASCII 字符。对于 Unicode 或复杂数据，请改用 QR 码——它们支持 UTF‑8 编码。

问：Code128 条形码最多能存储多少数据？
答：理论上最多 128 个字符，但在超过 30‑40 个字符后可读性显著下降。若数据量更大，请使用 QR 码。

问：添加条形码会显著增加 PDF 文件大小吗？
答：不会明显增加——条形码是矢量图形，通常每个条形码仅增加约 5‑20 KB，具体取决于尺寸和复杂度。

问：我可以旋转条形码或垂直放置吗？
答：可以！使用 options.setRotationAngle(90) 旋转条形码，这在边缘放置时非常方便。

问：如何让条形码出现在多页 PDF 的每一页上？
答：遍历页面并对每页应用签名。请查看 GroupDocs 文档中的 PagesSetup 类，以控制哪些页面需要签名。

问：如果我的条形码扫描仪无法读取生成的条形码怎么办？
答：首先确认扫描仪支持所选条形码类型。然后增大条形码尺寸——大多数扫描问题源于条形码太小。建议宽度至少为 1 英寸（2.54 cm），以确保可靠读取。

其他资源

文档：

下载与许可证：

社区与支持：

Support Forum - 活跃的社区，拥有 GroupDocs 工程师

最后更新： 2026-03-06
测试环境： GroupDocs.Signature 23.12（Java）
作者： GroupDocs