生成 QR Code Java：完整 QR Code 簽署指南

在本教學中，您將學會如何使用 GroupDocs.Signature for Java 在 PDF 文件中 生成 QR Code Java 簽名。我們將逐步說明如何添加 QR Code、精確定位，以及避免大多數開發者常犯的錯誤。無論您是構建合約管理平台還是安全發票流程，此指南都提供了可直接投入生產的解決方案。

快速答覆

• 哪個程式庫在 Java 中添加 QR Code 簽名？ GroupDocs.Signature for Java
• 哪個建置工具支援 Maven 依賴？ Maven（請參閱 maven dependency groupdocs）
• 我可以在特定頁面上定位 QR Code 嗎？ 可以，使用對齊與頁碼選項
• 生產環境需要授權嗎？ 需要，必須擁有商業版 GroupDocs 授權
• 簽署後 QR Code 能被掃描嗎？ 當尺寸 ≥ 100 × 100 px 且使用適當邊距時，絕對可以

您將學到的內容

完成本指南後，您將能夠：

• 在 Java 專案中設定 QR Code 簽署（Maven、Gradle 或直接下載）
• 在文件的精確位置（角落、中心、客製對齊）添加 QR Code
• 在問題變成生產故障前處理常見實作議題
• 為高吞吐量文件工作流程優化效能
• 將這些技術應用於真實商業情境

前置條件

在開始編寫程式碼之前，請確保您已具備：

• GroupDocs.Signature for Java – 版本 23.12 或更新（以下會說明安裝方式）
• Java Development Kit – JDK 8 或以上（大多數生產環境使用 JDK 11+）
• 建置工具 – Maven 或 Gradle 用於管理相依性
• 基本 Java 知識 – 能熟悉 try‑catch 區塊與檔案路徑處理

即使您是 GroupDocs 新手，我們也會一步一步帶您完成。

設定開發環境

將 GroupDocs.Signature 引入專案相當簡單，請依照您的建置系統選擇適合的方法。

使用 Maven

將以下 maven dependency groupdocs 加入 pom.xml 檔案：

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

加入後，執行 mvn clean install 以下載程式庫。

使用 Gradle

對於 Gradle 專案，將此行加入 build.gradle：

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

然後使用 gradle build 同步專案。

直接下載方式

想手動安裝？請從 GroupDocs.Signature for Java releases 下載 JAR，並將其加入專案的 classpath。

授權設定（重要！）

以下是常讓使用者感到意外的地方：GroupDocs 需要授權才能在生產環境使用。可選方案：

• 免費試用 – 完整功能，時間有限
• 臨時授權 – 需要更長測試時間？可取得 temporary license 進行延長測試
• 商業授權 – 生產部署時請 purchase a license

試用版會加上浮水印，請依需求規劃示範環境。

基本初始化

Signature 是 GroupDocs.Signature for Java 的主要入口類別，用於載入與操作文件以進行簽署。安裝程式庫後，初始化非常簡單，只需指向您的文件：

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

即可建立可供使用的 Signature 物件。

了解 QR Code 簽名

QR Code 簽名會將可驗證資料（例如時間戳、簽署者身分或驗證 URL）嵌入文件內的可掃描 QR 圖片。掃描後，QR Code 會導向驗證入口或顯示內嵌的中繼資料，讓使用者無需特殊軟體即可快速行動驗證。

何時應使用 QR Code 簽名？

• 手機快速驗證（使用手機掃描）
• 可能列印的實體文件
• 嵌入驗證入口的連結
• 支援離線驗證工作流程

實作指南：添加 QR Code 簽名

以下示範如何在 PDF 中於不同位置加入 QR Code 簽名。

為何定位很重要

正確的定位可確保 QR Code 易於掃描、符合合規標準，且不會遮蔽重要內容。合約常放在右下角；發票則適合右上角；證書則在底部居中較為美觀。

步驟式實作

1. 設定檔案路徑

定義來源文件與簽署後檔案的存放位置：

String filePath = "YOUR_DOCUMENT_DIRECTORY/sample.pdf";
String fileName = Paths.get(filePath).getFileName().toString();
String outputFilePath = new File("YOUR_OUTPUT_DIRECTORY", "SignWithAlignment/" + fileName).getPath();

小技巧： 使用 Paths.get() 取代字串串接，可自動處理作業系統的路徑分隔符。

2. 初始化 Signature 物件

將初始化包在 try‑catch 區塊中，以處理可能的檔案存取問題：

try {
    Signature signature = new Signature(filePath);
    // 簽署邏輯寫在這裡...
} catch (Exception e) {
    throw new RuntimeException("Error initializing signature: " + e.getMessage(), e);
}

RuntimeException 能在除錯時提供更多上下文資訊，省下大量時間。

3. 定義 QR Code 大小與位置

QrCodeSignOptions 用於設定將放置於文件的 QR 圖片，可設定尺寸、邊距與對齊方式。

int qrWidth = 100;
int qrHeight = 100;
List<SignOptions> listOptions = new ArrayList<>();

for (int horizontalAlignment : HorizontalAlignment.getValues()) {
    for (int verticalAlignment : VerticalAlignment.getValues()) {
        if (verticalAlignment != VerticalAlignment.None && horizontalAlignment != HorizontalAlignment.None) {
            QrCodeSignOptions options = new QrCodeSignOptions("Left-Top");
            options.setWidth(qrWidth);
            options.setHeight(qrHeight);
            options.setHorizontalAlignment(horizontalAlignment);
            options.setVerticalAlignment(verticalAlignment);
            options.setMargin(new Padding(5));
            listOptions.add(options);
        }
    }
}

此迴圈會為每種水平（左、置中、右）與垂直（上、置中、下）對齊建立 QR Code 設定，並加上 5 像素的邊距，避免貼到頁面邊緣。

在大多數生產情境下，您只會選擇單一位置，例如合約的右下角：

QrCodeSignOptions options = new QrCodeSignOptions("Signature");
options.setWidth(100);
options.setHeight(100);
options.setHorizontalAlignment(HorizontalAlignment.Right);
options.setVerticalAlignment(VerticalAlignment.Bottom);
options.setMargin(new Padding(10));

4. 簽署文件

一次性套用所有已配置的簽名：

SignResult signResult = signature.sign(outputFilePath, listOptions);

sign() 方法會處理列表中的每個 QR Code，並將結果寫入指定的輸出路徑。回傳的 SignResult 物件會告訴您成功加入的簽名數量，方便記錄。

效能說明： 簽署為同步操作。若每小時需處理上百份文件，建議將此流程放入背景工作佇列，而非直接在使用者請求中執行。

常見陷阱與解決方案

問題 1：「找不到檔案」錯誤

症狀： 即使檔案確實存在仍拋出檔案未找到例外。

解決方案： 檢查以下三點：

1. 使用絕對路徑或確認工作目錄正確。
2. 確認來源檔案具讀取權限，輸出資料夾具寫入權限。
3. 逃脫路徑中的特殊字元。

// 更佳做法：使用絕對路徑
String absolutePath = new File(filePath).getAbsolutePath();
Signature signature = new Signature(absolutePath);

問題 2：QR Code 與文件內容重疊

症狀： QR Code 蓋住重要文字或被裁切在頁邊。

解決方案： 增大邊距值，並選擇不會佔用文字區域的對齊方式：

options.setMargin(new Padding(20)); // 從 5 像素提升至 20 像素

問題 3：大型文件的記憶體問題

症狀： 處理超過 10 MB 的 PDF 時拋出 OutOfMemoryError。

解決方案： 盡快釋放 Signature 物件，並分批處理大型檔案：

try (Signature signature = new Signature(filePath)) {
    // 簽署程式碼寫在此處
} // 自動關閉並釋放資源

使用 try‑with‑resources 可確保即使發生例外也會正確清理。

問題 4：QR Code 內容未更新

症狀： 所有 QR Code 顯示相同文字，即使嘗試自訂。

解決方案： 為每個位置 建立新的 QrCodeSignOptions 物件，切勿重複使用同一個實例：

// 錯誤範例 – 重複使用同一物件
QrCodeSignOptions options = new QrCodeSignOptions("Text");
options.setHorizontalAlignment(HorizontalAlignment.Left);
listOptions.add(options);
options.setHorizontalAlignment(HorizontalAlignment.Right); // 會修改已加入的物件
listOptions.add(options);

// 正確範例 – 每次建立新物件
listOptions.add(new QrCodeSignOptions("Left"));
listOptions.add(new QrCodeSignOptions("Right"));

實務應用

1. 合約管理系統

工作流程：產生合約 PDF → 加入包含合約編號、時間戳、簽署者雜湊的 QR Code → 安全儲存 → 使用者掃描 QR → 入口顯示合約詳細資訊。此方式讓法務團隊能即時驗證列印版合約的真偽。

2. 發票處理自動化

在每張處理過的發票右上角加入 QR Code，編碼發票號、供應商 ID 與處理時間戳。固定位置讓掃描器快速定位，提高稽核效率。

3. 證書認證

在證書底部居中放置 QR Code，內含驗證 URL 與證書 ID。收件人可掃描確認憑證，亦提供印刷版 URL 供非行動裝置使用。

4. 內部文件追蹤

於多階段審批過程中，每完成一次簽核即嵌入 QR Code，內含審批者 ID、時間戳與版本號。掃描後即可看到完整審批歷史，滿足合規稽核需求。

生產環境最佳實踐

資源管理

務必關閉 Signature 物件以防止記憶體泄漏：

try (Signature signature = new Signature(filePath)) {
    // 您的程式碼
} // 自動關閉

對於 Web 應用，可考慮建立處理池以限制同時執行的作業數量。

錯誤處理策略

提供可操作的錯誤資訊，避免靜默捕獲：

try {
    SignResult result = signature.sign(outputFilePath, listOptions);
    if (result.getSucceeded().size() < listOptions.size()) {
        logger.warn("Only {} of {} signatures applied",
                    result.getSucceeded().size(),
                    listOptions.size());
    }
} catch (Exception e) {
    logger.error("Signature failed for document: {}", filePath, e);
    // 實作重試或警示機制
}

效能優化

高吞吐量環境建議：

1. 批次處理 – 並行處理文件，但依記憶體容量限制併發數。
2. 快取 – 在多份文件間重用相同的 QrCodeSignOptions 物件。
3. 非同步作業 – 將簽署移至背景工作者，以提升 API 回應速度。
4. 記憶體監控 – 設定警示，根據使用情形調整批次大小。

安全考量

• 將簽署後的文件與原始檔分開儲存。
• 為每一次簽署操作寫入日誌，以建立稽核追蹤。
• 嚴格控管簽署端點的存取權限。
• 必要時對 QR Code 內的敏感資料進行加密。

何時使用 QR Code 簽名（以及何時不適合）

適合使用 QR Code 簽名的情境：

• 需要行動裝置快速驗證。
• 文件可能列印且需再次掃描。
• 必須嵌入驗證 URL 或 ID。
• 工作流程包含離線驗證步驟。

不建議使用 QR Code 簽名的情境：

• 法律上必須使用具 PKI 的加密簽章（請改用加密簽名）。
• QR Code 在列印或搬運過程中容易受損或被遮蔽。
• 完全離線且無法使用掃描設備的環境。
• 文件大小受嚴格限制（每個 QR Code 會增加約 5‑20 KB）。

最佳做法： 同時結合加密簽章與 QR Code，兼顧法律效力與行動驗證便利性。

疑難排解指南

簽名未出現在文件中

1. 確認輸出檔案確實已產生。
2. 確認開啟的是正確的輸出檔案。
3. 檢查 SignResult 的成功計數。
4. 確認對齊與邊距設定未將 QR Code 推到頁面外。

QR Code 無法掃描

• 保持 QR 大小 ≥ 100 × 100 px。
• 使用高對比度（深色碼面對淺色背景）。
• 編碼資料少於 100 個字元，以提升掃描可靠度。
• 實體列印時解析度至少 300 dpi。

效能下降

• 減少每份文件的 QR Code 數量。
• 盡可能重用 Signature 實例。
• 監控記憶體使用情形，必要時改為較小批次處理。

常見問答

Q： 我可以簽署除 PDF 之外的文件嗎？
A： 可以。GroupDocs.Signature 支援 Word（DOC/DOCX）、Excel（XLS/XLSX）、PowerPoint（PPT/PPTX）以及影像格式（JPG、PNG、TIFF）。API 在所有支援類型上保持一致。

Q： 如何自訂 QR Code 的外觀？
A： 使用 QrCodeSignOptions 的 setForeColor()、setBackgroundColor()、setBorder() 等屬性。保持自訂簡潔，以免影響掃描。

Q： 能否在多頁文件的特定頁面加入 QR Code？
A： 完全可以。透過 options.setPageNumber(pageNumber); 設定頁碼。例如：

options.setPageNumber(1); // 僅在第一頁加入

Q： QR Code 可以編碼什麼資料？
A： 任意文字、URL、JSON 或 XML，建議不超過 200 個字元以確保掃描穩定。若資料較大，可編碼指向完整資料的短網址。

Q： 如何以程式方式驗證 QR Code 簽名？
A： GroupDocs.Signature 提供 verify 方法。例如：

VerificationResult result = signature.verify(verifyOptions);
if (result.isValid()) {
    // 簽名有效
}

Signature 類別是對文件套用簽名的主要入口。

Q： 可以在多執行緒環境使用嗎？
A： 可以，但每個執行緒必須建立獨立的 Signature 物件——實例本身不是執行緒安全的。建議使用處理佇列以因應高併發需求。

Q： 加入 QR Code 會對檔案大小產生多少影響？
A： 影響極小，通常每個 QR Code 只會增加約 5‑20 KB，對大多數 PDF 來說可忽略不計。但若一次簽署上千頁文件，仍需考慮累積效應。

最後更新： 2026-05-21
測試環境： GroupDocs.Signature 23.12 for Java
作者： GroupDocs

資源

• GroupDocs.Signature for Java releases
• temporary license
• purchase a license
• GroupDocs documentation
• GroupDocs.Signature Java Docs
• Complete API Reference
• Latest Java Release
• Buy GroupDocs.Signature
• Start Your Free Trial
• Get Temporary License
• GroupDocs Forum

相關教學

• Java QR Code Signature Library - Complete GroupDocs Tutorial
• Extract QR Code Data in Java - Complete Guide with GroupDocs
• Remove QR Code from PDF Java - Complete Guide with GroupDocs