chart/README.md

# @apigo.cc/chart API 手册

基于 Chart.js 4.x 的轻量级图表封装库。内置数据映射（Data Mapping）功能。

---

## 1. 引入方式 (UMD 优先)

在 HTML 中引入脚本即可，组件已内置 Chart.js，无需额外依赖。

```html
<script src="https://cdn.jsdelivr.net/npm/@apigo.cc/chart@1.0.1/dist/chart.min.js"></script>

<script>
    // 直接使用全局 DataChart 类
    const chart = new DataChart(myCanvas, config);
</script>
```

> **ESM 模式说明**：如需在模块化环境中使用，引入 `dist/chart.min.mjs`。

---

## 2. 基本用法

### 组件化用法 (推荐)
直接在 HTML 中使用 `<DataChart>` 标签，通过 `state` 进行数据绑定。

```html
<div $data="{ 
    myData: [{ month: 'Jan', sales: 120 }, { month: 'Feb', sales: 190 }],
    myMap: { labels: 'month', values: 'sales', label: '月销量' }
}">
    <DataChart type="bar" $.state.data="myData" $.state.map="myMap" style="height:300px"></DataChart>
</div>
```

### JS 调用方式 (兼容)
```html
<canvas id="myCanvas" width="400" height="200"></canvas>
...
---

## 3. API 参考

### `new DataChart(canvas, config)`
- **`canvas`**: HTMLCanvasElement。
- **`config.type`**: `'line'`, `'bar'`, `'pie'`。
- **`config.data`**: 原始对象数组。
- **`config.map`**: 映射规则。
- **`config.options`**: 透传给底层 Chart.js 的原生配置。

### 实例方法
- **`update(newData)`**: 传入新数组重绘图表。
- **`destroy()`**: 销毁实例。

---

## 开发者提示 (AI 必读)
1. **尺寸控制**: Canvas 必须具有明确的高度和宽度。
2. **全局变量**: UMD 模式下，`DataChart` 类自动挂载到 `window`。