Antv AVA入门教程

以下教程聚焦 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

• 功能：获取图表知识库对象。

• 参数：

  • 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

• 功能：与 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	数据需求定义
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(', ')}`);

---

六、常见配合场景

1. 图表推荐引擎：结合 ckb 返回的 purpose、dataPres 等字段，自定义规则进行推荐。
2. 多语言文档：通过 locale 参数快速切换中英文知识库。
3. 可视化教学：利用 alias、family、shape 等元信息，动态生成图表词典或教学手册。

---

七、小结

• ckb／CKBJson 是获取图表知识库的唯一入口，支持中英文与“完成度”过滤。
• 返回的 ChartInfo 对象涵盖图表的定义、使用场景、坐标系、形状、数据需求等，便于上层做自动化推荐和文档展示。
• 结合 JavaScript 原生对象操作（Object.keys、filter、map）即可灵活检索和使用知识库。