docx-generator

DOCX ジェネレーター

このスキルを使用する場面

次の場合にこのスキルを使用します。

• データや仕様からプログラムで 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. Analyze template for replaceable content
deno run --allow-read scripts/analyze-template.ts contract-template.docx --pretty

# 2. Create replacements.json with client data
# 3. Generate contract
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 | [email protected]", "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 文書の作成に使用します