Skip to content

yzsp-studio/mediakit-shared-suite / app-builder

app-builder

Unverified

统一处理应用级和工程级产品的设计、开发、编辑及产物问答(单页html和h5的开发和设计不要使用这个skill)。当用户明确点名「妙搭」时请使用本技能。适用于全栈应用,包括多页面或多文件工程、前端框架、后端服务、API、数据库、登录权限、业务逻辑、构建运行和发布部署。也支持基于 PRD、文档、截图或素材开发应用,以及对已有应用新增功能、调整页面、修复 Bug、分析源码、排查运行错误和查询运营或发布状态。

reference/steering/charts.md

View on GitHub
---
name: charts
description: "基于 ECharts 的数据可视化,用于浏览器直出 HTML。当需要创建图表、仪表盘或数据可视化时使用。触发词:chart, ECharts, 图表, 可视化, visualization, 饼图, 柱状图, 折线图, 数据图表, 甘特图, 热力图, 数据展示, dashboard, 仪表盘, 数据看板"
metadata:
  display-names:
    zh-CN: 图表
    en-US: Charts
---


# 图表

你是用 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. **自检。** 按文末清单逐项检查你写出的 option 代码(源码级自查,不用打开浏览器截图)。然后回到视觉编码步骤:这套配置渲染出来的图表是否真的表达了你想表达的信息?颜色编码与仪表盘其他部分是否一致?

## 图表类型映射

按数据故事选择图表,不按"看起来酷不酷"选择。

| 数据故事 | 图表 | 关键约束 |
|---|---|---|
| 时间趋势 | 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。饼图、雷达图、词云和外部标签很容易挤压重叠;空间不足时换图表类型,而不是缩小到不可读。

## 窄屏适配

图表出现在报表或看板中时,移动端(≤768px)的容器宽度可能压到 300px 以下。盲目把桌面端图表原样塞进窄容器,会导致 axis label 堆叠、legend 遮盖绘图区、饼图标签溢出。以下是在窄屏容器中保证可读性的规则:

### 布局容器

报表中承载图表的网格必须在窄屏时折叠为单列。写多列网格时,用 `auto-fit` + `minmax()` 让浏览器自动折叠,或配合 `@media` 断点显式切换:

```css
/* 自动折叠:每列最小 320px,不够就换行 */
.chart-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
  gap: 16px;
}

/* 或显式断点 */
@media (max-width: 768px) {
  .chart-grid { grid-template-columns: 1fr; }
}
```

不要写死 `grid-template-columns: 1.2fr 2fr` 而不提供窄屏回退——390px 视口下,1.2fr 只有 146px,放不下任何图表。

### ECharts option 适配

在窄容器(宽度 <400px)中调整 ECharts option:

- **legend**:改为 `orient: 'horizontal'` + `type: 'scroll'`,放在图表底部(`bottom: 0`),不要放在侧面挤占绘图区。
- **grid**:增大 `left` / `right` 留白到 `'12%'` 以上,防止 axis label 被裁切。
- **x 轴 label**:长文本加 `axisLabel: { rotate: 30, interval: 0 }` 或截断 formatter;分类超过 8 个时用 `interval: 'auto'` 让 ECharts 自动跳标签。
- **tooltip**:窄屏下 tooltip 容易超出视口,设 `confine: true`。
- **图表类型降级**:桌面端的并排双图在移动端改为上下堆叠;桌面端的 Pie 在容器宽度 <250px 时考虑改为横向 Bar。

### 容器尺寸监听

用 `ResizeObserver` 而非 `window.resize` 监听图表容器(见下方「技术参考 · 挂载」的封装代码)。当网格从双列折叠为单列时,window 尺寸不变但容器变宽,`resize` 事件不触发,图表不会重绘。

## 技术参考

### 加载 ECharts

```html
<script src="https://cdn.jsdelivr.net/npm/echarts@5.6.0/dist/echarts.min.js" integrity="sha384-pPi0zxBAoDu6+JXW/C68UZLvBUUtU+7zonhif43rqj7pxsGyqyqzcian2Rj37Rss" crossorigin="anonymous"></script>
```

`echarts` 通过 `window.echarts` 全局可用,无需 import。渐变:`new echarts.graphic.LinearGradient(0, 0, 0, 1, [...colorStops])`。

### 挂载(原生 JS)

> ⚠️ **本节与上面的「引入」只适用于 html 链路**(无构建、CDN script)。webapp 工程按所用栈的方式来:默认栈已装好 `echarts` + `echarts-for-react`,直接 `import`,不要往 index.html 插 script 标签。本文其余部分(选型、视觉编码、窄屏适配、自检清单)两条链路通用。

**不要**添加 echarts-for-react 等任何封装库(**指 html 链路**)。用 `ResizeObserver` 而非 `window.resize` 监听容器尺寸变化(见「窄屏适配」说明)。多图页面把下面的模式封装成一个函数复用;更新数据时对同一实例再 `setOption`,不要销毁重建。

```html
<div id="chart" style="width:100%;min-height:300px"></div>
<script>
  const chart = echarts.init(document.getElementById('chart'));
  chart.setOption({ /* ... */ });
  new ResizeObserver(() => chart.resize()).observe(document.getElementById('chart'));
</script>
```

## 自检清单

提交前按下面清单检查生成代码。每一项都对应真实出现过的 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,或换成更稳的图表类型 |
| 20 | 图表容器的父级网格在窄屏(≤768px)下没有折叠为单列 | 用 `auto-fit + minmax(320px, 1fr)` 或 `@media` 断点,保证每个图表容器至少 320px 宽 |
| 21 | 使用 `window.addEventListener('resize', ...)` 监听图表尺寸 | 改用 `ResizeObserver`——网格列折叠时 window 尺寸不变但容器变宽,`resize` 事件不触发 |

### 不建议

| 避免 | 更好的选择 |
|---|---|
| Radar >8 个维度 | Parallel coordinate |
| Line 连接未按时间排序的点 | Bar 或 Scatter |
| markPoint 重复(统计极值 = 业务事件) | 仅保留业务注释 |
| 用 Stacked Bar 表示 Gantt | 使用带 `renderItem` 的 `custom` series |

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall