xlsx-generator

XLSX Generator

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

次のような場合にこのスキルを使用します：

• データや仕様からプログラムで Excel スプレッドシートを作成する
• 書式を維持しながら、ブランド設定済みのテンプレートに動的コンテンツを入力する
• 既存の XLSX ファイルからセルのデータ、数式、構造を抽出する
• セル内の {{TITLE}} や ${date} のようなプレースホルダー文字列を検索して置換する
• スプレッドシート生成ワークフロー（レポート、データエクスポート、財務諸表）を自動化する

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

• スプレッドシートを開いて表示したい場合（標準の Excel またはビューアーを使用してください）
• 複雑なピボットテーブルやグラフが必要な場合（サポートは限定的です）
• 古い .xls 形式を扱う場合（XLSX のみ対応）
• リアルタイムでの共同編集が必要な場合

前提条件

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

クイックスタート

2 つの操作モード

1. テンプレートモード：既存のブランド設定済みテンプレートを変更します

   • テンプレートを分析してプレースホルダーと構造を確認します
   • {{PLACEHOLDERS}} を実際の値に置き換えます

2. スクラッチモード：JSON 仕様を使って、何もない状態からスプレッドシートを作成します

手順

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

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

置換可能な項目を把握するため、セル一覧を抽出します：

deno run --allow-read scripts/analyze-template.ts financial-template.xlsx > inventory.json

出力（inventory.json）：

{
  "filename": "financial-template.xlsx",
  "sheetCount": 3,
  "sheets": [
    {
      "name": "Summary",
      "rowCount": 25,
      "colCount": 8,
      "usedRange": "A1:H25",
      "cells": [
        { "address": "A1", "row": 1, "col": 1, "value": "{{REPORT_TITLE}}", "type": "string" },
        { "address": "B3", "row": 3, "col": 2, "value": "{{DATE}}", "type": "string" },
        { "address": "C5", "row": 5, "col": 3, "value": null, "type": "number", "formula": "SUM(C6:C20)" }
      ]
    }
  ],
  "placeholders": [
    { "tag": "{{REPORT_TITLE}}", "location": "Summary!A1", "sheet": "Summary", "address": "A1" },
    { "tag": "{{DATE}}", "location": "Summary!B3", "sheet": "Summary", "address": "B3" }
  ],
  "hasFormulas": true
}

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

replacements.json を作成します：

{
  "textReplacements": [
    { "tag": "{{REPORT_TITLE}}", "value": "Q4 2024 Financial Report" },
    { "tag": "{{DATE}}", "value": "December 15, 2024" },
    { "tag": "{{COMPANY}}", "value": "Acme Corporation", "sheets": ["Summary", "Cover"] }
  ],
  "cellUpdates": [
    { "sheet": "Data", "address": "B5", "value": 1250000 },
    { "sheet": "Data", "address": "B6", "value": 750000 }
  ]
}

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

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

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

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

spec.json を作成します：

{
  "title": "Sales Report",
  "author": "Finance Team",
  "sheets": [
    {
      "name": "Sales Data",
      "data": [
        ["Product", "Q1", "Q2", "Q3", "Q4", "Total"],
        ["Widget A", 10000, 12000, 15000, 18000, null],
        ["Widget B", 8000, 9000, 11000, 13000, null],
        ["Widget C", 5000, 6000, 7000, 8000, null]
      ],
      "cells": [
        { "address": "F2", "formula": "SUM(B2:E2)" },
        { "address": "F3", "formula": "SUM(B3:E3)" },
        { "address": "F4", "formula": "SUM(B4:E4)" }
      ],
      "columns": [
        { "col": "A", "width": 15 },
        { "col": "B", "width": 10 },
        { "col": "C", "width": 10 },
        { "col": "D", "width": 10 },
        { "col": "E", "width": 10 },
        { "col": "F", "width": 12 }
      ],
      "freezePane": "A2",
      "autoFilter": "A1:F4"
    }
  ]
}

ステップ 2b：スプレッドシートを生成する

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

例

例 1：月次売上レポート

シナリオ：テンプレートから月次売上レポートを生成します。

手順：

# 1. Analyze template for replaceable content
deno run --allow-read scripts/analyze-template.ts sales-template.xlsx --pretty

# 2. Create replacements.json with monthly data
# 3. Generate report
deno run --allow-read --allow-write scripts/generate-from-template.ts \
  sales-template.xlsx replacements.json November-Sales.xlsx

例 2：数式を使ったデータエクスポート

シナリオ：合計を計算するスプレッドシートを作成します。

spec.json：

{
  "sheets": [{
    "name": "Expenses",
    "data": [
      ["Category", "January", "February", "March", "Total"],
      ["Office", 1500, 1600, 1400, null],
      ["Travel", 3000, 2500, 4000, null],
      ["Software", 500, 500, 500, null],
      ["Total", null, null, null, null]
    ],
    "cells": [
      { "address": "E2", "formula": "SUM(B2:D2)" },
      { "address": "E3", "formula": "SUM(B3:D3)" },
      { "address": "E4", "formula": "SUM(B4:D4)" },
      { "address": "B5", "formula": "SUM(B2:B4)" },
      { "address": "C5", "formula": "SUM(C2:C4)" },
      { "address": "D5", "formula": "SUM(D2:D4)" },
      { "address": "E5", "formula": "SUM(E2:E4)" }
    ]
  }]
}

例 3：複数シートのブック

シナリオ：概要シートと詳細シートを含むブックを作成します。

spec.json：

{
  "title": "Q4 Report",
  "sheets": [
    {
      "name": "Summary",
      "data": [
        ["Department", "Budget", "Actual", "Variance"],
        ["Sales", 500000, 520000, null],
        ["Marketing", 200000, 195000, null]
      ],
      "cells": [
        { "address": "D2", "formula": "C2-B2" },
        { "address": "D3", "formula": "C3-B3" }
      ]
    },
    {
      "name": "Sales Detail",
      "data": [
        ["Month", "Revenue", "Cost", "Profit"],
        ["October", 180000, 120000, null],
        ["November", 170000, 115000, null],
        ["December", 170000, 110000, null]
      ],
      "cells": [
        { "address": "D2", "formula": "B2-C2" },
        { "address": "D3", "formula": "B3-C3" },
        { "address": "D4", "formula": "B4-C4" }
      ]
    }
  ]
}

スクリプトリファレンス

スクリプト	用途	権限
analyze-template.ts	XLSX からセル、数式、プレースホルダーを抽出	--allow-read
generate-from-template.ts	テンプレート内のプレースホルダーを置換	--allow-read --allow-write
generate-scratch.ts	JSON 仕様から XLSX を作成	--allow-read --allow-write

仕様リファレンス

シートのオプション

プロパティ	型	説明
name	string	シート名
data	array	A1 から始まるセル値の 2 次元配列
cells	array	個別のセル仕様
rows	array	行単位のデータ仕様
columns	array	列幅と表示設定
merges	array	セル結合の範囲
freezePane	string	このセルでウィンドウ枠を固定します（例："A2"）
autoFilter	string	オートフィルターの範囲（例："A1:F10"）

セルのオプション

プロパティ	型	説明
address	string	セルのアドレス（例："A1"、"B2"）
value	mixed	セルの値（文字列、数値、ブール値、null）
formula	string	= 記号を含まない数式
format	string	数値の書式（例："#,##0.00"）
type	string	型を指定します："string"、"number"、"boolean"、"date"

列のオプション

プロパティ	型	説明
col	string	列の英字（例："A"、"B"、"AA"）
width	number	文字数単位の列幅
hidden	boolean	列を非表示にするかどうか

テンプレート置換のオプション

プロパティ	型	説明
tag	string	検索するプレースホルダー（例："{{TITLE}}"）
value	mixed	置換後の値
sheets	array	対象を特定のシートに限定します
range	string	対象をセル範囲に限定します（例："A1:D10"）

よくある問題と解決策

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

症状：出力された XLSX に {{PLACEHOLDER}} タグが残っています。

解決方法：

1. analyze-template.ts を実行して、タグの正確なテキストと位置を確認します
2. プレースホルダーが数式ではなく、文字列セルにあることを確認します
3. 置換仕様のシートフィルターを確認します

問題：数式がテキストとして表示される

症状：数式が計算されず、テキストとして表示されます。

解決方法：

• 仕様で数式が「=」で始まっていないことを確認します（自動的に追加されます）
• セルの種類が「string」に固定されていないことを確認します

問題：数値がテキストとして書式設定される

症状：数値に、文字列として保存されていることを示す緑色の三角形が表示されます。

解決方法：

• 引用符で囲んだ文字列ではなく、仕様に数値を使用します
• テンプレート置換でセル全体がプレースホルダーで、置換する値が数値の場合、自動的に変換されます

問題：列幅が適用されない

症状：指定しているにもかかわらず、列幅がデフォルトのままです。

解決方法：

• 列の文字が大文字であることを確認します
• 列の仕様が配列形式であることを確認します

制限事項

• XLSX のみ：従来の .xls または .xlsb 形式には対応していません
• マクロなし：VBA マクロの作成や保持はできません
• グラフ機能は限定的：ネイティブのグラフ作成には対応していません
• ピボットテーブルなし：プログラムによるピボットテーブルの作成はできません
• 基本的なスタイル設定：セルの書式設定オプションは限られています
• 条件付き書式なし：条件付き書式のルールは設定できません
• 数式の再計算：数式は保存されますが、再計算されません（Excel を開くと再計算されます）

関連スキル

• pptx-generator：PowerPoint プレゼンテーションの作成に使用します
• docx-generator：Word ドキュメントの作成に使用します
• csv-processor：よりシンプルな CSV データ処理に使用します