使用 GroupDocs.Viewer for Java 轉換 DOCX 為 HTML（外部資源）

在本教學中，您將學習如何 convert docx to html，同時完整保留每張圖片、樣式表與字型的連結。GroupDocs.Viewer for Java 只需幾行程式碼即可完成繁重工作，非常適合網路出版平台、內容管理系統，或任何需要 Word 文件忠實 HTML 複製品的服務。

使用 GroupDocs.Viewer for Java 轉換 DOCX 為 HTML（外部資源）

使用 GroupDocs.Viewer for Java 轉換 DOCX 為 HTML（外部資源）

快速回答

  • convert docx to html 實際產生什麼？ 一個 HTML 頁面（或一組頁面），以及分別的圖片、CSS 與字型檔案。
  • 我需要授權才能使用 GroupDocs.Viewer 嗎？ 是 – 請參閱 groupdocs viewer licensing 章節以了解試用、臨時與完整購買選項。
  • 需要哪個 Java 版本？ Java 8 或更新版本；此函式庫可在任何現代 JDK 上運作。
  • 我可以自訂輸出資料夾與 URL 模式嗎？ 當然可以 – HtmlViewOptions.forExternalResources 允許您定義檔名佔位符。
  • 轉換速度足以處理大型文件嗎？ 只要妥善管理記憶體（使用 try‑with‑resources），效能可擴展；稍後請參考效能建議。

什麼是 “convert docx to html”？

Convert docx to html 將 Word 檔案轉換為標準的網頁標記，並將圖片、CSS 與字型抽取為獨立資源，供產生的 HTML 參照。此作法讓頁面保持輕量，同時保留原始版面，並確保樣式與排版在各瀏覽器與裝置上保持一致。

為何在此轉換使用 GroupDocs.Viewer？

GroupDocs.Viewer 支援 超過 100 種檔案格式 的轉換，且能在不將整個檔案載入記憶體的情況下渲染數百頁的文件。此引擎提供完整保真度的輸出，保留複雜表格、向量圖形與嵌入物件。由於它可在任何支援 Java 的作業系統上執行，您可輕鬆部署於雲端容器、內部伺服器或桌面工具。

前置條件

  • GroupDocs.Viewer 函式庫版本 25.2 或更新。
  • 用於相依管理的 Maven。
  • 已安裝 JDK 8 或更新版本。
  • 如 IntelliJ IDEA 或 Eclipse 等 IDE。

必要的函式庫與相依性

  • GroupDocs.Viewer（以下顯示 Maven 坐標）。

環境設定需求

  • 已在系統上安裝 Java Development Kit (JDK)。
  • 使用 IntelliJ IDEA 或 Eclipse 等 IDE 撰寫與執行程式碼。

知識前置條件

  • 基本的 Java 程式設計技能。
  • 熟悉 Maven 的 pom.xml 結構。

如何設定 GroupDocs.Viewer for Java

首先，將 GroupDocs 儲存庫與 viewer 相依項目加入您的 Maven pom.xml。此步驟確保 Maven 取得正確的 JAR 檔，並使函式庫可供專案使用。更新 pom.xml 後，執行 mvn clean install 下載相依項目，並驗證類路徑已正確配置給 Viewer API。

<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>

如何取得 GroupDocs.Viewer 授權？

GroupDocs 提供三種授權方案，以符合不同開發階段。免費試用 提供有限使用以快速評估、臨時授權 為短期測試提供免費金鑰，永久授權 則解鎖完整功能供正式環境使用。將您的 license.json（或 .lic）檔案放置於應用程式可讀取的位置，或依官方文件說明以程式方式設定授權。

實作指南

如何定義輸出路徑？

首先，決定 HTML 頁面及其相關資源的存放位置。佔位符（{0}、{1}）會在執行時被頁碼與資源索引取代，讓您產生乾淨且可預測的檔名。

String outputDirectory = "YOUR_OUTPUT_DIRECTORY/RenderToHtmlWithExternalResources";
String pageFilePathFormat = outputDirectory + "/page_{0}.html"; // Naming pattern for HTML pages
String resourceFilePathFormat = outputDirectory + "/page_{0}_{1}"; // Pattern for resources (e.g., images)
String resourceUrlFormat = outputDirectory + "/page_{0}_{1}"; // URL format in generated HTML

如何為外部資源設定 HtmlViewOptions？

HtmlViewOptions.forExternalResources 告訴 viewer 使用您提供的模式，將圖片、CSS 與字型寫入獨立檔案。

HtmlViewOptions 類別是設定中心，控制 HTML 資產的輸出位置與方式。透過提供 resourceFilePathFormat 與相對應的 resourceUrlFormat，即可完整掌控產生資源的資料夾結構與 URL 方案。

HtmlViewOptions viewOptions = HtmlViewOptions.forExternalResources(pageFilePathFormat, resourceFilePathFormat, resourceUrlFormat);

如何渲染文件？

Viewer 類別是入口點，負責載入來源文件並協調轉換流程。它提供渲染頁面、抽取資源與管理記憶體的方法。建立 Viewer 實例，指向您的 DOCX 檔案，然後呼叫 view。使用 try‑with‑resources 區塊可確保原生資源即時釋放。

try (Viewer viewer = new Viewer(TestFiles.SAMPLE_DOCX)) {
    viewer.view(viewOptions); // Renders DOCX as HTML with external resources
}

常見問題與解決方案

症狀可能原因解決方法
HTML 輸出中的圖片連結損壞resourceUrlFormat 與實際資料夾結構不符確認 URL 模式指向資源儲存的相同目錄
Viewer 在啟動時拋出 IOException輸出目錄不存在或缺乏寫入權限事先建立目錄或授予寫入權限
大型 DOCX 檔案的記憶體使用量過高一次載入整個文件盡可能分頁處理文件，並確保 JVM 堆積大小適當

效能考量

  • I/O 效率： 若自訂輸出，請寫入快速 SSD 或使用緩衝串流。
  • 記憶體管理： Viewer 類別實作 Closeable；務必使用 try‑with‑resources，讓 JVM 及時回收原生記憶體。
  • 執行緒安全性： 每個執行緒建立獨立的 Viewer 實例；此類別並非執行緒安全。

實務應用

  1. 網站內容管理： 自動將 Word 文章發布為保留所有圖片的 HTML 頁面。
  2. 文件歸檔： 以通用可讀的 HTML 格式儲存法律或合規文件。
  3. 跨平台入口網站： 在桌面瀏覽器、行動裝置與嵌入式網頁視圖上提供相同的視覺體驗。

常見問答

Q: 如何處理非常大的 DOCX 檔案？
A: 將文件分成較小的區塊處理，增加 JVM 堆積 (-Xmx) 大小，並確保及時釋放 Viewer 實例。

Q: GroupDocs.Viewer 能將其他格式轉換為 HTML 嗎？
A: 可以 – 內建支援 PDF、XPS、PPT 以及多種影像格式。

Q: GroupDocs.Viewer 的授權選項有哪些？
A: 可選擇免費試用以快速測試、臨時授權用於短期專案，或購買永久授權以無限制投入生產環境。

Q: 為何我的資源 URL 顯示 “page_0_0” 而非實際檔名？
A: 因為輸出資料夾模式不正確，導致 {0} 與 {1} 佔位符未被取代。請再次檢查 resourceFilePathFormat 與 resourceUrlFormat 字串。

Q: 是否可以將 CSS 直接嵌入 HTML，而非使用外部檔案？
A: 可以 – 若偏好單一檔案輸出，請使用 HtmlViewOptions.forEmbeddedResources()。

資源

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

相關教學