antv-g2-chart

G2 v5 图表可视化

概述

G2 v5 是 AntV 的图形语法图表库。它采用 Spec 模式——一种声明式、类似 JSON 的配置风格。生成的示例应从完整的 spec 开始；运行时代码之后可以通过 chart.options() 合并本地更新。

import { Chart } from '@antv/g2';

const chart = new Chart({ container: 'container', autoFit: true });
chart.options({
  type: 'interval',
  data: [{ genre: 'Sports', sold: 275 }],
  encode: { x: 'genre', y: 'sold' },
});
chart.render();

CDN 用法

<script src="https://unpkg.com/@antv/g2@5/dist/g2.min.js"></script>
<script>
  const chart = new G2.Chart({ container: 'container', autoFit: true });
  chart.options({
    type: 'interval',
    data: [{ genre: 'Sports', sold: 275 }],
    encode: { x: 'genre', y: 'sold' },
  });
  chart.render();
</script>

内容检索服务

使用 AntV G2 进行数据可视化时，如果需要了解 G2 v5 的概念、用法、API、示例及其他内容，可以使用提供的上下文检索服务。使用该技能时，会通过 GET 请求从 AntV HTTP API 服务检索内容。

• 主机：https://sive.antv.antgroup.com
• 端点：/api/v1/context/retrieve
• 方法：GET
• 参数：query、library、topK、content、maxTokens

根据查询检索参考文档（混合搜索 = FTS + 向量 + RRF 融合）。

参数	类型	必填	描述
query	string	✅	搜索关键词，例如 bar chart interval
library	string	✅	库名称：g2、g6、x6
topK	number		返回结果数量（默认：5）
content	boolean		返回完整的参考文档 Markdown（默认：true）
maxTokens	number		每条结果的最大 token 数（默认：不限）

curl "https://sive.antv.antgroup.com/api/v1/context/retrieve?query=bar+chart+stacked&library=g2"

关键规则

必须：仅使用 V5 Spec 模式

// ❌ WRONG — V4 chain API (deprecated, will not render)
chart.interval()
  .data([...])
  .encode('x', 'genre')
  .encode('y', 'sold')
  .style({ radius: 4 });

// ✅ CORRECT — V5 Spec Mode
chart.options({
  type: 'interval',
  data: [...],
  encode: { x: 'genre', y: 'sold' },
  style: { radius: 4 },
});

多标记叠加使用 view + children

chart.options() 支持增量深度合并更新，适用于运行时交互。对于生成的一次性代码，请提供完整的初始 spec。要创建相互独立的叠加标记，请使用一个带有 children 的 type: 'view'；依次更改根 type 不会创建叠加层。

// ❌ WRONG — this changes one root mark from line to point; it does not overlay them
chart.options({ type: 'line', data, encode: { x: 'date', y: 'value' } });
chart.options({ type: 'point', data, encode: { x: 'date', y: 'value' } });

// ✅ CORRECT — children array for multi-mark
chart.options({
  type: 'view',
  data,
  children: [
    { type: 'line',  encode: { x: 'date', y: 'value' } },
    { type: 'point', encode: { x: 'date', y: 'value' } },
  ],
});

必须：container 为必填项，并在末尾调用 chart.render()

// ❌ WRONG — no container, no render
const chart = new Chart();
chart.options({ type: 'interval', data });

// ✅ CORRECT
const chart = new Chart({ container: 'container', autoFit: true });
chart.options({ type: 'interval', data, encode: { x: 'genre', y: 'sold' } });
chart.render();

必须：仅使用正确的标记类型

❌ 幻觉内容（来自 ECharts/Vega）	✅ G2 的正确替代项
type: 'ruleX'	type: 'lineX'
type: 'ruleY'	type: 'lineY'
type: 'regionX'	type: 'rangeX'
type: 'regionY'	type: 'rangeY'
type: 'venn'	type: 'path' + transform

合法的 G2 标记：interval、line、area、point、rect、cell、text、image、path、polygon、shape、link、connector、vector、lineX、lineY、rangeX、rangeY、range、box、boxplot、density、heatmap、beeswarm、treemap、pack、partition、tree、sankey、chord、wordCloud、gauge、liquid。sunburst 需要 @antv/g2-extension-plot。

必须：encode 是对象，transform 是数组

// ❌ WRONG
.encode('x', 'genre')
.transform: { type: 'stackY' }

// ✅ CORRECT
encode: { x: 'genre', y: 'sold' }
transform: [{ type: 'stackY' }]

必须：使用复数形式 labels；范围编码使用与标记相适配的通道

// ❌ WRONG
label: { text: 'sold' }

// ✅ CORRECT
labels: [{ text: 'sold' }]
// Interval / link ranges may use either a two-field array or y + y1.
encode: { y: ['start', 'end'] }
// RangeY explicitly uses y + y1.
encode: { y: 'start', y1: 'end' }

必须：用户代码中不得使用 d3

// ❌ WRONG — d3 is not exposed in user scope
const total = d3.sum(data, d => d.value);

// ✅ CORRECT — use native JS or G2 built-in transforms
const total = data.reduce((sum, d) => sum + d.value, 0);

必须：不得使用白色或近白色填充，也不得将 padding 设为数组

// ❌ WRONG
style: { fill: '#fff' }       // invisible on white background
padding: [40, 30, 40, 50]     // invalid in G2 v5

// ✅ CORRECT
encode: { color: 'group' }    // let G2 assign colors
padding: 40                   // single number or 'auto'

必须：转置是 transform，而非坐标类型

// ❌ WRONG
coordinate: { type: 'transpose' }

// ✅ CORRECT
coordinate: { transform: [{ type: 'transpose' }] }

Default Aesthetics / 默认视觉基线

目标是默认清晰、克制、可读，而不是给每张图添加相同装饰。先遵守以下决策，再按需检索 default+aesthetics+design 获取完整示例。

注意区分两种“默认”。G2 引擎默认（theme/create.ts）是 line.lineWidth: 1、area.fillOpacity: 0.85、矩形 radius 无圆角；本节 Mark 基线里的 radius: 4 / lineWidth: 2 / fillOpacity: 0.5~0.6 是本 skill 的约定值，用来覆写引擎默认让生成示例更好看，必须显式写在 style 里，不是省略即生效。

1. 通用：container、完整初始 chart.options() spec、chart.render() 是必须项；普通嵌入式图优先 autoFit: true、theme: 'classic' 与 padding: 'auto'。classic 是为稳定视觉显式选择的浅色预设，不是引擎默认主题（引擎默认推断为 light）；深色容器使用 classicDark。两者共用同一套 category10 色板（首选 #5B8FF9），因此稳定主色在浅/深主题下都可用。
2. 颜色表达语义：仅当颜色表示独立的系列、状态或分组时使用 encode.color 和图例。单指标分类比较使用稳定单色（如 style.fill: '#5B8FF9'，作为样式值是合法的）并关闭颜色图例，避免彩虹柱和冗余图例。禁止的是把 hex 字符串存进数据后作为 encode.color 的类别字段编码。
3. Mark 基线（约定值，覆写引擎默认）：interval 用 radius: 4（引擎默认无圆角）；line 用 lineWidth: 2（引擎默认 1）；area 用 fillOpacity: 0.5~0.6（引擎默认 0.85，偏实，降下来更透气）。这些值都需显式写在 style 里，不是省略即生效；不需要渐变、阴影或自定义动画。
4. 文本只用已知语义：字段/单位/来源明确时，添加语义化轴标题、tooltip 名称和 formatter；报告语境或用户提供标题时添加顶层 title。信息未知时省略，不编造单位、来源或副标题。
5. 标签按密度选择：少量且需精确读取的数据可加标签；密集散点、多系列折线、类别很多时默认依赖 tooltip。inside 标签用 contrastReverse，发生碰撞时使用 overlapHide / overlapDodgeY / overflowHide；dx / dy 只用于避让后的细微调整。
6. 特殊图：饼/环图的少量类别优先外置标签，类别较多时改用 legend；不要默认同时重复两者。气泡图保持 G2 默认 sqrt size 映射，按数据范围设置 size.range，仅在 size legend 无助理解时隐藏它。

渐变、阴影、滑块、滚动条、自定义动画和 3D 气泡都属于用户明确要求“报告级 / 精致”时的增强项；添加前必须确认不会掩盖数据或降低标签对比度。

Quick Reference

User Intent	Retrieve Query
Chart initialization, container, autoFit	GET /api/v1/context/retrieve?query=chart+init&library=g2
Bar / column chart	GET /api/v1/context/retrieve?query=bar+chart+interval&library=g2
Line / area chart	GET /api/v1/context/retrieve?query=line+area+chart&library=g2
Pie / donut / rose chart	GET /api/v1/context/retrieve?query=pie+chart+theta&library=g2
Scatter / bubble	GET /api/v1/context/retrieve?query=scatter+point+bubble&library=g2
Treemap / sunburst / pack	GET /api/v1/context/retrieve?query=treemap+sunburst+pack&library=g2
Heatmap / density / boxplot	GET /api/v1/context/retrieve?query=heatmap+density+boxplot&library=g2
Funnel / gauge / wordcloud	GET /api/v1/context/retrieve?query=funnel+gauge+wordcloud&library=g2
Encode channels (x, y, color, size)	GET /api/v1/context/retrieve?query=encode+channel&library=g2
Scale / palette / color range	GET /api/v1/context/retrieve?query=scale+palette+color&library=g2
Coordinate (polar, theta, transpose)	GET /api/v1/context/retrieve?query=coordinate+polar+theta+transpose&library=g2
Transform (stack, normalize, sort)	GET /api/v1/context/retrieve?query=transform+stack+normalize&library=g2
Axis / legend / tooltip / labels	GET /api/v1/context/retrieve?query=axis+legend+tooltip+label&library=g2
Interaction (brush, highlight, drilldown)	GET /api/v1/context/retrieve?query=interaction+brush+highlight&library=g2
Theme / dark mode	GET /api/v1/context/retrieve?query=theme+dark+classicDark&library=g2
Default aesthetics / 视觉基线	GET /api/v1/context/retrieve?query=default+aesthetics+design&library=g2
Animation	GET /api/v1/context/retrieve?query=animation+animate&library=g2
Data fetch / filter / sort	GET /api/v1/context/retrieve?query=data+fetch+filter+sort&library=g2
Facet / view composition	GET /api/v1/context/retrieve?query=facet+view+composition&library=g2
Chart type selection guide	GET /api/v1/context/retrieve?query=chart+type+selection&library=g2
Rendering troubleshoot	GET /api/v1/context/retrieve?query=rendering+troubleshoot+debug&library=g2

Dependencies

• @antv/g2 — G2 v5 charting engine