v4 升级 v5 指南

G2 栈团队还会继续维护 v4 版本，针对 Bug 发布 Patch 版本修复，但是此后不再接收新的 Feature Request，截止日期为 2023 年年底。原 v4 官网迁移至 https://g2-v4.antv.vision/ 。

本文旨在帮助那些已经熟悉 G24.0 的用户了解 4.0 和 5.0 版本之间的区别。读者可以选择直接阅读新的文档，而不需要从头到尾阅读本文。本文将突出显示两个版本之间各个概念对应 API 的变化。

大小（Dimension）

4.0 的 padding 和 appendPadding 是一个数组，5.0 将其拆开了并且修改 appendPadding 为 margin。

// 4.0
const chart = new Chart({
  width: 600,
  height: 400,
  padding: [10, 20, 30, 40],
  appendPadding: [10, 20, 30, 40],
});

// 5.0
const chart = new Chart({
  width: 600,
  height: 400,
  paddingLeft: 10,
  paddingTop: 20,
  paddingRight: 30,
  paddingBottom: 40,
  marginLeft: 10,
  marginTop: 20,
  marginRight: 30,
  marginBottom: 40,
});

数据（Data）

4.0 中每个视图和一份数据绑定，该视图中的标记（前几何元素）共用一份数据。5.0 中每个视图中的所有标记可以有独立的数据，默认会同步比例尺。

// 4.0
chart.data(data);
chart.line();
chart.point();

// 5.0
chart.options({
  type: 'view',
  children: [
    { type: 'line', data: data1 },
    { type: 'line', data: data2 },
  ],
});

编码（Encode）

5.0 在编码方式上和 4.0 有以下的一系列不同：

声明方式

4.0 通过 geometry.position、geometry.color 等顶层 API 去编码通道。5.0 通过 mark.encode 去编码，并且不支持 * 语法。

// 4.0
chart.interval().position('name*value').color('genre');

// 5.0
chart.options({
  type: 'interval',
  encode: { x: 'name', y: 'value', color: 'genre' },
});

回调参数

4.0 中编码的回调，会从原始数据里面提供对应的字段。5.0 中编码的回调只提供原始数据。

// 4.0
chart.interval().color('name*value', (name, value) => {});

// 5.0
chart.options({
  type: 'interval',
  // 需要自己解构
  encode: { color: ({ name, value }) => {} },
});

回调返回值

4.0 回调返回视觉数据。5.0 回调默认返回抽象数据。

// 4.0
chart.interval().color('name', (name) => (name > 10 ? 'red' : 'yellow'));

// 5.0
chart.options({
  type: 'interval',
  encode: { color: (d) => (d.name > 10 ? 'high' : 'low') }, // 抽象数据
  scale: { color: { range: ['red', 'yellow'] } }, // 指定值域
});

// 5.0
chart.options({
  type: 'interval',
  encode: { color: (d) => (d.name > 10 ? 'red' : 'yellow') },
  scale: { color: { type: 'identity' } },
});

颜色值域

4.0 通过 geometry.color 的第二个参数声明颜色值域，5.0 通过 scale.color 指定。

// 4.0
chart.interval().color('name', ['red', 'blue']);
chart.interval().color('name', '#fff-#000');

// 5.0
chart.options({
  type: 'interval',
  encode: { color: 'name' }, // 离散
  scale: { color: { range: ['red', 'blue'] } },
});

chart.options({
  type: 'interval',
  encode: { color: 'name' }, //连续
  scale: { color: { range: '#fff-#000' } },
});

时序通道

4.0 会尝试解析时间字符串，5.0 不会去尝试解析，需要显示地转换成 Date 对象。

const data = [
  { year: '2020-10-01', value: 1 },
  { year: '2022-10-01', value: 2 },
  { year: '2023-10-01', value: 3 },
];

// 4.0
chart.line().position('year*value');

// 5.0
chart.options({
  type: 'line',
  encode: { x: (d) => new Date(d.year), y: 'value' },
});

样式（Style）

4.0 中样式的回调作用于整个对象上。5.0 中作用于每一个属性。

// 4.0
chart
  .interval()
  .style('a*b', (a, b) =>
    a + b > 10
      ? { stroke: 'red', strokeWidth: 10 }
      : { stroke: 'black', strokeWidth: 5 },
  );

// 5.0
chart.options({
  type: 'interval',
  style: { stroke: ({ a, b }) => (a + b > 10 ? 'red' : 'black'), strokeWidth: ({ a, b }) => (a + b > 10 ? 10 : 5) },
});

比例尺（Scale）

5.0 在比例尺的使用下和 4.0 有以下的一系列不同：

绑定对象

4.0 的比例尺是和字段绑定的，5.0 的比例尺是和通道绑定。

const data = [
  { genre: 'Sports', sold: 275 },
  { genre: 'Strategy', sold: 115 },
  { genre: 'Action', sold: 120 },
  { genre: 'Shooter', sold: 350 },
  { genre: 'Other', sold: 150 },
];

// 4.0
chart.data(data);
chart.scale('genre', {});
chart.interval().color('genre');

// 5.0
chart.options({
  type: 'interval',
  data,
  encode: { color: 'genre' },
  // 设置 color 通道比例尺
  scale: { color: {} },
});

属性

比例尺的部分属性变化如下：

• 定义域：values -> domain
• 定义域最小值：min -> domainMin
• 定义域最大值：max -> domainMax

// 4.0
chart.scale('genre', { values: ['a', 'b', 'c'] });

// 5.0
chart.options({ type: 'view', scale: { color: { domain: ['a', 'b', 'c'] } } });

离散比例尺

4.0 的离散比例尺有 cat 和 timeCat，在 5.0 中 cat 变成了 band，point 和 ordinal 比例尺，timeCat 被移除了。

// 4.0
chart.scale('genre', { type: 'cat' });

// 5.0
chart.options({
  type: 'interval',
  encode: { x: 'name', color: 'name' },
  // interval 的 x 通道默认是 band 比例尺
  scale: { x: { type: 'band', range: [0.1, 0.9] }, color: { type: 'ordinal', range: ['red', 'blue'] } },
});

chart.options({
  type: 'point',
  encode: { x: 'name' },
  // point 比例尺
  scale: { point: {} },
});

坐标系（Coordinate）

4.0 坐标系属性在 cfg 里面，通过 actions 去指定坐标系变换；5.0 坐标系属性平铺，同时通过 transform 去声明坐标系变换。

// 4.0
chart.coordinate({
  type: 'polar',
  cfg: {
    radius: 0.85,
  },
  actions: [['transpose']],
});

// 5.0
chart.options({
  type: 'view',
  coordinate: {
    type: 'polar',
    outerRadius: 0.85,
    transform: [{ type: 'transpose' }],
  },
});

标签（Label）

4.0 每个元素只能声明一个标签，5.0 每个元素可以声明多个标签。

// 4.0
chart.interval().label('field', (d) =>
  d > 10
    ? 'red'
    : 'blue'
    ? {
        style: { color: 'red', stroke: 'red' },
      }
    : {
        style: { color: 'black', stroke: 'black' },
      },
);

// 5.0
chart.options({
  type: 'interval',
  labels: [
    {
      text: 'field', // 指定内容
      style: {
        fill: (d) => (d > 10 ? 'red' : 'black'), // 设置属性
        stroke: (d) => (d > 10 ? 'red' : 'black'),
      },
    },
    { text: (d) => d.value },
  ],
});

提示信息（Tooltip）

4.0 可以通过 tooltip.containerTpl 自定义提示信息，5.0 通过 render 函数自定义提示信息。

// 4.0
chart.tooltip({ containerTpl: `<div></div>` });

// 5.0
chart.options({
  type: 'view',
  interaction: {
    tooltip: {
      render: () => `<div></div>`,
    },
  },
});

动画（Animation）

4.0 中有 appear 动画，5.0 将其合并到了 enter 动画里面去。

// 4.0
chart.interval().animate({
  appear: {
    animation: 'fade-in',
    easing: 'easeQuadIn',
    delay: 100,
    duration: 600,
  },
});

// 5.0
chart.options({
  type: 'interval',
  animate: { enter: { type: 'fadeIn', easing: 'easeQuadIn', delay: 100, duration: 600 } },
});

交互（Interaction）

4.0 通过 chart.removeInteraction(name) 移除交互，5.0 通过 chart.interaction(name, false) 移除交互。

// 4.0
chart.removeInteraction('tooltip');

// 5.0
chart.options({ type: 'view', interaction: { tooltip: false } });

标注（Annotation）

在 4.0 中图中的元素分为几何元素（Geometry）和标注（Annotation），在 5.0 中两者都是标注（Mark）。

声明方式

在 4.0 中标注通过 annotation 这个名称空间去声明，5.0 声明方式和标记保持一致。

// 4.0
chart.annotation().line({});

// 5.0
chart.options({ type: 'lineX' });

标注特定值

在 4.0 通过 start 和 end 去标注特定值，5.0 通过 transform 去标注特定值。

// 4.0
chart.annotation().line({
  start: ['min', 'mean'],
  end: ['max', 'mean'],
});

// 5.0
chart.options({
  type: 'lineX',
  encode: { y: 'value' },
  // 选择 y 通道最小的值
  transform: [{ type: 'selectY', y: 'mean' }],
});

分面（Facet）

4.0 分面通过 facet 这个名称空间去声明，5.0 和标记保持一致。

// 4.0
chart.facet('rect', {
  fields: ['cut', 'clarity'],
  eachView(view) {
    view
      .point()
      .position('carat*price')
      .color('cut')
      .shape('circle')
      .style({ fillOpacity: 0.3, stroke: null })
      .size(3);
  },
});

// 5.0
chart.options({
  type: 'facetRect',
  encode: { x: 'cut', y: 'clarity' },
  children: [
    {
      type: 'point',
      encode: { x: 'carat', y: 'price', color: 'cut', shape: 'point', size: 3 },
      style: { fillOpacity: 0.3, stroke: null },
    },
  ],
});