@logicflow/core 2.2.1 → 2.2.2

package/dist/docs/tutorial/extension/node-resize.zh.md

@@ -0,0 +1,221 @@
+---
+nav: 指南
+group:
+  title: 插件功能
+  order: 3
+title: 节点缩放 (NodeResize)
+order: 16
+toc: content
+tag: 已内置
+---
+
+## 使用
+
+LogicFlow 在 extension 包中提供了`RectResize`、`EllipseResize`、`DiamondResize`、`HtmlResize`这 4
+种支持缩放的基础节点, 每个节点都有`view`和`model`这两个属性。节点的缩放也是利用 LogicFlow
+的自定义节点机制，使开发者可以继承这 4 种可以缩放的节点，来实现节点的缩放。
+
+以我们需要一个可以缩放的矩形为例，在以前我们不支持节点缩放时，我们自定义节点方式为：
+
+```tsx | pure
+// 不可以缩放的节点
+import { RectNode, RectNodeModel } from '@logicflow/core'
+
+class CustomNode extends RectNode {
+}
+
+class CustomNodeModel extends RectNodeModel {
+}
+
+export default {
+  type: 'custom-node',
+  model: CustomNodeModel,
+  view: CustomNode,
+}
+```
+
+如果我们期望自定义的节点可以缩放，那么则改成：
+
+```tsx | pure
+// 支持缩放的节点
+import { RectResize } from "@logicflow/extension";
+
+class CustomNode extends RectResize.view {
+}
+
+class CustomNodeModel extends RectResize.model {
+}
+
+export default {
+  type: "custom-node",
+  model: CustomNodeModel,
+  view: CustomNode,
+};
+```
+
+### 设置节点的形状属性
+
+LogicFlow 把节点的宽高、半径等属性称之为[形状属性](../../api/runtime-model/nodeModel.zh.md#形状属性)，我们可以重写
+model 中的[initNodeData](../../api/runtime-model/nodeModel.zh.md#initnodedata)
+或者[setAttributes](../../api/runtime-model/nodeModel.zh.md#setattributes)
+方法来设置节点的形状属性。但是当节点可以缩放后，我们不能在`setAttributes`
+中设置宽高，只能在`initNodeData`中设置。
+
+```tsx | pure
+class ResizableRectModel extends RectResize.model {
+  initNodeData(data) {
+    super.initNodeData(data);
+    this.width = 100;
+    this.height = 40;
+  }
+}
+```
+
+### 自定义节点的 view
+
+在自定义节点中提到过，对于样式属性比较复杂的节点，我们可以重写`view`中的`getShape`
+方法来实现自定义节点真实渲染的外观。但是由于自定义节点需要在节点外观上填加用于缩放的调整点，所以对于自定义可缩放节点的
+view，我们需要重写`getResizeShape`, 而不是`getShape`。
+
+```tsx | pure
+import { RectResize } from "@logicflow/extension";
+
+class ResizableRectModel extends RectResize.model {
+  initNodeData(data) {
+    super.initNodeData(data);
+    this.width = 100;
+    this.height = 40;
+    this.text.draggable = true;
+  }
+}
+
+class ResizableRectView extends RectResize.view {
+  /**
+   * 此方法替代自定义节点的getShape方法。
+   */
+  getResizeShape() {
+    const { model } = this.props;
+    const { x, y, width, height, radius, properties } = model;
+    const style = model.getNodeStyle();
+    return h("g", {}, [
+      h("rect", {
+        ...style,
+        x: x - width / 2,
+        y: y - height / 2,
+        rx: radius,
+        ry: radius,
+        width,
+        height,
+      }),
+    ]);
+  }
+}
+
+export default {
+  type: "resizable-rect",
+  view: ResizableRectView,
+  model: ResizableRectModel,
+};
+```
+
+:::info{title=提示}
+对于继承`HtmlResize`的节点，自定义`view`请继续使用自定义 HTML 节点的`view`的`setHtml`方法。
+:::
+
+## 事件
+
+节点缩放后抛出事件`node:resize`，抛出数据包括节点缩放前后的节点位置、节点大小信息， 数据为{preData,
+data}, 详细字段如下。
+
+| 名称      | 类型   | 描述                     |
+| :-------- | :----- | :----------------------- |
+| id        | string | 节点 id                  |
+| type      | string | 节点类型                 |
+| modelType | string | 节点图形类型，已内部定义 |
+| x         | number | 节点中心 x 轴坐标        |
+| y         | number | 节点中心 y 轴坐标        |
+| rx        | number | x 轴半径(椭圆、菱形)     |
+| ry        | number | y 轴半径(椭圆、菱形)     |
+| width     | number | 节点宽度(矩形)           |
+| height    | number | 节点高度(矩形)           |
+
+```tsx | pure
+lf.on("node:resize", ({ preData, data }) => {
+  console.log(preData, data);
+});
+```
+
+## 设置放大缩小的最大最小值
+
+`v1.1.8`后，节点的放大缩小支持设置最大值和最小值。
+
+```tsx | pure
+class ResizableRectModel extends RectResize.model {
+  initNodeData(data) {
+    super.initNodeData(data);
+    this.width = 100;
+    this.height = 40;
+    this.maxWidth = 400;
+    this.maxHeight = 400;
+  }
+}
+```
+
+## 设置放大缩小的调整默认距离
+
+`v1.1.8`后，支持设置节点的`girdSize`属性，用来控制鼠标移动多少距离后开始缩放节点。
+
+```tsx | pure
+class ResizableRectModel extends RectResize.model {
+  initNodeData(data) {
+    super.initNodeData(data);
+    this.gridSize = 400;
+  }
+}
+```
+
+:::info{title=关于节点缩放的 gridSize}
+大多数情况下，为了保证节点的`整齐`，便于节点之间的上下左右对齐。`logicflow`
+默认在放大缩小时，只有鼠标移动的距离达到初始化画布传入的`gridSize`
+两倍时才改变节点的大小。但是这样会有一个缺点，那就是调整的时候有卡顿的感觉。可以在不改变初始化`gridSize`
+的情况下，单独设置每个节点的`gridSize`来让放大缩小节点更流畅。
+:::
+
+## 设置调整边框样式
+
+可放大缩小节点在被选中时，会贴着节点显示一个虚线框（矩形没有）。可以通过重写`getResizeOutlineStyle`
+方法实现自定义其样式。
+
+```tsx | pure
+class ResizableRectModel extends RectResize.model {
+  getResizeOutlineStyle() {
+    return {
+      stroke: "#000000",
+      strokeWidth: 1,
+      strokeDasharray: "3,3",
+    };
+  }
+}
+```
+
+## 设置调整点样式
+
+可放大缩小节点在被选中时，会在虚线框的四个角生成调整节点大小的操作点，可以通过重写`getControlPointStyle`
+方法实现自定义其样式。
+
+```tsx | pure
+class ResizableRectModel extends RectResize.model {
+  getControlPointStyle() {
+    return {
+      width: 7,
+      height: 7,
+      fill: "#FFFFFF",
+      stroke: "#000000",
+    };
+  }
+}
+```
+
+地址: [https://codesandbox.io/s/prod-resonance-ztpvtv](https://codesandbox.io/s/prod-resonance-ztpvtv?file=/step_26_nodeResize/index.js)
+
+<a href="https://codesandbox.io/embed/prod-resonance-ztpvtv?fontsize=14&hidenavigation=1&theme=dark&view=preview" target="_blank"> 去 CodeSandbox 查看示例</a>

package/dist/docs/tutorial/extension/pool.en.md

@@ -0,0 +1,227 @@
+---
+nav: Guide
+group:
+  title: Plug-in functionality
+  order: 3
+title: Swimlane (Pool)
+order: 14
+toc: content
+---
+
+LogicFlow provides a swimlane solution built on the DynamicGroup mechanism. A pool (`pool`) contains multiple lanes (`lane`). Lanes hold business nodes, and the plugin can automatically assign nodes to lanes during drag/drop. It also provides built-in interactions to insert and delete lanes.
+
+## Demonstration
+
+<code id="react-portal" src="@/src/tutorial/extension/pool"></code>
+
+## Using the Plugin
+
+```tsx | pure
+import LogicFlow from '@logicflow/core'
+import { PoolElements } from '@logicflow/extension'
+import '@logicflow/core/es/index.css'
+import '@logicflow/extension/es/index.css'
+
+const lf = new LogicFlow({
+  container: document.querySelector('#container') as HTMLElement,
+  plugins: [PoolElements],
+  allowResize: true,
+})
+```
+
+## Quick Start
+
+Create a node with `type: 'pool'`. If no lanes exist when the pool is first rendered, a default lane is created automatically.
+
+```ts | pure
+lf.render({
+  nodes: [
+    {
+      id: 'pool_1',
+      type: 'pool',
+      x: 400,
+      y: 260,
+      text: 'Pool',
+      properties: {
+        direction: 'horizontal',
+        width: 520,
+        height: 360,
+      },
+    },
+  ],
+  edges: [],
+})
+```
+
+## Data Format
+
+Pool/Lane nodes are special nodes. You can use `children` to describe hierarchy. During interactions, the plugin also maintains `properties.parent` for child nodes automatically.
+
+### Pool (`pool`)
+
+```ts
+type PoolProperties = {
+  direction?: 'horizontal' | 'vertical'
+  width?: number
+  height?: number
+  laneConfig?: Record<string, unknown>
+  children?: string[]
+}
+```
+
+### Lane (`lane`)
+
+```ts
+type LaneProperties = {
+  parent?: string
+  width?: number
+  height?: number
+  isRestrict?: boolean
+  autoResize?: boolean
+  children?: string[]
+}
+```
+
+### Full Example
+
+```ts | pure
+lf.render({
+  nodes: [
+    {
+      id: 'pool_1',
+      type: 'pool',
+      x: 500,
+      y: 260,
+      text: 'Pool (H)',
+      properties: {
+        direction: 'horizontal',
+        width: 520,
+        height: 360,
+        children: ['lane_1', 'lane_2'],
+      },
+      children: ['lane_1', 'lane_2'],
+    },
+    {
+      id: 'lane_1',
+      type: 'lane',
+      x: 540,
+      y: 340,
+      text: 'Lane 1',
+      properties: {
+        parent: 'pool_1',
+        width: 440,
+        height: 180,
+        isRestrict: true,
+        autoResize: false,
+        children: ['rect_1'],
+      },
+      children: ['rect_1'],
+    },
+    {
+      id: 'lane_2',
+      type: 'lane',
+      x: 540,
+      y: 160,
+      text: 'Lane 2',
+      properties: {
+        parent: 'pool_1',
+        width: 440,
+        height: 180,
+        children: ['circle_1'],
+      },
+      children: ['circle_1'],
+    },
+    {
+      id: 'rect_1',
+      type: 'rect',
+      x: 470,
+      y: 350,
+      text: 'Node A',
+      properties: {
+        parent: 'lane_1',
+      },
+    },
+    {
+      id: 'circle_1',
+      type: 'circle',
+      x: 620,
+      y: 150,
+      text: 'Node B',
+      properties: {
+        parent: 'lane_2',
+      },
+    },
+  ],
+  edges: [],
+})
+```
+
+## Interactions
+
+### Automatic Lane Assignment
+
+When you drag/drop a node into a lane area, the plugin assigns the node to that lane. If the node already belongs to another lane, it is removed from the previous lane first.
+
+### Insert/Delete Lanes
+
+When a lane is selected, operation icons appear on the right:
+
+- Insert: insert a new lane before/after the current lane (Up/Down for horizontal pools, Left/Right for vertical pools)
+- Delete: delete the current lane (at least one lane is kept)
+
+## API
+
+### Plugin API
+
+After enabling the plugin, access the plugin instance via `lf.graphModel.dynamicGroup`:
+
+#### getLaneByNodeId(nodeId)
+
+Get the lane model that a node belongs to.
+
+```ts | pure
+const laneModel = lf.graphModel.dynamicGroup.getLaneByNodeId('node_1')
+```
+
+#### getLaneByBounds(bounds, nodeData)
+
+Get the lane model for a given bounds. If multiple lanes overlap, the topmost lane is returned.
+
+```ts | pure
+const bounds = { minX: 100, minY: 100, maxX: 200, maxY: 200 }
+const nodeData = { id: 'temp', type: 'rect' }
+const laneModel = lf.graphModel.dynamicGroup.getLaneByBounds(bounds, nodeData)
+```
+
+### Pool Model Methods
+
+#### getLanes
+
+Get all lane models in the pool.
+
+#### addChildAbove / addChildBelow / addChildLeft / addChildRight
+
+Insert a new lane before/after a reference lane (depending on pool direction).
+
+#### deleteChild(childId)
+
+Delete a lane.
+
+### Lane Model Methods
+
+#### getPoolId / getPoolModel
+
+Get the owning pool of a lane.
+
+## Events
+
+### lane:not-allowed
+
+Triggered when a node is not allowed to be appended into a lane:
+
+```ts | pure
+lf.on('lane:not-allowed', ({ lane, node }) => {
+  console.log('not allowed', lane.id, node.id)
+})
+```
+

package/dist/docs/tutorial/extension/pool.zh.md

@@ -0,0 +1,227 @@
+---
+nav: 指南
+group:
+  title: 插件功能
+  order: 3
+title: 泳池泳道 (Pool)
+order: 14
+toc: content
+---
+
+LogicFlow 支持泳池泳道能力。泳池（pool）用于承载多个泳道（lane），泳道用于承载业务节点，并支持在拖拽/放置时自动把节点加入对应泳道，同时提供插入/删除泳道的交互入口。
+
+## 演示
+
+<code id="react-portal" src="@/src/tutorial/extension/pool"></code>
+
+## 使用插件
+
+```tsx | pure
+import LogicFlow from '@logicflow/core'
+import { PoolElements } from '@logicflow/extension'
+import '@logicflow/core/es/index.css'
+import '@logicflow/extension/es/index.css'
+
+const lf = new LogicFlow({
+  container: document.querySelector('#container') as HTMLElement,
+  plugins: [PoolElements],
+  allowResize: true,
+})
+```
+
+## 快速开始
+
+只需要新增一个 `type: 'pool'` 的节点即可。泳池在首次渲染且没有泳道时，会自动创建一条默认泳道。
+
+```ts | pure
+lf.render({
+  nodes: [
+    {
+      id: 'pool_1',
+      type: 'pool',
+      x: 400,
+      y: 260,
+      text: '泳池',
+      properties: {
+        direction: 'horizontal',
+        width: 520,
+        height: 360,
+      },
+    },
+  ],
+  edges: [],
+})
+```
+
+## 数据格式
+
+泳池/泳道基于 DynamicGroup 机制实现，因此它们仍然是“特殊节点”。在数据层面，你可以使用 `children` 来描述层级关系；同时插件也会在交互过程中自动维护子节点的 `properties.parent`。
+
+### 泳池（pool）
+
+```ts
+type PoolProperties = {
+  direction?: 'horizontal' | 'vertical'
+  width?: number
+  height?: number
+  laneConfig?: Record<string, unknown>
+  children?: string[]
+}
+```
+
+### 泳道（lane）
+
+```ts
+type LaneProperties = {
+  parent?: string
+  width?: number
+  height?: number
+  isRestrict?: boolean
+  autoResize?: boolean
+  children?: string[]
+}
+```
+
+### 完整示例
+
+```ts | pure
+lf.render({
+  nodes: [
+    {
+      id: 'pool_1',
+      type: 'pool',
+      x: 500,
+      y: 260,
+      text: '横向泳池',
+      properties: {
+        direction: 'horizontal',
+        width: 520,
+        height: 360,
+        children: ['lane_1', 'lane_2'],
+      },
+      children: ['lane_1', 'lane_2'],
+    },
+    {
+      id: 'lane_1',
+      type: 'lane',
+      x: 540,
+      y: 340,
+      text: '泳道1',
+      properties: {
+        parent: 'pool_1',
+        width: 440,
+        height: 180,
+        isRestrict: true,
+        autoResize: false,
+        children: ['rect_1'],
+      },
+      children: ['rect_1'],
+    },
+    {
+      id: 'lane_2',
+      type: 'lane',
+      x: 540,
+      y: 160,
+      text: '泳道2',
+      properties: {
+        parent: 'pool_1',
+        width: 440,
+        height: 180,
+        children: ['circle_1'],
+      },
+      children: ['circle_1'],
+    },
+    {
+      id: 'rect_1',
+      type: 'rect',
+      x: 470,
+      y: 350,
+      text: '节点A',
+      properties: {
+        parent: 'lane_1',
+      },
+    },
+    {
+      id: 'circle_1',
+      type: 'circle',
+      x: 620,
+      y: 150,
+      text: '节点B',
+      properties: {
+        parent: 'lane_2',
+      },
+    },
+  ],
+  edges: [],
+})
+```
+
+## 交互说明
+
+### 节点自动归属泳道
+
+当你把节点拖拽/放置到某条泳道区域内时，插件会自动把节点加入该泳道。若节点原本属于其他泳道，会先从旧泳道移除，再加入新泳道。
+
+### 插入/删除泳道
+
+选中泳道后，泳道右侧会显示操作按钮：
+
+- 插入：在当前泳道的前/后插入一条新泳道（横向泳池为“上/下”，竖向泳池为“左/右”）
+- 删除：删除当前泳道（至少保留 1 条泳道）
+
+## API
+
+### 插件类 API
+
+启用插件后，可通过 `lf.graphModel.dynamicGroup` 访问插件实例方法：
+
+#### getLaneByNodeId(nodeId)
+
+根据节点 id 获取其所属泳道的模型。
+
+```ts | pure
+const laneModel = lf.graphModel.dynamicGroup.getLaneByNodeId('node_1')
+```
+
+#### getLaneByBounds(bounds, nodeData)
+
+根据边界框获取该区域所属的泳道。当泳道重合时，优先返回最上层的泳道。
+
+```ts | pure
+const bounds = { minX: 100, minY: 100, maxX: 200, maxY: 200 }
+const nodeData = { id: 'temp', type: 'rect' }
+const laneModel = lf.graphModel.dynamicGroup.getLaneByBounds(bounds, nodeData)
+```
+
+### 泳池（pool）模型方法
+
+#### getLanes
+
+获取泳池内所有泳道模型。
+
+#### addChildAbove / addChildBelow / addChildLeft / addChildRight
+
+在指定泳道的前/后插入新泳道（方向由泳池布局决定）。
+
+#### deleteChild(childId)
+
+删除泳道。
+
+### 泳道（lane）模型方法
+
+#### getPoolId / getPoolModel
+
+从泳道反查其所属泳池。
+
+## 事件
+
+### lane:not-allowed
+
+当节点不被允许加入目标泳道时触发：
+
+```ts | pure
+lf.on('lane:not-allowed', ({ lane, node }) => {
+  console.log('not allowed', lane.id, node.id)
+})
+```
+