如何使用 Java 在 PDF 中建立條碼簽章

在本教學中，您將學習如何使用 Java 及 GroupDocs.Signature 建立條碼簽章於 PDF 檔案。條碼簽章嵌入機器可讀的識別碼，具防篡改且易於掃描的特性——非常適合合約、證書、發票以及任何需要可靠驗證的文件。

快速解答

什麼是條碼簽章？ 一個嵌入 PDF 中的條碼，可儲存結構化資料，並可由掃描器或軟件讀取。
建議使用哪種條碼類型？ Code128，因為它能緊湊地處理字母與數字資料。
我需要授權嗎？ 免費試用可用於測試；正式環境需購買完整授權。
我可以在任何頁面尺寸上放置條碼嗎？ 是的——使用百分比定位即可自動縮放。
條碼是向量圖嗎？ 是的，它只會在 PDF 中增加幾 KB，且在任何解析度下都保持清晰。

為什麼條碼簽章對您的 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，並將其加入 classpath。

取得授權設定

在正式上線前，您需要先處理授權事宜：

Free Trial: 完美的測試方案——可從 GroupDocs 官方網站取得，以探索核心功能
Temporary License: 需要更多時間評估？申請 30 天的臨時授權
Full License: 已準備好投入生產？購買授權以獲得無限制使用

這裡提供一個快速的檢查，以確保一切正常運作：

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 文件與 legal 大小的表單。透過百分比定位，條碼會自動按比例縮放，保持一致外觀。若使用固定像素，條碼在大文件上會過小，或在小文件上過大。

實務範例： 在 A4 頁面（595 × 842 點）上，10% 寬度的條碼約為 60 點寬；在 legal 頁面（612 × 1008 點）上則約為 61 點——自動保持比例。

步驟 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 Code 形式置於易於掃描的區域。自動分揀系統即可在無需人工介入的情況下處理發票，將處理時間從數小時縮短至數分鐘。

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 Code，支援 UTF‑8 編碼。

問：Code128 條碼最多能儲存多少資料？
答：理論上可容納 128 個字元，但超過 30‑40 個字元後可讀性會顯著下降。若資料量較大，請使用 QR Code。

問：加入條碼會顯著增加 PDF 檔案大小嗎？
答：不會明顯增加——條碼為向量圖形，通常每個條碼僅增加 5‑20 KB，視尺寸與複雜度而定。

問：我可以旋轉條碼或垂直放置嗎？
答：可以！使用 options.setRotationAngle(90) 旋轉條碼，適合在邊緣放置。

問：如何讓條碼出現在多頁 PDF 的每一頁？
答：迭代每一頁並對其套用簽章。請參考 GroupDocs 文件中的 PagesSetup 類別，以控制簽署的頁面。

問：如果條碼掃描器無法讀取產生的條碼怎麼辦？
答：首先確認掃描器支援所選的條碼類型。接著增大條碼尺寸——大多數掃描問題源於條碼過小。建議寬度至少 1 吋（2.54 cm）以確保可靠讀取。

其他資源

文件說明：

下載與授權：

社群與支援：

Support Forum - Active community with GroupDocs engineers

最後更新： 2026-03-06
測試環境： GroupDocs.Signature 23.12 (Java)
作者： GroupDocs