在 Java 中建立 Barcode Signature – 更新 PDF 條碼

介紹

曾經在包裝重新設計後，需要在成千上萬的運送標籤上重新定位條碼嗎？或是在法律團隊更改文件版面時，需要更新合約範本中的條碼位置？你並不孤單——這類情境在文件自動化工作流程中屢見不鮮。

手動更新 barcode signature 既繁瑣又容易出錯。使用 GroupDocs.Signature for Java，你可以 建立 barcode signature 物件，然後只需幾行程式碼即可修改它們。無論你是在建構庫存系統、自動化物流文件，或是管理法律合約，程式化更新 barcode signatures 都能為你節省大量手動工作時間。

本教學你將掌握的內容：

• 設定並初始化 Signature API 以處理文件
• 高效搜尋現有的 barcode signatures
• 更新條碼位置、大小及其他屬性（包括如何 變更條碼大小）
• 處理常見錯誤與邊緣案例
• 為批次作業優化效能

在撰寫任何程式碼之前，先確保你已備妥所有必要的環境。

前置條件

在你的專案中更新 barcode signature Java 程式碼之前，請先確認以下必備項目：

必要函式庫

• GroupDocs.Signature for Java：版本 23.12 或更新（較舊版本可能缺少我們將使用的更新方法）。

環境設定

• 可運作的 Java Development Kit (JDK)（建議 JDK 8 以上）
• IDE（如 IntelliJ IDEA、Eclipse 或 VS Code）

知識前提

• 基礎 Java（類別、物件、例外處理）
• Java 檔案操作（路徑、目錄）
• 可選：了解 PDF 結構與條碼概念

全部準備好了嗎？太好了！接下來安裝函式庫。

設定 GroupDocs.Signature for Java

將 GroupDocs.Signature 加入 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 檔，並手動加入專案的 classpath。

取得授權

GroupDocs.Signature 同時支援試用版與正式授權：

• 免費試用 – 適合測試與概念驗證
• 臨時授權 – 用於特定專案的延長評估
• 正式授權 – 移除浮水印與使用限制，適合正式上線

專業提示：先使用免費試用版確認 API 符合需求，之後再升級為正式授權。

函式庫安裝完成後，我們開始實作。

快速問答

• 「create barcode signature」是什麼意思？ 指的是產生一個條碼物件，之後可以透過 API 在文件內放置、移動或編輯。
• 可以在建立後變更條碼大小嗎？ 可以 – 使用 setWidth 與 setHeight 方法，或調整 Left/Top 座標。
• 更新條碼需要授權嗎？ 開發階段使用試用版即可，正式上線需使用正式授權。
• 這只適用於 PDF 嗎？ 不只 – 相同程式碼同樣適用於 Word、Excel、PowerPoint 以及影像檔。
• 一次可以處理多少文件？ 支援批次處理，只要妥善管理記憶體（使用 try‑with‑resources）即可。

如何在 Java 中建立 barcode signature

步驟 1：初始化 Signature 實例

為何重要

把 Signature 物件想像成文件的入口。它會將 PDF（或任何支援格式）載入記憶體，並提供所有與簽章相關的操作。若未完成此初始化，就無法搜尋或修改任何內容。

實作

先匯入必要類別並定義檔案路徑：

import com.groupdocs.signature.Signature;
import java.nio.file.Paths;

String filePath = "YOUR_DOCUMENT_DIRECTORY/your_document.pdf";

Signature signature = new Signature(filePath);

發生了什麼事？ 建構子會讀取檔案並為後續操作做好準備。路徑可以是絕對或相對路徑，只要確保 Java 程序具有讀取權限即可。

專業提示： 在建立 Signature 實例前先驗證路徑，以避免拋出 FileNotFoundException。

步驟 2：搜尋 Barcode Signatures

為何先搜尋很關鍵

找不到就無法更新。GroupDocs.Signature 提供強大的搜尋 API，能依類型過濾簽章。

實作

匯入搜尋相關類別：

import com.groupdocs.signature.options.search.BarcodeSearchOptions;
import com.groupdocs.signature.domain.signatures.BarcodeSignature;
import java.util.List;

設定搜尋選項（預設會搜尋所有頁面）：

BarcodeSearchOptions options = new BarcodeSearchOptions();

執行搜尋：

List<BarcodeSignature> signatures = signature.search(BarcodeSignature.class, options);

此時會取得 BarcodeSignature 物件清單，每個物件皆提供 Left、Top、Width、Height、Text、EncodeType 等屬性。

效能說明： 若 PDF 極大，建議將搜尋範圍縮小至特定頁面或條碼類型，以提升速度。

步驟 3：更新條碼屬性

主要任務：修改 Barcode Signatures

現在可以 變更條碼大小 或重新定位條碼。

實作

先匯入例外處理類別：

import java.io.File;
import com.groupdocs.signature.exception.GroupDocsSignatureException;

設定輸出路徑（修改後的文件將儲存於此）：

String fileName = Paths.get(filePath).getFileName().toString();
String outputFilePath = new File("YOUR_OUTPUT_DIRECTORY/UpdateBarcode/" + fileName).getPath();
checkDir(outputFilePath);

接著，定位第一個條碼（或遍歷整個清單），套用變更：

if (signatures.size() > 0) {
    BarcodeSignature barcodeSignature = signatures.get(0);
    
    // Update the barcode's position and size
    barcodeSignature.setLeft(100);
    barcodeSignature.setTop(100);
    
    // Apply the changes to the document
    boolean result = signature.update(outputFilePath, barcodeSignature);
    
    if (result) {
        System.out.println("Signature with Barcode '" +
            barcodeSignature.getText() + "' and encode type '"+
            barcodeSignature.getEncodeType().getTypeName() + "' was updated in the document ['" +
            fileName + "'].");
    }
} catch (GroupDocsSignatureException e) {
    System.err.println("Error updating signature: " + e.getMessage());
}

重點說明：

• setLeft / setTop 會移動條碼（座標以左上角為原點）。
• update 方法會產生新檔，原檔保持不變。
• 請將呼叫包在 try‑catch 中，以處理可能的 GroupDocsSignatureException。

何時應該更新 Barcode Signatures？

了解適用情境有助於設計高效工作流程。

文件重新品牌化與範本更新

新信頭或標籤版面常意味著條碼需要重新定位。使用 Java 自動化遠比手動編輯數百檔案來得省時。

資料遷移後的批次處理

遷移後的 PDF 可能不符合目前的條碼放置標準。批次更新即可在不重新產生每份文件的情況下恢復一致性。

法規遵循調整

物流或醫療等產業可能會變更條碼放置規範。快速腳本讓你即時符合新規定。

動態文件產生

若文件內容長度不固定，可能需要即時調整條碼座標。

不建議使用更新的情況： 若是全新建立文件，請在一開始就正確放置條碼，而非先加入再更新。

常見問題與解決方案

問題 1：「找不到 Barcode Signatures」

症狀： 搜尋結果為空清單，即使 PDF 中確實有條碼。

可能原因

• 條碼以圖像或表單欄位形式嵌入，非簽章物件。
• 文件受密碼保護。
• 你使用的條碼類型過濾與實際不符。

解決方式

BarcodeSearchOptions options = new BarcodeSearchOptions();
options.setAllPages(true); // Search all pages, not just the first
List<BarcodeSignature> signatures = signature.search(BarcodeSignature.class, options);

if (signatures.isEmpty()) {
    System.out.println("No barcode signatures found. The barcodes might be images, not signature objects.");
}

問題 2：更新後的文件損毀

症狀： PDF 在更新後無法開啟。

可能原因

• 磁碟空間不足。
• 輸出目錄不存在。
• 檔案系統權限阻止寫入。

解決方式

File outputDir = new File("YOUR_OUTPUT_DIRECTORY/UpdateBarcode/");
if (!outputDir.exists()) {
    outputDir.mkdirs(); // Create directories if they don't exist
}

// Check write permissions
if (!outputDir.canWrite()) {
    throw new IOException("Cannot write to output directory: " + outputDir.getAbsolutePath());
}

問題 3：大型文件效能下降

症狀： 處理超過約 50 頁的 PDF 時速度顯著變慢。

解決方式

BarcodeSearchOptions options = new BarcodeSearchOptions();
options.setPageNumber(1); // Start with page 1
options.setPagesSetup(new PagesSetup());
options.getPagesSetup().setFirstPage(true);
options.getPagesSetup().setLastPage(false);

效能優化技巧

批次作業的記憶體管理

一次只處理一份文件，讓 Java 自動釋放資源：

List<String> documentPaths = getDocumentList();
for (String path : documentPaths) {
    try (Signature sig = new Signature(path)) {
        // Process one document at a time
        // Signature instance is auto‑closed after each iteration
    }
}

快取搜尋結果

若需對同一批條碼修改多個屬性，請只搜尋一次並重複使用清單：

List<BarcodeSignature> signatures = signature.search(BarcodeSignature.class, options);

// Update multiple properties
for (BarcodeSignature barcode : signatures) {
    barcode.setLeft(100);
    barcode.setTop(100);
    barcode.setWidth(200);
    barcode.setHeight(50);
}

// Single update call with all changes
signature.update(outputPath, signatures);

大量批次的平行處理

利用 Java Streams 加速上千份文件的處理：

documentPaths.parallelStream().forEach(path -> {
    try (Signature sig = new Signature(path)) {
        List<BarcodeSignature> barcodes = sig.search(BarcodeSignature.class, new BarcodeSearchOptions());
        if (!barcodes.isEmpty()) {
            BarcodeSignature barcode = barcodes.get(0);
            barcode.setLeft(50);  // New position for smaller boxes
            barcode.setTop(10);
            sig.update(generateOutputPath(path), barcode);
        }
    } catch (Exception e) {
        logError(path, e);
    }
});

實務應用

用例 1：自動化物流標籤更新

某運輸公司因箱尺寸變更，需要重新定位 50,000 份既有標籤上的條碼。使用上述平行處理程式碼，作業時間從數天縮短至數小時。

用例 2：合約範本標準化

法律部門要求條碼固定於掃描位置。透過一次搜尋並批次更新所有合約 PDF，避免了昂貴的手動重新列印。

用例 3：庫存系統整合

ERP 升級後，產品條碼需與新標籤印表機對齊。程式化調整條碼大小與位置，為公司節省了大量時間與材料成本。

疑難排解清單

在尋求支援前，請先檢查以下項目：

• 檔案路徑正確且檔案確實存在
• 讀寫權限已授予來源與目的地
• GroupDocs.Signature 版本為 23.12 或更新
• 授權已正確設定（若使用正式授權）
• 輸出目錄已存在或已於程式中建立
• 磁碟空間充足以存放輸出檔案
• 無其他程序鎖定來源檔案
• 已加入例外處理以捕捉錯誤

常見問答

Q：可以在同一文件中一次更新多個條碼嗎？
A：當然可以。遍歷 List<BarcodeSignature>，對每個物件呼叫 signature.update()，或將整個清單一次傳入 update。

Q：GroupDocs.Signature 支援哪些條碼類型？
A：支援數十種，包括 Code 128、QR Code、EAN‑13、UPC‑A、DataMatrix、PDF417 等。可使用 barcodeSignature.getEncodeType() 取得類型。

Q：可以變更條碼的實際內容（編碼資料）嗎？
A：可以，透過 setText()，但請同時重新產生視覺條碼，以確保掃描器正確讀取。

Q：如何處理多頁文件中的條碼？
A：每個 BarcodeSignature 都有 getPageNumber()，可依頁面過濾或分別處理。

Q：更新後原始文件會怎樣？
A：原檔保持不變，GroupDocs 會將變更寫入你指定的輸出路徑，確保安全。

Q：可以在受密碼保護的 PDF 中更新條碼嗎？
A：可以。使用 Signature 建構子的 LoadOptions 參數提供密碼即可。

Q：如何有效批次處理成千上萬的文件？
A：結合平行串流與 try‑with‑resources（如前述平行處理範例），並監控記憶體使用情況。

Q：這只適用於 PDF 嗎？
A：不只。相同 API 同樣支援 Word、Excel、PowerPoint、影像等多種格式。

結論

現在你已掌握一套完整、可投入生產環境的指南，能在 Java 中 create barcode signature，並更新其位置、大小及其他屬性。我們涵蓋了初始化、搜尋、修改、疑難排解與效能調校，適用於單一文件與大規模批次情境。

後續建議

• 嘗試在同一次執行中更新多個屬性（如旋轉、透明度）。
• 建置 REST 服務，將條碼更新功能以 API 形式提供。
• 探索其他簽章類型（文字、影像、數位簽章），使用相同模式自動化文件流程。

GroupDocs.Signature API 的功能遠不止條碼更新，深入了解驗證、元資料處理與多格式支援，讓你的文件工作流程全面自動化。

資源

• GroupDocs.Signature for Java Documentation
• API Reference
• Support Forum
• Free Trial Download

最後更新日期： 2026-01-16
測試環境： GroupDocs.Signature 23.12
作者： GroupDocs