English | 简体中文

GPT-Vis

✨ 特性

• 🚀 框架无关 — 原生 JavaScript、React、Vue、Angular，任何框架均可使用
• ✍️ 类 Markdown 语法 — LLM 可以直接生成的简洁语法，易学易用
• 🌊 流式渲染 — 原生支持 AI 模型流式输出，边生成边渲染
• 🛡️ 高容错 — 优雅处理不完整、格式异常的数据，适配 AI 生成内容的不确定性
• 📊 26 种图表 — 统计图表、关系图表、文本可视化，覆盖主流场景
• 🎨 可复用主题 — 一份 ThemeSpec 应用于所有图表，在 Theme Studio 预览微调，也可通过 AI Skill 创建

🚀 快速开始

安装

npm install @antv/gpt-vis

基础用法

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

const gptVis = new GPTVis({
  container: 'container',
  width: 600,
  height: 400,
});

gptVis.render({
  type: 'line',
  data: [
    { time: '2020', value: 100 },
    { time: '2021', value: 120 },
    { time: '2022', value: 150 },
  ],
});

流式渲染

AI 模型边生成、图表边渲染，无需等待完整响应：

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

const gptVis = new GPTVis({ container: 'container', width: 600, height: 400 });
let buffer = '';

function onToken(token) {
  buffer += token;
  if (isVisSyntax(buffer)) {
    gptVis.render(buffer);
  }
}

📚 语法指南

render() 支持两种输入格式：对象配置（适合程序化调用）和 DSL 语法（适合 LLM 流式生成）。

对象配置

直接传入 JSON 对象，适合程序化图表创建：

折线图：

gptVis.render({
  type: 'line',
  data: [
    { time: '2020', value: 100 },
    { time: '2021', value: 120 },
    { time: '2022', value: 150 },
  ],
});

饼图：

gptVis.render({
  type: 'pie',
  data: [
    { category: 'Android', value: 72 },
    { category: 'iOS', value: 28 },
  ],
  innerRadius: 0.6,
});

主题：

内置三套主题，通过 theme 属性切换：

gptVis.render({
  type: 'line',
  data: [
    { time: '2020', value: 100 },
    { time: '2021', value: 120 },
  ],
  theme: 'dark',
});

可复用的自定义主题：

向构造函数的 theme 传入 ThemeSpec 对象，即可让全部 26 种图表共享颜色、字体、间距和 Mark 样式，包括关系图、Table 和 Summary：

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

const theme: ThemeSpec = {
  id: 'my-report',
  label: 'My report',
  tokens: { colorDefault: '#7047eb', fontFamily: 'Arial, sans-serif', radius: 6 },
};
const chart = new GPTVis({ container: '#chart', theme });

优先级：单图 config > 自定义 ThemeSpec > GPT-Vis 内置主题。具体合并顺序：内置默认值 < Tokens < 全局 style < charts[type].style < 单图 style。嵌套对象合并，数组整体替换。单图显式指定 theme 时，会替换构造函数选择的主题。Summary 通过构造函数接收主题，渲染输入仍为 T8 文本，没有单次渲染的 style 对象入口。

可在 Theme Studio 预览和分享主题，阅读主题文档，或使用主题创建指南 根据品牌参考资料生成 ThemeSpec。

工作台的预设是 ThemeSpec 示例，使用时需要把完整对象传给 theme；id 只是元数据，不是已注册的主题名称。

自定义样式：

gptVis.render({
  type: 'line',
  data: [
    { time: '2020', value: 100 },
    { time: '2021', value: 120 },
  ],
  style: { mark: { line: { lineWidth: 3 } }, palette: ['#5B8FF9', '#5AD8A6'] },
});

DSL 语法

类 Markdown 的声明式语法，LLM 无需学习复杂 API 即可生成：

vis [图表类型]
[属性] [值]
data
  - [字段] [值]

饼图：

vis pie
data
  - category 销售
    value 30
  - category 市场
    value 25
innerRadius 0.6

主题：

vis line
data
  - time 2020
    value 100
  - time 2021
    value 120
theme dark

自定义样式：

通过 style 设置线宽、自定义配色等：

vis line
data
  - time 2020
    value 100
  - time 2021
    value 120
style
  mark
    line
      lineWidth 3
  palette
    - #5B8FF9
    - #5AD8A6

包含空格的值用引号包裹：

vis pie
data
  - category "Q1 销售额"
    value 30
  - category "Q2 销售额"
    value 25

层级数据：

vis mindmap
data
  - name 项目规划
    children
      - name 第一阶段
      - name 第二阶段

使用 DSL 语法渲染：

const visSyntax = `
vis line
data
  - time 2020
    value 100
  - time 2021
    value 120
  - time 2022
    value 150
`;

gptVis.render(visSyntax);

📊 图表类型

支持 26 种图表，覆盖统计分析、关系网络、文本可视化三大类。

统计图表（18 种）

关系图表（6 种）

文本可视化（2 种）

查看全部示例 → 图表示例

🔧 框架集成

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

const gptVis = new GPTVis({ container: 'chart', width: 600, height: 400 });
gptVis.render(visSyntaxString);

import { GPTVis } from '@antv/gpt-vis';
import { useEffect, useRef } from 'react';

function ChartComponent({ visSyntax }) {
  const containerRef = useRef();
  const gptVisRef = useRef();

  useEffect(() => {
    gptVisRef.current = new GPTVis({ container: containerRef.current, width: 600, height: 400 });
    return () => gptVisRef.current?.destroy();
  }, []);

  useEffect(() => {
    if (gptVisRef.current && visSyntax) {
      gptVisRef.current.render(visSyntax);
    }
  }, [visSyntax]);

  return <div ref={containerRef} />;
}

<template>
  <div ref="chartRef"></div>
</template>

<script setup>
import { ref, watch, onUnmounted } from 'vue';
import { GPTVis } from '@antv/gpt-vis';

const props = defineProps(['visSyntax']);
const chartRef = ref(null);
let gptVis = null;

watch(
  () => props.visSyntax,
  (syntax) => {
    if (!gptVis) {
      gptVis = new GPTVis({ container: chartRef.value, width: 600, height: 400 });
    }
    gptVis.render(syntax);
  },
  { immediate: true },
);

onUnmounted(() => gptVis?.destroy());
</script>

npm install @antv/gpt-vis marked marked-highlight highlight.js

import { Marked } from 'marked';
import { markedHighlight } from 'marked-highlight';
import hljs from 'highlight.js';
import { GPTVis } from '@antv/gpt-vis';

class GPTVisElement extends HTMLElement {
  connectedCallback() {
    const syntax = decodeURIComponent(this.dataset.syntax);
    this._instance = new GPTVis({ container: this });
    this._instance.render(syntax);
  }
  disconnectedCallback() {
    this._instance?.destroy();
  }
}
if (!customElements.get('gpt-vis')) {
  customElements.define('gpt-vis', GPTVisElement);
}

const marked = new Marked(
  markedHighlight({
    langPrefix: 'hljs language-',
    highlight(code, lang) {
      if (lang?.startsWith('vis')) return code;
      const language = hljs.getLanguage(lang) ? lang : 'plaintext';
      return hljs.highlight(code, { language }).value;
    },
  }),
  {
    renderer: {
      code({ text, lang }) {
        if (lang?.startsWith('vis')) {
          const syntax = encodeURIComponent(lang + '\n' + text);
          return `<gpt-vis data-syntax="${syntax}" style="min-height:300px"></gpt-vis>`;
        }
        return false;
      },
    },
  },
);

const markdown = `# My Report

\`\`\`vis bar
data
  - category Python
    value 28.1
  - category JavaScript
    value 18.5
  - category Java
    value 15.6
  - category "C/C++"
    value 12.3
title 2024 Programming Language Popularity
\`\`\`
`;

document.getElementById('content').innerHTML = marked.parse(markdown);

🧩 Shadcn/ui

通过 shadcn CLI 将 GPT-Vis React 组件直接复制到你的项目中 — 完全源代码控制，高度可定制。

基础组件

通用的 GPTVis 组件，支持全部 26 种图表类型的 vis 语法字符串或 JSON 配置对象：

npx shadcn@latest add @gpt-vis/gpt-vis

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

<GPTVis
  content="vis line
data
  - time 2020
    value 100
  - time 2021
    value 120
  - time 2022
    value 150
title 销售趋势"
  theme="academy"
/>;

类型化图表组件

每种图表类型都有独立的组件，提供类型安全的 config 属性 — 仅支持 JSON，带 TypeScript 类型校验：

npx shadcn@latest add @gpt-vis/line

import { Line } from '@/components/ui/line';

<Line
  config={{
    data: [
      { time: '2020', value: 100 },
      { time: '2021', value: 120 },
      { time: '2022', value: 150 },
    ],
    title: '销售趋势',
    axisXTitle: '年份',
  }}
  height={400}
/>;

全部 26 种图表类型均可用，按名称安装即可：

npx shadcn@latest add @gpt-vis/pie
npx shadcn@latest add @gpt-vis/bar
npx shadcn@latest add @gpt-vis/mindmap
# ...等等

每个类型化组件自动将基础 GPTVis 组件作为依赖安装。width、height、theme、wrapper、locale、className、containerStyle 等属性在所有组件中保持一致。

🤖 AI 生态

GPT-Vis 提供完整的 AI 集成方案：

• MCP 服务 — 通过 Model Context Protocol 让 AI 模型直接调用可视化能力
• 图表技能 — 为 AI 助手提供图表选择、JSON、Syntax 和集成代码生成能力，内含 Theme Creator 参考文档，可创建可复用的自定义主题

🤝 贡献

AI 生成代码策略：本项目仅合并 AI 生成的代码。

1. 提交 Issue 描述问题或需求
2. 标记 @copilot 生成实现方案
3. 提交包含 AI 生成代码的 PR

📄 开源协议

MIT © AntV