Excel Chart Builder

Overview

将 Excel 表格数据一键转化为可视化图表。核心脚本 scripts/build_chart.py 读取 Excel 文件，根据图表类型与输出格式生成图表: HTML 使用 Chart.js(交互式, 支持悬停查看数值、一键下载 PNG、切换图例), PNG 使用 matplotlib(静态, 可嵌入文档/PPT)。支持 12 种图表类型、数据透视、两套配色方案。

Quick Start

确认 Python 环境已安装依赖: pandas openpyxl matplotlib
调用核心脚本生成图表:

python scripts/build_chart.py -i <Excel文件路径> -t <图表类型> -o <输出路径> -f <html|png>

图表类型(-t):
- 基础: bar(柱状) line(折线) area(面积) pie(饼图) doughnut(环形) scatter(散点)
- 扩展: hbar(水平柱状) stacked_bar(堆叠柱状) radar(雷达) polarArea(极坐标) bubble(气泡) combo(柱+线双轴)
输出格式(-f): html(交互式, 默认) 或 png(静态图片)
数据透视(--pivot): 先透视再绘图
配色方案(--palette): cn-stock(涨红跌绿, 默认) 或 vibrant(明亮风格)

图表类型选择

选择图表前参考 references/chart_guide.md 中的决策树。简要原则:

| 需求 | 图表类型 | |---|---| | 分类数值对比 | bar / hbar(类别名长时) | | 时间序列趋势 | line / area | | 构成+总量 | stacked_bar | | 占比构成 | pie / doughnut / polarArea | | 变量相关性 | scatter / bubble(三维度) | | 多维能力对比 | radar | | 量级+比率双视角 | combo(柱+线双轴) |

使用流程

步骤 1: 读取 Excel 并了解数据结构

读取用户提供的 Excel 文件, 确认列名与数据类型。默认 X 轴取第一列(类别/时间), Y 轴取其余数值列。

步骤 2: 确定图表类型与输出格式

根据用户意图选择:

"对比/排名" → bar (类别名长用 hbar)
"趋势/走势/变化" → line
"累积/总量构成" → stacked_bar 或 area
"占比/比例/构成" → pie / doughnut / polarArea
"关系/相关" → scatter (三维度用 bubble)
"能力/多维评估" → radar
"既要看量级又要看比率" → combo
要插入文档/PPT → png; 要在浏览器查看/分享 → html

步骤 3: 选择配色方案

| 方案 | 参数 | 适用场景 | 色彩特征 | |---|---|---|---| | 涨红跌绿 | --palette cn-stock(默认) | 金融、财报、股市数据 | 红=正向/涨, 绿=负向/跌 | | 明亮风格 | --palette vibrant | 演示、报告、PPT、数据看板 | 高饱和度, 视觉冲击力强 |

步骤 4: 是否需要数据透视

如果用户想"按某列分组汇总""交叉分析""各部门各月份"等, 用 --pivot 先透视再绘图:

# 二维透视: 行=部门, 列=月份, 值=营收求和
python scripts/build_chart.py -i data.xlsx \
    --pivot "rows=部门,cols=月份,values=营收,agg=sum" \
    -t bar -o pivot.html -f html --title "各部门各月营收"

# 一维聚合: 行=部门, 值=营收求和
python scripts/build_chart.py -i data.xlsx \
    --pivot "rows=部门,values=营收,agg=sum" \
    -t bar -o sum.html -f html --title "各部门营收汇总"

agg 可选: sum(默认) / mean / count / min / max。

步骤 5: 执行脚本生成图表

# 堆叠柱状图 (看构成+总量) - 明亮风格
python scripts/build_chart.py -i data.xlsx -t stacked_bar -o stacked.html -f html \
    --palette vibrant --title "各季度成本构成"

# 雷达图 (多维能力对比)
python scripts/build_chart.py -i scores.xlsx -t radar -o radar.html -f html \
    --title "员工能力评估"

# 柱+线组合双轴 (量级+比率)
python scripts/build_chart.py -i data.xlsx -t combo -o combo.html -f html \
    --y "营收,利润率" --palette vibrant --title "营收与利润率"

步骤 6: 交付结果

HTML 输出: 用浏览器打开预览, 或用 present_files 展示给用户。页面内置「下载 PNG」和「切换图例」按钮
PNG 输出: 告知用户文件路径, 可嵌入文档/PPT

参数说明

| 参数 | 说明 | 默认值 | |---|---|---| | -i/--input | Excel 文件路径(必填) | - | | -t/--type | 图表类型 | bar | | -f/--format | 输出格式 html/png | html | | -o/--output | 输出文件路径(必填) | - | | -s/--sheet | 工作表名 | 第一个工作表 | | --palette | 配色方案 cn-stock/vibrant | cn-stock | | -x | X 轴列名 | 第一列 | | -y | Y 轴列名, 多列逗号分隔 | 其余数值列 | | --pivot | 数据透视 rows=X,cols=Y,values=Z,agg=sum | 无 | | --title | 图表标题 | 无 | | --x-title | X 轴标题 | 无 | | --y-title | Y 轴标题 | 无 |

combo 类型提示: 用 --y "A,B" 指定两列, 第一列画柱(左轴), 第二列画线(右轴), 适合"量级+比率"双视角。

配色方案

cn-stock (默认 - 涨红跌绿)

遵循中国股市与金融数据惯例, 适合财报、股市、金融数据:

涨/正向/增长: 红色 #E53935
跌/负向/下降: 绿色 #43A047
中性/基准: 蓝色 #1E88E5
多系列: 蓝/红/绿/橙/紫/青/棕/深紫循环

vibrant (明亮风格)

高饱和度配色, 视觉冲击力强, 适合演示报告、PPT、数据看板:

亮橙 #FF6B35 / 青绿 #00C9A7 / 品紫 #C03BD1 / 金黄 #FFD23F
紫罗兰 #845EC2 / 天蓝 #00B8EE / 珊瑚红 #FF5E78 / 柠檬绿 #9BE564

详细色板与选择建议见 references/chart_guide.md。

HTML 交互功能

生成的 HTML 图表内置以下交互(无需额外配置):

悬停查看数值: 鼠标移到数据点显示精确数值
下载 PNG: 点击右上角「下载 PNG」按钮, 一键导出当前图表为 PNG 图片
切换图例: 点击「切换图例」按钮, 显示/隐藏图例区域
响应式: 自适应窗口大小, 移动端友好

Resources

scripts/

build_chart.py — 核心脚本, 读取 Excel 并生成 HTML 或 PNG 图表。支持 12 种图表类型、数据透视、两套配色方案, 可直接执行, 参数见上表。

references/

chart_guide.md — 图表类型选择决策树、配色方案对比、数据格式要求、数据透视用法与示例。在需要判断用哪种图表或确认配色时加载。

assets/

chart_template.html — Chart.js 的 HTML 骨架模板, 含响应式布局、悬停提示、下载 PNG 与切换图例按钮。生成 HTML 时由脚本读取并注入数据, 无需手动编辑。

依赖

执行脚本前确保 Python 环境已安装:

pandas  openpyxl  matplotlib

安装命令:

pip install pandas openpyxl matplotlib