@logicflow/core 2.2.0 → 2.2.2

package/dist/docs/tutorial/advanced/node.zh.md

@@ -0,0 +1,338 @@
+---
+nav: 指南
+group:
+  title: 进阶
+  order: 2
+title: 节点进阶
+order: 0
+toc: content
+---
+
+这页适合已经完成基础自定义节点、准备继续处理**连接规则、锚点、节点移动和框架节点渲染**的读者。
+
+::::info{title=阅读提示}
+- 前置知识：建议先读 [节点](../basic/node.zh.md) 和 [实例与图数据](../basic/class.zh.md)
+- 本页不解决插件选型和 API 全量参数查询；当你需要精确查属性或方法时，请转到 [`nodeModel`](../../api/runtime-model/nodeModel.zh.md)、[`graphModel`](../../api/runtime-model/graphModel.zh.md)、[`事件`](../../api/logicflow-instance/event.zh.md)
+- 如果你是 React / Vue 项目，优先看本页中的导读，再继续进入 [React 自定义节点](react.zh.md) 或 [Vue 自定义节点](vue.zh.md)
+::::
+
+## 本页导读
+
+你可以按下面的目标跳读：
+
+1. 想限制节点怎么连：看“连接规则”
+2. 想控制节点能不能移动：看“移动”
+3. 想精细控制连线落点：看“锚点”
+4. 想把 React / Vue 组件渲染进节点：优先看独立的 React / Vue 页面
+5. 想从节点内部和外部通信：看“外部通信”
+
+## 连接规则
+
+在某些时候，我们可能需要控制边的连接方式，比如开始节点不能被其它节点连接、结束节点不能连接其他节点、用户节点后面必须是判断节点等，要想达到这种效果，我们需要为节点设置以下两个属性。
+
+- `sourceRules` - 当节点作为边的起始节点（source）时的校验规则
+- `targetRules` - 当节点作为边的目标节点（target）时的校验规则
+
+以正方形（square）为例，连边时我们希望它的下一节点只能是圆形节点（circle），那么我们应该给`square`
+添加作为`source`节点的校验规则。
+
+```tsx | pure
+import { RectNode, RectNodeModel } from '@logicflow/core'
+
+class SquareModel extends RectNodeModel {
+  initNodeData(data) {
+    super.initNodeData(data)
+
+    const circleOnlyAsTarget = {
+      message: '正方形节点下一个节点只能是圆形节点',
+      validate: (sourceNode, targetNode, sourceAnchor, targetAnchor) => {
+        return targetNode.type === 'circle'
+      },
+    }
+    this.sourceRules.push(circleOnlyAsTarget)
+  }
+}
+```
+
+在上例中，我们为`model`的`sourceRules`
+属性添加了一条校验规则，校验规则是一个对象，我们需要为其提供`message`和`validate`属性。
+
+`message`属性是当不满足校验规则时所抛出的错误信息，`validate`则是传入规则检验的回调函数。`validate`
+方法有两个参数，分别为边的起始节点（source）和目标节点（target），我们可以根据参数信息来决定是否通过校验，其返回值是一个布尔值。
+
+:::warning{title=提示}
+当我们在面板上进行边操作的时候，LogicFlow 会校验每一条规则，只有**全部**通过后才能连接。
+:::
+
+连边时，当鼠标松开后如果没有通过自定义规则（`validate`方法返回值为`false`），LogicFlow
+会对外抛出事件`connection:not-allowed`。
+
+```tsx | pure
+lf.on('connection:not-allowed', (msg) => {
+  console.log(msg)
+});
+```
+
+下面举个例子，通过**设置不同状态下节点的样式**来展示连接状态👇
+
+在节点model中，有个state属性，当节点连接规则校验不通过时，state属性值为5。我们可以通过这个属性来实现连线时节点的提示效果。
+
+<code id="node-connect" src="../../../src/tutorial/advanced/node/connect"></code>
+
+## 移动
+
+有些时候，我们需要更加细粒度的控制节点什么时候可以移动，什么时候不可以移动，比如在实现分组插件时，需要控制分组节点子节点不允许移动出分组。和连线规则类似，我们可以给节点的`moveRules`
+添加规则函数。
+
+```tsx | pure
+class MovableNodeModel extends RectNodeModel {
+  initNodeData(data) {
+    super.initNodeData(data);
+    this.moveRules.push((model, deltaX, deltaY) => {
+      // 需要处理的内容
+    });
+  }
+}
+```
+
+在`graphModel`中支持添加全局移动规则，例如在移动A节点的时候，期望把B节点也一起移动了。
+
+```tsx | pure
+lf.graphModel.addNodeMoveRules((model, deltaX, deltaY) => {
+  // 如果移动的是分组，那么分组的子节点也跟着移动。
+  if (model.isGroup && model.children) {
+    lf.graphModel.moveNodes(model.children, deltaX, deltaY, true);
+  }
+  return true;
+});
+```
+
+<code id="node-movable" src="../../../src/tutorial/advanced/node/movable"></code>
+
+## 锚点
+
+对于各种基础类型节点，我们都内置了默认锚点。LogicFlow支持通过重写获取锚点的方法来实现自定义节点的锚点。
+
+<code id="node-sql" src="../../../src/tutorial/advanced/node/sql"></code>
+
+上面的示例中，我们自定义锚点的时候，不仅可以定义锚点的数量和位置，还可以给锚点加上任意属性。有了这些属性，我们可以再做很多额外的事情。例如，我们增加一个校验规则，只允许节点从右边连出，从左边连入；或者加个id,
+在获取数据的时候保存当前连线从那个锚点连接到那个锚点。
+
+:::warning{title=注意}
+一定要确保锚点id唯一，否则可能会出现在连线规则校验不准确的问题。
+在实际开发中，存在隐藏锚点的需求，可以参考github
+issue [如何隐藏锚点？](https://github.com/didi/LogicFlow/issues/454)，可以查看code
+sandbox [示例](https://codesandbox.io/s/reverent-haslett-dkb9n?file=/step_14_hideAnchor/index.js)
+:::
+### customTargetAnchor（自定义连线落点锚点）
+
+当你从锚点拖拽创建连线，并在某个节点上释放鼠标时，LogicFlow 需要根据鼠标释放位置（position）决定“目标节点”最终连接到哪个锚点。
+
+- 默认行为：连接到距离 position 最近的锚点
+- 自定义方式：在初始化 LogicFlow 时传入 `customTargetAnchor`，作为全局规则优先返回你期望的锚点；若返回 `undefined`，则回退到默认行为
+
+
+<code id="node-custom-target-anchor" src="../../../src/tutorial/advanced/node/customTargetAnchor"></code>
+
+## 文本
+
+LogicFlow 支持自定义节点文本的外观和编辑状态。参考 [nodeModel API](../../api/runtime-model/nodeModel.zh.md)
+中的`textObject`
+
+```tsx | pure
+class CustomNodeModel extends RectNodeModel {
+  initNodeData(data) {
+    super.initNodeData(data)
+    this.text.draggable = false; // 不允许文本被拖动
+    this.text.editable = false; // 不允许文本被编辑
+  }
+
+  getTextStyle() {
+    const style = super.getTextStyle();
+    style.fontSize = 16;
+    style.color = 'red';
+    return style;
+  }
+}
+```
+
+## HTML 节点
+
+LogicFlow内置了基础的HTML节点和其他基础节点不一样，我们可以利用LogicFlow的自定义机制，实现各种形态的HTML节点，而且HTML节点内部可以使用任意框架进行渲染。
+
+下面是HTML节点的示例👇
+
+<code id="node-html-node" src="../../../src/tutorial/advanced/node/htmlNode/index"></code>
+
+## React 节点
+
+因为自定义html节点对外暴露的是一个DOM节点，所以你可以使用框架现有的能力来渲染节点。在react中，我们利用`reactDom`
+的`render`方法，将react组件渲染到dom节点上。
+
+<code id="node-react-node" src="../../../src/tutorial/advanced/node/reactNode/index"></code>
+
+## Vue 节点
+
+<details> <summary>代码展开</summary>
+
+```tsx | pure
+import { HtmlNode, HtmlNodeModel } from "@logicflow/core";
+import { createApp, ref, h } from 'vue';
+import VueNode from './VueNode.vue';
+
+class VueHtmlNode extends HtmlNode {
+  constructor(props) {
+    super(props)
+    this.isMounted = false
+    this.r = h(VueNode, {
+      properties: props.model.getProperties(),
+      text: props.model.inputData,
+    })
+    this.app = createApp({
+      render: () => this.r
+    })
+  }
+
+  setHtml(rootEl) {
+    if (!this.isMounted) {
+      this.isMounted = true
+      const node = document.createElement('div')
+      rootEl.appendChild(node)
+      this.app.mount(node)
+    } else {
+      this.r.component.props.properties = this.props.model.getProperties()
+    }
+  }
+}
+
+class VueHtmlNodeModel extends HtmlNodeModel {
+  setAttributes() {
+    this.width = 300;
+    this.height = 100;
+    this.text.editable = false;
+    this.inputData = this.text.value
+  }
+
+  getOutlineStyle() {
+    const style = super.getOutlineStyle();
+    style.stroke = 'none';
+    style.hover.stroke = 'none';
+    return style;
+  }
+}
+
+export default {
+  type: 'vue-html',
+  model: VueHtmlNodeModel,
+  view: VueHtmlNode
+}
+```
+
+</details>
+
+## 外部通信
+
+当需要自定义节点与外部交互时，比如点击自定义 HTML 节点上的按钮，触发外部方法，可以用 LogicFlow
+的自定义事件机制来实现。
+
+```tsx | pure
+// view.js
+class VueHtmlNode extends HtmlNode {
+  constructor(props) {
+    super(props);
+    this.isMounted = false;
+    this.r = h(VueNode, {
+      properties: props.model.getProperties(),
+      text: props.model.inputData,
+      onBtnClick: (i) => {
+        props.graphModel.eventCenter.emit("custom:onBtnClick", i);
+      },
+    });
+    this.app = createApp({
+      render: () => this.r,
+    });
+  }
+
+  setHtml(rootEl) {
+    if (!this.isMounted) {
+      this.isMounted = true;
+      const node = document.createElement("div");
+      rootEl.appendChild(node);
+      this.app.mount(node);
+    } else {
+      this.r.component.props.properties = this.props.model.getProperties();
+    }
+  }
+
+  getText() {
+    return null;
+  }
+}
+
+// flow.js
+const lf = new LogicFlow();
+lf.render();
+lf.on("custom:onBtnClick", () => {});
+```
+
+:::success{title=提示}
+如果期望从外部传递一个方案给自定义节点使用。由于自定义节点中无法直接访问到`lf`实例，所以不支持直接给
+lf 绑定一个方法。但是自定义节点可以拿到整个图的 model 对象，也就是`graphModel`
+，所以可以把这个方法绑定到`graphModel`上。另外`lf`内置的方法`graphModel`
+中基本都有，所以在开发自定义节点的时候可以使用`graphModel`获取流程图相关数据即可。
+:::
+
+## 更新
+
+HTML节点目前通过修改properties触发节点更新。
+
+```tsx | pure
+ /**
+ * @overridable 支持重写
+ * 和react的shouldComponentUpdate类似，都是为了避免触发不必要的render.
+ * 但是这里不一样的地方在于，setHtml方法，我们只在properties发生变化了后再触发。
+ * 而x,y等这些坐标相关的方法发生了变化，不会再重新触发setHtml.
+ */
+class CustomComponent extends Component {
+  // ...
+  shouldUpdate() {
+    if (this.preProperties && this.preProperties === this.currentProperties) return
+    this.preProperties = this.currentProperties
+    return true
+  }
+
+  componentDidMount() {
+    if (this.shouldUpdate()) {
+      this.setHtml(this.rootEl)
+    }
+  }
+
+  componentDidUpdate() {
+    if (this.shouldUpdate()) {
+      this.setHtml(this.rootEl)
+    }
+  }
+
+  //..
+}
+```
+
+如果期望其他内容的修改可以触发节点更新，可以重写shouldUpdate（相关issue: [#1208](https://github.com/didi/LogicFlow/issues/1208)）
+
+```tsx | pure
+class CustomComponent extends Component {
+
+  shouldUpdate() {
+    if (this.preProperties &&
+      this.preProperties === this.currentProperties &&
+      this.preText === this.props.model.text.value
+    ) {
+      return
+    }
+    this.preProperties = this.currentProperties
+    this.preText = this.props.model.text.value
+    return true;
+  }
+}
+```
+

package/dist/docs/tutorial/advanced/react.en.md

@@ -0,0 +1,106 @@
+---
+nav: Guide
+group:
+  title: Intermediate
+  order: 2
+title: React Node Registry
+order:  6
+toc: content
+tag: New
+---
+
+:::info{title=New-Features-Introduction}
+- How to use React components to register node content
+- How to synchronize node content updates when properties change
+:::
+
+## Rendering React Components as Node Content
+Although we provide the capability to customize nodes by extending `HTMLNode`, user feedback indicates that this approach is not very intuitive and may cause performance issues due to improper destruction timing.
+
+Therefore, we offer a separate package `@logicflow/react-node-registry` to customize nodes in a more intuitive way by registering nodes through React components. This allows you to use the rich component libraries already included in the system or to quickly develop custom node content using React's convenient development features.
+
+```tsx | pure
+import { register, ReactNodeProps } from '@logicflow/react-node-registry'
+
+// Custom React component
+const NodeComponent: FC<ReactNodeProps> = ({ node }) => {
+  const data = node.getData()
+  if (!data.properties) data.properties = {}
+
+  return (
+    <div className="react-algo-node">
+      <img src={require('@/assets/didi.png')} alt="DiDi" />
+      <span>{data.properties.name as string}</span>
+    </div>
+  )
+}
+
+// Initialize LogicFlow instance
+const lf = new LogicFlow({
+  // ...options
+})
+
+// Register custom node
+register({
+  type: 'custom-react-node',
+  component: NodeComponent,
+}, lf)
+
+// Render custom node
+const node = lf.addNode({
+  id: 'react-node-1',
+  type: 'custom-react-node',
+  x: 80,
+  y: 80,
+  properties: {
+    name: 'Today's Trip',
+    width: 120,
+    height: 28,
+  },
+})
+console.log('node --->>>', node)
+```
+<code id="react-basic" src="@/src/tutorial/advanced/react/index.tsx"></code>
+
+## Updating Nodes
+Similar to `HTMLNode`, when users update node properties using `setProperties` or `setProperty`, the node content is automatically updated.
+
+```tsx | pure
+const node1 = lf.addNode({
+  id: 'react-node-1',
+  type: 'custom-react-node',
+  x: 80,
+  y: 80,
+  properties: {
+    name: 'Today's Trip',
+    width: 120,
+    height: 28,
+  },
+})
+
+const update = () => {
+  node1.setProperty('name', `Today's Trip ${(this.count += 1)}`)
+  this.timer = setTimeout(update, 1000)
+}
+
+update()
+
+// Remember to clear the timer in componentWillUnmount
+if (this.timer) {
+  clearTimeout(this.timer)
+}
+```
+
+## Portal Mode
+One drawback of the React component rendering method mentioned above is that the component is rendered into the node's DOM using the following method:
+
+```tsx | pure
+import { createRoot, Root } from 'react-dom/client'
+
+const root = createRoot(container)
+root.render(elem)
+```
+
+As a result, the React component is no longer part of the normal rendering document tree. This means it cannot access external Context content. If you have such use cases, you can use the `Portal` mode to render React components.
+
+<code id="react-portal" src="@/src/tutorial/advanced/react/Portal.tsx"></code>

package/dist/docs/tutorial/advanced/react.zh.md

@@ -0,0 +1,114 @@
+---
+nav: 指南
+group:
+  title: 进阶
+  order: 2
+title: React 节点
+order: 6
+toc: content
+tag: 新特性
+---
+
+:::info{title=我们带来了新特性，本节内容主要介绍}
+- 如何使用 React 组件来注册节点内容
+- properties 更新后如何同步更新节点内容
+:::
+
+::::info{title=阅读提示}
+- 适合已经理解 [节点](../basic/node.zh.md) 的 React 项目用户
+- 当前推荐优先使用 `@logicflow/react-node-registry`
+- 本页不展开连接规则、锚点和边能力；这些内容请回到 [进阶节点](node.zh.md)
+- 相关 API：[`nodeModel`](../../api/runtime-model/nodeModel.zh.md)、[`graphModel`](../../api/runtime-model/graphModel.zh.md)、[`事件`](../../api/logicflow-instance/event.zh.md)
+::::
+
+## 渲染 React 组件为节点内容
+我们虽然提供了通过继承 HTMLNode 自定义节点的能力，但从用户反馈来看，这种方式并不够直观且有可能因为销毁时机不对而出现性能问题。
+
+因此我们提供了一个独立的包 `@logicflow/react-node-registry`，以一种更直观的方式来自定义节点，即通过 React 组件来注册节点。
+它既可以直接使用系统中已引入的丰富的组件库，也可以使用 React 快捷的开发方式来自定义节点内容。
+
+```tsx | pure
+import { register, ReactNodeProps } from '@logicflow/react-node-registry'
+
+// 自定义 React 组件
+const NodeComponent: FC<ReactNodeProps> = ({ node }) => {
+  const data = node.getData()
+  if (!data.properties) data.properties = {}
+
+  return (
+    <div className="react-algo-node">
+      <img src={require('@/assets/didi.png')} alt="滴滴出行" />
+      <span>{data.properties.name as string}</span>
+    </div>
+  )
+}
+
+// 初始化 LogicFlow 实例
+const lf = new LogicFlow({
+  // ...options
+})
+
+// 注册自定义节点
+register({
+  type: 'custom-react-node',
+  component: NodeComponent,
+}, lf)
+
+// 渲染自定义节点
+const node = lf.addNode({
+  id: 'react-node-1',
+  type: 'custom-react-node',
+  x: 80,
+  y: 80,
+  properties: {
+    name: '今日出行',
+    width: 120,
+    height: 28,
+  },
+})
+console.log('node --->>>', node)
+```
+<code id="react-basic" src="@/src/tutorial/advanced/react/index.tsx"></code>
+
+## 更新节点
+跟 `HTMLNode` 一样，当用户通过 `setProperties` 或 `setProperty` 等更新节点 properties 时，我们会自动更新节点内容。
+
+```tsx | pure
+const node1 = lf.addNode({
+  id: 'react-node-1',
+  type: 'custom-react-node',
+  x: 80,
+  y: 80,
+  properties: {
+    name: '今日出行',
+    width: 120,
+    height: 28,
+  },
+})
+
+const update = () => {
+  node1.setProperty('name', `今日出行 ${(this.count += 1)}`)
+  this.timer = setTimeout(update, 1000)
+}
+
+update()
+
+// 记得在 componentWillUnmount 中清除定时器
+if (this.timer) {
+  clearTimeout(this.timer)
+}
+```
+
+## Portal 方式
+上面的 React 组件渲染方式有一个缺点，因为内部是通过以下方式将组件渲染到节点的 DOM 中。
+  
+```tsx | pure
+import { createRoot, Root } from 'react-dom/client'
+
+const root = createRoot(container)
+root.render(elem)
+```
+
+可以发现，React 组件已经不处于正常的渲染文档树中。所以它内部无法获取外部 Context 内容。如果有这种应用场景，可以使用 `Portal` 模式来渲染 React 组件。
+<code id="react-portal" src="@/src/tutorial/advanced/react/Portal.tsx"></code>
+

package/dist/docs/tutorial/advanced/silent-mode.en.md

@@ -0,0 +1,75 @@
+---
+nav: Guide
+group:
+  title: Intermediate
+  order: 2
+title: Edit Config Settings
+order: 5
+toc: content
+---
+
+LogicFlow provides a very large number of configurations that control how diagrams are edited,
+see [editConfigModel](../../api/runtime-model/graphModel.en.md#editconfigmodel) for details.
+
+## Initialization
+
+LogicFlow supports passing in many configuration parameters at initialization time, and the
+configuration for graph editing can also be passed in at initialization time.
+
+```tsx | pure
+const lf = new LogicFlow({
+  stopZoomGraph: true, // 禁止缩放
+  stopScrollGraph: true, // 禁止鼠标滚动移动画布
+});
+```
+
+## Updating the way the graph is edited
+
+```tsx | pure
+lf.updateEditConfig({
+  stopZoomGraph: false,
+  stopScrollGraph: false,
+})
+```
+
+## Silent Mode
+
+The silent mode of the canvas can be simply understood as a "read-only" mode, in which the nodes and
+edges of the canvas cannot be moved, no text modification is possible, and there are no anchor
+points.
+
+:::info{title=tip}
+Silent mode is just a shortcut to LogicFlow's built-in flowchart editing controls, a collection of
+multiple editing configurations that you can use to edit properties if the effect isn't satisfying.
+:::
+
+```tsx | pure
+const lf = new LogicFlow({
+  isSilentMode: true,
+});
+```
+
+Silent mode is equivalent to：
+
+```tsx | pure
+const SilentConfig = {
+  stopZoomGraph: false,
+  stopScrollGraph: false,
+  stopMoveGraph: false,
+  adjustEdge: false,
+  adjustEdgeStartAndEnd: false,
+  adjustNodePosition: false,
+  hideAnchors: true,
+  nodeSelectedOutline: true,
+  nodeTextEdit: false,
+  edgeTextEdit: false,
+  nodeTextDraggable: false,
+  edgeTextDraggable: false,
+};
+
+const lf = new LogicFlow({
+  ...SilentConfig
+});
+```
+
+<a href="https://codesandbox.io/embed/pedantic-microservice-db76o?fontsize=14&hidenavigation=1&theme=dark&view=preview"> Go to CodeSandbox for examples </a>

package/dist/docs/tutorial/advanced/silent-mode.zh.md

@@ -0,0 +1,71 @@
+---
+nav: 指南
+group:
+  title: 进阶
+  order: 2
+title: 图编辑配置项
+order: 5
+toc: content
+---
+
+LogicFlow提供了非常多的控制图如何编辑的配置，详情见[editConfigModel](../../api/runtime-model/graphModel.zh.md#editconfigmodel)。
+
+## 初始化
+
+LogicFlow 支持在初始化的时候传入很多配置参数，图编辑的配置也可以在初始化的时候传入。
+
+```tsx | pure
+const lf = new LogicFlow({
+  stopZoomGraph: true, // 禁止缩放
+  stopScrollGraph: true, // 禁止鼠标滚动移动画布
+});
+```
+
+## 更新图编辑方式
+
+```tsx | pure
+lf.updateEditConfig({
+  stopZoomGraph: false,
+  stopScrollGraph: false,
+});
+```
+
+## 静默模式
+
+画布的静默模式可以简单理解为“只读”模式，这种模式下，画布中的节点和边不可移动，不可进行文案修改，没有锚点。
+
+:::info{title=提示}
+静默模式只是 LogicFlow 内置的流程图编辑控制的一种快捷方式, 是多个编辑配置的集合，如果效果不满足，你可以使用这些属性编辑。
+:::
+
+```tsx | pure
+// 开启静默模式
+const lf = new LogicFlow({
+  isSilentMode: true,
+});
+```
+
+静默模式等同于：
+
+```tsx | pure
+const SilentConfig = {
+  stopZoomGraph: false,
+  stopScrollGraph: false,
+  stopMoveGraph: false,
+  adjustEdge: false,
+  adjustEdgeStartAndEnd: false,
+  adjustNodePosition: false,
+  hideAnchors: true,
+  nodeSelectedOutline: true,
+  nodeTextEdit: false,
+  edgeTextEdit: false,
+  nodeTextDraggable: false,
+  edgeTextDraggable: false,
+};
+// 开启静默模式
+const lf = new LogicFlow({
+  ...SilentConfig
+});
+```
+
+<a href="https://codesandbox.io/embed/pedantic-microservice-db76o?fontsize=14&hidenavigation=1&theme=dark&view=preview"> 去 CodeSandbox 查看示例</a>