---
title: 升级到 5.0
order: 6
---
本文档将引导你从 G6 `4.x` 版本升级到 `5.x` 版本。如果你使用的是 `3.x` 版本，请先升级到 `4.x` 版本。
## 升级前准备
1. 请确保当前 git 分支是干净的，没有未提交的代码。
2. 参考 [安装](/manual/getting-started/installation) 文档安装 `5.x` 版本，并移除 `4.x` 版本依赖。
## 开始升级
### 数据
新版本的数据格式有所变化，具体如下：
1. `nodes` `edges` `combos` 中所有样式属性都需要放在 `style` 中，`data` 中存放数据属性：
```typescript
// 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' }],
};
```
由于我们重新设计实现了元素，新的元素配置项请参考相应文档进行修改：
- [Node](/manual/element/node/overview)
- [Edge](/manual/element/edge/overview)
- [Combo](/manual/element/combo/overview)
2. 如果要在数据中指定元素类型，可以使用 `type` 属性：
```typescript
{
nodes: [
// 指定节点类型为 rect
{ id: 'node1', type: 'rect' },
];
}
```
### 配置项
变更 **fitView / fitCenter / fitViewPadding**
- `fitView` 和 `fitCenter` 配置项已经合并为 `autoFit`
- 若要使用 `fitView`，可以配置为 `autoFit: 'view'`
- 若要使用 `fitCenter`，可以配置为 `autoFit: 'center'`
- 也可以传入对象进行完整配置：
```js
autoFit: {
type: 'view',
options: {
// ...
}
}
```
- `fitViewPadding` 已变更为 `padding`
移除 **linkCenter**
5.x 的边连接机制会按照如下顺序依次尝试连接到节点/Combo：
1. 连接桩
2. 轮廓
3. 中心
移除 **groupByTypes**
移除 **autoPaint**
请手动调用 `render` 或 `draw` 方法进行绘制。
变更 **modes**
5.x 已经移除交互模式，你可以通过设置 `behaviors` 来切换当前启用的交互行为。
```typescript
// 4.x
{
modes: {
default: ['drag-canvas', 'zoom-canvas'],
preview: ['drag-canvas'],
},
}
graph.setMode('preview');
```
```typescript
// 5.x
{
behaviors: ['drag-canvas', 'zoom-canvas'],
}
graph.setBehaviors(['drag-canvas']);
```
变更 **defaultNode / defaultEdge / defaultCombo**
元素样式已移至 `[element].style` 中，如 `defaultNode` 变更为 `node.style`：
```typescript
// 4.x
{
defaultNode: {
size: 20,
fill: 'red',
}
}
// 5.x
{
node: {
style: {
size: 20,
fill: 'red',
}
}
}
```
变更 **nodeStateStyles / edgeStateStyles / comboStateStyle**
元素状态样式已移至 `[element].state` 中，如 `nodeStateStyles` 变更为 `node.stateStyles`：
```typescript
// 4.x
{
nodeStateStyles: {
selected: {
fill: 'red',
}
}
}
// 5.x
{
node: {
state: {
selected: {
fill: 'red',
}
}
}
}
```
变更 **animate / animateCfg**
- `animate` 配置项已变更为 `animation`
- `animate` 和 `animateCfg` 已合并为 `animation`
```typescript
// 4.x
{
animate: true,
}
// 5.x
{
animation: true,
}
{
animation: {
duration: 500,
easing: 'easeLinear',
}
}
```
变更 **minZoom / maxZoom**
`minZoom` 和 `maxZoom` 已合并为 `zoomRange`
```typescript
// 4.x
{
minZoom: 0.5,
maxZoom: 2,
}
// 5.x
{
zoomRange: [0.5, 2],
}
```
变更 **renderer**
G6 5.x 支持多层画布，默认使用 `canvas` 渲染。
renderer 不再支持字符串类型，变更为回调函数：
```typescript
// 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](/api/data)。
- 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` 插件，如：
```typescript
{
plugins: ['hull', 'hull'],
};
```
- `Hull` 的获取、更新、移除操作通过 `setPlugins`, `updatePlugin` 实现。
暂未提供 **getNodeDegree**
暂未提供 **getShortestPathMatrix**
暂未提供 **getAdjMatrix**
移除 **pushStack / getUndoStack / getRedoStack / getStackData / clearStack**
所有撤销重做相关 API 请获取到对应插件后调用 API，例：
```typescript
// 'history' 为使用插件时配置的 key
const history = graph.getPluginInstance('history');
history.redo();
```
移除 **positionsAnimate / stopAnimate / isAnimating**
动画相关信息通过事件抛出：
- 动画开始事件：`beforeanimate`
- 动画结束事件：`afteranimate`
- 停止动画：
```typescript
graph.on('beforeanimate', (event) => {
event.animation.stop();
});
```
变更 **getPointByClient / getClientByPoint / getPointByCanvas / getCanvasByPoint / getGraphCenterPoint / getViewPortCenterPoint**
G6 5.x 采用了与 4.x 不同的坐标系，详见 [坐标系](/manual/further-reading/coordinate)。
移除 **setTextWaterMarker / setImageWaterMarker**
要使用水印功能，请参考 [水印](/manual/plugin/watermark)插件。
变更 **toFullDataURL**
使用 `toDataURL` 替代，指定参数为：`mode: 'overall'`
```typescript
graph.toDataURL({ mode: 'overall' });
```
移除 **downloadFullImage / downloadImage**
仅提供导出为 `DataURL` 的能力，如需下载图片，请参考如下实例代码：
```typescript
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)，你可以参考 [注册扩展](/manual/graph/extension#注册扩展) 来注册 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
完整的事件列表请参考 [事件](/api/event)。