w-html2docx 1.0.8 → 1.0.10

package/README.md

@@ -49,3 +49,14 @@ test()
         console.log('catch', err)
     })
 ```
+
+### 外部提供docx模板要點
+
+轉檔時以docx模板為基底產出文件，可透過`opt.fpInTemp`指定外部模板；未指定時依序使用`./src/tmp.docx`或`./node_modules/w-html2docx/src/tmp.docx`(套件內建模板)。
+
+外部提供模板時須注意：
+
+1. **內容附加於模板文末**：轉檔係將html內容(含格式)插入至模板既有內容之後再另存，故模板一般提供空白文件；模板內既有內容會保留於輸出文件開頭。
+2. **頁面設定由模板決定**：輸出文件之紙張大小、邊界等頁面設定沿用模板；圖片縮放上限(滿版寬高)亦依模板版心(紙張大小扣除邊界)計算。
+3. **模板settings會帶入輸出文件**：模板`word/settings.xml`內之文件層級設定，轉檔後會保留於輸出docx。
+4. **建議帶入停用影像壓縮旗標**：模板`word/settings.xml`須含`<w:doNotAutoCompressPictures/>`，否則Word轉檔時會將寬圖(約超過1270px)自動降採樣至220ppi並轉存JPEG，導致圖內文字模糊。套件內建模板已含此旗標；外部模板可於Word開啟模板後，勾選[檔案 > 選項 > 進階 > 影像大小和品質 > 不壓縮檔案中的影像]再存檔，或直接編輯`word/settings.xml`加入該元素。

package/dist/w-html2docx.umd.js

@@ -1,5 +1,5 @@
 /*!
- * w-html2docx v1.0.8
+ * w-html2docx v1.0.10
  * (c) 2018-2021 yuda-lyu(semisphere)
  * Released under the MIT License.
  */

package/docs/WHtml2docx.mjs.html

@@ -246,7 +246,7 @@ export default WHtml2docx
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Wed Jul 08 2026 21:09:13 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Jul 12 2026 14:01:14 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/global.html

@@ -593,7 +593,7 @@
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Wed Jul 08 2026 21:09:13 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Jul 12 2026 14:01:14 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/index.html

@@ -71,7 +71,7 @@
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Wed Jul 08 2026 21:09:13 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Jul 12 2026 14:01:14 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "w-html2docx",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "main": "dist/w-html2docx.umd.js",
   "dependencies": {
     "lodash-es": "^4.18.1",
-    "wsemi": "^1.8.63"
+    "wsemi": "^1.8.64"
   },
   "devDependencies": {
+    "fflate": "^0.8.3",
     "w-package-tools": "^1.1.10"
   },
   "scripts": {

package/srcPython/htmlToDocx.py

@@ -229,6 +229,44 @@ def htmlToDocx(fpInSrc, fpInTemp, fpOut, opt):
         err=getError()
         print(err)
 
+    #設定本文段落(p)與清單項目(li)之水平對齊, 已為置中者(如表格標題列, 圖名)不更動, 其餘改為左右對齊(兩端對齊), 使右側邊界齊平較為美觀
+    try:
+
+        WdAlignParagraphCenter = 1   #置中對齊
+        WdAlignParagraphJustify = 3  #左右對齊
+        WdOutlineLevelBodyText = 10  #本文層級, 標題(h1-h6)匯入後為大綱層級1-9
+        WdWithInTable = 12           #Information之參數, 判斷是否位於表格內
+
+        for p in docInTemp.Paragraphs:
+            try:
+
+                rng = p.Range
+
+                #跳過標題段落
+                if p.OutlineLevel != WdOutlineLevelBodyText:
+                    continue
+
+                #跳過表格內段落
+                if rng.Information(WdWithInTable):
+                    continue
+
+                #跳過圖片段落
+                if rng.InlineShapes.Count > 0:
+                    continue
+
+                #跳過置中段落
+                if p.Alignment == WdAlignParagraphCenter:
+                    continue
+
+                p.Alignment = WdAlignParagraphJustify
+
+            except:
+                pass
+
+    except:
+        err=getError()
+        print(err)
+
     #移除零寬空格佔位字元(U+200B): 來源為w-md2html於換行標記空div內插入之佔位字元, 用以撐過Word匯入不被當成空段落丟棄
     #於此移除後該段落成為真正的空段落(乾淨段落標記, 顯示編輯標記時亦無可見字元)
     try:

package/test/WHtml2docx.test.mjs

@@ -1,38 +1,150 @@
-import fs from 'fs'
-import w from 'wsemi'
-import assert from 'assert'
-import WHtml2docx from '../src/WHtml2docx.mjs'
-
-
-function isWindows() {
-    return process.platform === 'win32'
-}
-
-
-describe('WHtml2docx', function() {
-
-    //check
-    if (!isWindows()) {
-        return
-    }
-
-    let fpOutTrue = `./test/ztmpTrue.docx`
-
-    let fpIn = `./test/ztmp.html`
-    let fpOut = `./test/ztmp.docx`
-    let opt = {
-        imgRatioWidthMax: 0.5,
-    }
-
-    it('convert', async function() {
-        await WHtml2docx(fpIn, fpOut, opt)
-        let r = (fs.statSync(fpOut)).size
-        let rr = (fs.statSync(fpOutTrue)).size
-        //轉出docx檔案每次不同, 改用門檻比對
-        // console.log('r', r, 'rr', rr)
-        let b = r > 62000 && rr > 62000
-        w.fsDeleteFile(fpOut)
-        assert.strict.deepEqual(true, b)
-    })
-
-})
+import fs from 'fs'
+import w from 'wsemi'
+import assert from 'assert'
+import { unzipSync, strFromU8 } from 'fflate'
+import WHtml2docx from '../src/WHtml2docx.mjs'
+
+
+function isWindows() {
+    return process.platform === 'win32'
+}
+
+
+function getDocumentXml(fp) {
+    //docx為zip, 取出主文件word/document.xml
+    let u8 = fs.readFileSync(fp)
+    let files = unzipSync(new Uint8Array(u8))
+    return strFromU8(files['word/document.xml'])
+}
+
+
+function getParagraphs(xml) {
+    //切出全部段落<w:p>, 並標記其分類與水平對齊
+
+    //tbls, 各表格之區間
+    let tbls = []
+    let rTbl = /<w:tbl>[\s\S]*?<\/w:tbl>/g
+    let mt
+    while ((mt = rTbl.exec(xml)) !== null) {
+        tbls.push([mt.index, mt.index + mt[0].length])
+    }
+    let inTable = (i) => {
+        return tbls.some((t) => i >= t[0] && i < t[1])
+    }
+
+    //ps, 各段落
+    let ps = []
+    let rP = /<w:p\b[^>]*\/>|<w:p\b[^>]*>[\s\S]*?<\/w:p>/g
+    let mp
+    while ((mp = rP.exec(xml)) !== null) {
+        let s = mp[0]
+        let mj = s.match(/<w:jc w:val="([^"]+)"\s*\/>/)
+        ps.push({
+            align: mj ? mj[1] : '', //both為左右對齊, center為置中, 空字串為未設定
+            isHeading: /<w:outlineLvl\b/.test(s), //h1-h6匯入後帶有大綱層級
+            isList: /<w:numPr>/.test(s), //ul或ol之li
+            isImage: /<w:drawing\b|<w:pict\b/.test(s), //含圖片(w:drawing)或水平線hr(w:pict之v:rect)
+            inTable: inTable(mp.index), //位於表格內
+            text: [...s.matchAll(/<w:t[^>]*>([^<]*)<\/w:t>/g)].map((v) => v[1]).join(''),
+        })
+    }
+
+    return ps
+}
+
+
+describe('WHtml2docx', function() {
+
+    //check
+    if (!isWindows()) {
+        return
+    }
+
+    let fpIn = `./test/ztmp.html`
+    let fpOut = `./test/ztmp.docx`
+    let imgRatioWidthMax = 0.5
+    let fontFamilies = ['標楷體', 'Times New Roman']
+    let opt = {
+        imgRatioWidthMax,
+        fontFamilies,
+    }
+
+    //轉出docx後解析word/document.xml, 各測試針對其內容比對, 不使用檔案大小門檻
+    let xml = null
+    let ps = null
+
+    before(async function() {
+        this.timeout(60000)
+        await WHtml2docx(fpIn, fpOut, opt)
+        xml = getDocumentXml(fpOut)
+        ps = getParagraphs(xml)
+    })
+
+    after(function() {
+        w.fsDeleteFile(fpOut)
+    })
+
+    it('convert', function() {
+        assert.strict.deepEqual(true, ps.length > 0)
+        assert.strict.deepEqual(true, xml.includes('計畫報告')) //來源html之h1
+        assert.strict.deepEqual(true, xml.includes('資料流程自動化')) //來源html之li
+    })
+
+    it('本文段落與清單項目, 除已置中者外, 均為左右對齊', function() {
+        let rs = ps.filter((p) => !p.isHeading && !p.isImage && !p.inTable && p.align !== 'center')
+        assert.strict.deepEqual(true, rs.length > 0)
+        let rsErr = rs.filter((p) => p.align !== 'both')
+        assert.strict.deepEqual([], rsErr)
+    })
+
+    it('清單項目(li)已納入左右對齊', function() {
+        let rs = ps.filter((p) => p.isList && !p.inTable && p.align !== 'center')
+        assert.strict.deepEqual(true, rs.length > 0)
+        let rsErr = rs.filter((p) => p.align !== 'both')
+        assert.strict.deepEqual([], rsErr)
+    })
+
+    it('標題段落不套用左右對齊', function() {
+        let rs = ps.filter((p) => p.isHeading)
+        assert.strict.deepEqual(true, rs.length > 0)
+        let rsErr = rs.filter((p) => p.align === 'both')
+        assert.strict.deepEqual([], rsErr)
+    })
+
+    it('表格內段落不套用左右對齊', function() {
+        let rs = ps.filter((p) => p.inTable)
+        assert.strict.deepEqual(true, rs.length > 0)
+        let rsErr = rs.filter((p) => p.align === 'both')
+        assert.strict.deepEqual([], rsErr)
+    })
+
+    it('已強制更改字型', function() {
+        assert.strict.deepEqual(true, xml.includes(`w:eastAsia="${fontFamilies[0]}"`))
+        assert.strict.deepEqual(true, xml.includes(`w:ascii="${fontFamilies[1]}"`))
+    })
+
+    it('圖片寬度不超過版心寬度乘以imgRatioWidthMax', function() {
+
+        //twContent, 版心寬度, 單位twip
+        let mSz = xml.match(/<w:pgSz w:w="(\d+)"/)
+        let mMar = xml.match(/<w:pgMar[^>]*w:right="(\d+)"[^>]*w:left="(\d+)"/)
+        assert.strict.deepEqual(true, mSz !== null)
+        assert.strict.deepEqual(true, mMar !== null)
+        let twContent = parseInt(mSz[1]) - parseInt(mMar[1]) - parseInt(mMar[2])
+
+        //emuMax, 圖片寬度上限, 單位EMU, 1twip=635EMU
+        let emuMax = twContent * 635 * imgRatioWidthMax
+
+        //cxs, 各圖片寬度, 單位EMU
+        let cxs = [...xml.matchAll(/<wp:extent cx="(\d+)"/g)].map((v) => parseInt(v[1]))
+        assert.strict.deepEqual(true, cxs.length > 0)
+
+        let rsErr = cxs.filter((cx) => cx > emuMax)
+        assert.strict.deepEqual([], rsErr)
+    })
+
+    it('已移除零寬空格佔位字元(U+200B)', function() {
+        assert.strict.deepEqual(false, xml.includes(String.fromCharCode(0x200B)))
+    })
+
+})

package/test/ztmp.html

@@ -294,6 +294,7 @@
 <hr>
 
 <h2>四、成果內容</h2>
+
 <h3>4.1 表格測試</h3>
 <table>
 <thead>
@@ -318,7 +319,38 @@
 <td>80%</td>
 <td>預計下期延伸</td>
 </tr>
-</tbody></table>
+</tbody>
+</table>
+
+<h3>4.2 表格測試（水平置中）</h3>
+<div style="text-align:center;">
+<table style="display:inline-table;">
+<thead>
+<tr>
+<th>項目</th>
+<th>完成度</th>
+<th>備註</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>自動化流程</td>
+<td>100%</td>
+<td>已完成</td>
+</tr>
+<tr>
+<td>系統效能優化</td>
+<td>95%</td>
+<td>尚可持續改善</td>
+</tr>
+<tr>
+<td>介面改善</td>
+<td>80%</td>
+<td>預計下期延伸</td>
+</tr>
+</tbody>
+</table>
+</div>
+
 <hr>
 
 <h2>五、圖片、連結與註腳</h2>
@@ -399,31 +431,46 @@
 
 <hr>
 
-<h2>八、表格水平置中測試（轉Docx）</h2>
+<h2>八、超長文字測試（換行與左右對齊）</h2>
 
-<h3>8.1 基本表格（對照組, 預設靠左）</h3>
-<table>
-<thead>
-<tr><th>欄位一</th><th>欄位二</th><th>欄位三</th></tr>
-</thead>
-<tbody>
-<tr><td>A1</td><td>B1</td><td>C1</td></tr>
-<tr><td>A2</td><td>B2</td><td>C2</td></tr>
-</tbody>
-</table>
+<h3>8.1 超長段落</h3>
+<p>本節之各段落均刻意撰寫為超出單行寬度之長句，用以檢驗轉出Docx後之自動換行與左右對齊（兩端對齊）效果；於Word中，兩端對齊僅對「非末行」之文字生效，故段落須至少折行兩行以上，方能於視覺上觀察到右側邊界是否確實對齊齊平，此即本測試段落須刻意加長之原因。</p>
+<p>資料處理流程之設計，須同時兼顧擴充性、可維護性與執行效能三者之平衡；當資料量由每日數萬筆成長至每日數百萬筆時，原本以單機批次處理為前提之架構，將面臨記憶體不足、處理時間過長以及失敗後難以續跑等問題，因此本計畫改以分散式串流處理為核心，並輔以檢查點（checkpoint）機制，使流程於任一節點失敗後，均可自最近之檢查點續行，而毋須自始重新執行。</p>
+<p>就中英文混排之情形而言，兩端對齊之演算法會調整字元間距與詞間空白，以使各行右側邊界齊平；例如本段落即刻意混入 Extract-Transform-Load (ETL)、Continuous Integration / Continuous Delivery (CI/CD) 以及 Application Programming Interface (API) 等較長之英文詞彙與縮寫，藉以觀察Word於中英文交界處之斷行行為是否合理，以及英文詞彙是否遭到不當之切斷。</p>
+<blockquote>
+<p>引用區塊內之超長文字亦一併測試：引用段落於Word中雖具有額外之左側縮排，惟其本質仍為本文層級之段落，故理應同樣套用左右對齊；本句刻意加長，以確保其於Docx中至少折行兩行以上，俾利肉眼確認右側邊界是否齊平。</p>
+</blockquote>
 
-<h3>8.2 表格水平置中（div+text-align:center轉Docx水平置中）</h3>
-<div style="text-align:center;">
-<table align="center" _style="margin:0 auto;">
-<thead>
-<tr><th>欄位一</th><th>欄位二</th><th>欄位三</th></tr>
-</thead>
-<tbody>
-<tr><td>A1</td><td>B1</td><td>C1</td></tr>
-<tr><td>A2</td><td>B2</td><td>C2</td></tr>
-</tbody>
-</table>
-</div>
+<h3>8.2 超長無序清單（ul li）</h3>
+<ul>
+<li style="margin:7px 0;">資料前處理：包含來源檔案之編碼偵測、分隔符號判別、欄位型別推斷、缺失值填補與離群值剔除等步驟；其中缺失值之填補策略，須依欄位語意分別採用平均值、中位數、前值延續或直接標記為無效等不同方式，不得一律以零值填補，否則將導致後續統計分析結果產生系統性偏誤。</li>
+<li style="margin:7px 0;">格式轉換：須將來源之CSV、TSV、JSON、XML與Excel等多種異質格式，統一轉換為內部之欄式儲存格式（columnar format），以利後續之向量化運算與壓縮儲存；轉換過程中並須保留原始欄位名稱與單位資訊，俾利日後回溯查核。</li>
+<li style="margin:7px 0;">短項目（對照組）</li>
+<li style="margin:7px 0;">雜訊清理：針對感測器所回傳之時間序列資料，須先以移動平均或Savitzky-Golay濾波器進行平滑化處理，再行判別突波（spike）與漂移（drift）等異常型態；經判別為異常者，應予標記而非逕行刪除，以維持時間序列之等間距特性。</li>
+</ul>
+
+<h3>8.3 超長有序清單（ol li）</h3>
+<ol>
+<li style="margin:7px 0;">第一階段——需求訪談與現況盤點：應與各業務單位進行至少三輪之訪談，逐一釐清其現行作業流程、資料來源、交付週期與品質要求，並將訪談結果整理為需求規格書，經雙方確認後始得進入設計階段，避免需求於開發中期反覆變更而導致工期延宕。</li>
+<li style="margin:7px 0;">第二階段——系統設計與雛形驗證：依前階段確認之需求規格，完成系統架構設計、資料庫綱要設計與介面設計，並以雛形（prototype）方式先行驗證關鍵技術風險，包含大量資料匯入之效能、第三方API之串接穩定性，以及視覺化平台於行動裝置之呈現效果。</li>
+<li style="margin:7px 0;">第三階段（短項目對照組）</li>
+</ol>
+
+<h3>8.4 巢狀清單之超長項目</h3>
+<ul>
+<li style="margin:7px 0;"><p><strong>統計分析模組</strong>：本模組須提供描述性統計、相關性分析、假設檢定與迴歸分析等基本功能，並就各項分析結果自動產製圖表與文字摘要，俾利使用者無須具備統計專業背景亦能理解分析結論。</p>
+<ul>
+<li style="margin:7px 0;">描述性統計：包含平均數、中位數、眾數、標準差、偏態與峰態等指標之計算，並須支援分組計算，以利跨群體之比較分析；各指標之計算結果均須標註樣本數，避免因樣本過少而導致統計量失去代表性。</li>
+<li style="margin:7px 0;">迴歸分析：支援線性迴歸、多元迴歸與邏輯斯迴歸等模型，並須輸出各係數之估計值、標準誤、t統計量與p值，另須提供殘差圖與共線性診斷（VIF）等模型檢核工具。</li>
+</ul>
+</li>
+<li style="margin:7px 0;"><p><strong>時間序列模組</strong></p>
+<ul>
+<li style="margin:7px 0;">ARIMA：須自動進行定態性檢定（ADF test）與差分階數選擇，並以資訊準則（AIC／BIC）挑選最適之(p, d, q)參數組合，另須提供殘差之白噪音檢定，以確認模型已充分擷取序列之自我相關結構。</li>
+<li style="margin:7px 0;">Prophet</li>
+</ul>
+</li>
+</ul>
 
 <hr>