DOCXの作成、編集、分析
.docx ファイルはXMLファイルのZIPアーカイブです。タスクに応じて適切なアプローチを選んでください。
| タスク | アプローチ |
|---|---|
| 新しい文書の作成 | 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インチ) と設定します。 - 横置き（Landscape）： 縦置きの寸法と
orientation: PageOrientation.LANDSCAPEを渡します — docx-js は内部で幅と高さを入れ替えます。 - 表には二重の幅設定が必要： テーブルに
columnWidthsを設定し、さらにすべてのセルにwidthを、両方ともWidthType.DXAで設定します（PERCENTAGEは Google Docs で壊れます）。列幅の合計はテーブル幅と一致する必要があります。 - 表の網掛け：
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 作成後、それをレンダリングして確認します：
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/ # 断片化されたランを結合してテキストを検索可能に
# 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 で一般的な問題を修正
# 変更履歴（redlining）？ --author "<変更履歴に記録したい名前>" を追加して、すべての編集が追跡されているか確認
Wordはテキストを多数の <w:r> ラン（リビジョンID、スペルチェックマーカー）に分割するため、文書内で見えるフレーズがXML内で連続した文字列として存在しないことがよくあります。merge_runs.py は、内容やレンダリングを変更せずに word/document.xml 内の隣接する同一フォーマットのランを結合します。また、.docx ファイルを直接受け取ることもできます（python scripts/merge_runs.py doc.docx -o merged.docx）。
変更履歴（Tracked changes）： 変更履歴をつける場合、--author "<変更履歴に記録した名前>" を指定して検証します（--original が必要） — これは、変更したにもかかわらず <w:ins> / <w:del> で囲まれていないテキストを報告します。これは誤って起こりやすく、承認済みビューでは見えません。ランを <w:ins> / <w:del> でラップし、w:id, w:author, w:date 属性を付けてください。<w:del> 内では、テキスト要素は <w:t> ではなく <w:delText> です。削除された段落記号（<w:pPr><w:rPr><w:del w:id=".." w:author=".." w:date=".."/></w:rPr></w:pPr>）は「この段落を次の段落にマージする」ことを意味します — したがって段落全体を削除するには、それに加えてすべてのランの周りに <w:del> を配置します。<w:del/> は rPr の他の子要素より前に来る必要があります。その順序はスキーマで強制されています。
すべての変更履歴を承認したクリーンコピーを作成するには： python scripts/accept_changes.py in.docx out.docx
削除された段落記号を承認すると、その段落を以下の段落に結合する必要があります。つまり、ランがすべて削除された段落は消えるべきです。Word はこれを行いますが、accept_changes.py と pandoc --track-changes=accept は常にそうとは限りません。両方とも同じように失敗します — 削除されたテキストは除去しますが、空になった段落が残り、自動番号が付いている場合は余分な空の箇条書きとして表示されます：
pandoc --track-changes=acceptは段落を結合しません。accept_changes.py（LibreOffice）は、削除された段落の後に空のスペーサー段落が続く場合を除き、正しく結合します。
どちらのビューでも空の箇条書きはそのビューのアーティファクトであり、文書の欠陥ではありません。段落の削除はXMLで確認してください。
コメント
コメントには相互にリンクした6つのファイルが必要です。ヘルパースクリプトを使用してください — document.xml も編集する場合はディレクトリモード（unzip/rezipサイクルを節約）、それ以外は .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）
このスキルは Anthropic によって作成・保守されています。フロントマターのメタデータを除き、そのままベンダー配置されています。利用条件については LICENSE.txt を参照してください。