Files
aibridge/docs/control/09-chart-controls.md
2026-05-18 09:28:15 +08:00

422 lines
8.1 KiB
Markdown

# 图表控件
## 目录
- [概述](#概述)
- [柱状图 (Bar)](#柱状图-bar)
- [横向柱状图 (BarAcross)](#横向柱状图-baracross)
- [折线面积图 (LineArea)](#折线面积图-linearea)
- [折线柱状图 (LineBar)](#折线柱状图-linebar)
- [饼图 (Pie)](#饼图-pie)
- [散点图 (Scatter)](#散点图-scatter)
- [K线图 (Candlestick)](#k线图-candlestick)
- [漏斗图 (Funnel)](#漏斗图-funnel)
- [仪表盘 (Gauge)](#仪表盘-gauge)
- [树图 (Tree)](#树图-tree)
---
## 概述
### 基本信息
JNPF 使用 **ECharts** 作为图表引擎,封装在 `@vben/plugins/echarts` 包中。
### 源码位置
```
$ccWorkDir/web/apps/jnpf-web-apps-main/src/views/extend/graphDemo/
```
### 通用引入
```typescript
import type { EchartsUIType } from '@vben/plugins/echarts';
import { EchartsUI, useEcharts } from '@vben/plugins/echarts';
const chartRef = ref<EchartsUIType>();
const { renderEcharts } = useEcharts(chartRef);
onMounted(() => {
renderEcharts(options);
});
// 模板
<EchartsUI ref="chartRef" height="500px" />
```
### 图表类型清单 (12 种)
| 类型 | 目录 | 说明 |
|------|------|------|
| 柱状图 | echartsBar | 堆叠柱状图,支持标记线 |
| 横向柱状图 | echartsBarAcross | 水平柱状图 |
| 折线面积图 | echartsLineArea | 堆叠面积图 |
| 折线柱状图 | echartsLineBar | 组合图 |
| 饼图 | echartsPie | 环形饼图 |
| 散点图 | echartsScatter | 散点分布 |
| K线图 | echartsCandlestick | 股票K线 |
| 漏斗图 | echartsFunnel | 流程漏斗 |
| 仪表盘 | echartsGauge | 多仪表盘 |
| 树图 | echartsTree | 层级树图 |
---
## 柱状图 (Bar)
### 源码位置
```
extend/graphDemo/echartsBar/index.vue
```
### 关键配置
```typescript
const options = {
tooltip: { trigger: 'axis' },
legend: { data: ['销量', '利润'] },
xAxis: { type: 'category', data: ['衬衫', '毛衣', '裤子', '袜子'] },
yAxis: { type: 'value' },
series: [
{
name: '销量',
type: 'bar',
data: [5, 20, 36, 10],
markPoint: { data: [{ type: 'max', name: '最大值' }] },
markLine: { data: [{ type: 'average', name: '平均值' }] }
}
]
};
```
### 特性
- 支持 `magicType`: 切换柱状/折线
- 支持 `markPoint`: 标记点 (最大/最小值)
- 支持 `markLine`: 标记线 (平均值)
---
## 横向柱状图 (BarAcross)
### 源码位置
```
extend/graphDemo/echartsBarAcross/index.vue
```
### 关键配置
```typescript
const options = {
tooltip: { trigger: 'axis' },
legend: { data: ['销量'] },
xAxis: { type: 'value' },
yAxis: { type: 'category', data: ['衬衫', '毛衣', '裤子', '袜子'] },
series: [{
name: '销量',
type: 'bar',
data: [5, 20, 36, 10]
}]
};
```
---
## 折线面积图 (LineArea)
### 源码位置
```
extend/graphDemo/echartsLineArea/index.vue
```
### 关键配置
```typescript
const options = {
tooltip: { trigger: 'axis' },
legend: { data: ['蒸发量', '降水量'] },
xAxis: { type: 'category', data: ['1月', '2月', '3月', '4月'], boundaryGap: false },
yAxis: { type: 'value' },
series: [
{
name: '蒸发量',
type: 'line',
data: [2.0, 4.9, 7.0, 23.2],
areaStyle: {}, // 填充面积
stack: '总量', // 堆叠
emphasis: { focus: 'series' }
}
]
};
```
### 特性
- `areaStyle`: 开启面积填充
- `stack: '总量'`: 堆叠模式
- `boundaryGap: false`: 折线连接
---
## 折线柱状图 (LineBar)
### 源码位置
```
extend/graphDemo/echartsLineBar/index.vue
```
### 关键配置
```typescript
const options = {
tooltip: { trigger: 'axis' },
legend: { data: ['蒸发量', '降水量', '平均温度'] },
xAxis: { type: 'category', data: ['1月', '2月', '3月', '4月'] },
yAxis: [
{ type: 'value', name: '水量' },
{ type: 'value', name: '温度', min: 0, max: 30 }
],
series: [
{ name: '蒸发量', type: 'bar', data: [2.0, 4.9, 7.0, 23.2] },
{ name: '降水量', type: 'bar', data: [2.6, 5.9, 9.0, 26.4] },
{ name: '平均温度', type: 'line', yAxisIndex: 1, data: [2.0, 2.2, 3.3, 4.5] }
]
};
```
---
## 饼图 (Pie)
### 源码位置
```
extend/graphDemo/echartsPie/index.vue
```
### 关键配置
```typescript
const options = {
tooltip: { trigger: 'item', formatter: '{b}: {c} ({d}%)' },
legend: { orient: 'vertical', left: 'left', data: ['直接访问', '邮件营销'] },
series: [{
name: '访问来源',
type: 'pie',
radius: ['40%', '70%'], // 环形
center: ['50%', '50%'],
avoidLabelOverlap: false,
label: { formatter: '{b}: {d}%' },
data: [
{ value: 335, name: '直接访问' },
{ value: 234, name: '邮件营销' }
]
}]
};
```
### 特性
- 环形: `radius: ['40%', '70%']`
- 南丁格尔: `roseType: 'area'`
---
## 散点图 (Scatter)
### 源码位置
```
extend/graphDemo/echartsScatter/index.vue
```
### 关键配置
```typescript
const options = {
tooltip: { trigger: 'item' },
xAxis: { type: 'value', scale: true },
yAxis: { type: 'value', scale: true },
series: [{
type: 'scatter',
symbolSize: 20,
data: [
[10.0, 8.04], [8.0, 6.95], [13.0, 7.58], [9.0, 8.81]
]
}]
};
```
---
## K线图 (Candlestick)
### 源码位置
```
extend/graphDemo/echartsCandlestick/index.vue
```
### 关键配置
```typescript
const options = {
tooltip: { trigger: 'axis' },
legend: { data: ['DowJS', 'Gold'] },
xAxis: { type: 'category', data: ['2012-12-14', '2012-12-15'] },
yAxis: { type: 'value' },
series: [{
name: 'DowJS',
type: 'candlestick',
data: [
[open, close, low, high], // [开盘, 收盘, 最低, 最高]
[20, 30, 10, 35]
]
}]
};
```
---
## 漏斗图 (Funnel)
### 源码位置
```
extend/graphDemo/echartsFunnel/index.vue
```
### 关键配置
```typescript
const options = {
tooltip: { trigger: 'item' },
legend: { data: ['展现', '点击', '访问', '咨询', '成交'] },
series: [{
name: '漏斗图',
type: 'funnel',
left: '10%',
top: 60,
bottom: 60,
width: '80%',
data: [
{ value: 100, name: '展现' },
{ value: 80, name: '点击' },
{ value: 60, name: '访问' },
{ value: 40, name: '咨询' },
{ value: 20, name: '成交' }
]
}]
};
```
---
## 仪表盘 (Gauge)
### 源码位置
```
extend/graphDemo/echartsGauge/index.vue
```
### 关键配置
```typescript
const options = {
series: [
{
type: 'gauge',
startAngle: 180,
endAngle: 0,
center: ['50%', '70%'],
radius: '90%',
progress: { show: true, width: 18 },
axisLine: { lineStyle: { width: 18 } },
axisTick: { show: false },
splitLine: { show: false },
axisLabel: { show: false },
pointer: { show: false },
title: { show: true, offsetCenter: [0, '10%'], fontSize: 16 },
detail: { valueAnimation: true, fontSize: 48, offsetCenter: [0, '-10%'] },
data: [{ value: 75, name: '完成率' }]
}
]
};
// 动态更新
timer.value = setInterval(() => {
options.series[0].data[0].value = (Math.random() * 100).toFixed(2) - 0;
renderEcharts(options, false); // false = 仅更新数据
}, 2000);
```
---
## 树图 (Tree)
### 源码位置
```
extend/graphDemo/echartsTree/index.vue
```
### 关键配置
```typescript
const options = {
tooltip: { trigger: 'item' },
series: [{
type: 'tree',
data: [{
name: '根节点',
children: [
{ name: '节点1', children: [{ name: '叶子1' }, { name: '叶子2' }] },
{ name: '节点2' }
]
}],
symbol: 'emptyCircle',
symbolSize: 8,
orient: 'horizontal', // 水平/vertical
expandAndCollapse: true,
label: { position: 'bottom', formatter: '{b}' }
}]
};
```
---
## 图表开发建议
### 动态图表
```typescript
// 使用 ref 和 setInterval 实现动态更新
const timer = ref<number>();
onUnmounted(() => {
if (timer.value) clearInterval(timer.value);
});
```
### 自适应尺寸
```typescript
// 窗口 resize 时自动适应
window.addEventListener('resize', () => {
chartRef.value?.resize();
});
```
---
## 下一步
- [表格高级模式](10-table-patterns.md)
- [表单高级模式](11-form-patterns.md)
- [示例参考](12-examples/extend-examples.md)