在 Word 文档中使用 Java 创建 QR 码签名

是否曾花费数小时手动签署文档，却仍在寻找更快、更可靠的方式？只需几行 Java 代码，即可在 Word 文档中创建 QR 码签名。无论是自动化合同工作流、管理法律文书，还是构建移动优先的审批门户，QR 码签名都能提供即时、可扫描的验证，适用于任何智能手机。在本教程中，您将学习如何设置 GroupDocs.Signature for Java、配置 QR 码选项，并将 URL、时间戳或 JSON 负载等丰富数据嵌入 Word 文件。完成后，您将能够大规模签署文档，降低人工工作量，提升合规性。

快速回答

  • 需要哪个库？ GroupDocs.Signature for Java (v23.12+)。
  • 代码行数多少？ 两行 QR 生成代码加上少量配置行。
  • 可以签署 PDF 吗？ 可以 – 同一 API 适用于 PDF、Excel、PowerPoint 和图像。
  • 需要商业许可证吗？ 仅在生产环境需要；开发阶段可使用免费试用或临时许可证。
  • 可以存储哪些数据？ 最多约 4 k 字符（URL、JSON、ID），但为保证扫描可靠性，建议保持在 500 字符以下。

什么是创建 QR 码签名？

创建 QR 码签名是一种可扫描的二维条码，嵌入文档中，用于表示数字签名或验证负载。当用户扫描 QR 码时，读取并验证编码的数据（通常是 URL 或令牌），即可在无需专用软件的情况下证明文档的真实性。

为什么使用 GroupDocs.Signature for Java 添加 QR 码？

GroupDocs.Signature 支持50+ 输入和输出格式，可在不将整个文档加载到内存的情况下处理数百页文件，并提供流式 API，使您能够在毫秒级程序化签署 Word 文件。库还内置 QR、Aztec、DataMatrix 和 PDF417 条码生成，是现代移动优先验证的一站式解决方案。

前置条件

必需的库和依赖

  • GroupDocs.Signature for Java 版本 23.12 或更高（唯一的外部依赖）。

环境搭建要求

  • JDK 8+（生产环境推荐 Java 11 或 17）。
  • IDE（IntelliJ IDEA、Eclipse、VS Code 任意）。
  • 构建工具 – Maven 或 Gradle（以下示例兼容两者）。

知识前提

  • 基础 Java 语法和文件 I/O 操作。
  • 熟悉 Maven/Gradle 依赖声明（我们将展示完整代码片段）。

设置 GroupDocs.Signature for Java

选择您的构建系统并按以下方式添加依赖。下面的占位符代表原始代码块，请保持不变。

Maven

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

Gradle

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

直接下载

想手动管理？从 GroupDocs.Signature for Java releases 下载 JAR 并将其添加到项目的类路径。

许可证获取

  • 免费试用： 适合原型开发，核心功能可用。
  • 临时许可证： 短期开发的完整功能访问。
  • 商业许可证： 生产部署必需。

小贴士： 先使用免费试用，然后在进入生产前申请临时许可证，这样可以在无前期成本的情况下验证工作流。

基本初始化

Signature 对象是所有签名操作的入口点。它实现了 AutoCloseable，因此可以安全地使用 try‑with‑resources 块。

Signature signature = new Signature("path/to/your/document");

实现指南：使用 QR 码签署 Word 文档

下面逐步演示每一步，并在需要时添加定义锚点和直接答案。

如何为 Word 文件初始化 Signature 对象？

在 try‑with‑resources 块中使用 new Signature("source.docx") 加载源文档；该对象准备对文件进行修改，并在块结束时自动释放资源。

String filePath = "YOUR_DOCUMENT_DIRECTORY/SampleDocX.docx";
Signature signature = new Signature(filePath);

说明： Signature 类在内存中表示单个文档，并提供添加、搜索和验证签名的方法。它支持 .docx、.doc 以及许多其他格式。

如何配置 QR 码签名选项？

创建 QrCodeSignOptions 实例，设置编码文本、条码类型和定位。以下代码展示最小配置。

QrCodeSignOptions signOptions = new QrCodeSignOptions("JohnSmith");
signOptions.setEncodeType(QrCodeTypes.QR);
signOptions.setLeft(100); // X 轴位置（像素）
signOptions.setTop(100);  // Y 轴位置（像素）

定义： QrCodeSignOptions 类封装了生成和放置 QR 码签名所需的所有设置，包括编码文本、条码类型、大小、颜色以及文档内的坐标。

自定义外观

您可以进一步调整大小、边距和颜色：

QrCodeSignOptions signOptions = new QrCodeSignOptions("https://yourapp.com/verify/doc-12345");

为何重要： 150 px 正方形的 QR 码，前景为黑色、背景为白色，在屏幕和打印上均能实现 >99 % 的扫描成功率。

如何设置已签署文档的输出选项？

在调用 sign 之前，定义目标格式和覆盖行为。

WordProcessingSaveOptions saveOptions = new WordProcessingSaveOptions();
saveOptions.setFileFormat(WordProcessingSaveFileFormat.Odt);
saveOptions.setOverwriteExistingFiles(true);

定义： WordProcessingSaveOptions 类定义了签署后 Word 文档的保存方式，您可以指定输出格式（DOCX、ODT 等）、是否覆盖已有文件以及其他文件级别的偏好设置。

如果需要开源格式，可切换为 OutputType.ODT：

saveOptions.setFileFormat(WordProcessingSaveFileFormat.Docx);

如何使用 QR 码签署并保存文档？

sign 方法一次性应用 QR 码并写入输出文件。

String outputFilePath = "YOUR_OUTPUT_DIRECTORY/SaveSignedOutputType/SampleDocX.odt";
signature.sign(outputFilePath, signOptions, saveOptions);

定义： Signature 对象的 sign 方法接受目标路径、已配置的签名选项以及可选的保存选项，然后将 QR 码嵌入文档并将结果写入指定位置。

执行过程：

  1. 库读取源文档。
  2. 根据 QrCodeSignOptions 生成 QR 码。
  3. 在指定坐标插入图形。
  4. 将修改后的文件保存到您提供的路径。

如何在签署过程中处理错误？

将签署逻辑包装在 try‑catch 块中，以捕获文件缺失、路径无效或许可证问题等异常。

try {
    signature.sign(outputFilePath, signOptions, saveOptions);
    System.out.println("Document signed successfully!");
} catch (Exception e) {
    System.err.println("Signing failed: " + e.getMessage());
}

定义： 捕获 Exception 可确保任何运行时问题（如文件缺失、路径错误或许可证问题）被优雅地报告，防止生产环境应用崩溃。

常见使用场景与真实案例

自动化合同管理

某 SaaS 平台每月签署500+ 合同，通过生成包含合同 ID 和验证 URL 的唯一 QR 码实现。收件人扫描后可在门户查看合同状态，消除手动邮件往返。

员工证书颁发

人力资源部门在培训证书的 QR 码中嵌入员工 ID 和颁发日期。扫描 QR 即可在内部数据库中即时验证真实性，欺诈率降低超过 80 %。

审批工作流自动化

每位审批人的 QR 码存储其工号、角色和时间戳。系统在审计时读取 QR，提供防篡改的审计轨迹，无需额外数据库查询。

发票与收据签署

财务团队在发票上添加指向支付网关的 QR 码。扫描后直接跳转到安全支付页面，处理时间缩短30 %，发票欺诈风险下降。

生产环境最佳实践

安全考虑

  • 绝不嵌入明文密码； 使用令牌或服务器端解析的引用 ID。
  • 始终使用 HTTPS； 避免使用 HTTP 防止中间人攻击。
  • 设置令牌过期时间（例如 24 小时有效的 JWT）以保护时效性文档。

性能优化

  • 批量处理： 保持单个 Signature 实例存活并遍历文件，避免重复 JVM 启动。
  • 内存管理： 对于 > 50 MB 的文档，顺序处理并在每个文件后释放 Signature 对象。
  • 位置优化： 将 QR 码放在页面底部以减少布局重排并提升速度。
List<String> documents = getDocumentPaths();
for (String docPath : documents) {
    Signature sig = new Signature(docPath);
    // Configure and sign
    sig.dispose();
}

QR 码放置技巧

  • 打印安全性： QR 码距离页面边缘至少 0.5 英寸，防止被裁切。
  • 尺寸建议： 最小 150 × 150 px，确保打印介质上的可靠扫描。
  • 多页文档： 循环遍历页面，为每个位置实例化新的 QrCodeSignOptions。
for (Document doc : documents) {
    Signature sig = new Signature(doc.getPath());
    sig.sign(outputPath, signOptions, saveOptions);
    sig.dispose();
}

高级配置选项

如何在单个文档中添加多个 QR 码？

为每个位置创建独立的 QrCodeSignOptions 对象，并多次调用 sign。

// 第一个 QR 码
QrCodeSignOptions sign1 = new QrCodeSignOptions("Approver 1");
sign1.setLeft(100);
sign1.setTop(100);

// 第二个 QR 码
QrCodeSignOptions sign2 = new QrCodeSignOptions("Approver 2");
sign2.setLeft(300);
sign2.setTop(100);

// 同时应用
signature.sign(outputPath, sign1, saveOptions);
signature.sign(outputPath, sign2, saveOptions);

支持哪些其他条码类型？

除了 QR，还可以通过更改 setEncodeType() 生成 Aztec、DataMatrix 或 PDF417 条码。

如何根据页面尺寸计算动态位置？

通过 Signature.getDocumentInfo() 获取页面尺寸，并在代码中计算坐标。

// 获取文档信息
DocumentInfo docInfo = signature.getDocumentInfo();
int pageWidth = docInfo.getWidth();
int pageHeight = docInfo.getHeight();

// 将 QR 码居中
int qrSize = 100;
signOptions.setLeft((pageWidth - qrSize) / 2);
signOptions.setTop((pageHeight - qrSize) / 2);

定义： Signature.getDocumentInfo() 返回包含页面宽高等元数据的 DocumentInfo 对象，可用于根据实际页面大小精确计算签名坐标。

常见问题排查

QR 码未显示

  • 确认 setLeft/setTop 位于页面范围内（A4 ≈ 595 × 842 px，72 DPI）。
  • 确保前景/背景颜色对比度足够（黑底白字）。
  • 如二维码过小，请增大宽高。

初始化 Signature 时出现 “File not found”

  • 开发阶段使用绝对路径，或使用 Paths.get(...) 验证相对路径。
  • 确认源文件未被其他进程锁定。

输出文件损坏

  • 检查 setFileFormat 与期望的扩展名匹配。
  • 在签署前确保关闭可能仍占用文件的流。

QR 码包含错误数据

  • 在签署前打印传入 QrCodeSignOptions 的字符串以确认编码。
  • 除非明确设置 UTF‑8，否则避免使用非 ASCII 字符。

大文档性能慢

  • 采用批处理（参见代码块 10）。
  • 避免在复杂表格内放置 QR 码，表格会触发大量布局重新计算。

常见问答

Q: 能否签署 PDF 而不是 Word 文档？
A: 可以。GroupDocs.Signature 支持 PDF、Excel、PowerPoint、图像等多种格式。只需将 setFileFormat 改为相应的输出类型。

Q: 添加 QR 码后如何验证签名？
A: 使用库的 SearchQrCodeSignatures 方法定位 QR 码，并将嵌入的数据与后端服务进行校验。

Q: QR 码最大能存储多少数据？
A: 标准 QR 码最多可容纳 4 296 个字母数字字符，但为保证扫描可靠性，建议将负载控制在 500 字符 以下。若需更大数据，请存储引用 ID 并在服务器端获取详情。

Q: 能否自定义 QR 码的视觉外观？
A: 可以。您可以设置大小、位置、前景/背景颜色，甚至添加 logo 覆盖。请使用高对比度颜色以获得最佳扫描效果。

Q: 大文档签署时如何高效处理？
A: 对于超过 50 页的文档，单个文件大约需要几秒钟。使用批处理、复用 Signature 实例，并监控 JVM 堆内存大小。

Q: QR 码签名在转换为 PDF 后还能保持吗？
A: 完全可以。QR 码作为图形嵌入，转换格式时只要保持足够分辨率即可。

Q: 能否直接对存储在 S3 等云存储的文档签名？
A: 可以。先将文件下载到本地临时路径进行签名，然后再上传回 S3。库仅支持本地文件操作。

Q: 如果文档在签名后被修改会怎样？
A: QR 图形本身保持不变，但它本身不检测篡改。若需强完整性校验，请结合基于哈希的验证或数字证书。

Q: 开发与生产需要不同的许可证吗？
A: 开发阶段可使用免费试用或临时许可证。生产部署必须使用商业许可证，符合 GroupDocs 条款。

Q: 没有 Java 环境的收件人能扫描这些 QR 码吗？
A: 能。QR 码遵循开放标准，任何智能手机摄像头或 QR 读取应用均可解码。Java 仅在创建签名时使用。

资源

结论

现在，您已经拥有使用 Java 和 GroupDocs.Signature 在 Word 文档中创建 QR 码签名的完整、可投入生产的路线图。从基础设置到批量处理，从安全最佳实践到高级条码类型，所有内容一应俱全。先使用免费试用，尝试不同负载，然后将签署步骤集成到现有文档生成流水线。祝编码愉快，签署安全！

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

相关教程