excel-report-generator

name	excel-report-generator
description	Automatically generate Excel reports from data sources including CSV, databases, or Python data structures. Supports data analysis reports, business reports, data export, and template-based report generation using pandas and openpyxl. Activate when users mention Excel, spreadsheet, report generation, data export, or business reporting.

Excel Report Generator

自动化 Excel 报表生成工具，支持从多种数据源生成专业的 Excel 报告。

功能概述

这个 Skill 可以帮助你：

• 📊 从 CSV、数据库或 Python 数据结构生成 Excel 报表
• 📈 创建包含图表、格式化和公式的数据分析报告
• 📋 基于模板填充数据生成业务报告
• 💾 将系统数据批量导出为格式化的 Excel 文件
• 🎨 应用专业的样式、颜色和条件格式

核心技术栈

• pandas: 数据处理和分析
• openpyxl: Excel 文件读写和格式化
• xlsxwriter: 高级图表和格式支持（可选）

使用场景

1. 数据分析报表

从原始数据生成包含统计分析、透视表和可视化图表的综合报告。

示例请求:

• "帮我从这个 CSV 生成销售分析报表"
• "创建一个包含月度趋势图的数据分析 Excel"
• "生成带有统计汇总的财务报表"

2. 业务报告

定期生成标准化的业务报告，如销售报告、KPI 仪表板等。

示例请求:

• "生成本月的销售业绩报告"
• "创建 KPI 跟踪报表"
• "导出季度业务总结 Excel"

3. 数据导出

将数据库查询结果或系统数据导出为格式化的 Excel 文件。

示例请求:

• "把用户数据导出到 Excel"
• "将数据库查询结果保存为 Excel 文件"
• "导出多个工作表的数据集"

4. 模板填充

基于预定义的 Excel 模板填充动态数据。

示例请求:

• "使用这个模板生成报告"
• "填充 Excel 模板中的数据"
• "批量生成基于模板的发票"

使用方法

基本工作流程

1. 准备数据源: CSV 文件、pandas DataFrame、数据库连接或 Python 字典
2. 定义报表需求: 描述所需的格式、图表、样式
3. 生成报表: 自动创建格式化的 Excel 文件
4. 验证输出: 检查生成的文件是否符合要求

命令示例

从 CSV 生成报表:

请从 sales_data.csv 生成一个销售分析报表，包含：
- 按产品分类的销售汇总
- 月度销售趋势图
- Top 10 产品排名

从 DataFrame 生成报表:

我有一个 pandas DataFrame，帮我生成 Excel 报表，包括：
- 数据透视表
- 条件格式高亮异常值
- 自动筛选和冻结首行

使用模板:

基于 templates/monthly_report.xlsx 模板，填充当月数据并生成报告

实现指南

当用户请求生成 Excel 报表时，遵循以下步骤：

Step 1: 数据准备

import pandas as pd
from openpyxl import load_workbook
from openpyxl.styles import Font, PatternFill, Alignment
from openpyxl.utils.dataframe import dataframe_to_rows

# 读取数据
df = pd.read_csv('data.csv')
# 或从数据库
# df = pd.read_sql(query, connection)

Step 2: 数据处理

# 数据清洗和转换
df_clean = df.dropna()

# 统计分析
summary = df.groupby('category').agg({
    'sales': ['sum', 'mean', 'count'],
    'profit': 'sum'
})

Step 3: 创建 Excel 文件

# 使用 pandas ExcelWriter
with pd.ExcelWriter('output.xlsx', engine='openpyxl') as writer:
    # 写入原始数据
    df_clean.to_excel(writer, sheet_name='Raw Data', index=False)

    # 写入汇总数据
    summary.to_excel(writer, sheet_name='Summary')

    # 获取 workbook 进行格式化
    workbook = writer.book
    worksheet = writer.sheets['Summary']

Step 4: 格式化和样式

# 标题样式
header_font = Font(bold=True, color='FFFFFF')
header_fill = PatternFill(start_color='4472C4', end_color='4472C4', fill_type='solid')

# 应用样式到标题行
for cell in worksheet[1]:
    cell.font = header_font
    cell.fill = header_fill
    cell.alignment = Alignment(horizontal='center')

# 列宽自动调整
for column in worksheet.columns:
    max_length = 0
    column_letter = column[0].column_letter
    for cell in column:
        if len(str(cell.value)) > max_length:
            max_length = len(str(cell.value))
    worksheet.column_dimensions[column_letter].width = max_length + 2

Step 5: 添加图表（可选）

from openpyxl.chart import BarChart, Reference

# 创建图表
chart = BarChart()
chart.title = "Sales by Category"
chart.x_axis.title = "Category"
chart.y_axis.title = "Sales"

# 数据引用
data = Reference(worksheet, min_col=2, min_row=1, max_row=10)
categories = Reference(worksheet, min_col=1, min_row=2, max_row=10)

chart.add_data(data, titles_from_data=True)
chart.set_categories(categories)

# 添加到工作表
worksheet.add_chart(chart, "E5")

高级功能

条件格式

from openpyxl.formatting.rule import ColorScaleRule, CellIsRule

# 色阶格式
worksheet.conditional_formatting.add(
    'B2:B100',
    ColorScaleRule(start_type='min', start_color='FF6347',
                   mid_type='percentile', mid_value=50, mid_color='FFFF00',
                   end_type='max', end_color='90EE90')
)

# 基于规则的格式
red_fill = PatternFill(start_color='FFC7CE', end_color='FFC7CE', fill_type='solid')
worksheet.conditional_formatting.add(
    'C2:C100',
    CellIsRule(operator='lessThan', formula=['0'], fill=red_fill)
)

数据验证

from openpyxl.worksheet.datavalidation import DataValidation

# 下拉列表
dv = DataValidation(type="list", formula1='"优秀,良好,一般,较差"', allow_blank=True)
worksheet.add_data_validation(dv)
dv.add('D2:D100')

公式应用

# 添加求和公式
worksheet['B11'] = '=SUM(B2:B10)'

# 添加平均值公式
worksheet['C11'] = '=AVERAGE(C2:C10)'

最佳实践

1. 性能优化

• 对于大数据集（>10万行），使用 openpyxl 的 write_only 模式
• 分批处理数据，避免内存溢出
• 使用 xlsxwriter 引擎处理复杂图表和格式

2. 错误处理

try:
    df = pd.read_csv('data.csv')
except FileNotFoundError:
    print("数据文件不存在")
except pd.errors.EmptyDataError:
    print("数据文件为空")

3. 文件命名规范

from datetime import datetime

# 使用时间戳避免文件覆盖
timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
filename = f'sales_report_{timestamp}.xlsx'

4. 数据验证

# 检查必需列
required_columns = ['date', 'product', 'sales']
if not all(col in df.columns for col in required_columns):
    raise ValueError(f"缺少必需列: {required_columns}")

# 数据类型验证
df['date'] = pd.to_datetime(df['date'])
df['sales'] = pd.to_numeric(df['sales'], errors='coerce')

5. 模板管理

• 将常用模板存放在 ~/.claude/skills/excel-report-generator/templates/ 目录
• 使用相对路径引用: templates/monthly_report.xlsx
• 保持模板简洁，只包含结构和样式，不包含数据

快速参考

常用代码片段

查看 examples/quick_reference.py 获取常用代码片段，包括：

• 基本 Excel 创建
• 多工作表管理
• 样式和格式化
• 图表创建
• 条件格式
• 公式应用

示例文件

• examples/basic_report.py - 基础报表生成示例
• examples/advanced_report.py - 高级功能示例
• examples/template_fill.py - 模板填充示例
• templates/business_report.xlsx - 业务报告模板
• templates/data_analysis.xlsx - 数据分析模板

依赖安装

确保已安装必需的 Python 包：

pip install pandas openpyxl xlsxwriter

可选依赖：

pip install matplotlib seaborn  # 用于数据可视化
pip install sqlalchemy pymysql  # 用于数据库连接

故障排查

常见问题

Q: 生成的 Excel 文件无法打开 A: 确保使用 .xlsx 扩展名，检查文件权限，验证数据中没有非法字符

Q: 图表不显示 A: 检查数据引用范围是否正确，确保数据类型为数值型

Q: 中文乱码 A: 使用 encoding='utf-8-sig' 读取 CSV，或在 Excel 中使用 UTF-8 编码

Q: 大文件生成很慢 A: 使用 write_only=True 模式，减少格式化操作，分批写入数据

相关资源

• pandas 官方文档
• openpyxl 官方文档
• xlsxwriter 官方文档
• 查看 REFERENCE.md 获取详细 API 参考

版本历史

• v1.0.0 (2025-01-12) - 初始版本，支持基础报表生成和模板填充