当前位置：首页 > news >正文

Antv AVA入门教程

news 来源：原创 2025/6/19 7:12:00

以下教程聚焦 AVA 核心包中的 CKB（Chart Knowledge Base）模块，详细介绍其安装、引入及核心 API，每个方法均给出完整示例代码。

一、安装

# 安装 AVA 核心包，包含 ckb 模块
npm install @antv/ava --save
# 如需单独使用 CKB JSON，也可安装独立包
npm install @antv/ckb --save

二、模块引入

2.1 从 `@antv/ava` 引入

import { ckb } from '@antv/ava';

2.2 从 `@antv/ckb` 引入

import { CKBJson } from '@antv/ckb';

两者都能获取完整的知识库 JSON 对象，区别在于前者依赖 AVA 核心包，后者仅含知识库内容 ([npmjs.com][1]) ([npmjs.com][2])。

三、核心 API

3.1 `ckb(locale?: string, completed?: boolean): Record<string, ChartInfo>`

功能：获取图表知识库对象。
参数：
- locale（可选）：语言标识，支持 'en'（默认）或 'zh-CN'。
- completed（可选）：是否只返回“已完成”高质量定义，布尔值，默认 false。
返回值：以图表 id 为键、ChartInfo 对象为值的字典。

import { ckb } from '@antv/ava';// 默认获取英文版、非“完成度”过滤
const kbEn = ckb();
console.log(Object.keys(kbEn)); 
// ['line_chart', 'bar_chart', 'pie_chart', …]// 获取中文“已完成”版本
const kbZh = ckb('zh-CN', true);
console.log(kbZh['line_chart'].name); 
// '折线图'

3.2 `CKBJson(locale?: string, completed?: boolean): Record<string, ChartInfo>`

功能：与 ckb 相同，直接从独立包获取知识库。
用法：

import { CKBJson } from '@antv/ckb';// 获取中文完整版
const kb = CKBJson('zh-CN', true);
console.log(kb['bar_chart'].def);
/*'柱状图用矩形条的高度（或长度）来表示数据值的大小，适用于展示离散或分组数据的比较。'
*/

四、`ChartInfo` 对象结构

每个 ChartInfo 包含如下字段：

字段	类型	含义
`id`	`string`	图表类型标识，如 `line_chart`
`name`	`string`	图表名称
`alias`	`string[]`	别名列表
`family`	`string[]`	所属图表家族，如 `['LineCharts']`
`def`	`string`	图表定义
`purpose`	`string[]`	使用场景，如 `['Trend', 'Comparison']`
`coord`	`string[]`	支持的坐标系，如 `['Cartesian2D']`
`category`	`string[]`	分类，如 `['Statistic']`
`shape`	`string[]`	图形形状，如 `['Lines']`
`dataPres`	`Array<Object>`	数据需求定义
`channel`	`string[]`	通道，如 `['Position', 'Direction']`
`recRate`	`string`	推荐等级，如 `'Recommended'`

以上结构基于 @antv/ckb 官方示例 ([npmjs.com][2])。

五、使用示例

5.1 列出所有图表名称

const kb = ckb('en', true);
const names = Object.values(kb).map(item => item.name);
console.log(names);
// ['Line Chart', 'Bar Chart', 'Pie Chart', …]

5.2 按“使用场景”筛选图表

// 筛选出“对比”（Comparison）场景下的所有图表
const comparisonCharts = Object.values(kb).filter(item => item.purpose.includes('Comparison')
);
comparisonCharts.forEach(chart => {console.log(`${chart.name}：${chart.def}`);
});

5.3 获取单个图表详情

const lineChart = kb['line_chart'];
console.log(`名称：${lineChart.name}`);
console.log(`定义：${lineChart.def}`);
console.log(`坐标系：${lineChart.coord.join(', ')}`);