diff --git a/docs/api/Group.en.md b/docs/api/Group.en.md index 53fe56de3b..3c21fe5ce4 100644 --- a/docs/api/Group.en.md +++ b/docs/api/Group.en.md @@ -49,6 +49,7 @@ The `cfg` above contains: | --- | --- | --- | | attrs | Object | The style configurations for the shape. e.g. `{x: 0, y: 10, fill: '#0f0'}` | | name | String | The name of the shape which can be not unique. It is required for each shape in G6 3.3. Besides, `name` can be used for searching this shape, e.g. `const shape = group.find(element => element.name === 'shape-name')`. The usage of find can be found at [find(fn)](#findfn) | +| draggable | Boolean | Whether the shape is allowed to response `dragstart`, `drag`, and `dragend` events. E.g. when user add a shape into a custom node with `draggable: true`, the shape will response the dragging events on the node, and the `'drag-node'` in the `modes` of the graph instance will take effect | | zIndex | Number | The visual index of the shape, similar to z-index of DOM. It is not required. `group.sort()` will sort the visual index of the shapes inside the group according to their zIndex | **Usage** diff --git a/docs/api/Group.zh.md b/docs/api/Group.zh.md index a01aa8c576..d2859c703b 100644 --- a/docs/api/Group.zh.md +++ b/docs/api/Group.zh.md @@ -49,6 +49,7 @@ group.addGroup({ | --- | --- | --- | | attrs | Object | 图形样式，例如：`{x: 0, y: 10, fill: '#0f0'}` | | name | String | 图形的标识，可以不唯一。在 G6 3.3 及以后版本中必须指定。另外，`name` 可以用于组内搜索到该元素：`const shape = group.find(element => element.name === 'shape-name')`，find 函数用法见 [find(fn)](#findfn) | +| draggable | Boolean | 该图形是否允许被拖拽。例如，自定义节点通过 `addShape` 添加图形，当该图形的 `draggable` 值为 `true` 时，鼠标在该自定义节点的这个图形上才能够响应 `dragstart`，`drag`，与 `dragend` 事件；在实例化图时的 `modes` 中配置的 `'drag-node'` 交互才可以在该图形上进行拖拽时生效 | | zIndex | Number | 该图形的视觉层次 z-index。非必须指定。指定后，调用 `group.sort()` 可以对组内所有图形根据各自 zIndex 进行视觉层次的排序 | **用法** diff --git a/docs/manual/FAQ/transform.en.md b/docs/manual/FAQ/transform.en.md index 456e0e16c1..035964985b 100644 --- a/docs/manual/FAQ/transform.en.md +++ b/docs/manual/FAQ/transform.en.md @@ -1,5 +1,5 @@ --- -title: Transform a Shape in G6 +title: Transform a Shape or a Graphics Group order: 6 --- @@ -43,50 +43,90 @@ rect.transform([ -### translate(x, y) +#### translate(x, y) -实例的相对位移方法。 +Translate the shape or group with vector (x, y). -### move(x, y) +#### move(x, y) -实例的相对位移方法。 +Translate the shape or group with vector (x, y). -### rotate(radian) +#### rotate(radian) -根据旋转弧度值对图形进行旋转。 +Rotate the shape or group with `radian`. -### scale(sx, sy) +#### scale(sx, sy) -对图形进行缩放。 +Scale the shape or group to sx times on x-axis and sy times on y-axis. -### resetMatrix() +#### resetMatrix() -清除图形实例的所有变换效果。 +Clear the matrix to reset all the transformantions on the shape or group. -### getTotalMatrix() +#### getTotalMatrix() -获取应用到实例上的所有变换的矩阵。 +Get all the transformations of the shape or group. ### G6 3.3 -在 G6 3.3 及以上版本中，废弃了 Group / Canvas 上只适用于三阶矩阵的变换函数: +After G6 3.3, the following transform methods are discarded: -- 🗑 平移函数 translate； -- 🗑 移动函数 move； -- 🗑 缩放函数 scale； -- 🗑 旋转函数 rotate； -- 🗑 以 (0, 0) 点为中心的旋转函数 rotateAtStart。 +- 🗑 translate; +- 🗑 move; +- 🗑 scale; +- 🗑 rotate; +- 🗑 rotateAtStart: rotate the shape or group with center (0, 0)。 -在 G6 3.3 版本中要应用矩阵变换的效果，需要手动设置矩阵的值: • 设置矩阵 setMatrix(matrix)； • 重置矩阵 resetMatrix()； • 设置矩阵 attr('matrix', matrix)； +To achive some transformation in G6 3.3, you should set the matrix value manually: +- Get the current matrix of a shape or a group: getMatrix(); +- Set the matrix to a shape or a group: setMatrix(matrix) or attr('matrix', matrix); +- Reset the matrix: resetMatrix(). -为了方面使用，我们提供了矩阵变换的工具方法: +We provide the function for transformantion: ```javascript import { transform } from '@antv/matrix-util'; -// 3*3 矩阵变换，用于二维渲染 +// transform a 3*3 matrix trasform(m, [ - ['t', x, y], // translate + ['t', x, y], // translate with vector (x, y) ['r', Math.PI], // rotate - ['s', 2, 2], // scale + ['s', 2, 2], // scale at x-axis and y-axis ]); ``` + +#### Example +The following code registers a custom node with a transfromed rect with: translation with vector `(100, 50)`, rotating with angle `Math.PI / 4`, maginifying 2 times on x-axis and 0.5 times on y-axis: + +```javascript +import { transform, mat3 } from '@antv/matrix-util'; +G6.registerNode('example', { + drawShape: (cfg, group) => { + const rect = group.addShape('rect', { + attrs: { + width: 100, + height: 100, + x: 100, + y: 100, + fill: '#9EC9FF', + stroke: '#5B8FF9', + lineWidth: 3, + }, + // must be assigned in G6 3.3 and later versions. it can be any value you want + name: 'rect-shape', + }); + const matrix = rect.getMatrix(); + + // the init matrix for a shape or a group is null, initiate it with unit matrix + if (!matrix) matrix = mat3.create(); + + // transform a 3*3 matrix + const newMatrix = trasform(matrix, [ + [ 't', 100, 50 ], // translate + [ 'r', Math.PI / 4 ], // rotate + [ 's', 2, 0.5 ], // scale + ]); + + rect.setMatrix(newMatrix); + } +}); +``` diff --git a/docs/manual/FAQ/transform.zh.md b/docs/manual/FAQ/transform.zh.md index 235f2124e0..f2649079d3 100644 --- a/docs/manual/FAQ/transform.zh.md +++ b/docs/manual/FAQ/transform.zh.md @@ -1,5 +1,5 @@ --- -title: 如何在 G6 中实现变换 +title: 图形或图形分组的变换 order: 6 --- @@ -43,33 +43,33 @@ rect.transform([ -### translate(x, y) +#### translate(x, y) 实例的相对位移方法。 -### move(x, y) +#### move(x, y) 实例的相对位移方法。 -### rotate(radian) +#### rotate(radian) 根据旋转弧度值对图形进行旋转。 -### scale(sx, sy) +#### scale(sx, sy) 对图形进行缩放。 -### resetMatrix() +#### resetMatrix() 清除图形实例的所有变换效果。 -### getTotalMatrix() +#### getTotalMatrix() 获取应用到实例上的所有变换的矩阵。 ### G6 3.3 -在 G6 3.3 及以上版本中，废弃了 Group / Canvas 上只适用于三阶矩阵的变换函数: +在 G6 3.3 及以上版本中，废弃了 Group / Canvas 上只适用于三阶矩阵的变换函数： - 🗑 平移函数 translate； - 🗑 移动函数 move； @@ -77,16 +77,57 @@ rect.transform([ - 🗑 旋转函数 rotate； - 🗑 以 (0, 0) 点为中心的旋转函数 rotateAtStart。 -在 G6 3.3 版本中要应用矩阵变换的效果，需要手动设置矩阵的值: • 设置矩阵 setMatrix(matrix)； • 重置矩阵 resetMatrix()； • 设置矩阵 attr('matrix', matrix)； +在 G6 3.3 版本中要应用矩阵变换的效果，需要手动设置矩阵的值： +- 获取当前矩阵：getMatrix()； +- 设置矩阵：setMatrix(matrix) 或 attr('matrix', matrix)； +- 重置矩阵：resetMatrix()。 -为了方面使用，我们提供了矩阵变换的工具方法: +为了方面使用，我们提供了矩阵变换的工具方法： ```javascript import { transform } from '@antv/matrix-util'; // 3*3 矩阵变换，用于二维渲染 trasform(m, [ - ['t', x, y], // translate - ['r', Math.PI], // rotate - ['s', 2, 2], // scale + [ 't', 100, 50 ], // translate (100, 50) + [ 'r', Math.PI ], // rotate Math.PI + [ 's', 2, 2 ], // scale 2 times at x-axis and y-axis ]); ``` + +#### 示例 +以下方法实现了在自定义节点 example 中增加一个矩形，并将该矩形位移 `(100, 50)` 后，旋转 `Math.PI / 4`，最后在 x 方向放大 2 倍，并在 y 方向缩小 2 倍： + +```javascript +import { transform, mat3 } from '@antv/matrix-util'; +G6.registerNode('example', { + drawShape: (cfg, group) => { + const rect = group.addShape('rect', { + attrs: { + width: 100, + height: 100, + x: 100, + y: 100, + fill: '#9EC9FF', + stroke: '#5B8FF9', + lineWidth: 3, + }, + // must be assigned in G6 3.3 and later versions. it can be any value you want + name: 'rect-shape', + draggable: true + }); + const matrix = rect.getMatrix(); + + // 图形或分组的初始矩阵时 null，为了避免变换一个 null 矩阵，需要通过 mat3.create() 将其初始化为单位矩阵 + if (!matrix) matrix = mat3.create(); + + // 3*3 矩阵变换，用于二维渲染 + const newMatrix = trasform(matrix, [ + [ 't', 100, 50 ], // translate + [ 'r', Math.PI / 4 ], // rotate + [ 's', 2, 0.5 ], // scale + ]); + + rect.setMatrix(newMatrix); + } +}); +``` diff --git a/docs/manual/advanced/custom-node.en.md b/docs/manual/advanced/custom-node.en.md index dcd0df3760..12e367f5f2 100644 --- a/docs/manual/advanced/custom-node.en.md +++ b/docs/manual/advanced/custom-node.en.md @@ -83,13 +83,16 @@ G6.registerNode(   ⚠️Attention: -- `draw` is required if the custom node does not extend any parent; -- `update` is not required. If it is undefined, the `draw` will be called when updating the node, which means all the graphics will be cleared and repaint; -- `afterDraw` and `afterUpdate` are used for extending the exited nodes in general. e.g. adding extra image on rect node, adding animation on a circle node, ...; +- `draw`: it is required if the custom node does not extend any parent; +- Coordinate system: The coordinate system of the shapes inside the custom node is a **sub coordinate system relating to itself**, which means the `(0, 0)` is the center of the node. And the coordinates of the node is related to the whole canvas, which is controled by the group contains it and users have no need to use it when customing a node type. See the detail in [Register a Bran-new Node](#1-register-a-bran-new-edge); +- `update`: + - When the `update` function is not undefined: If user has defined the third parameter `extendNodeName` of `registerNode`, which means extending a built-in node type, the `update` function of the extended node type of the custom node will be executed once the node is updated; If the third parameter of `registerNode` is not assigned, the `draw` function of the custom node will be executed instead; + - When the `update` function is defined, whether the third parameter of `registerNode` is defined, the `update` function will be executed when the node is updated. +- `afterDraw` and `afterUpdate`: they are used for extending the exited nodes in general. e.g. adding extra image on rect node, adding animation on a circle node, ...; - In general, `setState` is not required; -- `getAnchorPoints` is only required when you want to contrain the link points for nodes and their related edges. The anchorPoints can be assigned in the node data as well. +- `getAnchorPoints`: it is only required when you want to contrain the link points for nodes and their related edges. The anchorPoints can be assigned in the node data as well. -## 1. Register a Bran-new Edge +## 1. Register a Bran-new Node ### Render the Node @@ -99,6 +102,8 @@ Now, we are going to register a diamond node: img +   ⚠️ Attention: From the following code, you will understand that the coordinates of the sub shapes of the custom node is related to itself, which means the `(0, 0)` is the center of the node. E.g. the `x` and `y` of the `'text'` shape are both 0, which means the shape is on the center of the node; The `path` attribute of `'path'` is also defined with the origin `(0, 0)`. In the other words, users do not need to control the sub shapes' coordinates according to the nodes' coordinate which is controlled by the matrix of the parent group of the node. + ```javascript G6.registerNode('diamond', { draw(cfg, group) { diff --git a/docs/manual/advanced/custom-node.zh.md b/docs/manual/advanced/custom-node.zh.md index f1fb007a30..40b929576c 100644 --- a/docs/manual/advanced/custom-node.zh.md +++ b/docs/manual/advanced/custom-node.zh.md @@ -72,14 +72,19 @@ G6.registerNode( */ getAnchorPoints(cfg) {}, }, - extendNodeName, + // 继承内置节点类型的名字，例如基类 'single-node'，或 'circle', 'rect' 等 + // 当不指定该参数则代表不继承任何内置节点类型 + extendNodeName, ); ```   ⚠️ 注意: - 如果不从任何现有的节点扩展新节点时，`draw` 方法是必须的； -- `update` 方法可以不定义，数据更新时会走 `draw` 方法，所有图形清除重绘； +- 节点内部所有图形**使用相对于节点自身的坐标系**，即 `(0, 0)` 是该节点的中心。而节点的坐标是相对于画布的，由该节点 group 上的矩阵控制，自定义节点中不需要用户感知。详见例子 [从无到有定义节点](#1-从无到有定义节点)； +- `update` 方法可以不定义： + - 当 `update` 未定义：若指定了 `registerNode` 的第三个参数 `extendNodeName`（即代表继承指定的内置节点类型），则节点更新时将执行被继承的内置节点类型的 `update` 逻辑；若未指定 `registerNode` 的第三个参数，则节点更新时会执行 `draw` 方法，所有图形清除重绘； + - 当定义了 `update` 方法，则不论是否指定 `registerNode` 的第三个参数，在节点更新时都会执行复写的 `update` 函数逻辑。 - `afterDraw`，`afterUpdate` 方法一般用于扩展已有的节点，例如：在矩形节点上附加图片，圆节点增加动画等； - `setState` 方法一般也不需要复写，有全局的样式可以替换； - `getAnchorPoints` 方法仅在需要限制与边的连接点时才需要复写，也可以在数据中直接指定。 @@ -94,6 +99,8 @@ G6.registerNode( img +   ⚠️ 注意: 从下面代码可以看出，自定义节点中所有通过 `addShape` 增加的图形的坐标都是**相对于节点自身的子坐标系**，即 `(0, 0)` 是该节点的中心。如 `'text'` 图形的 `x` 和 `y` 均为 0，代表该图形相对于该节点居中；`'path'` 图形 `path` 属性中的坐标也是以 `(0, 0)` 为原点计算的。换句话说，在**自定义节点时不需要感知相对于画布的节点坐标**，节点坐标由该节点所在 group 的矩阵控制。 + ```javascript G6.registerNode('diamond', { draw(cfg, group) { diff --git a/docs/manual/middle/states/state.zh.md b/docs/manual/middle/states/state.zh.md index ea0c6a14c1..15861478d1 100644 --- a/docs/manual/middle/states/state.zh.md +++ b/docs/manual/middle/states/state.zh.md @@ -130,11 +130,7 @@ G6.registerBehavior('nodeClick', { fill: '#d3adf7', // name 为 shape-name1 的子图形在该状态值下的样式 'node-label': { - labelCfg: { - style: { - fontSize: 15 - } - } + fontSize: 15 }, }, // 二值状态 running 为 true 时的样式 diff --git a/examples/scatter/edge/index.en.md b/examples/scatter/edge/index.en.md index 00294eaf6e..f694033129 100644 --- a/examples/scatter/edge/index.en.md +++ b/examples/scatter/edge/index.en.md @@ -13,4 +13,4 @@ The three demos below show the edge animation realized by customing edge: - Example 2 : A running dashed edge; - Example 3 : A edge grow from source to target. -For more information, please refer to document [Animation](/zh/docs/manual/advanced/animation-zh)。 +For more information, please refer to document [Animation](/zh/docs/manual/advanced/animation). diff --git a/examples/scatter/edge/index.zh.md b/examples/scatter/edge/index.zh.md index 93fa37ee65..250d71ac7e 100644 --- a/examples/scatter/edge/index.zh.md +++ b/examples/scatter/edge/index.zh.md @@ -13,4 +13,4 @@ order: 1 - 虚线运动的效果； - 线从无到有的效果。 -G6 中更多关于动画的内容，请参考[动画文档](/zh/docs/manual/advanced/animation-zh)。 +G6 中更多关于动画的内容，请参考[动画文档](/zh/docs/manual/advanced/animation)。 diff --git a/examples/scatter/node/demo/node.js b/examples/scatter/node/demo/node.js index 80e9de57cb..0cb52bf79c 100644 --- a/examples/scatter/node/demo/node.js +++ b/examples/scatter/node/demo/node.js @@ -136,11 +136,11 @@ G6.registerNode( // 逐渐放大，并消失 r: r + 10, opacity: 0.1, - repeat: true, // 循环 }, { duration: 3000, easing: 'easeCubic', - delay: 0 + delay: 0, + repeat: true, // 循环 } ); // 无延迟 back2.animate( @@ -148,23 +148,23 @@ G6.registerNode( // 逐渐放大，并消失 r: r + 10, opacity: 0.1, - repeat: true, // 循环 }, { duration: 3000, easing: 'easeCubic', - delay: 1000 + delay: 1000, + repeat: true, // 循环 } ); // 1 秒延迟 back3.animate( { // 逐渐放大，并消失 r: r + 10, - opacity: 0.1, - repeat: true, // 循环 + opacity: 0.1 }, { duration: 3000, easing: 'easeCubic', - delay: 2000 + delay: 2000, + repeat: true, // 循环 }, ); // 2 秒延迟 },