antv-gpt-vis

注意：在 Markdown 模式下，内容区域必须包含第一行 vis <type>，与纯语法模式格式一致。

代码模式

根据目标框架生成完整的可运行代码。

安装

NPM：

npm install @antv/gpt-vis

import { GPTVis } from '@antv/gpt-vis';

CDN：

<script src="https://unpkg.com/@antv/gpt-vis/dist/umd/index.min.js"></script>

通过 CDN 加载后，可通过 GPTVis.GPTVis 访问主类。

完整 HTML 示例

<html>
  <head>
    <script src="https://unpkg.com/@antv/gpt-vis/dist/umd/index.min.js"></script>
  </head>
  <body>
    <div id="container"></div>
    <script>
      const gptVis = new GPTVis.GPTVis({
        container: '#container',
        width: 600,
        height: 400,
      });

      gptVis.render(`
vis line
data
  - time 2020
    value 100
  - time 2021
    value 120
title Annual Trend
`);
    </script>
  </body>
</html>

图表类型配置

通用配置

所有图表都包含以下字段，下文各图表类型定义中不再列出。每个小节标题就是 type 的值（例如 line、column），与上方图表类型表中的类型列相对应。

{ type: string; title?: string; theme?: 'default' | 'light' | 'dark' | 'academy'; style?: { backgroundColor?: string; palette?: string[] } }

line / area

{ data: { time: string | number; value: number; group?: string }[]; axisXTitle?: string; axisYTitle?: string; stack?: boolean; style?: { lineWidth?: number } }

stack 仅适用于 area。

column / bar

{ data: { category: string; value: number; group?: string }[]; axisXTitle?: string; axisYTitle?: string; stack?: boolean; group?: boolean }

pie

值不能是百分比数值。

{ data: { category: string; value: number }[]; innerRadius?: number }

将 innerRadius 设为 0.6，即可将其转换为环形图。

scatter

{ data: { x: number; y: number; group?: string }[]; axisXTitle?: string; axisYTitle?: string }

dual-axes

{ categories: string[]; series: { type: 'line' | 'column'; data: number[]; axisYTitle?: string }[]; axisXTitle?: string; style?: { startAtZero?: boolean } }

histogram

{ data: number[]; binNumber?: number; axisXTitle?: string; axisYTitle?: string }

boxplot / violin

同一类别需要有多个数据点才能显示分布。

{ data: { category: string; value: number; group?: string }[]; axisXTitle?: string; axisYTitle?: string; style?: { startAtZero?: boolean } }

radar

{ data: { name: string; value: number; group?: string }[]; align?: boolean }

align：是否对齐所有维度的刻度。默认为 false（每个轴独立缩放）；设为 true 时，所有轴共享相同的最大值，适合比较多个系列的绝对值。

funnel

{ data: { category: string; value: number; }[]; }

waterfall

值可以为负数，以表示减少。palette 是一个颜色数组，顺序为［正值颜色、负值颜色、总计颜色］。

{ data: { category: string; value: number }[]; axisXTitle?: string; axisYTitle?: string; style?: { palette?: string[] } }

liquid

percent 的取值范围为 0 到 1。

{ percent: number; shape?: 'rect' | 'circle' | 'pin' | 'triangle' }

word-cloud

{ data: { text: string; value: number; }[]; }

venn

交集使用逗号分隔集合标识符：sets: "A,B"。label 用于在图表上显示相应集合的名称。

{ data: { sets: string | string[]; value: number; label?: string }[] }

treemap

type TreeNode = { name: string; value: number; children?: TreeNode[] };
{ data: TreeNode[] }

sankey

{ data: { source: string; target: string; value: number }[]; nodeAlign?: 'left' | 'center' | 'right' | 'justify' }

flow-diagram / network-graph

source/target 引用节点的 name 值。

type GraphData = { nodes: { name: string }[]; edges: { source: string; target: string; name?: string }[] };

// flow-diagram
{ data: GraphData }

// network-graph
{ data: GraphData; layout?: 'force' | 'circular' | 'grid' | 'radial' | 'concentric' | 'dagre' }

mindmap / indented-tree / organization-chart

type TreeData = { name: string; children?: TreeData[] };

// mindmap
{ data: TreeData; direction?: 'H' | 'LR' | 'RL' }

// indented-tree
{ data: TreeData; direction?: 'LR' | 'RL' | 'H' }

// organization-chart
type OrganizationChartData = {
  name: string;
  description?: string;
  children?: OrganizationChartData[];
};

{ data: OrganizationChartData }

mindmap 默认为 'H'；indented-tree 默认为 'LR'。

fishbone-diagram

type FishboneNode = { name: string; children?: FishboneNode[] };
{ data: FishboneNode; style?: { texture?: 'rough' | 'default' } }

texture: 'rough' 会生成手绘风格。

table

{ data: Record<string, string | number>[]; }

summary

summary 与其他图表类型完全不同：它不使用 Syntax/JSON 配置，而是使用 T8 语法（Markdown + 语义注释）。

⚠️ 生成 summary 之前，必须：先阅读 references/summary.md，了解 T8 语法规则、完整的实体类型列表、属性字段定义、生成要求和示例，然后再生成内容。跳过此步骤会导致语法错误。

最佳实践

1. 饼图的类别数不要超过 5 个；其余类别合并为“其他”，或改用条形图
2. 不要用饼图展示趋势，也不要用折线图展示无序类别
3. 数值字段必须为数值类型；类别字段必须为文本类型
4. 连续值（例如薪资、分数、年龄）的分布必须使用直方图
5. 多维字段映射：有两个分类维度时，将 x 轴维度写为 time/category，另一个写为 group
6. 在 Syntax 模式下，优先使用 Syntax 格式（便于流式处理）
7. 在 Code 模式下，默认采用 HTML + CDN 方式（无需安装）；仅在用户指定框架时才使用 npm 方式