chartjs-reporter — Chart.js HTML 嵌入片段生成技能

技能目的

将结构化数据（SQL 查询结果、CSV 摘要、Python dict/list、手动提供的表格）转换为 嵌入用 HTML 片段，内嵌 Chart.js 图表和 KPI 卡片，不含完整 HTML 文档壳。 Host 页面需自行引入 Chart.js CDN 及本片段所需的 CSS 类。

触发条件

以下任意一种情况触发本技能：

用户提供了数据并要求"出图"、"可视化"、"生成报告"
用户已有 DuckDB / SQL / pandas 查询结果，需要图表化展示
用户指定了图表类型（饼图、柱状图、折线图等）+ 数据
与 chat2duckdb 技能配合：查询完成后生成可视化片段

操作步骤

步骤 1：理解数据结构

收到数据后，确认以下信息：

数据形态：数值列 / 分类列 / 时间列
分析目的：占比 / 趋势 / 对比 / 排名
期望图表类型（用户未指定时，按照「图表选型规则」自动选择）

步骤 2：选择图表类型

| 分析目的 | 推荐图表 | |---------|---------| | 占比 / 构成 | doughnut（≤6类）/ pie | | 趋势 / 时间序列 | line（fill: true 显示面积） | | 分类对比（≤8项） | bar（垂直） | | 分类对比（>8项或标签长） | bar（水平，indexAxis: 'y'） | | 多指标对比 | 分组 bar | | 排名 Top N | 水平 bar + 进度条 | | 关键指标摘要 | KPI 卡片（非图表） |

步骤 3：调用生成脚本

使用 scripts/generate_report.py 生成 HTML 嵌入片段：

python scripts/generate_report.py \
  --title "报告标题" \
  --subtitle "副标题说明" \
  --data '{"charts": [...], "kpis": [...]}' \
  --output embed.html

也可以直接在 Python 中调用（适合与 chat2duckdb 配合）：

from scripts.generate_report import build_report
html = build_report(title, subtitle, kpis, charts)
# 将 html 嵌入到 host 页面的容器中

步骤 4：数据格式规范

kpis 列表（可选，顶部 KPI 卡片）：

[
  {"label": "总营收", "value": "¥1,755,905", "sub": "全年累计", "color": "blue"},
  {"label": "订单数", "value": "200",         "sub": "5 品类",  "color": "green"}
]

color 可选值：blue | green | yellow | purple | red

charts 列表（图表配置）：

[
  {
    "type": "doughnut",
    "title": "品类营收占比",
    "labels": ["Food", "Electronics", "Sports"],
    "datasets": [{"data": [456833, 351665, 349967]}]
  },
  {
    "type": "line",
    "title": "月度趋势",
    "labels": ["1月","2月","3月"],
    "datasets": [{"label": "营收", "data": [158495, 185560, 98369]}]
  }
]

支持的 type 值：bar | line | doughnut | pie | horizontalBar（自动转 bar + indexAxis:y）

步骤 5：Host 页面引入

<!-- 1. 引入 Chart.js CDN -->
<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js"></script>

<!-- 2. 嵌入生成的 HTML 片段 -->
<div id="my-report"></div>
<script>
  document.getElementById('my-report').innerHTML = '...生成的 embed.html 内容...';
</script>

步骤 6：布局规则

KPI 卡片行：最多 4 列，超出自动换行
图表区：默认 2 列网格；1 个图表时全宽；3 个图表时 3 列
每张图表高度固定 240px，响应式宽度
表格（Top N 排名）：单独一行，全宽显示
页脚：说明数据来源和生成时间

CSS 类说明

嵌入片段使用的 CSS 类，Host 页面需确保可用（可从 template2.html 中提取）：

| 类名 | 说明 | |------|------| | .report-embed | 外层容器 | | .doc-header | 渐变蓝色标题区（背景 #0B3D6E → #1565A8） | | .kpi-row | KPI 卡片网格 | | .kpi-card | 单个 KPI 卡片（白底圆角） | | .chart-card | 单张图表卡片（白底圆角） | | .charts-grid | 图表网格布局 | | .table-card | 表格卡片 | | footer | 页脚 |

与 chat2duckdb 配合的标准流程

1. chat2duckdb 执行 SQL 查询 → 得到 DataFrame / 字典结果
2. chartjs-reporter 将结果转换为图表配置 JSON
3. 调用 generate_report.py 生成 HTML 嵌入片段
4. 将片段注入到 host 页面的容器中

参考资源

核心脚本：scripts/generate_report.py
图表配置参考：references/chart-config-guide.md
样式主题参考（亮色专业风格）：references/template2.html

注意事项

报告为亮色专业主题（参考 template2.html），背景色 #f5f4f0，卡片白色，适合商务展示
不包含 HTML 文档壳、Chart.js CDN 引入，由 host 页面提供
数值超过 1000 时，自动格式化为千分位（¥1,234,567）
颜色序列已内置，无需手动指定每个数据点颜色
Chart.js 版本固定为 4.4.0（CDN）
canvas ID 硬编码为 chart0、chart1……，同一页面嵌入多份时需自行替换 ID 避免冲突