在 PDF 中加入條碼簽章（使用 GroupDocs.Signature Java）

在現代以文件為中心的應用程式中，加入條碼簽章是一種快速且可靠的方式，讓 PDF 同時具備人類可讀與機器可掃描的特性。本教學將逐步說明從 Maven 設定、條碼樣式設定，到處理大型檔案的邊緣情況，讓您能自信地在 Java 專案中整合條碼簽章。

快速解答

  • 開始簽署的第一行程式碼是什麼？ Signature signature = new Signature("sample.pdf");
  • 我需要哪個 Maven 套件？ com.groupdocs:groupdocs-signature:23.10（請替換為最新版本）
  • 我可以簽署受密碼保護的 PDF 嗎？ 可以——在建立 Signature 物件時傳入密碼。
  • 支援多少種條碼格式？ 超過 30 種，包括 Code128、QR、DataMatrix 與 Aztec 等。
  • 對於 100 MB 的 PDF，建議的 JVM 堆積大小是多少？ 至少 -Xmx2g（2 GB），以避免 OutOfMemoryError。

什麼是條碼簽章？

條碼簽章是一種嵌入 PDF 的機器可讀條碼，作為防篡改標記，且可攜帶自訂資料，如 ID、時間戳記或 URL。它結合了視覺驗證與自動掃描，適用於庫存管理、合規性以及高量工作流程自動化。

為什麼要使用 GroupDocs.Signature Java 加入條碼簽章？

GroupDocs.Signature 支援 50+ 種輸入與輸出格式，能在不將整個檔案載入記憶體的情況下處理數百頁的 PDF，並提供流暢的 Java API，讓您微調條碼的每個視覺屬性。在基準測試中，於標準 2 vCPU 雲端實例上為 150 頁 PDF 加上 Code128 條碼的簽署時間 低於 1.2 秒。

前置條件

在開始之前，請確認您已具備以下條件：

  • Java Development Kit (JDK) 8 或更新版本（建議使用 JDK 11 或 17 以獲得長期支援）
  • IDE （IntelliJ IDEA、Eclipse 或配備 Java 擴充功能的 VS Code）
  • 建置工具 （Maven 3.6+ 或 Gradle 7.0+）
  • GroupDocs.Signature Java 函式庫（以下將示範 Maven 與 Gradle 設定）
  • 具備 Java OOP 概念以及 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 下載最新版本，並將其加入 classpath。

取得授權步驟

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 寫入，且適用於從幾 KB 到數百 MB 的 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());
        }
    }
}

主要設定說明：

  • 資料與類型 – "12345678" 為負載；BarcodeTypes.Code128 支援字母數字字串，且被掃描器廣泛支援。
  • 定位 – setLeft(100) 與 setTop(100) 使條碼相對左上角偏移 100 px；VerticalAlignment.Top + HorizontalAlignment.Right 依據這些偏移調整對齊。
  • 邊距與內距 – Padding 物件加入 20 px 緩衝，以避免頁面邊緣被裁切。
  • 樣式 – 邊框、字型與背景筆刷皆可完全自訂；在正式環境中可能會移除漸層以提升渲染速度。
  • 返回內容 – 啟用 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 px）。
  • 使用介於 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 的授權檔案以供 API 使用。
在每次簽署操作前檢查授權狀態，若過期則回退至唯讀模式或通知管理員。

```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

相關教學