# Apache ECharts

> 分类：`libs/charts/` · 档位：**评估** · 更新时间：2026-11-17

## 1. 基本信息

| 项 | 内容 |
|---|---|
| 当前版本 | 以官方 releases 为准（5.x / 6.x 迭代中） |
| License | Apache-2.0 |
| 维护方 | Apache Software Foundation |
| 仓库 / 文档 | https://github.com/apache/echarts · https://echarts.apache.org |
| 最近 release | 见官方 releases |

## 2. 一句话定位

功能最全的通用图表与可视化库：几十种图表、地图、数据集、联动、渐进渲染都在核心覆盖范围内。
代价是体积：全量构建很大，必须按需注册才能进入可接受的范围。

## 3. 体积

| 引入方式 | min | gzip |
|---|---|---|
| 全量 UMD | 约 1 MB | 约 300 KB（口径待实测） |
| 按需构建（折线 + 网格 + Canvas） | 明显更小 | 待实测 |

## 4. 核心 API

```js
import * as echarts from 'echarts/core';
import { LineChart } from 'echarts/charts';
import { GridComponent, TooltipComponent } from 'echarts/components';
import { CanvasRenderer } from 'echarts/renderers';

echarts.use([LineChart, GridComponent, TooltipComponent, CanvasRenderer]);

const chart = echarts.init(el);
chart.setOption({ xAxis: { type: 'category', data }, yAxis: {}, series: [{ type: 'line', data }] });
chart.resize();
chart.dispose();
```

## 5. 适用 / 不适用

- **适用**：复杂仪表盘、地图与关系图、需要联动/刷选/大数据渐进渲染的场景。
- **不适用**：只画一两张简单图（Chart.js 更轻）；极端体积敏感的营销页（uPlot 或原生 Canvas）。

## 6. 硬缺口与已知坑

- 全量体积大，不按需 `use()` 会直接把首屏拖慢。
- 容器必须有宽高，`display:none` 时初始化会得到 0×0，显示后需 `resize()`。
- 地图需要额外的 geoJSON 与 `registerMap`，不是开箱能力。
- 大数据要开 `large` / `progressive`，否则交互会卡。
- 动态重建前要 `dispose()`，否则实例与事件监听泄漏。
- SSR 需要用 SVG 渲染器导出字符串，Canvas 渲染器依赖浏览器。

## 7. 受限环境可用性

| 环境 | 结论 | 说明 |
|---|---|---|
| 无构建（UMD） | 可用 | 全量引入，体积最大 |
| ESM / 打包器 | 可用 | 推荐按需注册 |
| SSR | 可用 | SVG 渲染器可输出字符串 |
| 客户端重渲染 | 需处理生命周期 | `dispose()` 后重新 `init()` |

## 8. 稳定性评分

| 维度 | 评分 | 依据 |
|---|---|---|
| 维护活跃度 | 5 | Apache 顶级项目，长期活跃 |
| 版本与破坏性变更 | 4 | 大版本有迁移指南 |
| 采用度 | 5 | 国内仪表盘事实标准之一 |
| 体积与按需 | 3 | 全量偏大，强依赖按需构建 |
| 生态兼容 | 5 | 框架无关，UMD / ESM 均有 |
| License | 5 | Apache-2.0 |

## 9. 替代品对比

| 库 | 优势 | 劣势 | 何时选它 |
|---|---|---|---|
| Chart.js | 轻、上手快、树摇简单 | 图表类型与交互少 | 简单报表 |
| ApexCharts | 默认样式好、交互丰富 | 体积大、深度定制受限 | 快速做漂亮图表 |
| uPlot | 约 20 KB，百万级数据流畅 | 类型少、样式需自写 | 时序大数据 |
| D3 | 完全可控 | 学习成本高 | 定制可视化 |
