@logicflow/core 2.2.0 → 2.2.2

package/dist/docs/api/runtime-model/edgeModel.zh.md

@@ -0,0 +1,325 @@
+---
+nav: API
+group:
+  title: 运行时 Model
+  order: 3
+title: edgeModel
+toc: content
+order: 14
+---
+
+<style>
+table td:first-of-type {
+  word-break: normal;
+}
+</style>
+
+LogicFlow 中所有的边都会有一个 edgeModel 与其对应。由于数据驱动视图的机制，我们对边的所有操作事实上就是对
+model 的操作。大多数情况下，我们不建议直接对 edgeModel 的属性进行赋值操作，而是调用 model
+或者[graphModel](./graphModel.zh.md)上提供的方法。
+
+## 数据属性
+
+边的数据属性是指在 LogicFlow 流程图保存时，保存边的数据。
+
+| 名称           | 类型            | 是否必须 | 描述                                   |
+|:-------------|:--------------|:-----|:-------------------------------------|
+| id           | string        | ✅    | 边 id                                 |
+| type         | string        | ✅    | 边类型                                  |
+| sourceNodeId | string        | ✅    | 开始节点 Id                              |
+| targetNodeId | string        | ✅    | 结束节点 Id                              |
+| startPoint   | Point         | ✅    | 边的开始坐标                               |
+| endPoint     | Point         | ✅    | 边的结束坐标                               |
+| text         | Object/string |      | 边文本                                  |
+| points       | string        |      | 控制边的轨迹                               |
+| pointsList   | Array         |      | 控制边的轨迹，`polyline`和`bezier`有，`line`没有 |
+| properties   | Object        |      | 边的自定义属性                              |
+
+## 状态属性
+
+一般用于自定义边的时候，基于状态属性进行更细粒度的样式显示。
+
+| 名称                | 类型      | 是否必须 | 描述               |
+|:------------------|:--------|:-----|:-----------------|
+| isSelected        | boolean | ✅    | 边是否被选中           |
+| isHovered         | boolean | ✅    | 边是否在 hover 状态    |
+| isHitable         | boolean | ✅    | 边是否可点击           |
+| draggable         | boolean | ✅    | 边是否可拖动           |
+| isDragging        | boolean | ✅    | 边是否正在拖动          |
+| isAnimation       | boolean | ✅    | 边是否有动画           |
+| isShowAdjustPoint | boolean | ✅    | 边是否显示边两端的调整点     |
+| visible           | boolean | ✅    | 边是否显示, `1.1.0`新增 |
+
+## 形状属性
+
+一般用于自定义边的时候，形状属性可以通过`setAttributes`来设置。
+
+| 名称     | 类型     | 是否必须 | 描述                                             |
+|:-------|:-------|:-----|:-----------------------------------------------|
+| offset | number |      | polyline 表示折线转折点基于节点的距离。 bezier 表示控制曲线调整手柄的长度。 |
+
+## 其它属性
+
+LogicFlow 在`model`上还维护一些属性，开发者可以通过这些属性拿到一些信息。例如拿到`graphModel`,
+节点的基础`model`类型等。
+
+| 名称                 | 类型                            | 是否必须 | 描述                                                                                                                                        |
+|:-------------------|:------------------------------|:-----|:------------------------------------------------------------------------------------------------------------------------------------------|
+| graphModel         | `GraphModel`                  | ✅    | 整个画布对应的 model，[详情见](./graphModel.zh.md)                                                                                                     |
+| zIndex             | number                        | ✅    | 节点在 z 轴的高度，元素重合时，zIndex 高的在上面。默认为 0                                                                                                       |
+| state              | number                        | ✅    | 元素状态，不同的状态对应着元素显示效果。DEFAULT = 1 默认显示；TEXT_EDIT = 2 此元素正在进行文本编辑；ALLOW_CONNECT = 4, 此元素允许作为当前边的目标节点；NOT_ALLOW_CONNECT = 5, 此元素不允许作为当前边的目标节点 |
+| BaseType           | string                        | ✅    | 当前 model 的基础类型，对于边，则固定为`edge`。主要用在节点和边混合的时候识别此`model`是节点还是边。                                                                              |
+| modelType          | string                        | ✅    | 当前 model 的类型，可取值有`edge`,`polyline`,`bezier`,`line`                                                                                        |
+| sourceAnchorId     | string                        | -    | 连线起点锚点 id                                                                                                                                 |
+| additionStateData  | `Model.AdditionStateDataType` | -    | 传递的额外值                                                                                                                                    |
+| targetAnchorId     | string                        | -    | 连线终点锚点 id                                                                                                                                 |
+| customTextPosition | boolean                       | -    | 自定义连线文本位置                                                                                                                                 |
+| style              | `LogicFlow.CommonTheme`       | -    | 边的样式                                                                                                                                      |
+| arrowConfig        | `{markerStart, markerEnd}`    | -    | 箭头属性                                                                                                                                      |
+| virtual            | boolean                       | -    | 是否为虚拟连线，默认 false。当为 true 时导出数据不会包含此元素。 `v1.1.24`                                                                                          |
+
+## 样式属性
+
+LogicFlow 所有的边最终都是以 SVG DOM 的方式渲染。svg 的样式相关属性都不会直接存在`edgeModel`。当开发者想要对
+SVG DOM 添加更多的 <a href="https://developer.mozilla.org/zh-CN/docs/Web/SVG/Attribute" target="_blank">svg 属性</a>
+时，可以通过重写`edgeModel`上获取边样式属性方法来实现。
+
+## getEdgeStyle
+
+支持重写，自定义边样式属性。默认为[主题（Theme 类型说明）](../logicflow-instance/theme.zh.md)
+
+```tsx | pure
+class SequenceFlowModel extends PolylineModel {
+  getEdgeStyle() {
+    const style = super.getEdgeStyle();
+    style.stroke = "blue";
+    style.strokeDasharray = "3 3";
+    return style;
+  }
+}
+```
+
+## getAdjustPointStyle
+
+自定义边调整点样式 (在 isShowAdjustPoint 为 true 时会显示调整点)
+
+返回值: `LogicFlow.CircleTheme`
+
+## getAnimation
+
+支持重写，自定义边的流向动画
+
+```tsx | pure
+class CustomBezierModel extends BezierEdgeModel {
+  getAnimation() {
+    const animation = super.getAnimation();
+    animation.stroke = "blue";
+    return animation;
+  }
+}
+```
+
+## getTextStyle
+
+支持重写，自定义边文本样式属性，默认为[主题（Theme 类型说明）](../logicflow-instance/theme.zh.md)
+
+```tsx | pure
+class SequenceFlowModel extends PolylineModel {
+  getTextStyle() {
+    const style = super.getTextStyle();
+    style.color = "blue";
+    style.fontSize = "20";
+    return style;
+  }
+}
+```
+
+## getEdgeAnimationStyle
+
+自定义边动画样式
+
+返回值：`LogicFlow.EdgeAnimation`
+
+```tsx | pure
+getEdgeAnimationStyle()
+{
+  const style = super.getEdgeAnimationStyle();
+  style.stroke = 'blue';
+  style.animationDuration = '30s';
+  style.animationDirection = 'reverse';
+  return style;
+}
+```
+
+## getArrowStyle
+
+自定义边箭头样式
+
+```tsx | pure
+getArrowStyle()
+{
+  const style = super.getArrowStyle();
+  style.stroke = 'green';
+  return style;
+}
+```
+
+## getOutlineStyle
+
+自定义边被选中时展示其范围的矩形框样式
+
+```tsx | pure
+getOutlineStyle()
+{
+  const style = super.getOutlineStyle();
+  style.stroke = 'none';
+  style.hover.stroke = 'none';
+  return style;
+}
+```
+
+## initEdgeData
+
+支持重写，初始化边数据。
+
+```tsx | pure
+class UserEdgeModel extends PolylineEdgeModel {
+  initEdgeData(data) {
+    super.initEdgeData(data);
+    this.offset = 20;
+  }
+}
+```
+
+:::info{title=提示}
+initEdgeData 和 setAttributes 都可以对 edgeModel 的属性进行赋值，但是两者的区别在于：<br>
+
+- `initEdgeData`只在初始化的时候调用，用于初始化的属性。
+- `setAttributes`除了初始化调用外，还会在 properties 发生变化了调用。
+  :::
+
+## setAttributes
+
+设置 model 形状属性，每次 properties 发生变化会触发
+
+```tsx | pure
+class UserEdgeModel extends PolylineEdgeModel {
+  setAttributes(data) {
+    super.setAttributes(data)
+    this.offset = 20
+  }
+}
+```
+
+## createId
+
+支持重写，自定义节点 id 的生成规则.
+
+:::warning{title=注意}
+
+1. 请保证此方法返回 id 的唯一性。<br>
+2. 此方法为同步方法，如果想要异步修改边 id,
+   请参考 <a href="https://github.com/didi/LogicFlow/issues/272" target="_blank">issues</a>。
+   :::
+
+```tsx | pure
+import { v4 as uuidv4 } from "uuid";
+
+class UserTaskModel extends RectNodeModel {
+  createId() {
+    return uuidv4();
+  }
+}
+```
+
+## getData
+
+获取被保存时返回的数据。LogicFlow 有固定边数据格式。如果期望在保存数据上添加数据，请添加到 properties
+上。
+
+不支持重写此方法
+
+```tsx | pure
+const edgeModel = lf.getEdgeModelById("edge_1");
+const edgeData = edgeModel.getData();
+```
+
+## getHistoryData
+
+同`getData`
+
+## getProperties
+
+获取边属性
+
+不支持重写此方法
+
+```tsx | pure
+const edgeModel = lf.getEdgeModelById("edge_1");
+const properties = edgeModel.getProperties();
+```
+
+## setProperties
+
+设置边 properties
+
+```tsx | pure
+const edgeModel = lf.getEdgeModelById("edge_1");
+edgeModel.setProperties({
+  // 自定义properties
+});
+```
+
+## deleteProperty
+
+删除边的某个属性
+
+```tsx | pure
+lf.on("edge:click", ({ data }) => {
+  lf.getEdgeModelById(data.id).deleteProperty("disabled");
+  lf.getEdgeModelById(data.id).deleteProperty("scale");
+});
+```
+
+## updateText
+
+修改边文本内容
+
+参数
+
+| 名称    | 类型     | 必传   | 默认值 | 描述  |
+|:------|:-------|:-----|:----|:----|
+| value | string | true | 无   | 文本值 |
+
+```tsx | pure
+const edgeModel = lf.getEdgeModelById("edge_1");
+edgeModel.updateText("hello world");
+```
+
+## getTextPosition
+
+支持重写，自定义连线上文本位置。
+
+## getAnchorPosition
+
+获取锚点位置
+
+入参：`sourceNode: BaseNodeModel, targetPosition: LogicFlow.Position`
+
+返回值：`LogicFlow.Point`
+
+## getBeginAnchor
+
+获取开始锚点
+
+入参：`sourceNode: BaseNodeModel, targetNode: BaseNodeModel`
+
+返回值：`LogicFlow.Point`
+
+## getEndAnchor
+
+获取结束锚点
+
+入参：`targetNode: BaseNodeModel`
+
+返回值：`LogicFlow.Point`

package/dist/docs/api/runtime-model/graphModel.en.md

@@ -0,0 +1,275 @@
+---
+nav: API
+group:
+  title: Runtime Model
+  order: 3
+title: graphModel
+toc: content
+order: 12
+---
+
+<style>
+table td:first-of-type {
+  word-break: normal;
+}
+</style>
+
+`graphModel` is the model for the entire LogicFlow canvas.
+
+Most instance methods are thin wrappers around `graphModel`.
+
+You can access `graphModel`:
+
+- From the instance: `lf.graphModel`
+- Inside a custom `model` constructor or methods via `this.graphModel`
+- Inside a custom `view` via `this.props.graphModel`
+
+```tsx | pure
+class CustomModel extends RectNodeModel {
+  getNodeStyle() {
+    const graphModel = this.graphModel
+  }
+}
+```
+
+```tsx | pure
+class CustomNode extends RectNode {
+  getShape() {
+    const { model, graphModel } = this.props
+    // ...
+  }
+}
+```
+
+:::info{title=Tip}
+All `graphModel` fields are read-only; change state only through the documented methods.
+:::
+
+## Properties
+
+| Property | Type | Default | Description |
+| :------- | :--- | :------ | :---------- |
+| width | `number` | | Canvas width |
+| height | `number` | | Canvas height |
+| theme | `LogicFlow.Theme` | | See [Theme API](../logicflow-instance/theme.en.md) |
+| animation | `boolean \| LFOptions.AnimationConfig` | false | Animation flags |
+| [eventCenter](#eventcenter) | `EventEmitter` | | Internal event hub |
+| modelMap | `Map<string, BaseNodeModel \| BaseEdgeModel>` | | Model ctor registry by type |
+| [topElement](#topElement) | `BaseNodeModel \| BaseEdgeModel` | | Top-most element (default overlap mode) |
+| idGenerator | `(type?: string) => string \| undefined` | | Custom id factory |
+| nodeMoveRules | `Model.NodeMoveRule[]` | [] | Hooks evaluated while moving nodes |
+| customTrajectory | `LFOptions.CustomAnchorLineProps` | | Custom anchor line renderer |
+| customTargetAnchor | `LFOptions.customTargetAnchorType` | | Anchor picking when manually connecting |
+| edgeGenerator | `LFOptions.EdgeGeneratorType` | | Edge type factory |
+| edgeType | `string` | | Default edge type for UI-created edges |
+| nodes | `BaseNodeModel[]` | [] | All node models |
+| edges | `BaseEdgeModel[]` | [] | All edge models |
+| fakeNode | `BaseNodeModel \| null` | null | Placeholder while dragging external nodes |
+| [overlapMode](#overlapmode) | `OverlapMode` | | Z-order policy when elements overlap |
+| background | `false \| LFOptions.BackgroundConfig` | | Background layer config |
+| transformModel | `TransformModel` | | Pan/zoom matrix; see [transformModel](#transformmodel) below |
+| editConfigModel | `EditConfigModel` | | Edit toggles; see [editConfigModel](#editconfigmodel) and [Edit config](../logicflow-instance/edit-config.en.md) |
+| gridSize | `number` | 1 | Grid step |
+| partial | `boolean` | false | Partial rendering for large graphs |
+| nodesMap | `GraphModel.NodesMapType` | | Node id → model map |
+| edgesMap | `GraphModel.EdgesMapType` | | Edge id → model map |
+| modelsMap | `GraphModel.ModelsMapType` | | Combined map |
+| selectNodes | `BaseNodeModel[]` | | Selected nodes |
+| sortElements | `array` | | Elements sorted by `zIndex` |
+| textEditElement | `BaseNodeModel \| BaseEdgeModel` | | Element currently in text edit |
+| selectElements | `Map<string, BaseNodeModel \| BaseEdgeModel>` | | Current selection map |
+
+### eventCenter {#eventcenter} (property)
+
+LogicFlow’s internal `EventEmitter` for custom events.
+
+```tsx | pure
+class UserTaskModel extends RectNodeModel {
+  setAttributes() {
+    this.menu = [
+      {
+        text: 'Details',
+        callback: (res) => {
+          this.graphModel.eventCenter.emit('user:detail', res)
+        },
+      },
+    ]
+  }
+}
+
+lf.on('user:detail', (res) => {})
+```
+
+### topElement (property)
+
+The element rendered on top in default overlap mode; used to restore ordering after temporary promotion.
+
+### overlapMode (property)
+
+Controls stacking when elements overlap.
+
+- `-1` (**STATIC**): selection does not change z-order; `toFront` is ignored; use per-element `zIndex`.
+- `0` (**DEFAULT**): nodes render above edges; selection temporarily raises elements.
+- `1` (**INCREASE**): each `toFront` bumps `zIndex` permanently.
+- `2` (**EDGE_TOP**): edges render above nodes; `toFront` still promotes temporarily.
+
+Only **INCREASE** and **STATIC** persist `zIndex` into serialized graph data.
+
+## transformModel {#transformmodel}
+
+`graphModel.transformModel` is the `TransformModel` instance that applies pan/zoom. Prefer `lf.graphModel.transformModel` or helpers on `lf` when available.
+
+### zoom(zoomSize, point)
+
+Zoom the canvas. Step size follows `transformModel.ZOOM_SIZE`.
+
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| zoomSize | `TransformModel.ZoomParamType` | false | Zoom factor (`0..n`), or `true` / `false` to step by the built-in preset. |
+| point | [`PointTuple`](../type/MainTypes.en.md#pointtuple) | optional | Anchor point for zoom (transform origin). |
+
+```tsx | pure
+const { transformModel } = lf.graphModel
+transformModel.zoom(true)
+```
+
+### resetZoom
+
+Reset zoom to the default scale.
+
+### translate(x, y)
+
+Pan the canvas by `(x, y)` in canvas space.
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| x | number | Delta on X. |
+| y | number | Delta on Y. |
+
+### focusOn(targetX, targetY, width, height)
+
+Center the rectangle `(targetX, targetY, width, height)` in the viewport.
+
+### HtmlPointToCanvasPoint(point)
+
+Maps a point from the HTML tool overlay into canvas overlay coordinates after applying zoom/pan.
+
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| point | `PointTuple` | Yes | Input coordinate. |
+
+Returns `PointTuple`.
+
+### CanvasPointToHtmlPoint(point)
+
+Inverse of `HtmlPointToCanvasPoint`.
+
+### updateTranslateLimits(limit)
+
+Updates how far the canvas may be panned. Argument type matches constructor option `stopMoveGraph`: `boolean \| 'vertical' \| 'horizontal' \| [number, number, number, number]`.
+
+## editConfigModel {#editconfigmodel}
+
+`graphModel.editConfigModel` holds interaction toggles (wheel zoom, canvas drag, adjust handles, anchors, selection outlines, text editing, multi-select keys, etc.). Instance helpers [`lf.updateEditConfig` / `lf.getEditConfig`](../logicflow-instance/edit-config.en.md) wrap this model.
+
+Field meanings and typings follow [`IEditConfigType`](../type/MainTypes.en.md#ieditconfigtype-edit-control); this section documents model methods only.
+
+### updateEditConfig(config)
+
+Merge partial edit configuration. Runs through `computeConfig`, including silent-mode bookkeeping.
+
+```ts
+updateEditConfig(config: Partial<IEditConfigType>): void
+```
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| config | `Partial<IEditConfigType>` | Keys to merge (see type dictionary). |
+
+### getConfig()
+
+Returns the fully merged edit configuration currently in effect (`IEditConfigType`).
+
+### updateTextMode(textMode)
+
+Updates global `textMode` and synchronizes related node/edge text modes.
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| textMode | `TextMode` | Same semantics as constructor `textMode`. |
+
+```ts
+import { TextMode } from '@logicflow/core'
+
+lf.graphModel.editConfigModel.updateTextMode(TextMode.LABEL)
+```
+
+## Methods {#methods}
+
+The following table summarizes `graphModel` mutation and query helpers. Several have matching shortcuts on the `lf` instance.
+
+| Method | Purpose |
+| ------ | ------- |
+| `getAreaElement(leftTop, rightBottom, wholeEdge?, wholeNode?, ignoreHide?)` | Elements intersecting a rectangle (legacy helper). |
+| `getModel(type)` | Registered model constructor for `type`. |
+| `getNodeModelById(id)` | Look up a node model by id. |
+| `getPointByClient(point)` | Convert a browser `Position` to `{ domOverlayPosition, canvasOverlayPosition }`. |
+| `isElementInArea(element, lt, rb, wholeEdge?, wholeNode?)` | Hit-test an element against a box. |
+| `getAreaElements(...)` | Same as `getAreaElement` with explicit defaults for hidden/hit rules. |
+| `graphDataToModel(graphData)` | Replace the entire canvas from [`GraphConfigData`](../type/MainTypes.en.md#graphconfigdata) (clears existing elements). |
+| `modelToGraphData()` | Export [`GraphConfigData`](../type/MainTypes.en.md#graphconfigdata). |
+| `modelToHistoryData()` | Snapshot formatted for the history stack (`false` when disabled). |
+| `getEdgeModelById(edgeId)` | Edge model lookup. |
+| `getElement(id)` | Node or edge model by id. |
+| `getNodeEdges(nodeId)` | All edges attached to a node. |
+| `getSelectElements(isIgnoreCheck?)` | Selected elements as graph config data. |
+| `getVirtualRectSize(includeEdge?)` | Bounding box of the diagram. |
+| `changeNodeId` / `changeEdgeId` | Rename elements while keeping wiring consistent. |
+| `handleEdgeTextMove(edge, x, y)` | Reposition edge label. |
+| `toFront(id)` | Bring node/edge forward per overlap rules. |
+| `setElementZIndex(id, zIndex)` | Manual stacking (`number` \| `'top'` \| `'bottom'`). |
+| `deleteNode` / `addNode` / `cloneNode` / `moveNode` / `moveNode2Coordinate` | Node lifecycle helpers. |
+| `editText(id)` | Open inline editor for node/edge text. |
+| `setElementState(type)` | Element-local state flag (see model docs). |
+| `addEdge` / `deleteEdge*` | Edge lifecycle helpers. |
+| `updateText(id, value)` | Update label string. |
+| `selectNodeById` / `selectEdgeById` / `selectElementById` / `clearSelectElements` | Selection API. |
+| `moveNodes(nodeIds, dx, dy)` | Batch move with edge refresh. |
+| `addNodeMoveRules(rule)` | Push additional move guards. |
+| `getNodeIncomingNode` / `getNodeOutgoingNode` | Graph neighbourhood (nodes). |
+| `getNodeIncomingEdge` / `getNodeOutgoingEdge` | Graph neighbourhood (edges). |
+| `setDefaultEdgeType(type)` | Change default edge created by UI. |
+| `changeNodeType` / `changeEdgeType` | Swap registered types in place. |
+| `openEdgeAnimation` / `closeEdgeAnimation` | Per-edge animation toggles. |
+| `setTheme(partial)` | Merge runtime theme overrides. |
+| `resize(width, height)` | Canvas dimensions. |
+| `clearData()` | Remove all nodes and edges. |
+| `translateCenter()` | Pan content to the canvas center. |
+| `fitView(verticalOffset?, horizontalOffset?)` | Zoom/pan to fit the diagram with padding. |
+
+### updateAttributes {#updateattributes}
+
+Low-level merge into element model fields.
+
+:::warning{title=Warning}
+Prefer `setProperties`, `updateText`, `changeNodeId`, and other high-level APIs. Writing ids or geometry incorrectly can desynchronize edges and hit-testing.
+:::
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| id | string | Element id. |
+| attributes | object | Patch object applied to the model. |
+
+### setElementStateById {#setelementstatebyid}
+
+Ensures a single element owns an interactive state (for example connection targeting).
+
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| id | string | Yes | Node or edge id. |
+| state | [`ElementState`](../type/MainTypes.en.md#elementstate) | Yes | Target state code. |
+| additionStateData | `Model.AdditionStateDataType` | No | Extra payload for the state machine. |
+
+```tsx | pure
+lf.graphModel.setElementStateById('node_1', 4)
+```