DOCX Generator

このスキルをいつ使うか

以下の場合に、このスキルを使用してください：

• データや仕様からプログラムで Word ドキュメントを作成する
• 企業のスタイルを保持しながら、ブランド化されたテンプレートに動的コンテンツを入力する
• 既存の DOCX ファイルからテキスト、表、構造を抽出して分析する
• {{TITLE}} や ${author} のようなプレースホルダーテキストを検索・置換する
• ドキュメント生成ワークフローを自動化する（レポート、契約書、手紙など）

以下の場合は、このスキルを使用しないでください：

• ユーザーがドキュメントを開く・表示したい場合（ネイティブ Word またはビューアーを使用）
• データソースを使った複雑なメールマージ（ネイティブ Word メールマージを使用）
• 古い .doc フォーマットで作業する場合（DOCX のみ対応）
• PDF 出力が必要な場合（pdf-generator スキルを使用してください）

前提条件

• Deno がインストールされていること（https://deno.land/）
• テンプレートベースの操作用の入力 DOCX ファイル
• スクラッチ生成用の JSON 仕様

クイックスタート

2 つの操作モード

1. テンプレートモード：既存のブランド化されたテンプレートを修正

   • テンプレートを分析してプレースホルダーを見つける
   • {{PLACEHOLDERS}} を実際のコンテンツに置換

2. スクラッチモード：JSON 仕様を使ってゼロからドキュメントを作成

手順

モード 1：テンプレートベースの生成

ステップ 1a：テンプレートを分析する

テキストインベントリを抽出して、何を置換できるかを理解します：

deno run --allow-read scripts/analyze-template.ts corporate-template.docx > inventory.json

出力 (inventory.json)：

{
  "filename": "corporate-template.docx",
  "paragraphCount": 25,
  "tableCount": 2,
  "imageCount": 1,
  "paragraphs": [
    {
      "index": 0,
      "style": "Title",
      "fullText": "{{DOCUMENT_TITLE}}",
      "runs": [
        { "text": "{{DOCUMENT_TITLE}}", "bold": true, "fontSize": 28 }
      ]
    }
  ],
  "placeholders": [
    { "tag": "{{DOCUMENT_TITLE}}", "location": "paragraph", "paragraphIndex": 0 },
    { "tag": "{{AUTHOR}}", "location": "footer-default", "paragraphIndex": 0 },
    { "tag": "${date}", "location": "table", "tableIndex": 0, "cellLocation": "R1C2" }
  ]
}

ステップ 1b：置換仕様を作成する

replacements.json を作成します：

{
  "textReplacements": [
    { "tag": "{{DOCUMENT_TITLE}}", "value": "Q4 2024 Financial Report" },
    { "tag": "{{AUTHOR}}", "value": "Finance Department" },
    { "tag": "${date}", "value": "December 15, 2024" },
    { "tag": "{{COMPANY}}", "value": "Acme Corporation" }
  ],
  "includeHeaders": true,
  "includeFooters": true
}

ステップ 1c：出力を生成する

deno run --allow-read --allow-write scripts/generate-from-template.ts \
  corporate-template.docx replacements.json output.docx

モード 2：スクラッチからの生成

ステップ 2a：仕様を作成する

spec.json を作成します：

{
  "title": "Quarterly Report",
  "creator": "Finance Team",
  "styles": {
    "defaultFont": "Calibri",
    "defaultFontSize": 11
  },
  "sections": [
    {
      "header": {
        "paragraphs": [
          { "text": "Acme Corporation", "alignment": "right" }
        ]
      },
      "footer": {
        "paragraphs": [
          { "text": "Confidential", "alignment": "center" }
        ]
      },
      "content": [
        {
          "text": "Q4 2024 Financial Report",
          "heading": 1,
          "alignment": "center"
        },
        {
          "runs": [
            { "text": "Executive Summary: ", "bold": true },
            { "text": "This report provides an overview of our financial performance for Q4 2024." }
          ]
        },
        { "pageBreak": true },
        {
          "text": "Revenue Breakdown",
          "heading": 2
        },
        {
          "rows": [
            {
              "cells": [
                { "content": [{ "text": "Category" }], "shading": "DDDDDD" },
                { "content": [{ "text": "Amount" }], "shading": "DDDDDD" },
                { "content": [{ "text": "Change" }], "shading": "DDDDDD" }
              ],
              "isHeader": true
            },
            {
              "cells": [
                { "content": [{ "text": "Product Sales" }] },
                { "content": [{ "text": "$1,250,000" }] },
                { "content": [{ "text": "+15%" }] }
              ]
            },
            {
              "cells": [
                { "content": [{ "text": "Services" }] },
                { "content": [{ "text": "$750,000" }] },
                { "content": [{ "text": "+8%" }] }
              ]
            }
          ],
          "width": 100,
          "borders": true
        }
      ]
    }
  ]
}

ステップ 2b：ドキュメントを生成する

deno run --allow-read --allow-write scripts/generate-scratch.ts spec.json output.docx

例

例 1：契約書生成

シナリオ：ブランド化されたテンプレートから契約書を生成します。

ステップ：

# 1. テンプレートを分析して置換可能なコンテンツを探す
deno run --allow-read scripts/analyze-template.ts contract-template.docx --pretty

# 2. クライアントデータを含む replacements.json を作成する
# 3. 契約書を生成
deno run --allow-read --allow-write scripts/generate-from-template.ts \
  contract-template.docx replacements.json acme-contract.docx

例 2：表を含むレポート

シナリオ：表とフォーマット付きのデータレポートを生成します。

spec.json：

{
  "title": "Sales Report",
  "sections": [{
    "content": [
      { "text": "Monthly Sales Report", "heading": 1 },
      { "text": "January 2025", "heading": 2 },
      {
        "runs": [
          { "text": "Total Sales: ", "bold": true },
          { "text": "$125,000", "color": "2E7D32" }
        ]
      }
    ]
  }]
}

例 3：ヘッダー/フッター付きの手紙

シナリオ：レターヘッド付きの形式的な手紙を作成します。

spec.json：

{
  "sections": [{
    "header": {
      "paragraphs": [
        { "text": "ACME CORPORATION", "alignment": "center", "runs": [{"text": "ACME CORPORATION", "bold": true, "fontSize": 16}] },
        { "text": "123 Business Ave, City, ST 12345", "alignment": "center" }
      ]
    },
    "content": [
      { "text": "December 15, 2024", "alignment": "right" },
      { "text": "" },
      { "text": "Dear Valued Customer," },
      { "text": "" },
      { "text": "Thank you for your continued business..." },
      { "text": "" },
      { "text": "Sincerely," },
      { "text": "John Smith" },
      { "runs": [{ "text": "CEO", "italic": true }] }
    ],
    "footer": {
      "paragraphs": [
        { "text": "www.acme.com | contact@acme.com", "alignment": "center" }
      ]
    }
  }]
}

スクリプトリファレンス

スクリプト	用途	パーミッション
analyze-template.ts	DOCX からテキスト、表、プレースホルダーを抽出	--allow-read
generate-from-template.ts	テンプレート内のプレースホルダーを置換	--allow-read --allow-write
generate-scratch.ts	JSON 仕様から DOCX を作成	--allow-read --allow-write

仕様リファレンス

パラグラフオプション

プロパティ	タイプ	説明
text	string	シンプルなテキストコンテンツ
runs	array	フォーマット付きテキストラン（混合フォーマット用）
heading	1-6	見出しレベル
alignment	string	left、center、right、justify
bullet	boolean	箇条書きリストアイテム
numbering	boolean	番号付きリストアイテム
spacing	object	before、after、line スペーシング
indent	object	left、right、firstLine インデント
pageBreakBefore	boolean	パラグラフの前にページブレークを挿入

テキストランオプション

プロパティ	タイプ	説明
text	string	テキストコンテンツ
bold	boolean	太字フォーマット
italic	boolean	イタリックフォーマット
underline	boolean	下線フォーマット
strike	boolean	打ち消し線
fontSize	number	フォントサイズ（ポイント）
font	string	フォントファミリー名
color	string	テキストの色（16進数、# なし）
highlight	string	ハイライト色
superScript	boolean	上付き文字
subScript	boolean	下付き文字

表オプション

プロパティ	タイプ	説明
rows	array	行仕様の配列
width	number	テーブル幅（パーセンテージ）
borders	boolean	表のボーダーを表示

ハイパーリンクオプション

プロパティ	タイプ	説明
text	string	リンクテキスト
url	string	ターゲット URL
bold	boolean	太字フォーマット
italic	boolean	イタリックフォーマット

一般的な問題と解決策

問題：プレースホルダーが置換されない

症状：出力 DOCX に {{PLACEHOLDER}} タグが残っている。

解決策：

1. analyze-template.ts を実行して、正確なタグテキストを確認する
2. タグが複数の XML ラン間で分割されている可能性があります。スクリプトがこれらを自動的に統合します
3. プレースホルダーがヘッダー/フッターにある場合、includeHeaders と includeFooters が true であることを確認してください

問題：置換後にフォーマットが失われる

症状：置換されたテキストが元のフォーマットと一致しない。

解決策：

• テキスト置換は元のプレースホルダーのフォーマットを保持します
• プレースホルダーが最終テキストに望む方法でフォーマットされていることを確認してください

問題：画像が表示されない

症状：出力の画像要素が空白になっている。

解決策：

1. spec.json ファイルの場所に相対するパスを使用してください
2. 画像ファイルが存在し、読み取り可能であることを確認してください
3. サポートされている形式を確認してください：PNG、JPEG、GIF

問題：表のセルコンテンツが正しくない

症状：表のセルにコンテンツが間違っているか、フォーマットが正しくない。

解決策：

• 各セルの content は、パラグラフ仕様の配列である必要があります
• shading を背景色に、verticalAlign をアライメントに使用してください

制限事項

• DOCX のみ：レガシー .doc フォーマットには対応していません
• 変更追跡なし：変更追跡を追加または処理できません
• コメントなし：ドキュメントコメントを追加できません
• マクロなし：VBA マクロを含めることはできません
• 基本的な番号付け：複雑な番号付けスキームのサポートは限定的です
• テキストランの分割：Word がテキストを XML 要素間で分割することがあります。スクリプトが一般的なケースに対応しています

関連スキル

• pptx-generator：PowerPoint プレゼンテーションを作成する場合
• xlsx-generator：Excel スプレッドシートを作成する場合
• pdf-generator：PDF ドキュメントを作成する場合