在需要创建、定制或排错 AntV G2 v5…

适用于使用 @antv/g2 v5 绘制、配置或调试各类图表（柱状图、折线图、饼图等）的场景。

适用场景

解决思路

1. 使用 G2 v5 Spec Mode：通过 chart.options({...}) 传入完整声明式配置（type、data、encode 等），不要使用 V4 链式 API（如 chart.interval().data().encode()）。
2. 生成一次性代码时从完整初始 spec 开始；运行时交互可通过 chart.options() 进行增量深合并更新。
3. CDN 用法：引入 <script src="https://unpkg.com/@antv/g2@5/dist/g2.min.js"></script>，使用 new G2.Chart({ container: 'container', autoFit: true })，调用 chart.options({...}) 后执行 chart.render()。
4. 需要理解 G2 v5 的概念、用法、API、示例时，使用内容检索服务：GET https://sive.antv.antgroup.com/api/v1/context/retrieve，参数 query（必填，搜索关键词）、library（必填，如 g2）、topK（默认 5）、content（默认 true）、maxTokens（默认不限）。例如：curl "https://sive.antv.antgroup.com/api/v1/context/retrieve?query=bar+chart+stacked&library=g2"。
5. 创建 Chart 实例时必须提供 container，并在最后调用 chart.render()。例如：const chart = new Chart({ container: 'container', autoFit: true }); chart.options({ type: 'interval', data, encode: { x: 'genre', y: 'sold' } }); chart.render();
6. 多 mark 叠加使用 view + children：用 type: 'view' 和 children 数组包含多个 mark，不要顺序修改根 type 来叠加。
7. 只使用合法的 G2 mark 类型：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。避免使用 ruleX（用 lineX）、ruleY（用 lineY）、regionX（用 rangeX）、regionY（用 rangeY）、venn（用 path + transform）。
8. encode 是对象，transform 是数组。例如：encode: { x: 'genre', y: 'sold' }，transform: [{ type: 'stackY' }]。
9. labels 是复数形式：labels: [{ text: 'sold' }]。范围编码使用合适的通道：interval/link 范围可用两字段数组或 y + y1；rangeY 明确使用 y + y1，例如 encode: { y: 'start', y1: 'end' }。
10. 用户代码中不要使用 d3：例如不用 d3.sum，改用原生 JS（如 data.reduce((sum, d) => sum + d.value, 0)）或 G2 内置 transform。
11. 不要使用白色/近白色填充（在白色背景上不可见），不要使用数组作为 padding。应使用 encode: { color: 'group' } 让 G2 分配颜色，padding: 40 或 padding: 'auto'。
12. 转置是 transform，不是 coordinate 类型：使用 coordinate: { transform: [{ type: 'transpose' }] }，不要用 coordinate: { type: 'transpose' }。
13. 默认视觉基线：普通嵌入式图优先 autoFit: true、theme: 'classic' 与 padding: 'auto'；classic 是显式选择的浅色预设，不是引擎默认主题（引擎默认推断为 light）；深色容器使用 classicDark。两者共用 category10 色板（首选 #5B8FF9）。
14. 颜色表达语义：仅当颜色表示独立系列、状态或分组时使用 encode.color 和图例；单指标分类比较使用稳定单色（如 style.fill: '#5B8FF9'）并关闭颜色图例；禁止把 hex 字符串存进数据后作为 encode.color 的类别字段编码。
15. Mark 基线（约定值，覆写引擎默认）：interval 用 radius: 4；line 用 lineWidth: 2；area 用 fillOpacity: 0.5~0.6；这些值需显式写在 style 里，不是省略即生效；不需要渐变、阴影或自定义动画。
16. 文本只用已知语义：字段/单位/来源明确时，添加语义化轴标题、tooltip 名称和 formatter；报告语境或用户提供标题时添加顶层 title；信息未知时省略，不编造单位、来源或副标题。
17. 标签按密度选择：少量且需精确读取的数据可加标签；密集散点、多系列折线、类别很多时默认依赖 tooltip；inside 标签用 contrastReverse，发生碰撞时使用 overlapHide / overlapDodgeY / overflowHide；dx / dy 只用于避让后的细微调整。
18. 特殊图：饼/环图的少量类别优先外置标签，类别较多时改用 legend，不要默认同时重复两者；气泡图保持 G2 默认 sqrt size 映射，按数据范围设置 size.range，仅在 size legend 无助理解时隐藏它。
19. 渐变、阴影、滑块、滚动条、自定义动画和 3D 气泡都属于用户明确要求“报告级/精致”时的增强项；添加前必须确认不会掩盖数据或降低标签对比度。
20. 按用户意图使用 Quick Reference 检索具体图表示例和配置：图表初始化 query=chart+init；柱状图 query=bar+chart+interval；折线/面积图 query=line+area+chart；饼图/环图/玫瑰图 query=pie+chart+theta；散点/气泡 query=scatter+point+bubble；矩形树图/旭日图/打包图 query=treemap+sunburst+pack；热力图/密度图/箱线图 query=heatmap+density+boxplot；漏斗图/仪表盘/词云 query=funnel+gauge+wordcloud；编码通道 query=encode+channel；比例尺/调色板/颜色范围 query=scale+palette+color；坐标系 query=coordinate+polar+theta+transpose；变换 query=transform+stack+normalize；坐标轴/图例/tooltip/标签 query=axis+legend+tooltip+label；交互 query=interaction+brush+highlight；主题/深色模式 query=theme+dark+classicDark；默认视觉基线 query=default+aesthetics+design；动画 query=animation+animate；数据获取/过滤/排序 query=data+fetch+filter+sort；分面/视图组合 query=facet+view+composition；图表类型选择 query=chart+type+selection；渲染排错 query=rendering+troubleshoot+debug。
21. 依赖：@antv/g2（G2 v5 图表引擎）。

适用边界 · 注意事项

• 不要用于 G6 图/网络可视化。
• 不要用于 X6 编辑器图表。
• 不要用于 S2 透视表。