建立條碼簽名 Java – 更新 PDF 條碼

當您需要在成千上萬的運送標籤上重新定位條碼，或在模板重新設計後調整條碼位置時，手動操作容易出錯且耗時。於本指南中，您將學習 how to create barcode signature java，並使用 GroupDocs.Signature for Java 以程式方式修改其位置、大小及其他屬性。此方法適用於 PDF、Word、Excel、PowerPoint 及圖像檔案，為您的所有文件自動化情境提供單一且一致的 API。

快速解答

• 什麼是「create barcode signature」？ 它表示產生一個 BarcodeSignature 物件，可透過 API 在文件中放置、移動或編輯。
• 建立條碼後可以變更其大小嗎？ 是的 – 使用 setWidth/setHeight 或調整其 Left/Top 座標。
• 更新條碼需要授權嗎？ 試用版可用於開發；正式版授權則需於生產環境使用。
• 這只能用於 PDF 嗎？ 不能 – 相同程式碼可用於 Word、Excel、PowerPoint 以及常見的圖像格式。
• 一次可以處理多少文件？ 支援批次處理；只需使用 try‑with‑resources 來管理記憶體。

什麼是 create barcode signature java？

Create barcode signature java 是指實例化一個 BarcodeSignature 物件，該物件代表嵌入於文件中的條碼數位簽名。使用 GroupDocs.Signature API，您可以以程式方式新增條碼、定位既有條碼，或修改其屬性（如位置、大小與編碼文字），全部不需在視覺編輯器中開啟檔案。

為何使用 GroupDocs.Signature for Java？

GroupDocs.Signature 支援 50+ 種輸入與輸出格式——包括 PDF、DOCX、XLSX、PPTX 以及常見圖像類型，且能在記憶體使用量低於 100 MB 的情況下處理數百頁的 PDF。其批次 API 在一般伺服器上每次可處理多達 10,000 份文件，使大規模更新成為可能。

前置條件

• GroupDocs.Signature for Java ≥ 23.12（較早的版本缺少此處使用的更新方法）。
• Java Development Kit 8 或更高版本。
• 如 IntelliJ IDEA、Eclipse 或 VS Code 等 IDE。
• 基本的 Java 知識（類別、物件、例外處理）。

必要的函式庫

使用您偏好的建置工具將 GroupDocs.Signature 加入專案。

Maven

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

Gradle

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

Direct download – 從 GroupDocs.Signature for Java releases 下載最新的 JAR，並加入您的 classpath。

取得授權

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

• Free trial – 適合概念驗證（Proof‑of‑Concept）工作。
• Temporary license – 用於特定專案的延伸評估。
• Full license – 移除水印與使用限制，適用於正式環境。

Pro tip：先使用免費試用版，驗證工作流程後再升級。

如何建立 create barcode signature java

步驟 1：初始化簽名實例

Signature 是主要的入口類別，用於載入文件並提供搜尋、加入與更新簽名的方法。

直接回答

透過傳入欲編輯文件的路徑來建立 Signature 物件；此動作會將檔案載入記憶體，並為條碼操作做好準備。Signature 類別是所有簽名相關操作的入口，負責讀取檔案並提供搜尋、加入或更新簽名的方法。

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

String filePath = "YOUR_DOCUMENT_DIRECTORY/your_document.pdf";

Signature signature = new Signature(filePath);

Pro tip：在建立 Signature 實例前先驗證檔案路徑，以避免 FileNotFoundException。

步驟 2：搜尋條碼簽名

BarcodeSearchOptions 定義掃描文件以尋找條碼簽名時使用的條件。

直接回答

使用 BarcodeSearchOptions 搭配 search 方法，可取得文件中所有條碼簽名的清單。找不到的就無法更新。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 等屬性。

Performance note：對於非常大的 PDF，將搜尋範圍縮小至特定頁面或條碼類型，可加快執行速度。

步驟 3：更新條碼屬性

BarcodeSignature 代表文件中嵌入的單一條碼，並提供設定其視覺屬性的 setter 方法。

直接回答

修改取得的 BarcodeSignature 的 Left、Top、Width 與 Height，然後呼叫 signature.update 將變更寫入新檔案。這讓您可以調整條碼大小或重新定位，而原始檔案保持不變。

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());
}

Key points

• setLeft / setTop 會移動條碼（座標以左上角為基準）。
• update 會寫入新檔案，原始檔案保持不變。
• 將呼叫包在 try‑catch 區塊中，以處理可能的 GroupDocsSignatureException。

何時應該更新條碼簽名？

當文件版面變更、法規要求調整，或在資料遷移後需要批次處理現有檔案時，應更新條碼簽名。以程式方式更新可避免手動重新編輯，降低錯誤率，並確保成千上萬檔案的條碼位置一致。

常見問題與解決方案

問題 1：「找不到條碼簽名」

症狀：即使 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: 可以在同一文件中更新多個條碼簽名 Java 程式碼嗎？
A: 當然可以。遍歷 search 回傳的 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: 結合平行 streams 與 try‑with‑resources（如平行處理範例所示），並監控記憶體使用情況。

Q: 除了 PDF，這也適用於其他格式嗎？
A: 適用。相同的 API 可用於 Word、Excel、PowerPoint、圖像以及 GroupDocs.Signature 支援的其他多種格式。

結論

您現在擁有完整且可投入生產的指南，說明如何建立 create barcode signature java 物件並更新其位置、大小及其他屬性。我們涵蓋了初始化、搜尋、修改、疑難排解與效能調校，適用於單一文件與大規模批次情境。

後續步驟

• 嘗試在同一次執行中更新其他屬性，如旋轉或不透明度。
• 將此邏輯封裝為 REST 服務，將條碼更新作為 API 端點提供。
• 使用相同模式探索其他簽名類型（文字、圖像、數位），全面自動化文件工作流程。

資源

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

最後更新： 2026-08-19
測試版本： GroupDocs.Signature 23.12
作者： GroupDocs

相關教學

• 在 Java 中建立 PDF 條碼簽名 – GroupDocs 指南
• GroupDocs.Signature Java 教學 – 為 PDF 新增條碼簽名
• Java 條碼簽名教學 – 新增、驗證與管理 PDF 中的條碼