G2

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.line().data(data1);
chart.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
  .interval()
  .encode('x', 'name')
  .encode('y', 'value')
  .encode('color', 'genre');

回调参数

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

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

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

回调返回值

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

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

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

// 5.0
chart
  .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
  .interval()
  .encode('color', 'name') // 离散
  .scale('color', { range: ['red', 'blue'] });

chart
  .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
  .line()
  .encode('x', (d) => new Date(d.year))
  .encode('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
  .interval()
  .style('stroke', ({ a, b }) => (a + b > 10 ? 'red' : 'black'))
  .style('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
  .interval()
  .data(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.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
  .interval()
  .encode('x', 'name')
  .encode('color', 'name')
  // interval 的 x 通道默认是 band 比例尺
  .scale('x', { type: 'band', range: [0.1, 0.9] })
  .scale('color', { type: 'ordinal', range: ['red', 'blue'] });

chart
  .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.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
  .interval()
  .label({
    text: 'field', // 指定内容
    style: {
      color: d > 10 ? 'red' : 'black', // 设置属性
      stroke: d > 10 ? 'red' : 'black',
    },
  })
  .label({ text: (d) => d.value });

提示信息（Tooltip）

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

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

// 5.0
chart.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.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.interaction('tooltip', false);

标注（Annotation）

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

声明方式

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

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

// 5.0
chart.lineX();

标注特定值

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

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

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

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
  .facetRect()
  .encode('x', 'cut')
  .encode('y', 'clarity')
  .point()
  .encode('x', 'carat')
  .encode('y', 'price')
  .encode('color', 'cut')
  .encode('shape', 'point')
  .encode('size', 3)
  .style('fillOpacity', 0.3)
  .style('stroke', null);

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

大小（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.line().data(data1);
chart.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
  .interval()
  .encode('x', 'name')
  .encode('y', 'value')
  .encode('color', 'genre');

回调参数

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

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

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

回调返回值

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

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

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

// 5.0
chart
  .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
  .interval()
  .encode('color', 'name') // 离散
  .scale('color', { range: ['red', 'blue'] });

chart
  .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
  .line()
  .encode('x', (d) => new Date(d.year))
  .encode('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
  .interval()
  .style('stroke', ({ a, b }) => (a + b > 10 ? 'red' : 'black'))
  .style('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
  .interval()
  .data(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.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
  .interval()
  .encode('x', 'name')
  .encode('color', 'name')
  // interval 的 x 通道默认是 band 比例尺
  .scale('x', { type: 'band', range: [0.1, 0.9] })
  .scale('color', { type: 'ordinal', range: ['red', 'blue'] });

chart
  .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.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
  .interval()
  .label({
    text: 'field', // 指定内容
    style: {
      color: d > 10 ? 'red' : 'black', // 设置属性
      stroke: d > 10 ? 'red' : 'black',
    },
  })
  .label({ text: (d) => d.value });

提示信息（Tooltip）

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

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

// 5.0
chart.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.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.interaction('tooltip', false);

标注（Annotation）

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

声明方式

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

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

// 5.0
chart.lineX();

标注特定值

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

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

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

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
  .facetRect()
  .encode('x', 'cut')
  .encode('y', 'clarity')
  .point()
  .encode('x', 'carat')
  .encode('y', 'price')
  .encode('color', 'cut')
  .encode('shape', 'point')
  .encode('size', 3)
  .style('fillOpacity', 0.3)
  .style('stroke', null);

v4 升级 v5 指南

v4 升级 v5 指南

大小（Dimension）

数据（Data）

编码（Encode）

声明方式

回调参数

回调返回值

颜色值域

时序通道

样式（Style）

比例尺（Scale）

绑定对象

属性

离散比例尺

坐标系（Coordinate）

标签（Label）

提示信息（Tooltip）

动画（Animation）

交互（Interaction）

标注（Annotation）

声明方式

标注特定值

分面（Facet）

大小（Dimension）

数据（Data）

编码（Encode）

声明方式

回调参数

回调返回值

颜色值域

时序通道

样式（Style）

比例尺（Scale）

绑定对象

属性

离散比例尺

坐标系（Coordinate）

标签（Label）

提示信息（Tooltip）

动画（Animation）

交互（Interaction）

标注（Annotation）

声明方式

标注特定值

分面（Facet）