如何在 Java 中使用 GroupDocs 追蹤轉換進度

如果您需要在 Java 應用程式中了解如何追蹤轉換——尤其是想要convert docx pdf java——GroupDocs.Conversion 提供一個簡潔、事件驅動的方式。透過掛載監聽器，您可以即時取得轉換管線每個階段的回饋，讓批次作業、UI 進度條與日誌記錄更加透明。

快速答覆

  • Listener 會做什麼？ 它會回報開始、進度（百分比）以及完成事件。
  • 我可以監控哪些格式？ 任何 GroupDocs.Conversion 支援的格式，例如 DOCX → PDF。
  • 需要授權嗎？ 免費試用可用於開發；正式環境需要付費授權。
  • 必須使用 Maven 嗎？ Maven 可簡化相依管理，但您也可以使用 Gradle 或手動 JAR。
  • 可以在 Web 服務中使用嗎？ 可以——將轉換呼叫包在 REST 端點，並將進度串流回客戶端。

在 GroupDocs 中「如何追蹤轉換」是什麼？

GroupDocs.Conversion 提供 IConverterListener 介面。實作此介面可讓程式在轉換引擎狀態變更時作出回應，從而記錄、更新 UI 元件或觸發後續流程。

為什麼要追蹤轉換進度？

  • 使用者體驗： 在 UI 儀表板或 CLI 工具中顯示即時百分比。
  • 錯誤處理： 及早偵測卡住情況，並重新嘗試或優雅地中止。
  • 資源規劃： 估算大量批次的處理時間，並相應配置資源。

前置條件

  • Java Development Kit (JDK 8+)。
  • Maven（或任何能解析 Maven 套件庫的建置工具）。
  • GroupDocs.Conversion for Java 函式庫。
  • 有效的 GroupDocs 授權（免費試用可用於測試）。

設定 GroupDocs.Conversion for Java

透過 Maven 安裝 GroupDocs.Conversion

將以下儲存庫與相依加入您的 pom.xml：

<repositories>
    <repository>
        <id>groupdocs-repo</id>
        <name>GroupDocs Repository</name>
        <url>https://releases.groupdocs.com/conversion/java/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.groupdocs</groupId>
        <artifactId>groupdocs-conversion</artifactId>
        <version>25.2</version>
    </dependency>
</dependencies>

取得授權

GroupDocs 提供免費試用、評估用臨時授權，以及商業使用的購買方案。前往他們的購買頁面取得授權。

基本初始化

將函式庫加入 classpath 後，您即可建立 ConverterSettings 實例：

import com.groupdocs.conversion.Converter;
import com.groupdocs.conversion.ConverterSettings;

public class InitializeGroupDocs {
    public static void main(String[] args) {
        ConverterSettings settings = new ConverterSettings();
        // Additional configurations can be set here.
    }
}

實作指南

我們將逐步說明每個功能，並在每段程式碼前提供說明。

功能 1：轉換狀態與進度監聽器

概觀

此監聽器會告知您轉換何時開始、進度多少以及何時完成。

實作監聽器

建立一個實作 IConverterListener 的類別：

import com.groupdocs.conversion.IConverterListener;

class ListenConversionStateAndProgress implements IConverterListener {
    public void started() {
        System.out.println("Conversion has begun.");
    }

    public void progress(byte current) {
        System.out.printf("Conversion Progress: %d%%\n", current);
    }

    public void completed() {
        System.out.println("Conversion has finished.");
    }
}

說明

  • started() – 在引擎開始處理前立即呼叫。可用於重設計時器或 UI 元件。
  • progress(byte current) – 接收 0 到 100 的值，代表完成的百分比。非常適合用於進度條。
  • completed() – 在輸出檔案寫入完成後觸發。此處可清理資源。

功能 2：帶監聽器的 Converter Settings

概觀

將您的監聽器附加至 ConverterSettings，讓引擎知道要將事件發送至何處。

設定步驟

  1. 建立您的監聽器實例：

    IConverterListener listener = new ListenConversionStateAndProgress();

  2. 設定 ConverterSettings 物件：

    ConverterSettings settingsFactory = new ConverterSettings();
settingsFactory.setListener(listener);

功能 3：執行文件轉換

概觀

現在您將在將 DOCX 檔案轉換為 PDF 時看到監聽器的運作。

實作步驟

  1. 定義輸入與輸出路徑（請替換為實際目錄）：

    String inputDocPath = "YOUR_DOCUMENT_DIRECTORY/SAMPLE_DOCX";
String outputPath = "YOUR_OUTPUT_DIRECTORY/converted.pdf";

  2. 使用已啟用監聽器的設定初始化 Converter，然後執行轉換：

    try (Converter converter = new Converter(inputDocPath, settingsFactory)) {
    PdfConvertOptions options = new PdfConvertOptions();
    converter.convert(outputPath, options);
}

說明

  • Converter – 負責協調轉換的核心類別。
  • PdfConvertOptions – 告訴 GroupDocs 您想要 PDF 輸出。您可以改用 PptxConvertOptions、HtmlConvertOptions 等，監聽器仍會回報進度。

如何使用 GroupDocs 進行 docx pdf java 轉換

上述程式碼已示範 docx → pdf 流程。若需其他目標格式，只需將 PdfConvertOptions 替換為相應的選項類別（例如 HtmlConvertOptions 轉成 HTML）。監聽器保持不變，無論輸出類型皆能取得即時進度。

實務應用

  1. 自動化文件管理系統 – 批次處理數千個檔案，同時顯示即時進度儀表板。
  2. 企業軟體解決方案 – 將轉換嵌入發票流程、法律文件歸檔或 e‑learning 內容產生。
  3. 內容遷移工具 – 監控從舊版格式大規模遷移至現代 PDF，確保及早發現卡頓。

效能考量

  • 記憶體管理： 使用 try‑with‑resources（如範例所示）確保 Converter 及時關閉。
  • 執行緒： 大量批次時，可在平行執行緒中執行轉換，但每個執行緒需有自己的監聽器實例，以免輸出混雜。
  • 日誌記錄： 讓監聽器的 System.out 呼叫保持輕量；正式環境建議導向至適當的日誌框架（SLF4J、Log4j）。

常見問題與解決方案

問題解決方案
No progress output確認在建立 Converter 前已呼叫 settingsFactory.setListener(listener);。
OutOfMemoryError on large files增加 JVM 堆大小（-Xmx2g 或更高），並盡可能將檔案分成較小的區塊處理。
Listener not triggered on error將 converter.convert 包在 try‑catch 區塊，並在監聽器實作中呼叫自訂的 error(byte code) 方法。

常見問答

Q: 我可以追蹤除 PDF 之外的其他格式的轉換進度嗎？
A: 可以。相同的 IConverterListener 可用於 GroupDocs.Conversion 支援的任何目標格式，只需更換選項類別即可。

Q: 如何有效處理大型文件？
A: 使用 Java 的串流 API、增加 JVM 堆大小，並透過監聽器的進度監控長時間執行的步驟。

Q: 若轉換途中失敗會發生什麼？
A: 在監聽器中實作額外方法（例如 error(byte code)），並在 convert 呼叫周圍加入例外處理，以捕捉並記錄失敗。

Q: 檔案大小或類型有沒有限制？
A: 大多數常見格式皆受支援，但極大檔案可能需要更多記憶體。請參考官方GroupDocs 文件了解詳細限制。

Q: 如何在 Web 應用程式中提供此功能？
A: 將轉換邏輯包在 REST 端點（例如 Spring Boot）中，並透過 Server‑Sent Events（SSE）或 WebSocket 串流進度更新，將監聽器的輸出傳送給客戶端。

資源

最後更新： 2025-12-19
測試環境： GroupDocs.Conversion 25.2
作者： GroupDocs