升级到 5.0

本文档将引导你从 G6 4.x 版本升级到 5.x 版本。如果你使用的是 3.x 版本，请先升级到 4.x 版本。

升级前准备

请确保当前 git 分支是干净的，没有未提交的代码。
参考安装文档安装 5.x 版本，并移除 4.x 版本依赖。

开始升级

数据

新版本的数据格式有所变化，具体如下：

nodes edges combos 中所有样式属性都需要放在 style 中，data 中存放数据属性：

// 4.x
const data = {
  nodes: [
    { id: 'node1', label: 'node1', size: 20 },
    { id: 'node2', label: 'node2', size: 20 },
  ],
  edges: [{ source: 'node1', target: 'node2' }],
};

// 5.x
const data = {
  nodes: [
    // label 为非样式属性，放在 data 中，可在样式映射函数中访问
    // size 为样式属性，放在 style 中
    { id: 'node1', data: { label: 'node1' }, style: { size: 20 } },
    { id: 'node2', data: { label: 'node2' }, style: { size: 20 } },
  ],
  edges: [{ source: 'node1', target: 'node2' }],
};

由于我们重新设计实现了元素，新的元素配置项请参考相应文档进行修改：

如果要在数据中指定元素类型，可以使用 type 属性：

{
  nodes: [
    // 指定节点类型为 rect
    { id: 'node1', type: 'rect' },
  ];
}

配置项

变更 fitView / fitCenter / fitViewPadding

fitView 和 fitCenter 配置项已经合并为 autoFit
若要使用 fitView，可以配置为 autoFit: 'view'
若要使用 fitCenter，可以配置为 autoFit: 'center'
也可以传入对象进行完整配置：

autoFit: {
  type: 'view',
  options: {
    // ...
  }
}

fitViewPadding 已变更为 padding

移除 linkCenter

5.x 的边连接机制会按照如下顺序依次尝试连接到节点/Combo：

连接桩
轮廓
中心

移除 groupByTypes

移除 autoPaint

请手动调用 render 或 draw 方法进行绘制。

变更 modes

5.x 已经移除交互模式，你可以通过设置 behaviors 来切换当前启用的交互行为。

// 4.x
{
  modes: {
    default: ['drag-canvas', 'zoom-canvas'],
    preview: ['drag-canvas'],
  },
}

graph.setMode('preview');

// 5.x
{
  behaviors: ['drag-canvas', 'zoom-canvas'],
}

graph.setBehaviors(['drag-canvas']);

变更 defaultNode / defaultEdge / defaultCombo

元素样式已移至 [element].style 中，如 defaultNode 变更为 node.style：

// 4.x
{
  defaultNode: {
    size: 20,
    fill: 'red',
  }
}

// 5.x
{
  node: {
    style: {
      size: 20,
      fill: 'red',
    }
  }
}

变更 nodeStateStyles / edgeStateStyles / comboStateStyle

元素状态样式已移至 [element].state 中，如 nodeStateStyles 变更为 node.stateStyles：

// 4.x
{
  nodeStateStyles: {
    selected: {
      fill: 'red',
    }
  }
}

// 5.x
{
  node: {
    state: {
      selected: {
        fill: 'red',
      }
    }
  }
}

变更 animate / animateCfg

animate 配置项已变更为 animation
animate 和 animateCfg 已合并为 animation

// 4.x
{
  animate: true,
}

// 5.x
{
  animation: true,
}
{
  animation: {
    duration: 500,
    easing: 'easeLinear',
  }
}

变更 minZoom / maxZoom

minZoom 和 maxZoom 已合并为 zoomRange

// 4.x
{
  minZoom: 0.5,
  maxZoom: 2,
}

// 5.x
{
  zoomRange: [0.5, 2],
}

变更 renderer

G6 5.x 支持多层画布，默认使用 canvas 渲染。

renderer 不再支持字符串类型，变更为回调函数：

// 4.x
var options = {
  renderer: 'svg',
};

// 5.x
import { Renderer } from '@antv/g-svg';

{
  renderer: () => new Renderer(),
}

移除 enabledStack / maxStep

5.x 已移除内置撤销重做功能，相关能力请使用插件实现。

API

变更 data / save / read / changeData

5.x 提供了全新的数据 API，详见数据 API。

4.x data changeData 方法使用 5.x setData 替代
4.x save 方法使用 5.x getData 替代
4.x read 方法使用 5.x setData + render 替代

变更 get / set

若要访问 Graph options，请使用 getOptions 或者 getXxx API，例如 getZoomRange getBehaviors 等。 set 同理。

变更 getContainer

暂不支持直接获取容器的 API，但可以通过 graph.getCanvas().getContainer() 获取。

绝大部分情况下，你都不需要直接操作容器。

移除 getGroup

变更 getMinZoom / getMaxZoom

使用 getZoomRange 获取。

变更 setMinZoom / setMaxZoom

使用 setZoomRange 方法设置。

变更 getWidth / getHeight

使用 getSize 获取。

变更 changeSize

使用 setSize 设置。

变更 zoom

变更为 zoomBy。

变更 translate

变更为 translateBy。

变更 moveTo

变更为 translateTo。

变更 focusItem

变更为 focusElement。

移除 addItem / updateItem / removeItem

通过 addData / updateData / removeData 方法操作数据来添加或删除元素。

移除 refreshItem

移除 refreshPositions

移除 updateCombo

移除 updateCombos

移除 updateComboTree

变更 node / edge / combo

使用 setNode / setEdge / setCombo 方法替代。

变更 showItem / hideItem

使用 setElementVisibility 方法替代。

移除 getNodes / getEdges / getCombos / getComboChildren /getNeighbors /find /findById / findAll /findAllByState

5.x 不支持直接获取元素实例。

若要获取元素数据，使用 getData getNodeData getEdgeData getComboData 方法，支持传入元素 id 进行查找。
获取子节点数据，使用 getChildrenData 方法。
获取邻居节点数据，使用 getNeighborNodesData 方法。
基于状态查找元素数据，使用 getElementDataByState。

变更 collapseCombo / expandCombo

使用 collapseElement / expandElement 方法替代。

移除 collapseExpandCombo

移除 createCombo

通过 addData / addComboData 方法添加 Combo。

移除 uncombo

通过 removeData / removeComboData 方法移除 Combo。

变更 setItemState

使用 setElementState 方法替代。

移除 clearItemStates

清除单个元素所有状态：graph.setElementState(id, [])
清除多个元素所有状态：graph.setElementState({ id1: [], id2: [] })

移除 priorityState

setElementState 时状态数组中靠后的状态优先级更高。

移除 setMode

使用 setBehaviors 来设置当前交互。

移除 setCurrentMode

变更 layout

不支持参数，如需配置布局，请使用 setLayout。

变更 updateLayout

变更为 setLayout。

移除 destroyLayout

变更 addBehaviors / removeBehaviors

使用 setBehaviors 替代。

移除 createHull / getHulls / removeHull / removeHulls

多个 Hull 需在 plugins 中配置多个 hull 插件，如：

{
  plugins: ['hull', 'hull'],
};

Hull 的获取、更新、移除操作通过 setPlugins, updatePlugin 实现。

暂未提供 getNodeDegree

暂未提供 getShortestPathMatrix

暂未提供 getAdjMatrix

移除 pushStack / getUndoStack / getRedoStack / getStackData / clearStack

所有撤销重做相关 API 请获取到对应插件后调用 API，例：

// 'history' 为使用插件时配置的 key
const history = graph.getPluginInstance('history');

history.redo();

移除 positionsAnimate / stopAnimate / isAnimating

动画相关信息通过事件抛出：

动画开始事件：beforeanimate
动画结束事件：afteranimate
停止动画：

graph.on('beforeanimate', (event) => {
  event.animation.stop();
});

变更 getPointByClient / getClientByPoint / getPointByCanvas / getCanvasByPoint / getGraphCenterPoint / getViewPortCenterPoint

G6 5.x 采用了与 4.x 不同的坐标系，详见坐标系。

移除 setTextWaterMarker / setImageWaterMarker

要使用水印功能，请参考水印插件。

变更 toFullDataURL

使用 toDataURL 替代，指定参数为：mode: 'overall'

graph.toDataURL({ mode: 'overall' });

移除 downloadFullImage / downloadImage

仅提供导出为 DataURL 的能力，如需下载图片，请参考如下实例代码：

async function downloadImage() {
  const dataURL = await graph.toDataURL();
  const [head, content] = dataURL.split(',');
  const contentType = head.match(/:(.*?);/)![1];

  const bstr = atob(content);
  let length = bstr.length;
  const u8arr = new Uint8Array(length);

  while (length--) {
    u8arr[length] = bstr.charCodeAt(length);
  }

  const blob = new Blob([u8arr], { type: contentType });

  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = 'graph.png';
  a.click();
}

移除 clear

使用 setData + draw 清空数据和画布。

扩展注册

与 G6 4.x 不同，G6 5.x 使用的统一的扩展注册函数(register)，你可以参考注册扩展来注册 G6 扩展。

下列 G6 4.x 的注册函数已经废除：

registerNode
registerEdge
registerCombo
registerLayout
registerBehavior

事件

与 G6 4.x 相比，G6 5.x 的事件但存下如下差异：

移除了 mouse 和 touch 事件，统一使用 pointer 事件
生命周期事件名命名格式通常为： before/after + 对象/属性 + 操作，例如：beforeelementcreate 表示在创建元素前触发
下列事件已被移除：
- afteractivaterelations
- afteradditem
- aftercreateedge
- aftergraphrefresh
- aftergraphrefreshposition
- afteritemrefresh
- aftermodechange
- afterremoveitem
- afterupdateitem
- beforeadditem
- beforecreateedge
- beforegraphrefresh
- beforegraphrefreshposition
- beforeitemrefresh
- beforemodechange
- beforeremoveitem
- beforeupdateitem
- dragnodeend
- nodeselectchange
- stackchange
- tooltipchange
下列元素变更事件被移除，但你仍可通过 beforeelementupdate 和 afterelementupdate 获取：
- afteritemstatechange
- afteritemstatesclear
- afteritemvisibilitychange
- beforeitemstatechange
- beforeitemstatesclear
- beforeitemvisibilitychange
下列事件有所变更：
- graphstatechange 事件变更为 beforeelementstatechange / afterelementstatechange
- viewportchange 事件变更为 beforetransform / aftertransform

完整的事件列表请参考事件。