@logicflow/core 2.2.0 → 2.2.2

package/dist/docs/tutorial/basic/edge.en.md

@@ -0,0 +1,151 @@
+---
+nav: Guide
+group:
+  title: Basics
+  order: 1
+title: Edge
+order: 2
+toc: content
+---
+
+Like nodes, LogicFlow has some basic edges built in.
+
+1. line
+2. polyline
+3. bezier
+
+The effect is as follows：
+
+<code id="edge-shapes" src="../../../src/tutorial/basic/edge/shapes"></code>
+
+## Selecting built-in edges inherited by custom edges
+
+```tsx | pure
+// line
+import { LineEdge, LineEdgeModel } from '@logicflow/core'
+// polyline
+import { PolylineEdge, PolylineEdgeModel } from '@logicflow/core'
+// bezier
+import { BezierEdge, BezierEdgeModel } from '@logicflow/core'
+```
+
+## Inheritance-based customization of edges
+
+Like nodes, LogicFlow edges support inheritance-based customization. Again, you only need to inherit
+from both `view` and `model`.
+However, unlike nodes, in most cases it is not recommended to customize `view` when customizing
+edges due to the editing complexity of edges.
+You just need to customize the style class in [edgeModel](../../api/runtime-model/edgeModel.en.md).
+
+<code id="edge-custom" src="../../../src/tutorial/basic/edge/custom"></code>
+
+:::info{title=提示}
+Custom edges also need to be registered using `register`.
+:::
+## Modify edge style
+Similar to node style attributes, edge styles can also be customized via [theme configuration](../../api/logicflow-instance/theme.en.md). The edge style is then redefined by this.
+
+- If you need to define styles according to the state of the edge, you can put the passed parameters into `properties`, and in `getEdgeStyle`, you can judge the parameters in `properties` and return different styles according to different parameters.
+- To achieve the hover effect, you can listen for the `edge:mouseenter` and `edge:mouseleave` events, modify the parameters in `properties`, and then call the `edge.updateStyle()` method to update the edge style.
+- It is not recommended to use the `setStyle` method to set the style of the edges. This method is generally used to skip the rendering of custom edges when developing plugins.
+
+<code id="edge-style" src="../../../src/tutorial/basic/edge/style"></code>
+## Customize side text position
+
+By default, the position of the text on the edge is the position when the user double-clicks on the
+edge. If the text is added to the edge via the API, the text position will be as follows.
+
+- line: the middle of the start and end points
+- polyline: middle of the longest line segment
+- bezier: middle of start, end, and adjustment points.
+
+LogicFlow allows developers to customize the text position, e.g. the text position will always be
+next to the start of the edge. The way to define this is to set the property `customTextPosition` to
+true, then override the `getTextPosition` method, the coordinates sent back by this method are the
+coordinates of the text.
+
+<code id="edge-text" src="../../../src/tutorial/basic/edge/textPosition"></code>
+
+## Customize the type of edges between nodes
+
+By default, edges generated by manually connecting nodes from anchors are of the type specified by
+the initialization `edgeType`, which can also be specified by `lf.setDefaultEdgeType(edgeType)`. But
+when the edge types needed to connect different nodes to each other are different, the only way to
+customize the types of the edges between nodes is to customize the edge types between nodes.
+
+```tsx | pure
+const lf = new LogicFlow({
+  ...,
+  // Set default margins manually
+  edgeType: 'bezier',
+  // currentEdge information when moving existing edges, otherwise null
+  edgeGenerator: (sourceNode, targetNode, currentEdge) => {
+    // custom-edge
+    if (sourceNode.type === 'rect') return 'custom-edge'
+  }
+})
+
+```
+
+## Customize arrows
+
+After version `1.1.27`, LogicFlow supports individual customization of the arrows at each end of a
+line. As with previous customization methods, full customization is supported by customizing basic
+data such as size by theme and by overriding the corresponding methods.
+
+### Theme settings
+
+```tsx | pure
+lf.setTheme({
+  arrow: {
+    offset: 4, // Arrow vertical line length
+    verticalLength: 2, // Arrow bottom line length
+  },
+});
+```
+
+### Customizing arrow shapes
+
+When customizing the line view, you can override the `getEndArrow` and `getStartArrow` methods to
+customize the shapes of the ends of the line, which can be any of the `svg` shapes returned by the
+two methods.
+
+Here's an example of controlling the appearance of a line by using the arrowType in the line's
+properties.
+
+<code id="custom-arrow" src="../../../src/tutorial/basic/edge/arrow"></code>
+
+### Customize the adjustment point style
+
+When initializing a LogicFlow instance, you can enable the function of adjusting the start and end
+points of edges with the parameter `adjustEdgeStartAndEnd`.
+
+When customizing the line view, you can override the `getAdjustPointShape` method to achieve the
+custom adjust point shape.
+
+```tsx | pure
+// lf.js
+const lf = new LogicFlow({
+  adjustEdgeStartAndEnd: true,
+});
+
+// edge.js
+class CustomEdge extends LineEdge {
+  getAdjustPointShape(x, y, edgeModel) {
+    return h("g", {}, [
+      h("image", {
+        x: x - 9,
+        y: y - 9,
+        width: 18,
+        height: 18,
+        cursor: "move",
+        href: "data:image/svg+xml;base64,PCFET0NUWVBFIHN2ZyBQVUJMSUMgIi0vL1czQy8vRFREIFNWRyAxLjEvL0VOIiAiaHR0cDovL3d3dy53My5vcmcvR3JhcGhpY3MvU1ZHLzEuMS9EVEQvc3ZnMTEuZHRkIj48c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHdpZHRoPSIyMnB4IiBoZWlnaHQ9IjIycHgiIHZlcnNpb249IjEuMSI+PGNpcmNsZSBjeD0iMTEiIGN5PSIxMSIgcj0iNyIgc3Ryb2tlPSIjZmZmIiBmaWxsPSIjMjliNmYyIi8+PGNpcmNsZSBjeD0iMTEiIGN5PSIxMSIgcj0iMyIgc3Ryb2tlPSIjZmZmIiBmaWxsPSJ0cmFuc3BhcmVudCIvPjwvc3ZnPg==",
+      }),
+    ]);
+  }
+}
+```
+
+<a href="https://codesandbox.io/embed/logicflow026-edgeanimation-forked-fdg3v0?fontsize=14&hidenavigation=1&theme=dark" target="_blank">
+Go to CodeSandbox for examples</a>
+

package/dist/docs/tutorial/basic/edge.zh.md

@@ -0,0 +1,152 @@
+---
+nav: 指南
+group:
+  title: 基础
+  order: 1
+title: 边
+order: 2
+toc: content
+---
+
+本页从内置边出发，介绍如何定义符合业务语义的自定义边。更复杂的连线交互和路径控制，会在 [进阶-边](../advanced/edge.zh.md) 中继续展开。
+
+::::info{title=阅读提示}
+- 适合已经读过 [快速上手](../get-started.zh.md) 和 [实例与图数据](class.zh.md) 的读者
+- 前置知识：知道节点、边、`graphData` 和 `render` 的基本用法
+- 本页不展开更复杂的边交互和框架节点方案，这些内容请继续阅读 [进阶-边](../advanced/edge.zh.md)
+- 相关 API：[`edgeModel`](../../api/runtime-model/edgeModel.zh.md)、[`主题`](../../api/logicflow-instance/theme.zh.md)、[`事件`](../../api/logicflow-instance/event.zh.md)
+::::
+
+和节点一样，LogicFlow 也内置一些基础的边。LogicFlow 的内置边包括:
+
+1. 直线 - line
+2. 直角折线 - polyline
+3. 贝塞尔曲线 - bezier
+
+效果如下：
+
+<code id="edge-shapes" src="../../../src/tutorial/basic/edge/shapes"></code>
+
+## 选择自定义边继承的内置边
+
+```tsx | pure
+// 直线
+import { LineEdge, LineEdgeModel } from '@logicflow/core'
+// 折线
+import { PolylineEdge, PolylineEdgeModel } from '@logicflow/core'
+// 贝塞尔曲线
+import { BezierEdge, BezierEdgeModel } from '@logicflow/core'
+```
+
+## 基于继承的自定义边
+
+和节点一样，LogicFlow 的边也支持基于继承的自定义机制。同样也只需同时继承`view`和`model`。
+但是和节点不一样的是，由于边的编辑复杂度问题，绝大多数情况下，自定义边时不推荐自定义`view`。
+只需要在自定义 [edgeModel](../../api/runtime-model/edgeModel.zh.md) 中定义样式相关逻辑即可。
+
+<code id="edge-custom" src="../../../src/tutorial/basic/edge/custom"></code>
+
+:::info{title=提示}
+自定义边同样需要使用`register`注册哦。
+:::
+## 修改边样式
+和节点的样式属性一样边样式也支持通过 [主题配置](../../api/logicflow-instance/theme.zh.md) 自定义边的样式则是它重新定义。
+
+- 如果需要按照边的状态定义样式，可以把传递的参数放入`properties`中，在`getEdgeStyle`中判断`properties`中的参数，根据不同的参数返回不同的样式。
+- 如果需要实现hover的效果，可以监听`edge:mouseenter`和`edge:mouseleave`事件，修改完`properties`中的参数，然后调用`edge.updateStyle()`方法更新边的样式。
+- 不建议使用`setStyle`方法设置边的样式,这个方法一般用于插件开发时跳过自定义边的渲染。
+
+<code id="edge-style" src="../../../src/tutorial/basic/edge/style"></code>
+## 自定义边文本位置
+
+默认情况下，边上文本的位置是用户双击点击边时的位置。如果是通过 API 的方式给边添加的文本，文本位置按照如下规则。
+
+- line: 起点和终点中间
+- polyline: 最长线段中间
+- bezier: 起点、终点、调整点中间
+
+LogicFlow 支持开发者自定义文本位置，例如文本位置永远在边起点旁边。定义方式为将属性`customTextPosition`
+设置为 true, 然后重写`getTextPosition`方法, 此方法返回的坐标就是文本的坐标。
+
+<code id="edge-text" src="../../../src/tutorial/basic/edge/textPosition"></code>
+
+## 自定义节点之间边的类型
+
+默认情况下，通过从锚点手动连接节点生成的边为初始化`edgeType`
+指定的类型，也可以通过`lf.setDefaultEdgeType(edgeType)`来指定。但是当需要不同的节点之间连接的边类型不一样时，就只有自定义节点之间边的类型了。
+
+```tsx | pure
+const lf = new LogicFlow({
+  ...,
+  // 手动设置默认边
+  edgeType: 'bezier',
+  // 移动已有边时会有 currentEdge 信息, 否则为空
+  edgeGenerator: (sourceNode, targetNode, currentEdge) => {
+    // 起始节点类型 rect 时使用 自定义的边 custom-edge
+    if (sourceNode.type === 'rect') return 'custom-edge'
+  }
+})
+
+```
+
+## 自定义箭头
+
+在`1.1.27`版本后，LogicFlow 支持单独自定义连线两端的箭头。和之前的自定义方式一样，支持通过主题自定义大小等基本数据和通过重写对应的方法实现完全的自定义。
+
+### 主题设置
+
+```tsx | pure
+lf.setTheme({
+  arrow: {
+    offset: 4, // 箭头垂线长度
+    verticalLength: 2, // 箭头底线长度
+  },
+});
+```
+
+### 自定义箭头形状
+
+在自定义连线 view 的时候，可以重写`getEndArrow`和`getStartArrow`
+方法来实现自定义连线两端的图形，这两个方法可以返回的任意`svg`图形。
+
+这里以通过连线属性中的 arrowType 来控制连线不同的外观为例。
+
+<code id="custom-arrow" src="../../../src/tutorial/basic/edge/arrow"></code>
+
+### 自定义调整点样式
+
+在初始化 LogicFlow 实例的时候,可以通过参数`adjustEdgeStartAndEnd`来开启调整边的起始点和结束点的功能。
+
+在自定义连线 view 的时候，可以重写`getAdjustPointShape`方法来实现自定义调整点的样式。
+
+```tsx | pure
+// lf.js
+const lf = new LogicFlow({
+  adjustEdgeStartAndEnd: true,
+});
+
+// edge.js
+class CustomEdge extends LineEdge {
+  getAdjustPointShape(x, y, edgeModel) {
+    return h("g", {}, [
+      h("image", {
+        x: x - 9,
+        y: y - 9,
+        width: 18,
+        height: 18,
+        cursor: "move",
+        href: "data:image/svg+xml;base64,PCFET0NUWVBFIHN2ZyBQVUJMSUMgIi0vL1czQy8vRFREIFNWRyAxLjEvL0VOIiAiaHR0cDovL3d3dy53My5vcmcvR3JhcGhpY3MvU1ZHLzEuMS9EVEQvc3ZnMTEuZHRkIj48c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHdpZHRoPSIyMnB4IiBoZWlnaHQ9IjIycHgiIHZlcnNpb249IjEuMSI+PGNpcmNsZSBjeD0iMTEiIGN5PSIxMSIgcj0iNyIgc3Ryb2tlPSIjZmZmIiBmaWxsPSIjMjliNmYyIi8+PGNpcmNsZSBjeD0iMTEiIGN5PSIxMSIgcj0iMyIgc3Ryb2tlPSIjZmZmIiBmaWxsPSJ0cmFuc3BhcmVudCIvPjwvc3ZnPg==",
+      }),
+    ]);
+  }
+}
+```
+
+<a href="https://codesandbox.io/embed/logicflow026-edgeanimation-forked-fdg3v0?fontsize=14&hidenavigation=1&theme=dark" target="_blank"> 去 CodeSandbox 查看示例</a>
+
+## 下一步阅读
+
+1. [进阶-边](../advanced/edge.zh.md)：继续看动画、数据扩展和更复杂的边能力
+2. [事件 API](../../api/logicflow-instance/event.zh.md)：查看边事件和交互事件
+3. [edgeModel API](../../api/runtime-model/edgeModel.zh.md)：精确查阅可用属性和方法
+

package/dist/docs/tutorial/basic/event.en.md

@@ -0,0 +1,70 @@
+---
+nav: Guide
+group:
+  title: Basics
+  order: 1
+title: Event
+order: 6
+toc: content
+---
+
+Events are triggered when we interact with the canvas using the mouse or other means. By listening
+to these events, we can get the data generated when they are triggered, and then use this data to
+realize the required functions. See [event API](../../api/logicflow-instance/event.en.md) for details on
+listening to events.
+
+## Listening to events
+
+The `on` method is provided on the `lf` instance to support listening to events.
+
+```tsx | pure
+lf.on("node:dnd-add", (data) => {});
+```
+
+LogicFlow supports splitting event names with commas.
+
+```tsx | pure
+lf.on("node:click,edge:click", (data) => {});
+```
+
+## Customizing events
+
+In addition to the listening events supported on lf, events can be listened to and triggered using
+the [eventCenter](../../api/runtime-model/graphModel.en.md#eventcenter) object. `eventCenter` is a property on
+a `graphModel`. So when customizing a node, we can use `eventCenter` to trigger custom events.
+
+```tsx | pure
+class ButtonNode extends HtmlNode {
+  setHtml(rootEl) {
+    const { properties } = this.props.model
+
+    const el = document.createElement('div')
+    el.className = 'uml-wrapper'
+    const html = `
+      <div>
+        <div class="uml-head">Head</div>
+        <div class="uml-body">
+          <div><button onclick="setData()">+</button> ${properties.name}</div>
+          <div>${properties.body}</div>
+        </div>
+        <div class="uml-footer">
+          <div>setHead(Head $head)</div>
+          <div>setBody(Body $body)</div>
+        </div>
+      </div>
+    `
+    el.innerHTML = html
+    rootEl.innerHTML = ''
+    rootEl.appendChild(el)
+    window.setData = () => {
+      const { graphModel, model } = this.props
+      graphModel.eventCenter.emit('custom:button-click', model)
+    }
+  }
+}
+```
+
+## example
+
+<a href="https://codesandbox.io/embed/logicflow-step7-dpmgb?fontsize=14&hidenavigation=1&theme=dark&view=preview" target="_blank">
+Go to CodeSandbox for examples</a>

package/dist/docs/tutorial/basic/event.zh.md

@@ -0,0 +1,66 @@
+---
+nav: 指南
+group:
+  title: 基础
+  order: 1
+title: 事件
+order: 6
+toc: content
+---
+
+当我们使用鼠标或其它方式与画布交互时，会触发的对应的事件。通过监听这些事件，可以获取其在触发时所产生的数据，根据这些数据来实现需要的功能。详细可监听事件见[事件 API](../../api/logicflow-instance/event.zh.md)。
+
+## 监听事件
+
+`lf`实例上提供`on`方法支持监听事件。
+
+```tsx | pure
+lf.on("node:dnd-add", (data) => {});
+```
+
+LogicFlow 支持用逗号分割事件名。
+
+```tsx | pure
+lf.on('node:click,edge:click', (data) => {})
+```
+
+## 自定义事件
+
+除了 lf 上支持的监听事件外，还可以使用 [eventCenter](../../api/runtime-model/graphModel.zh.md#eventcenter)
+对象来监听和触发事件。`eventCenter`是一个`graphModel`
+上的一个属性。所以在自定义节点的时候，我们可以使用`eventCenter`触发自定义事件。
+
+```tsx | pure
+class ButtonNode extends HtmlNode {
+  setHtml(rootEl) {
+    const { properties } = this.props.model
+
+    const el = document.createElement('div')
+    el.className = 'uml-wrapper'
+    const html = `
+      <div>
+        <div class="uml-head">Head</div>
+        <div class="uml-body">
+          <div><button onclick="setData()">+</button> ${properties.name}</div>
+          <div>${properties.body}</div>
+        </div>
+        <div class="uml-footer">
+          <div>setHead(Head $head)</div>
+          <div>setBody(Body $body)</div>
+        </div>
+      </div>
+    `
+    el.innerHTML = html
+    rootEl.innerHTML = ''
+    rootEl.appendChild(el)
+    window.setData = () => {
+      const { graphModel, model } = this.props
+      graphModel.eventCenter.emit('custom:button-click', model)
+    }
+  }
+}
+```
+
+## 示例
+
+<a href="https://codesandbox.io/embed/logicflow-step7-dpmgb?fontsize=14&hidenavigation=1&theme=dark&view=preview" target="_blank"> 去 CodeSandbox 查看示例</a>

package/dist/docs/tutorial/basic/grid.en.md

@@ -0,0 +1,77 @@
+---
+nav: Guide
+group:
+  title: Basics
+  order: 1
+title: Grid
+order: 4
+toc: content
+---
+
+A mesh is the smallest unit for rendering/moving nodes. The primary purpose of a mesh is to ensure
+that the position of each node center point is on the mesh when moving nodes. This is more conducive
+to direct node alignment. Generally speaking, the larger the interval of the grid, the better the
+nodes are aligned when editing the flowchart; the smaller the interval of the grid, the smoother the
+feeling of dragging nodes.
+
+Grid is off by default, and the minimum unit of rendering/movement is 1px. If grid is on, the
+default size of grid is 20px, which means that the nodes are aligned to the network with the minimum
+unit of 20 when rendering them, and the minimum distance of 20px each time they are moved when
+moving them.
+
+:::warning{title=注意}
+When setting node coordinates, the coordinates are transformed according to the size of the grid.
+For example, if the center point is set at { x: 124, y: 138 }, the actual position of the rendered
+node on the canvas would be { x: 120, y: 140 }. Therefore, when replacing the old flow designer in
+the project with LogicFlow, it is necessary to handle the coordinates of historical data.<br>
+In practical development, if you want nodes to align both to the center and to the sides, the custom
+node's width and height should be multiples of the grid size. This means that the width of all nodes
+is preferably in even multiples such as 20, 40, 80, 120, assuming the grid size is 20.
+:::
+
+## Enable Grid
+
+When creating the canvas, set grid properties through the configuration grid.
+
+To enable the grid and apply default properties:
+
+```tsx | pure
+const lf1 = new LogicFlow({
+  grid: true,
+})
+
+// or
+
+const lf2 = new LogicFlow({
+  grid: {
+    size: 20,
+    visible: true,
+    type: 'dot',
+    config: {
+      color: '#ababab',
+      thickness: 1,
+    },
+  },
+})
+```
+
+## Set Grid Properties
+
+Supports setting grid properties such as size, type, grid line color, and width.
+
+```tsx | pure
+export type GridOptions = {
+  size?: number  // Set grid size.
+  visible?: boolean,  // Set visibility; if set to false, grid lines will not be displayed, but the size grid effect will still be retained.
+  type?: 'dot' | 'mesh', // Set grid type; currently supports dot and mesh types.
+  config?: {
+    color: string,  // Set grid color.
+    thickness?: number,  // Set grid line width.
+  }
+};
+```
+
+## example
+
+<a href="https://codesandbox.io/embed/logicflow-base8-hxtqr?fontsize=14&hidenavigation=1&theme=dark&view=preview" target="_blank">
+Go to CodeSandbox for examples</a>