---
name: component-chart
description: Chart component - types, data format, colors, barDirection, grouping
---
# Chart 组件规范
Chart 组件用于在 PPT 中嵌入数据图表，适合展示：趋势（折线/面积）、对比（柱/条）、占比（饼/圆环）。
> 继承关系：`Chart` 继承自 `Box`，完整兼容 `Box` 的 `style` 属性，可直接设置宽高、背景、边距、阴影等样式。
## 1) 快速使用（推荐写法）
> 推荐：让 `Chart` 直接参与父级布局，宽度可依赖父容器（默认 `width: '100%'`），只需通过 `style.height` 或 `style.flex`（如 `flex: 1`, `minHeight`）保证垂直空间，否则无法撑满。
```jsx
```
## 2) 支持的图表类型
- 柱状/条形：`barChart`, `bar3dChart`
- `barDirection: 'bar' | 'column'`（默认 `column`）
- **注意**: `'bar'` 表示横向条形图，`'column'` 表示纵向柱形图（不要使用 `'horizontal'` 或 `'vertical'`）
- 折线/面积：`lineChart`, `areaChart`
- 支持 `grouping='stacked'`（面积/柱状常用）
- 饼图/圆环：`pieChart`, `doughnutChart`
- **仅支持单系列数据**（两列：类别 + 数值）
## 3) 数据格式（必须遵守）
- `data` 为二维数组
- 第 1 行：表头（第一列是分类名，其余列为系列名）
- 后续行：数据行（第一列为分类值，其余列为数值）
- **数值必须是 `number`，不要用字符串**（例如 `120` 而不是 `'120'`）
基础格式：
```jsx
[
['类别名', '系列1', '系列2'],
['分类1', 10, 20],
['分类2', 15, 18],
];
```
饼图/圆环（单系列）格式：
```jsx
[
['类别', '占比'],
['产品A', 35],
['产品B', 25],
['产品C', 20],
['产品D', 15],
['其他', 5],
];
```
## 4) 颜色与背景（纯色 / 渐变）
- `colors: string[]`：系列配色（可纯色、可渐变）
- `background: string`：图表背景（可纯色、可渐变）
- `titleColor / legendColor / axisColor / dataLabelColor`：**文本颜色只支持纯色**
支持的渐变语法（CSS 字符串）：
```txt
linear-gradient(90deg, #起始颜色 0%, #结束颜色 100%)
radial-gradient(circle, #起始颜色 0%, #结束颜色 100%)
```
混合纯色与渐变示例：
```jsx
```
## 5) 属性说明
| 属性 | 类型 | 必需 | 说明 |
| ---------------- | ---------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `chartType` | `string` | ✅ | 图表类型（小驼峰字符串，如 `barChart`） |
| `data` | `any[]` | ✅ | 二维数组数据（数值必须为 `number`） |
| `style` | `object` | ✅ | 必填。可继承 `Box` 的所有样式；宽度可依赖父容器（默认 `100%`），但必须提供高度（`height`）或 `flex`/`minHeight` 等设置来撑满垂直空间 |
| `title` | `string` | ❌ | 标题 |
| `colors` | `string[]` | ❌ | 系列配色（纯色或渐变） |
| `background` | `string` | ❌ | 背景（纯色或渐变） |
| `showLegend` | `boolean` | ❌ | 是否显示图例（默认 `true`） |
| `showDataLabels` | `boolean` | ❌ | 是否显示数据标签（默认 `false`） |
| `titleColor` | `string` | ❌ | 标题文本颜色（纯色） |
| `legendColor` | `string` | ❌ | 图例文本颜色（纯色） |
| `axisColor` | `string` | ❌ | 坐标轴文本颜色（纯色） |
| `dataLabelColor` | `string` | ❌ | 数据标签颜色（纯色） |
| `grouping` | `string` | ❌ | 分组方式：`clustered \| stacked \| percentStacked \| standard` |
| `barDirection` | `string` | ❌ | 柱状方向：`'bar'`（横向） \| `'column'`（纵向，默认）。**不要使用** `'horizontal'` 或 `'vertical'` |
`grouping` 取值说明：
```js
'clustered'; // 簇状图：多系列并排显示，柱子之间有间隙
'stacked'; // 堆积图：多系列堆叠显示，显示绝对值总和
'percentStacked'; // 百分比堆积图：多系列堆叠显示，显示百分比（总和100%）
'standard'; // 标准图：用于折线图等
```
**注意拼写**：是 `percentStacked` (有字母 r)，不是 `precentStacked`
`barDirection` 取值示例：
```js
'bar'; // 横向条形图
'column'; // 纵向柱形图（默认）
// ❌ 不要使用: 'horizontal', 'vertical'
```
## 6) 常见场景怎么选
| 场景 | 推荐图表 | 说明 |
| ------------- | ------------------------------------- | -------------------------------- |
| 数据对比 | 柱状/条形（`barChart`） | 适合多类别横向比较 |
| 趋势展示 | 折线（`lineChart`） | 时间序列/趋势最清晰 |
| 数量变化/构成 | 面积（`areaChart`） | 强调累积与变化幅度；可 `stacked` |
| 占比分析 | 饼/圆环（`pieChart`/`doughnutChart`） | 单系列、占比表达直观 |
| 精确数值清单 | Table（不建议用图表） | 静态明细更适合表格 |
## 7) 代表性示例
### A. 折线趋势
```jsx
```
### B. 堆积面积图（产品构成）
```jsx
```
### C. 横向条形对比（`barDirection='bar'`）
```jsx
```
### D. 饼图占比（单系列 + 渐变背景）
```jsx
```
## 8) 最佳实践
1. **尺寸**：`Chart` 默认横向拉伸，可省略宽度；务必提供 `style.height` 或 `style.flex`（如 `flex: 1` + `minHeight`），否则高度为 0。
2. **数据类型**：所有数值必须为 `number`。
3. **饼/圆环限制**：仅支持单系列（两列）。
4. **颜色策略**：`colors/background` 可渐变；文本色（`titleColor/legendColor/axisColor/dataLabelColor`）仅纯色。
5. **可读性**：`axisColor` 建议中性灰（如 `#999999` / `#9ca3af`），避免喧宾夺主；`dataLabelColor` 确保与背景对比足够。
6. **选型**：趋势用折线，构成用堆积面积或堆积柱，对比用柱/条，占比用饼/圆环；静态明细优先 Table。