G2 v5 Chart Visualization

Overview

G2 v5 is AntV's grammar-of-graphics charting library. It uses Spec Mode — a declarative, JSON-like configuration style where chart.options() defines the entire visualization in one call.

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 Usage

<​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​>

Content Retrieval Service

When using AntV G2 for data visualization, if you need to understand the concepts, usage, API, examples, and other aspects of G2 v5, you can use the provided context retrieval service. When using the skill, content is retrieved via an antv HTTP API server using GET requests.

• Host: https://sive.antv.antgroup.com
• Endpoint: /api/v1/context/retrieve
• Method: GET
• Parameters: query, library, topK, content, maxTokens, progressiveLevel

Retrieve skills by query (hybrid search = FTS + vector + RRF fusion). Constraints docs are indexed as regular skill documents and will appear in search results naturally.

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

Critical Rules

MUST: Use V5 Spec Mode ONLY

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

MUST: chart.options() called exactly ONCE

Multiple calls overwrite each other. For multi-mark overlays, use type: 'view' + children:

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

MUST: container is mandatory, chart.render() at the end

// ❌ WRONG — no container, no renderconst chart = new Chart();chart.options({ type: 'interval', data });
// ✅ CORRECTconst chart = new Chart({ container: 'container', autoFit: true });chart.options({ type: 'interval', data, encode: { x: 'genre', y: 'sold' } });chart.render();

MUST: Correct mark types only

Legal G2 marks: 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 requires @antv/g2-extension-plot.

MUST: encode is an object, transform is an array

// ❌ WRONG.encode('x', 'genre').transform: { type: 'stackY' }
// ✅ CORRECTencode: { x: 'genre', y: 'sold' }transform: [{ type: 'stackY' }]

MUST: labels is plural, range encoding uses y/y1

// ❌ WRONGlabel: { text: 'sold' }encode: { y: ['start', 'end'] }
// ✅ CORRECTlabels: [{ text: 'sold' }]encode: { y: 'start', y1: 'end' }

MUST: No d3 in user code

// ❌ WRONG — d3 is not exposed in user scopeconst total = d3.sum(data, d => d.value);
// ✅ CORRECT — use native JS or G2 built-in transformsconst total = data.reduce((sum, d) => sum + d.value, 0);

MUST: No white/near-white fill, no padding as array

// ❌ WRONGstyle: { fill: '#fff' }       // invisible on white backgroundpadding: [40, 30, 40, 50]     // invalid in G2 v5
// ✅ CORRECTencode: { color: 'group' }    // let G2 assign colorspadding: 40                   // single number or 'auto'

MUST: Transpose is a transform, not a coordinate type

// ❌ WRONGcoordinate: { type: 'transpose' }
// ✅ CORRECTcoordinate: { transform: [{ type: 'transpose' }] }

Default Aesthetics / 默认视觉基线

这一段不依赖内容检索，是每次生成都必须满足的视觉底线。 目标：即使用户只说"画个柱状图"，产出的也是一张"开箱即用就好看"的图——而不是裸 type + data + encode 三件套骨架。

下面把视觉分成两层，二者并行不悖：

• 「基线美观」(MUST)：默认必加，无需用户请求。这是最低视觉档次，缺失即视为缺陷。
• 「装饰增强」(MAY)：仅当用户明确想"好看 / 精致 / 报告级"时才追加。默认不要堆砌——保留 G2 克制的取向，避免图表喧宾夺主。

MUST: 基线美观（默认必加）

1. 容器与会话：new Chart({ container: 'container', autoFit: true, theme: 'classic' })，末尾 chart.render()。容器背景为深/黑色时才换 'classicDark'。
2. 颜色交给主题：分类数据用 encode: { color: <类别字段> } 让 G2 自动套用 Category10（#5B8FF9 #5AD8A6 #5D7092 #F6BD16 #6F5EF9 #6DC8EC #945FB9 #FF9845 #1E9493 #FF99C3）。不要手动写死单色 style.fill，不要把 hex 色值塞进数据再用 encode.color 映射（会被当类别 key，图例显示 hex）。单系列也用 encode.color 而非裸 fill，以求与多系列风格一致。
3. 柱/条形加圆角：type: 'interval' 默认 style: { radius: 4 }（柱顶圆角）。
4. 面积/折线降透明度并描边：area 默认 style: { fillOpacity: 0.6 }；line 默认 style: { lineWidth: 2 }；面积常用 area + line 描边组合，fillOpacity: 0.5。
5. 数据标签防重叠：labels 一律用 position 定位，禁用 dx/dy 偏移。柱内标签必带 transform: [{ type: 'contrastReverse' }]（深底白字自适应）；多系列折线、散点、分组柱状等密集场景必带 overlapDodgeY 或 overlapHide；堆叠 / treemap / 旭日图等空间有限场景必带 overflowHide。
6. 坐标轴有语义标题：业务数据默认 axis: { x: { title: '<语义化短词>' }, y: { title: '<量纲>' } }，如 '月份'、'销量 / 件'。禁止写 'x' / 'y' / 'field' 这类无信息标题。纯探索性图可省略，但不要写空标题。
7. 语义化示例数据：示例数据用真实业务名——体育 / 策略 / 动作、北京 / 上海 / 广州、产品A / 产品B、1月 … 12月。严禁 a / b / c、x / y、类别1、node1 这类惰性命名。带数值量纲的字段名最好体现单位（sales_cny、latency_ms）。
8. 留白用 auto：默认 padding: 'auto'（坐标轴/图例已自动预留）。不要写 padding: 0（会截断组件），不要写数组形式 padding: [40,20,...]。确需微调某一边用 paddingTop / Right / Bottom / Left 单独设置。

MAY: 装饰增强（仅用户明确要"好看 / 报告级"时）

Mark 配色渐变（按 mark 类型选择，不要混用语法）

渐变写在 style.fill 里，是一条 CSS gradient 字符串。不同 mark 用不同形态，见下表——不要在一个 chart 里混用两种渐变思路，也不要给本应纯色的折线加渐变。

deg 规则（与 CSS 相反，务必记牢）：@antv/g 渐变角度用数学/Canvas 坐标系——0deg = 向右、90deg = 向下、180deg = 向左、270deg = 向上。这不是 CSS 规格（CSS 里 180deg 才是向下）。所以本表竖向柱/面积要"顶→底"用 90deg，横向条形要"左→右"用 0deg。方向关键字（to top/to bottom 等）则按 CSS 语义、已自动修正，可放心用——但数值角必须按上表换算。

为什么这样固定：渐变绑死画布坐标系，不跟 coordinate.transform: transpose 转。竖向柱转成横向条后，柱体从竖变横，但 deg 不变——所以柱→条要把 90deg 改成 0deg 才方向正确。与其让 LLM 现算，不如按"竖向=90deg / 横向=0deg"两条死规则记。

关键细节：径向渐变的高光点统一取 circle at 35% 35%（左上偏移，模拟左上方光源），这是全仓一致的约定，照抄即可、不要自创偏移量。渐变填充的 mark 若再叠 label，标签字色要用 contrastReverse 或手动给深色字，避免压在浅色高光上不可读。

其他装饰

shadowBlur / shadowColor 轻阴影、自定义 animate 缓动、折线末端常驻标签（labels: [{ text: 'value', selector: 'last' }]）、slider 缩略轴、scrollbar 滚动条。这些与渐变一同属于"锦上添花"——用户没提就别加，更不要一次性把所有装饰全堆上。

基线 vs 装饰：一张图对照

// ❌ 骨架（当前最易出现的默认产出）——只有 type + data + encode，没有视觉档次chart.options({ type: 'interval', data, encode: { x: 'genre', y: 'sold' } });
// ✅ 基线美观（默认目标）——圆角 + 主题色 + 语义数据 + 轴标题 + 标签，约 10 行chart.options({  type: 'interval',  data: [    { genre: '体育', sold: 275 },    { genre: '策略', sold: 115 },    { genre: '动作', sold: 120 },  ],  encode: { x: 'genre', y: 'sold', color: 'genre' },  style: { radius: 4 },  axis: { x: { title: '游戏类型' }, y: { title: '销量 / 件' } },  labels: [{ text: 'sold', position: 'outside' }],});
// ✨ 装饰增强（仅当用户要"报告级"时才加）——渐变 + 阴影 + 末端焦点chart.options({  type: 'interval',  data: [/* 同上 */],  encode: { x: 'genre', y: 'sold', color: 'genre' },  style: {    fill: 'linear-gradient(90deg, #5B8FF9 0%, #6DC8EC 100%)',    radius: 6,    shadowColor: 'rgba(0,0,0,0.15)',    shadowBlur: 8,  },  axis: { x: { title: '游戏类型' }, y: { title: '销量 / 件' } },  labels: [{ text: 'sold', position: 'outside', fontWeight: 'bold' }],});

契约优先级：当检索召回的 mark 文档与本段冲突时，以本段为准——本段是每次都生效的硬契约，mark 文档里的"最小示例"多为裸骨架，照抄即丑。可用 mark 文档补全数据结构 / 特有 API，但视觉基线以本段补齐。

Quick Reference

Dependencies

• @antv/g2 — G2 v5 charting engine