chartjs-generator

Chart.js 生成器

概述

此技能使用 Chart.js 生成专业的交互式图表，支持所有主要图表类型。Chart.js 是一个功能强大、灵活的 JavaScript 库，可用于创建响应式数据可视化。此技能会创建完整的 MicroSim 软件包，适用于嵌入使用 MkDocs 构建的教育内容或文档网站。在智能书籍中，默认通过 iframe 嵌入，并采用最小内边距和外边距。 请勿在图表区域上方或下方添加任何分析内容或辅助文档。

支持的图表类型

Chart.js 支持以下图表类型：

1. 折线图 - 时间序列、趋势、连续数据
2. 条形图 - 比较、分类数据、横向或纵向
3. 饼图 - 占比、百分比、部分与整体的关系
4. 圆环图 - 与饼图类似，但中心区域可用于放置标签
5. 雷达图 - 多维数据、蜘蛛网图
6. 极区图 - 与饼图类似，但半径各异
7. 气泡图 - 三维数据（x、y、大小）
8. 散点图 - 相关性、分布、关系

何时使用此技能

当用户请求以下内容时，请使用此技能：

• 数据可视化：用于展示数据的任何图表或图形
• 比较：条形图、分组条形图、堆叠条形图
• 趋势：折线图、面积图、多折线图
• 占比：饼图、圆环图
• 分布：散点图、气泡图
• 多维数据：雷达图、气泡图
• 交互式图表：悬停提示、可点击元素、动画

常见触发语句：

• “创建一个展示……的[图表类型]……”
• “将[数据]可视化为[图表类型]……”
• “构建一个用于……的交互式图表”
• “生成一个展示……的图表”

工作流

第 1 步：确定图表类型

如果用户没有指定图表类型，请让他们从支持的类型中选择：

使用 AskUserQuestion 工具，并提供以下选项：

1. 折线图 - 最适合展示随时间变化的趋势和连续数据
2. 条形图 - 最适合比较类别和离散数据
3. 饼图/圆环图 - 最适合展示占比和百分比
4. 气泡图/散点图 - 最适合展示多维数据或相关性数据
5. 雷达图 - 最适合比较不同类别中的多个变量
6. 极区图 - 最适合突出差异的占比展示

第 2 步：收集数据和需求

生成图表前，请收集以下信息：

1. 数据结构：需要可视化哪些数据？

   • 数据点/数值
   • 标签/类别
   • 多个数据集（如适用）
   • 时间段或类别
   • 计量单位

2. 图表配置：

   • 图表标题
   • 坐标轴标签（用于条形图、折线图、散点图、气泡图）
   • 图例要求
   • 配色方案偏好
   • 特殊功能（堆叠、分组、填充区域等）

3. 上下文：可视化的用途是什么？

   • 教育内容
   • 数据分析
   • 报告或演示文稿
   • 仪表板组件

4. 集成方式：图表将用于何处？

   • 独立页面
   • 嵌入文档
   • 集成到 MkDocs 网站

第 3 步：创建目录结构

按照以下模式为 MicroSim 创建新目录：

docs/sims/<chart-name>/
├── main.html         # Main visualization file
├── style.css         # Styling
└── index.md          # Documentation (if part of MkDocs)

命名规范：目录名称使用 kebab-case（小写字母并以连字符分隔），做到描述清晰且适合 URL（例如：sales-trend-chart、market-share-pie、student-performance-radar）。

第 4 步：使用 Chart.js 创建 main.html

按照以下结构生成主 HTML 文件：

1. HTML 基本模板，包含适当的元标签
2. Chart.js CDN 导入：https://cdn.jsdelivr.net/npm/[email protected]/dist/chart.umd.min.js
3. 图表用的 Canvas 元素
4. 可选的分析／图例区域，除非有要求，否则不要添加任何分析或文档
5. JavaScript 实现：
   • 数据数组／对象
   • 配色方案配置
   • 所选图表类型的 Chart.js 配置
   • 自定义插件（如需要）
   • 交互功能（工具提示、图例、动画）
   • 始终使用工具提示

各类型图表的关键 Chart.js 配置：

折线图

{
    type: 'line',
    data: {
        labels: ['Jan', 'Feb', 'Mar', ...],
        datasets: [{
            label: 'Dataset 1',
            data: [12, 19, 3, 5, 2, 3],
            borderColor: 'rgb(75, 192, 192)',
            backgroundColor: 'rgba(75, 192, 192, 0.2)',
            tension: 0.1  // Curve smoothness
        }]
    },
    options: {
        responsive: true,
        scales: {
            y: { beginAtZero: true }
        }
    }
}

柱状图

{
    type: 'bar',
    data: {
        labels: ['Category A', 'Category B', ...],
        datasets: [{
            label: 'Dataset 1',
            data: [65, 59, 80, 81, 56, 55],
            backgroundColor: 'rgba(54, 162, 235, 0.8)',
            borderColor: 'rgb(54, 162, 235)',
            borderWidth: 1
        }]
    },
    options: {
        responsive: true,
        scales: {
            y: { beginAtZero: true }
        }
    }
}

饼图／圆环图

{
    type: 'pie',  // or 'doughnut'
    data: {
        labels: ['Red', 'Blue', 'Yellow', ...],
        datasets: [{
            data: [300, 50, 100],
            backgroundColor: [
                'rgba(255, 99, 132, 0.8)',
                'rgba(54, 162, 235, 0.8)',
                'rgba(255, 206, 86, 0.8)'
            ]
        }]
    },
    options: {
        responsive: true,
        plugins: {
            legend: { position: 'top' }
        }
    }
}

雷达图

{
    type: 'radar',
    data: {
        labels: ['Strength', 'Speed', 'Intelligence', ...],
        datasets: [{
            label: 'Player 1',
            data: [65, 59, 90, 81, 56],
            backgroundColor: 'rgba(255, 99, 132, 0.2)',
            borderColor: 'rgb(255, 99, 132)',
            pointBackgroundColor: 'rgb(255, 99, 132)'
        }]
    },
    options: {
        responsive: true,
        scales: {
            r: {
                beginAtZero: true,
                max: 100
            }
        }
    }
}

气泡图

{
    type: 'bubble',
    data: {
        datasets: [{
            label: 'Dataset 1',
            data: [
                { x: 20, y: 30, r: 15 },  // r = bubble radius
                { x: 40, y: 10, r: 10 }
            ],
            backgroundColor: 'rgba(255, 99, 132, 0.8)'
        }]
    },
    options: {
        responsive: true,
        scales: {
            x: { min: 0, max: 100 },
            y: { min: 0, max: 100 }
        }
    }
}

散点图

{
    type: 'scatter',
    data: {
        datasets: [{
            label: 'Dataset 1',
            data: [
                { x: -10, y: 0 },
                { x: 0, y: 10 },
                { x: 10, y: 5 }
            ],
            backgroundColor: 'rgba(255, 99, 132, 0.8)'
        }]
    },
    options: {
        responsive: true,
        scales: {
            x: { type: 'linear', position: 'bottom' }
        }
    }
}

重要注意事项：

• 响应式设计：设置 responsive: true 并指定合适的纵横比
• 颜色可访问性：使用易于区分且对比度良好的颜色
• 工具提示：自定义工具提示，以显示相关信息
• 图例：将图例放置在合适的位置（top、bottom、left、right）
• 动画：根据使用场景启用或禁用
• 数据标签：如有需要，使用 Chart.js 插件显示数据标签

第 5 步：创建 style.css

生成具有专业样式的 CSS：

1. 重置和基础样式：设置简洁的默认样式，确保跨浏览器一致性
2. 图表容器：设置合适的尺寸、内边距和阴影
3. 图例／分析容器：为补充信息设置样式
4. 交互元素：悬停效果、过渡效果
5. 响应式设计：为手机／平板设备添加媒体查询
6. 打印样式：不要添加额外的打印 CSS

关键设计原则：

• 采用简洁、现代的美学风格
• 假设图表通过 iframe 放置在一本页边距较窄的书中
• 提供清晰的视觉层次
• 添加细微的阴影和边框
• 添加平滑的过渡效果
• 确保对比度充足，满足无障碍要求
• 确保文本在所有尺寸下都清晰易读

第 6 步：创建 index.md 文档

如果图表属于 MkDocs 站点，请创建完整的文档：

1. YML 元数据：添加标题和描述
2. 标题和概述：简要描述该可视化内容
3. 嵌入式 iframe：在页面内显示图表
4. 全屏链接：添加指向 main.html 的 Markdown 链接，按钮文字为“全屏查看 MicroSim”
5. 解读指南：说明如何阅读图表
6. 功能部分：列出交互元素
7. 自定义指南：详细说明如何修改：
   • 数据结构
   • 颜色和样式
   • 图表选项
   • 响应行为
   • 动画
8. 技术细节：依赖项、浏览器兼容性、文件结构
9. 使用场景：此图表类型的其他应用
10. 参考资料：Chart.js 文档和相关资源的链接

文档结构模板：

---
title: [Chart Title]
description: [brief description of chart]
---

# [Chart Title]

[Brief description]

## Interactive Chart

<iframe src="main.html" width="100%" height="500" scrolling="no"></iframe>

[View Fullscreen](main.html){ .md-button .md-button--primary }

## Overview

[Detailed explanation of what the chart shows]

## Features

### Interactive Elements
- Hover tooltips showing detailed data
- Clickable legend items to show/hide datasets
- Smooth animations on load and update

### Visual Design
- Color-coded categories
- Clear axis labels and grid lines
- Responsive layout

## Customization Guide

### Changing the Data

To modify the chart data, edit the `data` object in `main.html`:

```javascript
const data = {
    labels: ['Your', 'Labels', 'Here'],
    datasets: [{
        label: 'Your Dataset',
        data: [10, 20, 30, 40]
    }]
};

调整颜色

通过修改 backgroundColor 和 borderColor 属性来自定义配色方案：

backgroundColor: [
    'rgba(255, 99, 132, 0.8)',
    'rgba(54, 162, 235, 0.8)',
    // Add more colors...
]

图表选项

在 options 对象中修改图表行为：

options: {
    responsive: true,
    maintainAspectRatio: true,
    aspectRatio: 2,  // Width:height ratio
    plugins: {
        title: { display: true, text: 'Your Title' },
        legend: { position: 'top' }
    }
}

技术细节

• 库：Chart.js 4.4.0
• 浏览器兼容性：所有现代浏览器（Chrome、Firefox、Safari、Edge）
• 依赖项：Chart.js（从 CDN 加载）
• 响应式：是，可适应容器宽度

使用场景

此图表类型适用于：

• [列出相关使用场景]

参考资料

- [Chart.js Documentation](https://www.chartjs.org/docs/latest/)
- [Chart Type Guide](https://www.chartjs.org/docs/latest/charts/[type].html)

第 7 步：集成到导航中（MkDocs）

始终将图表添加到 mkdocs.yml 的导航中：

- MicroSims:
    - Introduction: sims/index.md
    - [Chart Name]: sims/[chart-name]/index.md
    - [Other sims...]: ...

按字母顺序排列该条目。

步骤 8：测试和验证

在认为图表已完成之前：

1. 视觉测试：

   • 直接在浏览器中打开 main.html
   • 如适用，使用 mkdocs serve 进行测试
   • 检查所有断点（桌面、平板、移动设备）
   • 验证数据显示是否正确
   • 确认标签和图例清晰易读

2. 交互测试：

   • 将鼠标悬停在图表元素上，验证工具提示
   • 点击图例项以显示/隐藏数据集
   • 测试动画（重新加载页面）
   • 在不同浏览器上测试

3. 文档审查：

   • 验证所有代码示例是否准确
   • 测试自定义说明
   • 检查所有内部和外部链接

4. 数据验证：

   • 确认所有数据点均已正确绘制
   • 如适用，验证计算结果
   • 检查图表是否准确反映数据

最佳实践

数据准备

1. 格式一致：使用一致的数据类型和格式
2. 标签含义明确：使用清晰且具有描述性的标签
3. 刻度适当：选择能有效展示数据的刻度
4. 数据完整：确保包含所有必需字段

视觉设计

1. 颜色编码：使用直观且易于识别的配色方案
2. 对比度：确保对比度足够，便于阅读
3. 标签：确保不同尺寸下的所有文本都清晰可读
4. 间距：通过适当的内边距避免重叠
5. 一致性：在各图表中使用一致的样式

文档

1. 代码示例：提供准确且可测试的代码片段
2. 修改前后：展示自定义设置的效果
3. 参数范围：建议适当的取值范围
4. 常见问题：说明典型问题及其解决方法

MkDocs 集成

1. Iframe 尺寸：根据图表类型设置合适的高度（通常为 500-900px）
2. 路径引用：使用相对路径（../sims/...）
3. 导航位置：与相关的 MicroSims 放在一起
4. 响应式嵌入：确保 iframe 具有响应式布局

图表类型选择指南

帮助用户选择合适的图表类型：

图表类型	最适合	不适合
折线图	随时间变化的趋势、连续数据	类别比较
条形图	比较类别、离散数据	趋势、连续数据
饼图/圆环图	整体与部分、比例（≤6 个扇区）	精确比较、类别过多
雷达图	比较多个变量、展示轮廓	单一变量、连续数据
极区图	强调差异的比例展示	精确比较
气泡图	三个维度（x、y、大小）	简单的一维或二维数据
散点图	相关性、分布	类别数据

常见变体

堆叠条形图

options: {
    scales: {
        x: { stacked: true },
        y: { stacked: true }
    }
}

水平条形图

{
    type: 'bar',
    options: {
        indexAxis: 'y'  // Makes bars horizontal
    }
}

多折线图

向折线图添加多个数据集：

data: {
    datasets: [
        { label: 'Series 1', data: [...], borderColor: 'red' },
        { label: 'Series 2', data: [...], borderColor: 'blue' }
    ]
}

填充区域图

{
    type: 'line',
    data: {
        datasets: [{
            fill: true,  // Fill area under line
            backgroundColor: 'rgba(75, 192, 192, 0.2)'
        }]
    }
}

故障排除

图表未显示

解决方案：检查 Chart.js CDN 是否正确加载，并确认 canvas 元素具有 ID。

数据未更新

解决方案：修改数据后，确保调用 chart.update()：

chart.data.datasets[0].data = newData;
chart.update();

标签重叠

解决方案：旋转标签或减小字号：

scales: {
    x: {
        ticks: {
            maxRotation: 45,
            minRotation: 45
        }
    }
}

未显示颜色

解决方案：验证颜色格式（rgba、rgb、hex），并确保数组长度与数据长度一致。

响应式问题

解决方案：设置容器尺寸并使用 maintainAspectRatio：

options: {
    responsive: true,
    maintainAspectRatio: true,
    aspectRatio: 2
}

高级功能

数据标签插件

要在图表元素上显示数值，请使用 Chart.js Data Labels 插件：

<script src="https://cdn.jsdelivr.net/npm/chartjs-plugin-datalabels@2"></script>

动画

自定义动画时间和缓动效果：

options: {
    animation: {
        duration: 2000,
        easing: 'easeInOutQuart'
    }
}

自定义工具提示

创建完全自定义的工具提示内容：

plugins: {
    tooltip: {
        callbacks: {
            label: function(context) {
                return 'Custom: ' + context.parsed.y;
            }
        }
    }
}

点击事件

处理图表元素上的点击事件：

options: {
    onClick: (event, elements) => {
        if (elements.length > 0) {
            const dataIndex = elements[0].index;
            console.log('Clicked:', chart.data.labels[dataIndex]);
        }
    }
}

参考资料

此技能使用以下资源和参考资料：

资源

• Chart.js CDN：https://cdn.jsdelivr.net/npm/[email protected]/dist/chart.umd.min.js
• 可选的数据标签插件：https://cdn.jsdelivr.net/npm/chartjs-plugin-datalabels@2
• 无需本地资源（Chart.js 从 CDN 加载）

参考资料

• Chart.js 文档
• Chart.js 示例
• Chart.js GitHub
• 图表类型指南

示例实现

请参阅 /docs/sims/ 目录中的示例图表，了解不同图表类型的实现。