一個 JavaScript 處理流程,負責把 HTML 轉成 DOCX 檔案,幾乎一定會從序列化步驟開始:在 mammoth.js、html-docx-js,或自訂後端端點這類函式庫能讀取之前,標記內容必須先以 JavaScript 字串的形式存在。若要在 JavaScript 中可靠地將 HTML 轉換為 DOCX,首要任務就是產生一個字串常值,讓它在複製、貼上與模組打包過程中,不會發生分隔符衝突、空白遺失,或意外的樣板插值。HTML to JavaScript Converter 正是用來處理這個工作的工具,它會逐字元掃描輸入內容,並輸出一個 const 指派,同時跳脫所有反斜線、控制字元,以及你所選擇的分隔符。這個轉換器不會剖析 HTML、不會渲染、不會清理內容,也不會上傳;它是一個文字序列化輔助工具,位於 DOCX 處理流程的最前端,讓下游函式庫收到的標記內容,其字元與原始輸入完全一致。本文將說明這個序列化步驟在何時重要、針對常見 HTML 片段應選擇哪種分隔符模式、如何逐步使用這個轉換器,以及在字串送達 DOCX 產生器之前應該執行的驗證測試。
HTML 轉 DOCX 的工作流程始於一個 JavaScript 字串
大多數用戶端與 Node 端的 DOCX 轉換器都接受 HTML 作為主要輸入。mammoth.js 可以把 .docx 檔案轉成 HTML,並透過其瀏覽器版本接受 HTML 字串以執行反向處理;html-docx-js 將 HTML 包進一個產生的文件中;而以 Pandoc 或 LibreOffice 為基礎的端點,則透過 HTTP 接收一個序列化後的字串。這些工具都不在乎字串是如何產生的,它們只在乎字串內的字元是否正確。這也使得序列化步驟成為 HTML 轉 DOCX JavaScript 處理流程中風險最高的環節,因為只要有一個未跳脫的分隔符——不管是雙引號字串中的 "、單引號字串中的 ',或是樣板字串中混入的 ${——都可能截斷字串並毀損文件。內嵌的 <style> 區塊、JSON-LD 內容,以及 SVG 片段常常同時包含這三種分隔符,這就是為何手寫跳脫很快就會出錯。一個專門的序列化工具,瞭解 ECMAScript 字串常值文法規則以及 U+2028 / U+2029 的可移植性陷阱,能產生下游函式庫可放心取用的字串。
HTML to JavaScript Converter 序列化了哪些內容
這個轉換器的範圍刻意設計得很窄:它以 UTF-16 程式碼單位掃描輸入內容,先跳脫反斜線,接著處理控制字元、行分隔符、所選的分隔符,(在樣板模式下)還有 ${ 這個插值序列,最後輸出一個 const 指派。標籤、屬性、空白、註解、HTML 實體、內嵌樣式,甚至格式錯誤的標記,都會在輸出中保留為純文字。這個工具不會建立 DOM、不會重新排序屬性、不會統一大小寫,也不會修補未閉合的標籤,因為這個狹窄的契約,正好就是 HTML 轉 DOCX 使用者所需要的:你所貼上的文字會原封不動地被複製。如果你還需要在將標記嵌入 JavaScript 之前清理或正規化內容,請參考 how to clean HTML text using the browser parser,這是這個轉換器以剖析器為基礎的對應版本。
| 步驟 / 工具 | 會剖析 HTML 嗎? | 會跳脫字串分隔符嗎? | 會產生 DOCX 檔案嗎? |
|---|---|---|---|
| HTML to JavaScript Converter | 否 (僅文字) | 是 | 否 |
| mammoth.js (瀏覽器或 Node) | 是 | 否 | 是 |
| html-docx-js | 是 | 否 | 是 |
| 伺服器端端點 (Pandoc、LibreOffice headless) | 是 | 否 | 是 |
這樣的定位,讓這個轉換器成為一個前處理步驟,而不是任何 DOCX 函式庫的替代品。當你需要把 HTML 放進 JavaScript 模組、JSON 內容、fetch 主體,或 worker 訊息時,把它放在處理流程的最前端,再讓專門的函式庫在下游處理剖析與渲染。
選擇正確的分隔符模式
JavaScript 提供三種實用的分隔符,正確的選擇取決於 HTML 中最常出現哪些字元。雙引號能讓撇號保持可讀,同時也會跳脫反斜線、控制字元、行分隔符、U+2028 與 U+2029;單引號則相反。樣板字串能讓多行 HTML 在手寫程式碼中保持可讀,但同時帶來兩個新風險:未跳脫的反引號會關閉字串,而未跳脫的 ${ 會啟動運算式插值。不論你選擇哪種模式,這個轉換器都會排除這三種風險。
| 分隔符模式 | 字串內會跳脫的字元 | HTML 包含下列情況時最適合 |
|---|---|---|
| 雙引號 ("…") | 反斜線、"、控制碼、行分隔符、U+2028、U+2029 | 大量撇號 (英文文案、替代文字、縮寫) |
| 單引號 ('…') | 反斜線、'、控制碼、行分隔符、U+2028、U+2029 | 大量雙引號 (屬性、JSON-LD 區塊、內嵌 SVG) |
| 樣板字串 (`…`) | 反斜線、`、${、控制碼、行分隔符、U+2028、U+2029 | 多行標記、<style> 區塊、手寫的樣板 |
對大多數 DOCX 使用情境而言,單引號或樣板字串較為適合:HTML 屬性中充滿了雙引號,而典型文件通常也不會只有一行。ECMAScript string-literal grammar 與 MDN template literals reference 明確列出每種模式下哪些字元必須跳脫;這個轉換器會實作這些規則,因此產生的檔案在任何現代 JavaScript 引擎下都能正確剖析。
在 JavaScript 中將 HTML 轉為 DOCX:序列化工作流程
選定分隔符模式後,實際的工作流程很短且可重現:
- 將 HTML 原始碼以其最終在字串中的樣貌原樣貼上,不進行任何前處理。空白、實體、註解,甚至刻意的怪異之處,都會原封不動地保留下來。
- 輸入一個非保留的 ASCII 變數名稱,例如 invoiceTemplate 或 reportFragment。以字母、底線或錢字符號開頭的名稱都會被接受;class、const、for、return 等保留字則會被拒絕,因為它們會產生無效的宣告。
- 選擇雙引號、單引號或樣板字串,然後按轉換。輸出是一個 const 指派;如果你的應用程式確實需要 let 或 var,請在複製之後手動編輯那個關鍵字。
- 複製指派內容、貼到你的模組中,並單獨評估這個字串常值。在字串進入 mammoth.js 或 html-docx-js 之前,所得的字串必須與原始輸入逐字元完全相同。
對於每個屬性都使用雙引號、且包含多行 <style> 區塊的典型發票樣板,單引號模式是最安全的預設值。如果標記中包含內嵌的樣板,例如程式碼範例中的字面 ${ 或是建構期的預留位置,樣板模式能維持文件的可讀性,同時會跳脫錢字符號,使內嵌的序列不會變成執行階段的插值。MDN 樣板字串參考文件有記載這個行為,這個轉換器也直接實作了它,因此貼上的內容絕對不會意外地變成可執行的 JavaScript。變數欄位刻意只接受保守的 ASCII 識別字;Unicode 識別字在 ECMAScript 中雖然可能合法,但把產生的名稱限制在一個清楚且可移植的子集中,能避免在不同工具鏈之間出現外觀相似的字元與版本相關的意外狀況。
DOCX 步驟之前的來回驗證
在任何字串進入 DOCX 函式庫之前,請執行一輪來回相等性檢查。最便宜的測試方式,是把產生的指派複製到像 JavaScript Playground 這樣的本機暫存模組中,評估它,並斷言所得的字串與你貼進轉換器的原始 HTML 完全相等。任何偏差——不管是空白遺失、字元被刪除,或是實體被更改——都是跳脫序列或原始標記中的錯誤,在整合前修正,遠比在毀損的 DOCX 檔案中除錯要省事得多。產品說明列出轉換器已通過驗證的八個外部文法案例,涵蓋引號、反斜線、換行、樣板分隔符、插值語法,以及 Unicode 行分隔符;把這些案例當作你自己測試套件的最低基準,就能建立穩固的基礎。對於較大型的專案,請在建構期產生指派、快照結果,若快照與來源有所出入,就讓建構失敗。
所產生字串的安全界線
這個轉換器會產生一個能夠正確來回還原的字串常值;它並不會讓 HTML 變得可以安全地注入到頁面中。如果之後把所得的字串指派給 innerHTML、餵給用戶端的樣板引擎、以 eval 或 new Function 執行,或是與不受信任的資料結合,目標端依然需要依情境進行適當的跳脫與清理。千萬不要僅僅為了顯示 HTML 就使用 eval 或 new Function;不需要標記時請使用 textContent,而當不可避免需要渲染不受信任的標記時,請搭配一個有維護的清理工具,以及限制嚴格的內容安全政策 (CSP)。當目標是 DOCX 檔案時,在呼叫 mammoth.js 或 html-docx-js 之前,請根據 XSL-FO 或 OOXML 特有的風險進行清理,因為這些函式庫預期接收的是格式正確的輸入,否則潛在的問題可能會浮上檯面。這個轉換器也完全在目前的瀏覽器分頁中執行:不會上傳、不會儲存、不會執行、也不會預覽任何內容,不需要帳號,也不需要新的相依套件。
想更深入了解,請參考 How to Run Code in a JavaScript Playground。