docx

DOCX の作成、編集、分析

.docx は XML ファイルを格納した ZIP アーカイブです。タスクに応じてアプローチを選んでください。

タスク	アプローチ
新しい文書を作成する	docx (npm) スクリプトを作成する — 以下の注意点を参照
テンプレートのプレースホルダーを埋める	docx の patchDocument({ data, outputType, patches }) を使用する
既存の任意のコンテンツを編集する	安全に展開 → 該当する OOXML パートを編集 → 再パッケージ化する
コンテンツを読み取る	レビューには pandoc -f docx -t markdown --track-changes=all file.docx、承諾済みテキストビューには accept を使用する

以下のスクリプトパスは、このスキルのディレクトリからの相対パスです。

docx-js での作成 — 注意点

例は docx 9.8.1 を対象としています。まずスクリプトのプロジェクトで node -p "require.resolve('docx')" を確認してください。存在しない場合は、そこに npm install [email protected] でインストールしてください。事前インストールは環境に依存します。以下が主なレイアウト上の制約です。

• ページサイズはデフォルトで A4 です。 US Letter にするには page: { size: { width: 12240, height: 15840 } } を設定します (DXA、1440 = 1″) 。
• 横向き: 縦向きの寸法を渡し、orientation: PageOrientation.LANDSCAPE を指定します — docx-js が内部的に幅と高さを入れ替えます。
• テーブル: 予測可能な固定ジオメトリには、layout: TableLayoutType.FIXED、テーブルの width: { size, type: WidthType.DXA }、DXA 単位の数値による columnWidths、そしてセルに一致する幅を使用してください。連結セルがある場合は、連結した列の幅を合計します。パーセンテージ幅もサポートされていますが、エディター間でのレイアウトは視覚的に確認する必要があります。
• テーブルの網掛け: 単色の背景には fill と共に ShadingType.CLEAR を使用してください。SOLID は fill だけでなく前景パターン色を使用します。
• リスト: • をそのまま挿入しないでください。LevelFormat.BULLET を指定した numbering 設定を使用してください。
• ImageRun には type: が必要です ("png"、"jpg" など) 。
• PageBreak は Paragraph の内部に置く必要があります。
• 段落と改行: 段落には個別の Paragraph 要素を使用してください。new TextRun({ break: 1, text: "Next line" }) は段落内で改行を行います。プレーンテキスト文字列内の \n が段落を作成することを期待しないでください。
• 目次: 組み込みの HeadingLevel.* は headingStyleRange と連携します。カスタムスタイルには stylesWithLevels、または useAppliedParagraphOutlineLevel: true を指定した outlineLevel を使用してください。ページ番号を確認する前に Word/LibreOffice で目次フィールドを更新してください。フィールドを作成してもページ割り付けは計算されません。
• 水平罫線としてテーブルを使用しないでください — 代わりに段落の下罫線を使用してください。
• ドットリーダー / 同じ行での右揃え: リテラルの . やスペースによるパディングではなく、TextRun の内部で PositionalTab (alignment: PositionalTabAlignment.RIGHT、relativeTo: PositionalTabRelativeTo.MARGIN、leader: PositionalTabLeader.DOT) を使用してください。LibreOffice 26.2.4.2 では、スモークテストでその位置指定リーダー/配置はレンダリングされませんでした。そのレンダラーで再現する必要がある場合は、段落の tabStops と Tab ランを使用してください。

簡単な作成とテンプレートの例

この CommonJS スクリプトを node example.cjs で実行してください。patchDocument は 完全な文書の再構築を必要とせずに {{name}} を置換します。これはプレースホルダーの パッチャーであり、汎用の Word 文書編集オブジェクトモデルではありません。

const fs = require("node:fs/promises");
const { Document, Packer, Paragraph, TextRun, HeadingLevel,
        patchDocument, PatchType } = require("docx");

async function main() {
  const document = new Document({ sections: [{
    properties: { page: { size: { width: 12240, height: 15840 } } },
    children: [
      new Paragraph({ text: "Research memo", heading: HeadingLevel.HEADING_1 }),
      new Paragraph("Prepared for {{name}}"),
    ],
  }] });
  const template = await Packer.toBuffer(document);
  const output = await patchDocument({
    data: template, outputType: "nodebuffer",
    patches: { name: { type: PatchType.PARAGRAPH,
      children: [new TextRun({ text: "Research team", bold: true })] } },
  });
  await fs.writeFile("output.docx", output);
}
main().catch(error => { console.error(error); process.exitCode = 1; });

出力を検証する

.docx を作成したら、それをレンダリングして確認してください。

mkdir -p preview
python scripts/office/soffice.py --headless --convert-to pdf --outdir preview output.docx
test -s preview/output.pdf
pdftoppm -jpeg -r 100 preview/output.pdf preview/page
ls preview/page-*.jpg   # then Read the images

新しいプレビューディレクトリを使用するか、先に古い PDF を削除してください。コンバーターの 終了ステータスだけでは、新しいファイルが書き込まれたことを証明できません。レンダリングされた すべてのページで、オーバーフロー、ヘッダー、テーブル、欠落している画像を確認してください。 変換時に利用できないフォントが代替されることがあります。

pdftoppm はページ番号をページ数の桁数に合わせてゼロ埋めします (page-01.jpg…page-12.jpg) 。

既存のドキュメントを編集する

レガシーな .doc ファイルは先に変換する必要があります: python scripts/office/soffice.py --headless --convert-to docx file.doc。

python - <<'PY'
import sys, zipfile
from pathlib import Path
sys.path.insert(0, "scripts")
from office.helpers import safe_extract
with zipfile.ZipFile("doc.docx") as archive:
    safe_extract(archive, Path("unpacked"))  # rejects symlinks and traversal
PY
python scripts/merge_runs.py unpacked/   # coalesce fragmented runs so text is findable
# edit unpacked/word/document.xml in place — do NOT reformat or pretty-print
(cd unpacked && rm -f ../out.docx && zip -Xr ../out.docx .)
python scripts/office/validate.py out.docx --original doc.docx   # bundled schema and package checks
# redlining? add --author "<the name you redlined under>" to check every edit is tracked

Word はテキストを多数の <w:r> ラン（リビジョン ID、スペルチェックマーカー）に分割するため、ドキュメント内で見えるフレーズが XML 内で連続した文字列として存在しないことがよくあります。merge_runs.py は word/document.xml 内の隣接する同一書式のランを、テキストと書式の境界を保ったままマージします。結果をレンダーチェックしてください。特にフィールドや複雑なコンテンツに注意してください。また、.docx を直接受け取ることもできます（python scripts/merge_runs.py doc.docx -o merged.docx）。

変更履歴: 既存の作成者／日付／ID およびリビジョンを保持してください。レッドラインを作成する際は、--author "<redline に使用した名前>" で検証してください（--original が必要です）。これは新しい <w:ins>／<w:del> リビジョンを元に戻したうえで本文テキストを比較し、変更を承諾したビューでは隠れてしまう未追跡のテキスト編集を洗い出します。ランは w:id、w:author、w:date 属性を付けて <w:ins>／<w:del> で囲みます。<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:rPr 内では、そのコンテンツモデルで要求されるように、リビジョンマーカーを他のラン プロパティより前に配置してください。

すべての変更履歴を承諾したクリーンなコピーを生成するには: python scripts/accept_changes.py in.docx out.docx。

このヘルパーは一時コピーと分離された LibreOffice プロファイルを使用します。独自のアプリケーション マクロは MacroExecutionMode=NEVER_EXECUTE で入力を開くため、ドキュメントが提供する マクロは無効化されます。プロファイルのマクロセキュリティを下げることはありません。タイムアウト、 変換失敗、またはいずれかの Word XML パートにリビジョン要素が残っている場合、出力先は 変更されません。--timeout 120 は LibreOffice 操作ごとの制限を引き上げます。リビジョン要素の ないドキュメントは、LibreOffice のラウンドトリップなしでコピーされます。

削除された段落記号を承諾すると、その段落は次に結合されるはずです。Pandoc の承諾済みテキスト ビューや LibreOffice の変換が Word の段落・リスト・書式のセマンティクスを正確に再現すると 仮定しないでください。XML 内の削除された段落記号を検査し、クリーンなコピーをレンダリング してください。特に、空のスペーサーの隣にある削除された番号付き段落に注意してください。予期しない 空の箇条書きは、自動的に片付けず調査が必要です。

同梱のバリデーターは、出荷されている 2016 スキーマおよび選択された Microsoft 拡張に対する 実用的なチェックであり、完全な現在の Word 互換性の判定ではありません。 --original は継承されたスキーマ エラーを抑制します。--auto-repair は入力を書き換え、 重要な空白を変更する可能性があります。その変更を検査してください。レッドライン チェックは 本文テキストのみを対象とし、書式、テーブルの構造リビジョン、その他のストーリーは対象外です。

ドキュメント全体にわたる編集カバレッジ

word/document.xml に含まれるのはメイン ストーリーであり、ドキュメントのすべてのテキストでは ありません。ドキュメント全体の置換を行う前に、パッケージのリレーションシップを通じて、関連する ヘッダー、フッター、脚注、文末脚注、コメント、テキスト ボックスのストーリーを洗い出してください。 merge_runs.py は word/document.xml のみを処理し、これらの他のパートを正規化しません。 要求された編集をそのスコープが必要とする箇所に適用し、リレーションシップを保持し、本文だけで なく、レンダリングされた先頭ページおよび奇数／偶数ページのヘッダーとフッターも確認してください。 Microsoft の WordprocessingML structure を参照してください。

コメント

基本的なコメントには、コメントパート、そのリレーションシップ/コンテンツタイプ、および対応する commentReference が必要です。範囲の開始/終了マーカーは、テキスト範囲を識別するために任意で使用します。 このヘルパーはさらに、返信スレッド用の Microsoft 拡張パートも書き込みます。これを使用してください。document.xml も編集する場合はディレクトリモード（unzip/rezip のサイクルを節約できます）、それ以外の場合は .docx 直接モードを使用します:

# Against an already-unpacked directory (preferred when also placing markers)
python scripts/comment.py unpacked/ "Fees & expenses cap is too low"
python scripts/comment.py unpacked/ "Agreed" --parent 0

# Against a .docx directly
python scripts/comment.py contract.docx "This cap is too low" -o annotated.docx

このスクリプトは comments.xml、commentsExtended.xml、commentsIds.xml、commentsExtensible.xml、リレーションシップ、およびコンテンツタイプのオーバーライドを書き込みます。コメント ID は自動割り当てされます。明示的な ID の重複は拒否されます。返信は親コメントの最後の段落 ID を参照します。別のファイル名を使用している既存のパートについては、それらのリレーションシップターゲットを直接編集する必要があります。ヘルパーは、競合するコメントパートを作成する代わりにそれらを拒否します。その後、コメントを特定のテキストにアンカーするために word/document.xml に追加する <w:commentRangeStart>/<w:commentRangeEnd>/<w:commentReference> スニペットを出力します。これらのマーカーを配置するまで、コメントは存在しますが表示されません。

依存関係

docx (npm) · Python の defusedxml と lxml · pandoc · LibreOffice (soffice) · pdftoppm (Poppler)。 Python パッケージのインストール: 専用の環境で python -m pip install defusedxml lxml を実行します。認証情報やサービス API の呼び出しは不要です。

現在の docx API、 patchDocument、 LibreOffice コマンドライン、 Microsoft コメント、 返信の段落 ID、 および Pandoc オプション に対してレビュー済みです。 作成、プレースホルダーのパッチ適用、PDF レンダリング、コメント、リビジョンの承認は、docx 9.8.1、LibreOffice 26.2.4.2、Pandoc 3.11、および Poppler 26.09.0 でスモークテスト済みです。Microsoft Word および Google Docs でのレンダリングはテストされていません。

---

このスキルは Anthropic によって作成および保守されています。ここでは frontmatter メタデータと編集スコープのガイダンスを加えて適応しています。条件については LICENSE.txt を参照してください。