# @antv/gpt-vis 中文文档

规范地址：https://npmcn.com/package/%40antv/gpt-vis/

版本：1\.3\.1
npm 元数据更新时间：2026-11-04T08:10:45.071Z
中文译文更新时间：2026-11-06T07:20:14.785Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40antv/gpt-vis
原文对照：https://npmcn.com/package/%40antv/gpt-vis/?lang=original
项目主页：https://gpt-vis.antv.vision/
源码仓库：https://github.com/antvis/GPT-Vis

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3.2 MB，209 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：6 个
- 首次发布：2024-08-14T12:40:38.831Z
- 最新版本发布：2026-11-04T08:10:44.539Z
- 近 30 天下载量：31777（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：51（近 12 个月 16 个）

## 中文简介

GPT、基因AI和LLM项目的组件。 不只是UI组件.

## 安装

```sh
npm install @antv/gpt-vis
```

也可以使用：`pnpm add @antv/gpt-vis`、`yarn add @antv/gpt-vis`、`bun add @antv/gpt-vis`

## README

![](https://gw.alipayobjects.com/zos/antfincdn/R8sN%24GNdh6/language.svg) [English](https://npmcn.com/package/%40antv/gpt-vis/README.md) | 简体中文

![](https://github.com/eosphoros-ai/GPT-Vis/assets/17919400/c8804ffb-d3d6-45d3-846f-cf217681ab05)

# GPT-Vis

面向 LLM 时代的 AI 原生可视化库，框架无关，开箱即用。

[![npm version](https://img.shields.io/npm/v/@antv/gpt-vis.svg)](https://www.npmjs.com/package/@antv/gpt-vis) [![npm downloads](https://img.shields.io/npm/dm/@antv/gpt-vis.svg)](https://www.npmjs.com/package/@antv/gpt-vis) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/%40antv/gpt-vis/LICENSE)

[📖 文档](https://gpt-vis.antv.vision/) · [🎨 图表示例](https://gpt-vis.antv.vision/examples) · [🔌 MCP 服务](https://github.com/antvis/mcp-server-chart) · [🧩 图表技能](https://npmcn.com/skills/chart-visualization)

![GPT-Vis Hero Image](https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*yNtZT47dH1kAAAAAgBAAAAgAemJ7AQ/fmt.webp)

  

## ✨ 特性

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

## 🚀 快速开始

### 安装

```bash
npm install @antv/gpt-vis
```

### 基础用法

```javascript
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 模型边生成、图表边渲染，无需等待完整响应：

![](https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*_xY7Q6QyuZ4AAAAAWeAAAAgAemJ7AQ/original)

```javascript
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 对象，适合程序化图表创建：

**折线图：**

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

**饼图：**

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

**主题：**

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

| 主题 | 标识 | 背景色 | 色板 |
| --- | --- | --- | --- |
| 默认（亮色） | `default` | `#FFF` | `#5B6CFF` `#2DAF9E` `#F2B84B` `#EF6A6A` `#55A6D9` ... |
| 暗色 | `dark` | `#141414` | `#5B6CFF` `#2DAF9E` `#F2B84B` `#EF6A6A` `#55A6D9` ... |
| 学术 | `academy` | `#FFF` | `#4e79a7` `#f28e2c` `#e15759` `#76b7b2` `#59a14f` ... |

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

**可复用的自定义主题：**

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

```typescript
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](https://gpt-vis.antv.vision/themes) 预览和分享主题，阅读[主题文档](https://gpt-vis.antv.vision/docs#custom-themes)，或使用[主题创建指南](https://npmcn.com/package/%40antv/gpt-vis/skills/chart-visualization/references/theme-creator.md) 根据品牌参考资料生成 ThemeSpec。

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

**自定义样式：**

```javascript
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 语法渲染：**

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

gptVis.render(visSyntax);
```

## 📊 图表类型

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

### 统计图表（18 种）

| 图表 | 类型标识 |
| --- | --- |
| 折线图 | `line` |
| 面积图 | `area` |
| 柱状图 | `column` |
| 条形图 | `bar` |
| 饼图 | `pie` |
| 散点图 | `scatter` |
| 雷达图 | `radar` |
| 漏斗图 | `funnel` |
| 瀑布图 | `waterfall` |
| 双轴图 | `dual-axes` |
| 直方图 | `histogram` |
| 箱线图 | `boxplot` |
| 小提琴图 | `violin` |
| 韦恩图 | `venn` |
| 桑基图 | `sankey` |
| 树图 | `treemap` |
| 词云 | `word-cloud` |
| 水波图 | `liquid` |

### 关系图表（6 种）

| 图表 | 类型标识 |
| --- | --- |
| 流程图 | `flow-diagram` |
| 网络图 | `network-graph` |
| 思维导图 | `mindmap` |
| 缩进树 | `indented-tree` |
| 组织架构图 | `organization-chart` |
| 鱼骨图 | `fishbone-diagram` |

### 文本可视化（2 种）

| 图表 | 类型标识 |
| --- | --- |
| 表格 | `table` |
| 文本摘要 | `summary` |

查看全部示例 → [图表示例](https://gpt-vis.antv.vision/examples)

## 🔧 框架集成

**原生 JavaScript**

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

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

```jsx
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} />;
}
```
**Vue**

```vue
<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>
```
**Markdown 渲染器（marked）**

GPT-Vis 的 vis 语法天然兼容 Markdown code fence，可以与任何 Markdown 渲染器集成。以下示例使用 `marked` + `marked-highlight`，普通代码块走语法高亮，`vis` 代码块自动渲染为交互式图表。

**安装依赖：**

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

**完整示例：**

```javascript
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 配置对象：

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

```tsx
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 类型校验：

```bash
npx shadcn@latest add @gpt-vis/line
```

```tsx
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 种图表类型均可用，按名称安装即可：

```bash
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 服务](https://github.com/antvis/mcp-server-chart)** — 通过 Model Context Protocol 让 AI 模型直接调用可视化能力
-   **[图表技能](https://github.com/antvis/GPT-Vis/tree/main/skills/chart-visualization)** — 为 AI 助手提供图表选择、JSON、Syntax 和集成代码生成能力，内含 Theme Creator 参考文档，可创建可复用的自定义主题

## 🤝 贡献

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

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

## 📄 开源协议

[MIT](https://npmcn.com/package/%40antv/gpt-vis/LICENSE) © [AntV](https://antv.antgroup.com/)

## 常见问题

### @antv/gpt-vis 是什么？

GPT、基因AI和LLM项目的组件。 不只是UI组件\.

### 如何安装 @antv/gpt-vis？

在项目目录运行 npm install @antv/gpt-vis，或使用 pnpm add / yarn add / bun add。

### @antv/gpt-vis 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @antv/gpt-vis 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @antv/gpt-vis 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @antv/gpt-vis 可以商用吗？

@antv/gpt-vis 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @antv/gpt-vis 的下载量有多少？

根据 npm 官方下载统计，@antv/gpt-vis 在 2026/10/06 – 2026/11/04 这 30 天内被下载 31,777 次，日均约 1,059 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @antv/gpt-vis 还在维护吗？

最新版本 1\.3\.1 发布于 2026/11/04（1 天前）；至今共发布 51 个版本，其中过去 12 个月发布了 16 个；首次发布于 2024/08/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。