在項目中，我需要實現(xiàn)一個功能：將頁面渲染出來的 HTML 內(nèi)容導出為 Word 文檔（.docx）

看起來很簡單，但真正落地時踩了不少坑。這篇文章記錄一下從插件選擇到最終解決方案的全過程。

一、插件選型對比

html-docx-js

最早嘗試的是 html-docx-js。

優(yōu)點：

• 使用簡單
• 直接將 HTML 字符串轉(zhuǎn)換成 Word

但是很快遇到了問題：

多層級有序列表在 WPS 中顯示異常

當 HTML 中存在：

<ol>
  <li>一級</li>
  <li>
    二級
    <ol>
      <li>子級</li>
    </ol>
  </li>
</ol>

在 Microsoft Word 中顯示正常，但在 WPS 中會出現(xiàn)：

• 序號錯亂
• 層級縮進異常
• 列表結(jié)構(gòu)被打亂

也就是說：

html-docx-js 在生成的 docx 結(jié)構(gòu)中，列表兼容性并不穩(wěn)定。

對于需要兼容 WPS 的場景來說，這是不可接受的。

html-to-docx / htmltodoc

后來嘗試 html-to-docx 這一類庫。

問題也很明顯：

不支持 canvas 圖片

如果頁面中有：

• canvas 圖表
• 圖形繪制
• Echarts
• GPT 可視化圖表

導出后：

圖片為空白

原因是：

• 這些庫只識別 <img>
• 不會處理 <canvas> 的內(nèi)容
• 不會主動把 canvas 轉(zhuǎn)成圖片

在圖表場景下，這幾乎無法使用。

最終選擇：docx

最后選擇了 docx（dolanmiu/docx）。

原因：

• 底層生成真實 docx 結(jié)構(gòu)
• 可控性強
• 可自定義 ImageRun / Paragraph
• 兼容性更好

但同時：自己要負責 HTML → docx 的映射邏輯。

這也是后面踩坑的開始。

二、使用 docx 時踩到的坑

坑 1：canvas 圖片第一次導出是空白

現(xiàn)象：

• 頁面中 canvas 渲染正常
• 第一次導出 Word，圖片是空白
• 第二次導出卻正常

原因

docx 需要的是：

Uint8Array（二進制圖片數(shù)據(jù)）

而 canvas：

• 是繪圖上下文
• 不是圖片資源
• 如果在 clone 之后再去讀取，很可能上下文已經(jīng)丟失

尤其是：

element.cloneNode(true)

克隆出來的 canvas：不包含繪制內(nèi)容

正確做法

必須在克隆 HTML 之前：

• 遍歷所有 canvas
• 調(diào)用 canvas.toDataURL()
• 緩存結(jié)果
• 在 clone 后替換成 <img src="dataURL">

核心原則：

canvas 先轉(zhuǎn)圖片，再克隆 DOM。

坑 2：ImageRun 被嵌套在 Paragraph 中，圖片直接消失

這是最隱蔽、最坑的一個問題。

現(xiàn)象：

• 圖片數(shù)據(jù)正確
• 不跨域
• 二進制正常
• 但導出 Word 后圖片消失
• 有時 Office Word 還會提示文件有問題

打印結(jié)構(gòu)后發(fā)現(xiàn)：

Paragraph
  └─ Paragraph
       └─ ImageRun

也就是說：

ImageRun 外面包了兩層 Paragraph。

問題本質(zhì)

在 docx 結(jié)構(gòu)中：

• Paragraph 是塊級元素
• Paragraph 不能嵌套 Paragraph
• ImageRun 必須直接存在于 Paragraph.children 中

非法結(jié)構(gòu)雖然可以被創(chuàng)建，但：

Word 會忽略或報結(jié)構(gòu)錯誤。

正確結(jié)構(gòu)

new Paragraph({
  children: [
    new ImageRun(...)
  ]
})

而不是：

new Paragraph({
  children: [
    new Paragraph({
      children: [
        new ImageRun(...)
      ]
    })
  ]
})

坑 3：HTML 的結(jié)構(gòu) ≠ docx 的結(jié)構(gòu)

在 Markdown 渲染后，HTML 往往是這樣：

<div>
  <p>
    文字
    <img />
  </p>
</div>

但 docx 并不是 DOM 樹結(jié)構(gòu)。

docx 的正確模型更像是：

Section
 ├─ Paragraph
 ├─ Paragraph
 ├─ Paragraph

是一個扁平結(jié)構(gòu)。

因此正確做法是：

• 文字 → 一個 Paragraph
• 圖片 → 一個 Paragraph
• 保持順序
• 不強行還原 HTML 嵌套

例如：

<p>hello <img /> world</p>

應轉(zhuǎn)換為：

Paragraph("hello")
Paragraph(Image)
Paragraph("world")

而不是試圖在一個 Paragraph 里混排。

三、最終總結(jié)

在前端做 HTML → Word 導出時，需要注意：

插件層面

• html-docx-js：WPS 兼容性問題
• html-to-docx：不支持 canvas
• docx：可控但需要自己處理結(jié)構(gòu)

使用 docx 時必須注意

• canvas 必須提前轉(zhuǎn)為圖片
• 不要嵌套 Paragraph
• ImageRun 必須直接在 Paragraph.children 中
• 不要試圖 1:1 還原 HTML 結(jié)構(gòu)

四、核心經(jīng)驗

Word 文檔不是瀏覽器。HTML 的語義嵌套不能直接映射到 docx。

當你開始：

• 把結(jié)構(gòu)扁平化
• 圖片獨立成段
• 主動控制文檔結(jié)構(gòu)

問題就會變得清晰很多。

到此這篇關于前端實現(xiàn)將HTML轉(zhuǎn)成Word文檔的踩坑指南的文章就介紹到這了,更多相關前端HTML轉(zhuǎn)Word內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！

最新評論