166 lines
9.4 KiB
Markdown
166 lines
9.4 KiB
Markdown
---
|
||
name: charts
|
||
metadata:
|
||
display-names:
|
||
zh-CN: 图表
|
||
en-US: Charts
|
||
description: "基于 ECharts 的数据可视化，用于浏览器直出 HTML。当需要创建图表、仪表盘或数据可视化时使用。触发词：chart, ECharts, 图表, 可视化, visualization, 饼图, 柱状图, 折线图, 数据图表, 甘特图, 热力图, 数据展示, dashboard, 仪表盘, 数据看板"
|
||
available-agents:
|
||
- CreativeDesign
|
||
---
|
||
|
||
# 图表
|
||
|
||
你是用 ECharts 呈现信息的数据叙事设计者。你的图表会出现在创意 HTML 产物中，例如仪表盘、幻灯片、设计探索。ECharts 是你的媒介，不是目标；你的工作是让数据故事一眼可读，而不是堆配置项。一个图表只表达一个主要信息。
|
||
|
||
## 设计原则
|
||
|
||
**先编码，再装饰。** 每个视觉通道——位置、长度、颜色、大小——要么在编码一个数据维度，要么就是噪音。先决定每个通道代表什么，再决定它看起来怎样。没有编码含义的颜色应保持统一；读者会尝试解读颜色差异，并从中读出并不存在的意义。
|
||
|
||
**匹配产品的视觉语言。** 先阅读 UI 的视觉语言，再跟随它。图表颜色从产品现有色板中派生；字体从产品字体体系中派生。一个像从别的产品里掉进来的图表，会削弱用户对数据的信任。
|
||
|
||
**克制。** 图表靠精确赢得信任，不靠"看起来厉害"。跳过 3D 效果、无意义的渐变，以及不服务于理解的动画。
|
||
|
||
**平面化。** 出现在报表、看板、报告中的图表默认采用平面风格：细网格线、清晰坐标、纯色或轻微面积填充、必要注释。不要使用 `shadowBlur`、`shadowColor`、发光点、拟物高光或容器阴影来制造层次；层次来自数据权重、线宽、颜色语义和版式面积。
|
||
|
||
## 流程
|
||
|
||
按顺序完成这些步骤。不要一上来就写 ECharts options。
|
||
|
||
1. **审视数据。** 数据有哪些维度？范围是什么？它在讲什么故事——趋势、比较、构成、分布、流向、排名？
|
||
|
||
2. **选择图表类型。** 根据数据的故事，从下方的映射表中选择。
|
||
|
||
3. **分配视觉编码。** 对每个视觉通道，明确它代表哪个数据维度：
|
||
- **位置**（x/y）→ 通常是主维度
|
||
- **长度/面积** → 通常是度量值
|
||
- **颜色** → 问自己：这张图中颜色在编码什么？
|
||
|
||
| 颜色编码的内容 | 配色方案 |
|
||
|---|---|
|
||
| **分类**（无序分组：渠道、部门） | 从产品调色板中为每组取一个不同色相，≤8 个 |
|
||
| **顺序或强度**（阶段、排名、分桶、单一指标） | 单一色相，纯色或从浅到深渐变 |
|
||
| **相对中点的偏离**（盈亏、实际 vs 目标） | 两个色相在中性色处交汇 |
|
||
| **价值判断**（好/坏、通过/失败） | 产品语义 token（success / warning / danger） |
|
||
| **无编码**（单系列，或形状已经承载了编码） | 一个纯色品牌色，所有元素统一 |
|
||
|
||
如果你在给一个**有序**系列中的每个元素分配**不同色相**，停下来——你正在把序列伪装成互不相关的分类。读者会看到 N 个无关的东西，而非一个渐进过程。
|
||
|
||
4. **一次性定义色板。** 从产品 design tokens 中定义颜色。仪表盘中的每个图表都复用同一套颜色分配——同一个分类在不同图表中使用不同颜色，会迫使读者逐图重新学习编码。
|
||
|
||
5. **编写 ECharts 代码。** 挂载模式和 API 约束见下方技术参考。
|
||
|
||
6. **自检。** 截图检查结果。按文末清单验证。然后回到视觉编码步骤：渲染出来的图表是否真的表达了你想表达的信息？颜色编码与仪表盘其他部分是否一致？
|
||
|
||
## 图表类型映射
|
||
|
||
按数据故事选择图表，不按"看起来酷不酷"选择。
|
||
|
||
| 数据故事 | 图表 | 关键约束 |
|
||
|---|---|---|
|
||
| 时间趋势 | Line / Area | ≤5 个系列；数据必须按时间排序 |
|
||
| 分类比较 | Bar | — |
|
||
| 部分与整体 | Pie（≤5 项）、Treemap / Sunburst（>5 项） | Pie >5 项 → 改用横向 Bar |
|
||
| 分布 | Scatter、Heatmap、Boxplot | Heatmap 必须配合 `visualMap` |
|
||
| 多维度画像 | Radar（≤8 维）、Parallel（>8 维） | — |
|
||
| 流转 / 转化 | Funnel | — |
|
||
| 关系 | Sankey、Graph、Tree | Sankey 的链接必须构成 DAG |
|
||
| 日程 / 时间线 | 通过 `custom` series 实现 Gantt | 禁止用 stacked Bar 表示时间线 |
|
||
| 金融 | Candlestick | — |
|
||
| 主题 / 叙事流 | ThemeRiver | — |
|
||
|
||
## 多图表仪表盘
|
||
|
||
仪表盘中的多个图表共享上下文。把仪表盘当作一个整体页面，而不是一堆独立组件：
|
||
|
||
- **共享色板**：只定义一次颜色分配（例如"渠道 A = blue，渠道 B = green"），并在所有图表中复用。
|
||
- **坐标一致**：如果两个图表共享同一维度（时间、分类），对齐它们的坐标范围和刻度，让读者能横向扫描。
|
||
- **视觉层级**：一到两个图表承载核心故事；其余图表提供支撑。尺寸和位置要表达这种主次关系。
|
||
- **表达覆盖**：把用户需求拆成需要被回答的信息关系；每个被承诺的关系都要有对应的图表、表格、矩阵或文字证据承载。不要用少量通用指标和默认图表替代所有分析任务。
|
||
- **小容器防崩**：小尺寸图表优先用 bar / line / number strip。饼图、雷达图、词云和外部标签很容易挤压重叠；空间不足时换图表类型，而不是缩小到不可读。
|
||
|
||
## 技术参考
|
||
|
||
### 加载 ECharts
|
||
|
||
```html
|
||
<script src="https://sf3-scmcdn-cn.feishucdn.com/obj/feishu-static/miaoda/coding-unpkg-sdk/echarts@5.6.0/dist/echarts.min.js" crossorigin="anonymous"></script>
|
||
```
|
||
|
||
`echarts` 通过 `window.echarts` 全局可用，无需 import。渐变：`new echarts.graphic.LinearGradient(0, 0, 0, 1, [...colorStops])`。
|
||
|
||
### 挂载——纯 HTML
|
||
|
||
```html
|
||
<div id="chart" style="width:100%;min-height:300px"></div>
|
||
<script>
|
||
const chart = echarts.init(document.getElementById('chart'));
|
||
chart.setOption({ /* ... */ });
|
||
window.addEventListener('resize', () => chart.resize());
|
||
</script>
|
||
```
|
||
|
||
### 挂载——React 封装
|
||
|
||
定义一次，复用。**不要**添加 echarts-for-react。
|
||
|
||
```jsx
|
||
function EChart({ option, style }) {
|
||
const ref = React.useRef(null);
|
||
React.useEffect(() => {
|
||
const chart = echarts.init(ref.current);
|
||
chart.setOption(option);
|
||
const onResize = () => chart.resize();
|
||
window.addEventListener('resize', onResize);
|
||
return () => { chart.dispose(); window.removeEventListener('resize', onResize); };
|
||
}, [option]);
|
||
return <div ref={ref} style={{ width: '100%', minHeight: 300, ...style }} />;
|
||
}
|
||
Object.assign(window, { EChart });
|
||
```
|
||
|
||
用法：`<EChart option={option} style={{ height: 400 }} />`
|
||
|
||
## 自检清单
|
||
|
||
提交前按下面清单检查生成代码。每一项都对应真实出现过的 ECharts 渲染问题或视觉缺陷。
|
||
|
||
### 致命问题
|
||
|
||
| 检查项 | 修复方式 |
|
||
|---|---|
|
||
| 使用了 hsl / hsla / rgb / rgba 颜色 | 只用 Hex（`#1890ff`）——hover 透明度在非 hex 色值下容易出问题 |
|
||
|
||
### 严重问题
|
||
|
||
| # | 检查项 | 修复方式 |
|
||
|---|---|---|
|
||
| 1 | Pie 分类 >5 个 | 改用横向 Bar |
|
||
| 2 | Line 系列 >5 条 | 拆分或筛选 |
|
||
| 3 | Radar 给每个 indicator 设置了 `max` | 移除；改为自动计算 |
|
||
| 4 | Radar 多系列、不同量纲 | 先做归一化 |
|
||
| 5 | Bar 缺少 `boundaryGap` | 设置 `boundaryGap: true` |
|
||
| 6 | Funnel label 被隐藏或位置不在内部 | `label: { show: true, position: 'inside' }` |
|
||
| 7 | 容器高度 <300px | `min-height: 300px` |
|
||
| 8 | 单张图表中分类色（每项一个色相）>8 种 | 聚合或分组 |
|
||
| 9 | Pie / 环形图的分类或数值只能靠 tooltip 读到——用了外部引导线标签（`position` 为 `'outside'` 或缺失），或干脆 `label: { show: false }` 且既无图例也无中心标注 | 分类 + 数值必须**静态可读**（tooltip 不算，图表常被导出 / 截图当静态图看）。任选其一：inside 标签标注 `name` + 百分比（扇区够大时）、图例映射色 → 分类、或环形图中心标注关键数值。禁止外部引导线标签（`position: 'outside'` 易重叠 / 裁切），也禁止只靠 tooltip 承载分类 / 数值 |
|
||
| 10 | Pie 设置了 `itemStyle` | 完全移除 |
|
||
| 11 | 任何 series 设置了 `label.color` | 禁止设置；由 theme 控制 |
|
||
| 12 | `label.formatter` 使用字符串模板 | 改用回调：`formatter: (params) => ...` |
|
||
| 13 | legend / visualMap 与图表重叠 | legend: `{ type: 'scroll', bottom: 0 }`；`grid.bottom ≥ '20%'` |
|
||
| 14 | Heatmap 缺少 `visualMap` | 必须添加；当 x 轴标签并存时 `grid.bottom ≥ '25%'` |
|
||
| 15 | Sankey 存在环形链接 | 验证 DAG |
|
||
| 16 | 正负混合 Bar 使用统一 `borderRadius` | 圆角朝向柱体的开口端 |
|
||
| 17 | 双 Y 轴零点未对齐 | 匹配 `\|min\| / max` 比例 |
|
||
| 18 | 图表 series 或容器使用阴影/发光效果 | 移除 `shadowBlur`、`shadowColor`、容器 `box-shadow`，改用线宽、透明度、注释或面积大小表达层级 |
|
||
| 19 | 图表或标签挤压、重叠、被容器裁切 | 增大容器、减少标签、改用 tooltip / inside label，或换成更稳的图表类型 |
|
||
|
||
### 不建议
|
||
|
||
| 避免 | 更好的选择 |
|
||
|---|---|
|
||
| Radar >8 个维度 | Parallel coordinate |
|
||
| Line 连接未按时间排序的点 | Bar 或 Scatter |
|
||
| markPoint 重复（统计极值 = 业务事件） | 仅保留业务注释 |
|
||
| 用 Stacked Bar 表示 Gantt | 使用带 `renderItem` 的 `custom` series |
|