DOCX 建立、編輯與分析
.docx 檔實為 ZIP 壓縮的 XML 檔案集合。請依任務選擇處理方式:
| 任務 | 方式 |
|---|---|
| 建立新文件 | 撰寫 docx (npm) 腳本 — 請見下方注意事項 |
| 編輯現有文件 | unzip → 編輯 word/document.xml → zip(docx-js 無法開啟現有檔案) |
| 讀取內容 | pandoc -t markdown file.docx |
此處腳本路徑均相對於本技能目錄。
使用 docx-js 建立文件 — 注意事項
docx 已預先安裝 — 請勿先執行 npm install;直接撰寫腳本並 require('docx')。僅在 require 失敗時才執行 npm install docx。模型已了解 API;以下是常見陷阱:
- 頁面尺寸預設為 A4。 若要 US Letter 請設定
page: { size: { width: 12240, height: 15840 } }(DXA 單位;1440 = 1 英寸)。 - 橫向頁面: 傳入直向尺寸並加上
orientation: PageOrientation.LANDSCAPE— docx-js 會內部交換寬/高。 - 表格需有雙重寬度: 在表格上設定
columnWidths,同時在每個儲存格上設定width,兩者皆使用WidthType.DXA(使用 PERCENTAGE 會在 Google 文件中出錯)。各欄寬度總和必須等於表格寬度。 - 表格網底: 使用
ShadingType.CLEAR,絕不使用SOLID(會顯示為黑色)。 - 清單: 絕對不要直接插入
•字元;應使用包含LevelFormat.BULLET的numbering設定。 ImageRun需要指定type:(如"png"、"jpg"等)。PageBreak必須放在Paragraph內部。- 絕不使用
\n— 請使用獨立的Paragraph元素。 - 目錄 (TOC): 標題必須使用內建的
HeadingLevel.*;自訂標題樣式需設定outlineLevel,否則不會出現在目錄中。 - 不要用表格充當水平線 — 改為在段落上使用底部邊框。
- 點狀引導 / 同行靠右對齊: 在
TextRun內部使用PositionalTab(alignment: PositionalTabAlignment.RIGHT、leader: PositionalTabLeader.DOT),不要使用文字句號或空白填充。
驗證輸出結果
產生 .docx 後,將其轉為 PDF 並檢查:
python scripts/office/soffice.py --headless --convert-to pdf output.docx
pdftoppm -jpeg -r 100 output.pdf page
ls page-*.jpg # 然後讀取圖片
pdftoppm 會根據總頁數補零(例如 page-01.jpg…page-12.jpg)。
編輯現有文件
舊版 .doc 檔案必須先轉換:python scripts/office/soffice.py --headless --convert-to docx file.doc。
unzip -q doc.docx -d unpacked/
find unpacked -type l -delete # 移除符號連結項目 — 外部提供的 docx 可能不可信
python scripts/merge_runs.py unpacked/ # 合併分散的 run,讓文字可被搜尋
# 就地編輯 unpacked/word/document.xml — 請勿重新格式化或美化排版
(cd unpacked && rm -f ../out.docx && zip -Xr ../out.docx .)
python scripts/office/validate.py out.docx --original doc.docx # XSD 檢查;--auto-repair 自動修復常見問題
# 需要檢查修訂?加上 --author "<您的修訂姓名>" 以確認每次編輯都有被追蹤
Word 會將文字分散到多個 <w:r> run 中(因修訂 ID、拼字檢查標記等),因此在 XML 中,您在文件裡看到的片語往往並非連續字串。merge_runs.py 會合併 word/document.xml 中相鄰且格式相同的 run,且不改變內容或顯示效果;它也可以直接接受 .docx 檔案(python scripts/merge_runs.py doc.docx -o merged.docx)。
追蹤修訂: 進行修訂時,請以 --author "<您的修訂姓名>" 進行驗證(需要 --original)— 它會回報您修改過但沒有被 <w:ins>/<w:del> 包圍的文字,這很容易意外發生且在「接受」檢視中不可見。需在 run 外層加上含有 w:id、w:author、w:date 屬性的 <w:ins>/<w:del>。在 <w:del> 內部,文字元素是 <w:delText>,而非 <w:t>。被刪除的段落標記(<w:pPr><w:rPr><w:del w:id=".." w:author=".." w:date=".."/></w:rPr></w:pPr>)表示「將此段落合併至下一段」— 因此完全刪除一個段落就是這個標記加上每個 run 外層的 <w:del>。<w:del/> 必須位於 rPr 的其他子元素之前;它們的順序受到 XML Schema 約束。
若要產生一份接受所有追蹤修訂的乾淨副本:python scripts/accept_changes.py in.docx out.docx。
接受已刪除的段落標記應將該段落與其下一段合併,因此所有 run 都被刪除的段落會消失。Word 能做到這一點;但 accept_changes.py 和 pandoc --track-changes=accept 不一定能做到。兩者都以相同方式失敗:它們會移除已刪除的文字,但留下空的段落,當該段落是自動編號時,就會顯示為一個多餘的空項目符號:
pandoc --track-changes=accept永遠不會合併段落。accept_changes.py(LibreOffice)能正確合併,除非被刪除的段落後面緊跟著一個空的間隔段落。
在任何一種檢視中出現空項目符號,都是該檢視的假象,並非文件本身的缺陷。請在 XML 中檢查段落刪除。
註解
註解需要六個相互關聯的檔案。請使用輔助腳本 — 若您同時也要編輯 document.xml,請使用目錄模式(可省去解壓縮/重新壓縮的步驟);否則請使用 .docx 直接模式:
# 針對已解壓縮的目錄(在同時放置標記時優先使用)
python scripts/comment.py unpacked/ "費用與支出上限過低"
python scripts/comment.py unpacked/ "同意" --parent 0
# 直接對 .docx 操作
python scripts/comment.py contract.docx "此上限過低" -o annotated.docx
該腳本會寫入 comments.xml、commentsExtended.xml、commentsIds.xml、commentsExtensible.xml、相關的關聯以及內容類型覆寫。註解 ID 會自動指派。腳本接著會輸出需加入 word/document.xml 的 <w:commentRangeStart>/<w:commentRangeEnd>/<w:commentReference> 程式碼片段,以便將註解錨定到特定文字 — 在您放置這些標記之前,註解雖然存在但不會顯示。
相依性
docx (npm,已預先安裝 — 僅在 require('docx') 失敗時安裝) · pandoc · LibreOffice (soffice) · pdftoppm (Poppler)