DOCX 建立、編輯與分析

DOCX 建立、編輯與分析 是做什麼的？

總覽

使用者可能會要求您建立、編輯或分析 .docx 檔案的內容。.docx 檔案本質上是一個包含 XML 檔案與其他資源的 ZIP 壓縮檔，您可以讀取或編輯。針對不同任務，您可以使用不同的工具與工作流程。

工作流程決策樹

讀取/分析內容

請使用下方的「文字擷取」或「原始 XML 存取」章節

建立新文件

請使用「建立新的 Word 文件」工作流程

編輯現有文件

• 您自己的文件 + 簡單變更 使用「基本 OOXML 編輯」工作流程

• 他人的文件 使用**「修訂工作流程」**（建議預設）

• 法律、學術、商業或政府文件 使用**「修訂工作流程」**（必須）

讀取與分析內容

文字擷取

如果您只需要讀取文件的文字內容，應使用 pandoc 將文件轉換為 Markdown。Pandoc 能極佳地保留文件結構，並可顯示追蹤修訂：

# 將文件轉換為 Markdown，保留追蹤修訂
pandoc --track-changes=all path-to-file.docx -o output.md
# 選項：--track-changes=accept/reject/all

原始 XML 存取

當您需要處理註解、複雜格式、文件結構、嵌入媒體及後設資料時，需要原始 XML 存取。為此，您必須解壓縮文件並讀取其原始 XML 內容。

解壓縮檔案

python ooxml/scripts/unpack.py <office_file> <output_directory>

關鍵檔案結構

• word/document.xml - 主要文件內容
• word/comments.xml - 在 document.xml 中被引用的註解
• word/media/ - 嵌入的圖片與媒體檔案
• 追蹤修訂使用 <w:ins>（插入）和 <w:del>（刪除）標籤

建立新的 Word 文件

從頭建立新的 Word 文件時，請使用 docx-js，它能讓您使用 JavaScript/TypeScript 建立 Word 文件。

工作流程

1. 必須 - 完整閱讀檔案：從頭到尾完整閱讀 docx-js.md（約 500 行）。讀取此檔案時切勿設定任何範圍限制。 在開始建立文件前，請完整閱讀檔案內容以取得詳細語法、關鍵格式規則及最佳實務。
2. 使用 Document、Paragraph、TextRun 元件建立 JavaScript/TypeScript 檔案（您可以假設所有依賴項目皆已安裝，若未安裝，請參閱下方的依賴項目章節）
3. 使用 Packer.toBuffer() 匯出為 .docx

編輯現有 Word 文件

編輯現有 Word 文件時，請使用 Document 函式庫（一個用於 OOXML 操作的 Python 函式庫）。此函式庫會自動處理基礎設施設定，並提供文件操作方法。對於複雜情境，您可以透過函式庫直接存取底層 DOM。

工作流程

1. 必須 - 完整閱讀檔案：從頭到尾完整閱讀 ooxml.md（約 600 行）。讀取此檔案時切勿設定任何範圍限制。 請完整閱讀檔案內容以取得 Document 函式庫 API 及直接編輯文件的 XML 模式。
2. 解壓縮文件：python ooxml/scripts/unpack.py <office_file> <output_directory>
3. 使用 Document 函式庫建立並執行 Python 腳本（詳見 ooxml.md 中的「Document 函式庫」章節）
4. 封裝最終文件：python ooxml/scripts/pack.py <input_directory> <office_file>

Document 函式庫同時提供用於常見操作的高階方法，以及用於複雜情境的直接 DOM 存取。

文件審閱的修訂工作流程

此工作流程允許您在將修訂實作到 OOXML 前，先使用 Markdown 規劃完整的追蹤修訂。關鍵：要實現完整的追蹤修訂，您必須有系統地實作所有變更。

批次策略：將相關變更分組為每批 3-10 個變更。這能在維持效率的同時，讓除錯更易管理。在進行下一批前，請先測試每一批。

原則：最小化、精確的編輯 在實作追蹤修訂時，僅標記實際變動的文字。重複未變動的文字會讓編輯更難審閱，且顯得不專業。將替換分解為：[未變動文字] + [刪除] + [插入] + [未變動文字]。對於未變動的文字，請從原始 <w:r> 元素中擷取 RSID 並重複使用。

範例 - 將句子中的「30 天」改為「60 天」：

# 不好 - 取代整個句子
'<w:del><w:r><w:delText>期限為 30 天。</w:delText></w:r></w:del><w:ins><w:r><w:t>期限為 60 天。</w:t></w:r></w:ins>'

# 好 - 僅標記變動部分，保留原始 <w:r> 給未變動文字
'<w:r w:rsidR="00AB12CD"><w:t>期限為 </w:t></w:r><w:del><w:r><w:delText>30</w:delText></w:r></w:del><w:ins><w:r><w:t>60</w:t></w:r></w:ins><w:r w:rsidR="00AB12CD"><w:t> 天。</w:t></w:r>'

追蹤修訂工作流程

1. 取得 Markdown 表示法：將文件轉換為 Markdown，並保留追蹤修訂：

   pandoc --track-changes=all path-to-file.docx -o current.md
   

2. 識別並分組變更：審閱文件，識別所有需要的變更，並將其組織為邏輯批次：

   定位方法（用於在 XML 中尋找變更）：

   • 章節/標題編號（例如「第 3.2 節」、「第四條」）
   • 段落標識符（若有編號）
   • 使用獨特周圍文字的 Grep 模式
   • 文件結構（例如「第一段」、「簽名欄」）
   • 請勿使用 Markdown 行號 - 它們無法對應到 XML 結構

   批次組織（每批分組 3-10 個相關變更）：

   • 依章節：「批次 1：第 2 條修正」、「批次 2：第 5 條更新」
   • 依類型：「批次 1：日期修正」、「批次 2：當事人名稱變更」
   • 依複雜度：先從簡單的文字取代開始，再處理複雜的結構變更
   • 依順序：「批次 1：第 1-3 頁」、「批次 2：第 4-6 頁」

3. 閱讀文件並解壓縮：

   • 必須 - 完整閱讀檔案：從頭到尾完整閱讀 ooxml.md（約 600 行）。讀取此檔案時切勿設定任何範圍限制。 特別注意「Document 函式庫」和「追蹤修訂模式」章節。
   • 解壓縮文件：python ooxml/scripts/unpack.py <file.docx> <dir>
   • 記錄建議的 RSID：解壓縮腳本會建議一個用於追蹤修訂的 RSID。請複製此 RSID 以在步驟 4b 中使用。

4. 分批實作變更：將變更邏輯分組（依章節、依類型或依鄰近性），並在單一腳本中一起實作。這種方法：

   • 讓除錯更容易（批次較小 = 更容易隔離錯誤）
   • 允許逐步推進
   • 維持效率（每批 3-10 個變更效果良好）

   建議的批次分組：

   • 依文件章節（例如「第 3 節變更」、「定義」、「終止條款」）
   • 依變更類型（例如「日期變更」、「當事人名稱更新」、「法律用語取代」）
   • 依鄰近性（例如「第 1-3 頁的變更」、「文件前半部的變更」）

   對於每批相關變更：

   a. 將文字對應到 XML：對 word/document.xml 執行 grep，以驗證文字如何跨 <w:r> 元素分割。

   b. 建立並執行腳本：使用 get_node 尋找節點，實作變更，然後執行 doc.save()。詳見 ooxml.md 中的**「Document 函式庫」**章節以取得模式。

   注意：在撰寫腳本前，請務必立即對 word/document.xml 執行 grep，以取得當前行號並驗證文字內容。每次執行腳本後，行號都會變更。

5. 封裝文件：完成所有批次後，將解壓縮的目錄轉換回 .docx：

   python ooxml/scripts/pack.py unpacked reviewed-document.docx
   

6. 最終驗證：對完整文件進行全面檢查：

   • 將最終文件轉換為 Markdown：

     pandoc --track-changes=all reviewed-document.docx -o verification.md
     

   • 驗證所有變更是否正確套用：

     grep "原始詞句" verification.md  # 應該找不到
     grep "取代詞句" verification.md  # 應該找得到
     

   • 檢查是否引入非預期的變更

將文件轉換為圖像

若要視覺化分析 Word 文件，請透過以下兩步驟將其轉換為圖像：

1. 將 DOCX 轉換為 PDF：

   soffice --headless --convert-to pdf document.docx
   

2. 將 PDF 頁面轉換為 JPEG 圖像：

   pdftoppm -jpeg -r 150 document.pdf page
   

   這會建立如 page-1.jpg、page-2.jpg 等檔案。

選項：

• -r 150：設定解析度為 150 DPI（可調整以在品質/大小間取得平衡）
• -jpeg：輸出 JPEG 格式（若偏好 PNG，請使用 -png）
• -f N：要轉換的第一頁（例如 -f 2 表示從第 2 頁開始）
• -l N：要轉換的最後一頁（例如 -l 5 表示停止於第 5 頁）
• page：輸出檔案的前綴

指定範圍的範例：

pdftoppm -jpeg -r 150 -f 2 -l 5 document.pdf page  # 僅轉換第 2-5 頁

程式碼風格指南

重要：在產生用於 DOCX 操作的程式碼時：

• 撰寫簡潔的程式碼
• 避免冗長的變數名稱與多餘操作
• 避免不必要的 print 陳述式

依賴項目

需要的依賴項目（若未安裝，請安裝）：

• pandoc：sudo apt-get install pandoc（用於文字擷取）
• docx：npm install -g docx（用於建立新文件）
• LibreOffice：sudo apt-get install libreoffice（用於 PDF 轉換）
• Poppler：sudo apt-get install poppler-utils（用於 pdftoppm 將 PDF 轉換為圖像）
• defusedxml：pip install defusedxml（用於安全的 XML 解析）