從 PDF 產生 HTML 並停用分組（使用 GroupDocs Viewer for Java）

在許多專案中，您需要 從 PDF 產生 HTML，同時確保每個字形精確地位於其應有的位置。對於複雜文字、古代語言或法律文件尤為重要，因為單一錯位的字元可能改變含義。在本教學中，我們將逐步說明如何使用 GroupDocs Viewer for Java 將 PDF 轉換為 HTML，並展示 如何停用分組，使每個字元都被視為獨立元素。

使用 GroupDocs.Viewer for Java 的精確渲染技術

快速解答

  • 「停用分組」的作用是什麼？ 它強制渲染器將每個字元視為獨立元素，保留精確的版面配置。
  • 哪個 API 選項控制此行為？ viewOptions.getPdfOptions().setDisableCharsGrouping(true)。
  • 我需要授權嗎？ 試用版可用於測試，但正式環境需要完整授權。
  • 我可以同時從 PDF 產生 HTML 嗎？ 可以——使用 HtmlViewOptions 產生 HTML 輸出，同時停用分組。
  • 此功能僅限於 PDF 嗎？ 主要針對 PDF，但 Viewer 支援許多其他格式。

什麼是從 PDF 產生 HTML？

generate html from pdf 描述將 PDF 文件轉換為一組保留原始版面、字型與圖像的 HTML 頁面的過程。此轉換可讓使用者在網頁上輕鬆檢視、索引與互動，無需 PDF 外掛。

為什麼使用 GroupDocs Viewer for Java？

GroupDocs.Viewer for Java 支援 超過 100 種輸入格式，且可在不將整個檔案載入記憶體的情況下渲染最多 500 頁 的 PDF。此函式庫以串流方式處理每一頁，與完整文件載入相比，可將堆積記憶體使用量降低最多 70 %。這些具體的效能指標使其成為高容量、企業級文件流程的可靠選擇。

介紹

在處理 PDF 文件時，渲染精度至關重要——尤其是面對如象形文字或需要精確字元呈現的語言時。「字元分組」功能常會因錯誤地將字元合併而導致文件內容被誤讀。這對需要精確複製文件文字版面的使用者而言，尤其成問題。

GroupDocs.Viewer for Java 是一個伺服器端函式庫，可將超過 100 種文件格式渲染為 HTML、圖像與 PDF，提供像素級的精確度。

前置條件

  • 函式庫與相依性：您需要 GroupDocs.Viewer for Java 版本 25.2 或更新版本。
  • 環境設定：安裝 Java Development Kit（JDK），並為 Maven 專案設定 IDE。
  • 知識前提：基本的 Java 程式設計、檔案系統操作，以及熟悉 Maven。

如何使用 GroupDocs Viewer 從 PDF 產生 HTML

從 PDF 產生 HTML 是兩步驟的流程：先設定 Viewer，然後渲染文件。關鍵是在渲染前關閉字元分組，使 HTML 輸出能逐字元精確對應原始 PDF 版面。

設定 GroupDocs.Viewer for Java

透過 Maven 安裝

Add the following dependency to your pom.xml:

<repositories>
   <repository>
      <id>repository.groupdocs.com</id>
      <name>GroupDocs Repository</name>
      <url>https://releases.groupdocs.com/viewer/java/</url>
   </repository>
</repositories>
<dependencies>
   <dependency>
      <groupId>com.groupdocs</groupId>
      <artifactId>groupdocs-viewer</artifactId>
      <version>25.2</version>
   </dependency>
</dependencies>

取得授權

To fully utilize GroupDocs.Viewer, consider acquiring a license:

  • 免費試用：先使用免費試用版測試功能。
  • 臨時授權：若需要更長時間，可申請臨時授權。
  • 購買授權：長期專案建議直接購買授權。

基本初始化與設定

HtmlViewOptions 用於設定將文件渲染為 HTML 時的輸出格式與選項。

import com.groupdocs.viewer.Viewer;
import com.groupdocs.viewer.options.HtmlViewOptions;
import java.nio.file.Path;

// Initialize the GroupDocs Viewer
Path outputDirectory = Utils.getOutputDirectoryPath("DisableCharactersGrouping");
Path pageFilePathFormat = outputDirectory.resolve("page_{0}.html");

HtmlViewOptions viewOptions = HtmlViewOptions.forEmbeddedResources(pageFilePathFormat);
viewOptions.getPdfOptions().setDisableCharsGrouping(true);

try (Viewer viewer = new Viewer("YOUR_DOCUMENT_DIRECTORY/HIEROGLYPHS_PDF")) {
    viewer.view(viewOptions);
}

實作指南

功能：停用字元分組

以下我們逐行說明範例程式碼，讓您了解 為何 這樣做以及 如何 使從 PDF 產生 HTML 時避免不必要的字元合併。

步驟 1：定義輸出目錄
Path outputDirectory = Utils.getOutputDirectoryPath("DisableCharactersGrouping");

為什麼？ 這確保渲染出的 HTML 檔案儲存在專屬資料夾，便於日後查找與管理。

步驟 2：設定檔案路徑格式
Path pageFilePathFormat = outputDirectory.resolve("page_{0}.html");

為什麼？ 使用佔位符（{0}）可讓 Viewer 為每個 PDF 頁面產生獨立的 HTML 檔案，保持輸出有序。

步驟 3：初始化 HTML 檢視選項
HtmlViewOptions viewOptions = HtmlViewOptions.forEmbeddedResources(pageFilePathFormat);

為什麼？ 嵌入式資源將圖像、字型與 CSS 直接與每個 HTML 頁面捆綁，適合網頁檢視器或 e‑learning 平台。

步驟 4：停用字元分組

setDisableCharsGrouping(true) 會停用預設的相鄰字元分組行為，確保每個字形分別渲染。

viewOptions.getPdfOptions().setDisableCharsGrouping(true);

為什麼？ 這是關鍵程式碼，告訴渲染引擎 不要 合併相鄰字元，確保產生的 HTML 完全對應來源 PDF 中的字形位置。

步驟 5：渲染文件

Viewer 是主要的類別，用於開啟文件並提供渲染功能。

try (Viewer viewer = new Viewer("YOUR_DOCUMENT_DIRECTORY/HIEROGLYPHS_PDF")) {
    viewer.view(viewOptions);
}

為什麼？ 將 Viewer 包在 try‑with‑resources 區塊中，可自動釋放所有原生資源，避免長時間執行的應用程式發生記憶體洩漏。

停用字元分組如何提升 HTML 的忠實度？

停用字元分組會迫使引擎將每個字形輸出為獨立的 HTML 元素，從而完整保留原始的間距、連字與變音符號，與來源 PDF 完全一致。此舉可產生忠實的網頁呈現，對於字元順序與間距傳遞意義的文字（如阿拉伯文、天城文或古代象形文字）尤為重要。

停用分組的效能影響為何？

關閉分組會略微增加 CPU 使用，因為渲染器會逐一處理每個字元。實務上，對於一般 100 頁的 PDF，額外開銷低於 5 %；即使文件超過 500 頁，只要 JVM 堆積大小適當（例如 -Xmx2g），開銷仍維持在 12 % 以下。當需要精確的視覺忠實度時，此權衡是值得的。

常見問題與解決方案

  • FileNotFoundException – 請再次確認傳遞給 new Viewer(...) 的路徑。建議使用絕對路徑或 Path.of(...) 以提升可讀性。
  • 寫入權限 – 確保 Java 程序對輸出目錄具有寫入權限；在 Linux 上可能需要調整資料夾權限（chmod 775）。
  • 版本不匹配 – setDisableCharsGrouping 選項自 25.2 版起提供。請確認 pom.xml 中使用正確的版本號。

實務應用

  1. 語言保存 – 適用於中文、日文、阿拉伯文或其他字元間距具意義的古代文字文件渲染。
  2. 法律與金融文件 – 確保文字精確複製，符合合規性需求。
  3. 教育資源 – 適合包含複雜圖表、註釋或多語言內容的教科書。

效能考量

  • 最佳化資源使用 – 大型 PDF 可能佔用大量記憶體。建議分批處理頁面，並及時釋放 Viewer 實例。
  • Java 記憶體管理 – 若預期處理數百頁的 PDF，請調整 JVM 堆積大小（如 -Xmx2g 或更高）。
  • 平行渲染 – 大量轉換時，可為每個執行緒建立獨立的 Viewer 實例，以利用多核心 CPU。

常見問答

Q: 為什麼需要停用字元分組？
A: 停用分組可防止渲染器合併屬於不同字形的字元，對於間距與順序傳遞意義的文字至關重要。

Q: setDisableCharsGrouping 設定僅適用於 HTML 輸出嗎？
A: 不，只影響底層的 PDF 渲染引擎，任何輸出格式（HTML、PNG、JPEG 等）皆會套用此變更。

Q: 我可以將此設定與自訂字型結合使用嗎？
A: 可以——在初始化 Viewer 前先載入自訂字型，分組規則仍會生效。

Q: 停用分組會影響效能嗎？
A: 稍微會有影響，因為引擎會逐一處理字元，但對大多數文件的影響很小（通常低於 5 % 的額外開銷）。

Q: 有沒有辦法在每頁單獨切換分組？
A: 目前此選項在每個 PdfOptions 實例中為全域設定；若需在不同頁面混合行為，必須為不同頁面建立獨立的 Viewer 實例。

資源

最後更新： 2026-09-05
測試環境： GroupDocs.Viewer 25.2 for Java
作者： GroupDocs

相關教學