mcpField
X
xlsx-generator

xlsx-generator

github.com/jwynia文档处理179393 次安装35 周前更新
代码仓库

关于 xlsx-generator

xlsx-generator 是用于从数据或 JSON 规格生成 XLSX 电子表格的技能，也可填充现有模板并提取单元格信息。适合自动生成报表和数据导出的工作流。

主要功能

  1. 01从 JSON 规格创建工作簿
  2. 02填充模板并替换占位符
  3. 03提取单元格与公式信息
  4. 04设置单元格值和公式
  5. 05配置列宽、合并与筛选

适用场景

  1. 01按月更新销售报表模板
  2. 02从数据生成多工作表报表
  3. 03导出带公式的费用明细
  4. 04检查模板中的单元格和占位符

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jwynia/agent-skills --skill xlsx-generator

安装后在 Claude Code 中输入/xlsx-generator确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

scripts/
analyze-template.ts
generate-from-template.ts
generate-scratch.ts

详细介绍

XLSX 生成器

何时使用此技能

在以下情况使用此技能：

  • 根据数据或规格以编程方式创建 Excel 电子表格
  • 在保留格式的同时，向品牌模板填充动态内容
  • 从现有 XLSX 文件中提取单元格数据、公式和结构
  • 在单元格中查找并替换 {{TITLE}} 或 ${date} 等占位文本
  • 自动化电子表格生成工作流（报告、数据导出、财务报表）

在以下情况不要使用此技能：

  • 用户想要打开／查看电子表格（使用原生 Excel 或查看器）
  • 需要复杂的数据透视表或图表（支持有限）
  • 使用较旧的 .xls 格式（仅支持 XLSX）
  • 需要实时协作编辑

前置条件

  • 已安装 Deno（https://deno.land/）
  • 用于基于模板操作的输入 XLSX 文件
  • 用于从头生成的 JSON 规格

快速开始

两种操作模式

  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

规格参考

工作表选项
属性类型说明
namestring工作表名称
dataarray从 A1 开始的二维单元格值数组
cellsarray单个单元格规格
rowsarray基于行的数据规格
columnsarray列宽和可见性设置
mergesarray合并单元格范围
freezePanestring在此单元格处冻结窗格（例如，“A2”）
autoFilterstring自动筛选范围（例如，“A1:F10”）
单元格选项
属性类型说明
addressstring单元格地址（例如，“A1”、“B2”）
valuemixed单元格值（字符串、数字、布尔值、null）
formulastring不带 = 符号的公式
formatstring数字格式（例如，“#,##0.00”）
typestring强制指定类型：“string”、“number”、“boolean”、“date”
列选项
属性类型说明
colstring列字母（例如，“A”、“B”、“AA”）
widthnumber以字符数表示的列宽
hiddenboolean隐藏列
模板替换选项
属性类型说明
tagstring要查找的占位符（例如，“{{TITLE}}”）
valuemixed替换值
sheetsarray限定为指定工作表
rangestring限定为单元格范围（例如，“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 数据处理

评论

支持 Markdown