@logicflow/core 2.2.1 → 2.2.3

package/dist/docs/api/logicflow-instance/element.zh.md

@@ -0,0 +1,379 @@
+---
+nav: API
+group:
+  title: LogicFlow 实例
+  order: 2
+title: 元素相关
+toc: content
+order: 4
+---
+
+本页汇总 LogicFlow 实例中面向节点与边等元素的批量操作、选择控制与属性更新方法。
+
+### addElements
+
+批量添加节点和边。
+
+**签名**
+
+```ts
+addElements(data: GraphData): void
+```
+
+**参数**
+
+| 名称 | 类型 | 必传 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `data` | [`GraphData`](../type/MainTypes.zh.md#graphdata画布数据) | 是 | 批量添加的节点与边数据。 |
+
+**示例**
+
+```ts
+lf.addElements({
+  nodes: [{ id: 'node_1', type: 'rect', x: 100, y: 100 }],
+  edges: [],
+});
+```
+
+### selectElementById
+
+选中指定图形元素。
+
+**签名**
+
+```ts
+selectElementById(id: string, multiple?: boolean, toFront?: boolean): BaseNodeModel | BaseEdgeModel
+```
+
+**参数**
+
+| 名称 | 类型 | 必传 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `id` | `string` | 是 | 节点或边 ID。 |
+| `multiple` | `boolean` | 否 | 是否多选；`true` 时保留已有选中项。 |
+| `toFront` | `boolean` | 否 | 是否将选中元素置顶。 |
+
+**返回值**
+
+| 类型 | 说明 |
+| :--- | :--- |
+| `BaseNodeModel \| BaseEdgeModel` | 选中的元素 model。 |
+
+**示例**
+
+```ts
+lf.selectElementById('node_1', true, true);
+```
+
+### deselectElementById
+
+取消指定元素的选中状态。
+
+**签名**
+
+```ts
+deselectElementById(id: string): void
+```
+
+**参数**
+
+| 名称 | 类型 | 必传 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `id` | `string` | 是 | 元素 ID。 |
+
+**示例**
+
+```ts
+lf.deselectElementById('node_1');
+```
+
+### getSelectElements
+
+获取当前选中的所有元素数据。
+
+**签名**
+
+```ts
+getSelectElements(isIgnoreCheck?: boolean): GraphConfigData
+```
+
+**参数**
+
+| 名称 | 类型 | 必传 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `isIgnoreCheck` | `boolean` | 否 | 是否包含 source/target 未被选中的边，默认包含。 |
+
+**返回值**
+
+| 类型 | 说明 |
+| :--- | :--- |
+| [`GraphConfigData`](../type/MainTypes.zh.md#graphconfigdata流程图渲染数据类型) | 当前选中元素数据。 |
+
+**示例**
+
+```ts
+lf.getSelectElements(false);
+```
+
+### clearSelectElements
+
+取消所有元素的选中状态。
+
+**签名**
+
+```ts
+clearSelectElements(): void
+```
+
+**示例**
+
+```ts
+lf.clearSelectElements();
+```
+
+### getModelById
+
+按节点或边 ID 获取对应 model。
+
+**签名**
+
+```ts
+getModelById(id: string): BaseNodeModel | BaseEdgeModel | undefined
+```
+
+**参数**
+
+| 名称 | 类型 | 必传 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `id` | `string` | 是 | 节点或边 ID。 |
+
+**返回值**
+
+| 类型 | 说明 |
+| :--- | :--- |
+| `BaseNodeModel \| BaseEdgeModel \| undefined` | 元素 model；不存在时返回 `undefined`。 |
+
+**示例**
+
+```ts
+lf.getModelById('node_id');
+lf.getModelById('edge_id');
+```
+
+### getDataById
+
+按节点或边 ID 获取对应数据。
+
+**签名**
+
+```ts
+getDataById(id: string): NodeConfig | EdgeConfig | undefined
+```
+
+**参数**
+
+| 名称 | 类型 | 必传 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `id` | `string` | 是 | 节点或边 ID。 |
+
+**返回值**
+
+| 类型 | 说明 |
+| :--- | :--- |
+| [`NodeConfig`](../type/MainTypes.zh.md#nodeconfig节点配置) \| [`EdgeConfig`](../type/MainTypes.zh.md#edgeconfig边配置) \| `undefined` | 元素数据；不存在时返回 `undefined`。 |
+
+### deleteElement
+
+删除节点或边元素。
+
+**签名**
+
+```ts
+deleteElement(id: string): boolean
+```
+
+**参数**
+
+| 名称 | 类型 | 必传 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `id` | `string` | 是 | 节点或边 ID。 |
+
+**返回值**
+
+| 类型 | 说明 |
+| :--- | :--- |
+| `boolean` | 是否删除成功。 |
+
+**示例**
+
+```ts
+lf.deleteElement('node_id');
+```
+
+### setElementZIndex
+
+设置元素 zIndex。
+
+**签名**
+
+```ts
+setElementZIndex(id: string, zIndex: string | number): void
+```
+
+**参数**
+
+| 名称 | 类型 | 必传 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `id` | `string` | 是 | 节点或边 ID。 |
+| `zIndex` | `string \| number` | 是 | 可传数字或 `top` / `bottom`。 |
+
+**示例**
+
+```ts
+lf.setElementZIndex('element_id', 'top');
+```
+
+### getAreaElement
+
+获取指定 DOM 区域内的元素集合。
+
+**签名**
+
+```ts
+getAreaElement(
+  leftTopPoint: PointTuple,
+  rightBottomPoint: PointTuple,
+  wholeEdge?: boolean,
+  wholeNode?: boolean,
+  ignoreHideElement?: boolean
+): (BaseNodeModel | BaseEdgeModel)[]
+```
+
+**参数**
+
+| 名称 | 类型 | 必传 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `leftTopPoint` | `PointTuple` | 是 | 区域左上点。 |
+| `rightBottomPoint` | `PointTuple` | 是 | 区域右下点。 |
+| `wholeEdge` | `boolean` | 否 | 是否要求整条边都在区域内。 |
+| `wholeNode` | `boolean` | 否 | 是否要求整个节点都在区域内。 |
+| `ignoreHideElement` | `boolean` | 否 | 是否忽略隐藏元素。 |
+
+**返回值**
+
+| 类型 | 说明 |
+| :--- | :--- |
+| `(BaseNodeModel \| BaseEdgeModel)[]` | 命中区域的元素 model 列表。 |
+
+**示例**
+
+```ts
+lf.getAreaElement([100, 100], [500, 500]);
+```
+
+### setProperties
+
+设置节点或边的自定义属性。
+
+**签名**
+
+```ts
+setProperties(id: string, properties: Record<string, unknown>): void
+```
+
+**参数**
+
+| 名称 | 类型 | 必传 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `id` | `string` | 是 | 节点或边 ID。 |
+| `properties` | `Record<string, unknown>` | 是 | 自定义属性对象。 |
+
+**示例**
+
+```ts
+lf.setProperties('aF2Md2P23moN2gasd', {
+  isRollbackNode: true,
+});
+```
+
+### getProperties
+
+获取节点或边的自定义属性。
+
+**签名**
+
+```ts
+getProperties(id: string): Record<string, any>
+```
+
+**参数**
+
+| 名称 | 类型 | 必传 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `id` | `string` | 是 | 节点或边 ID。 |
+
+**返回值**
+
+| 类型 | 说明 |
+| :--- | :--- |
+| `Record<string, any>` | 自定义属性对象。 |
+
+**示例**
+
+```ts
+lf.getProperties('id');
+```
+
+### deleteProperty
+
+删除节点或边的指定属性键。
+
+**签名**
+
+```ts
+deleteProperty(id: string, key: string): void
+```
+
+**参数**
+
+| 名称 | 类型 | 必传 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `id` | `string` | 是 | 节点或边 ID。 |
+| `key` | `string` | 是 | 要删除的属性键名。 |
+
+**示例**
+
+```ts
+lf.deleteProperty('aF2Md2P23moN2gasd', 'isRollbackNode');
+```
+
+### updateAttributes
+
+修改元素 model 属性；该方法内部调用 `graphModel` 的同名能力。
+
+:::warning{title=注意}
+此方法慎用，除非您对 LogicFlow 内部有足够了解。  
+大多数情况下，请优先使用 `setProperties`、`updateText`、`changeNodeId` 等更高层方法。  
+例如直接使用该方法修改节点 `id`，可能导致连接到此节点的边出现 `sourceNodeId` 无法匹配的问题。
+:::
+
+**签名**
+
+```ts
+updateAttributes(id: string, attributes: object): void
+```
+
+更多说明参考 [`graphModel.updateAttributes`](../runtime-model/graphModel.zh.md#updateattributes)。
+
+**参数**
+
+| 名称 | 类型 | 必传 | 说明 |
+| :--- | :--- | :--- | :--- |
+| `id` | `string` | 是 | 元素 ID。 |
+| `attributes` | `object` | 是 | 要更新的 model 属性。 |
+
+**示例**
+
+```ts
+lf.updateAttributes('node_id_1', { radius: 4 });
+```

package/dist/docs/api/logicflow-instance/event.en.md

@@ -0,0 +1,326 @@
+---
+nav: API
+group:
+  title: LogicFlow Instance
+  order: 2
+title: Events
+toc: content
+order: 7
+---
+
+<style>
+table td:first-of-type {
+  word-break: normal;
+}
+</style>
+
+LogicFlow exposes an event bus so your code can react to diagram interactions. For narrative examples, see the guide [Events](../../tutorial/basic/event.en.md).
+
+## Event APIs
+
+### on
+
+Subscribe to one or many events (comma-separated names).
+
+**Parameters**
+
+| Name | Type | Required | Default | Description |
+| :------- | :------------ | :--- | :----- | :----------------------------------- |
+| evt | string | Yes | - | Event name(s). |
+| callback | EventCallback | Yes | - | Handler. |
+
+**Example**
+
+```ts
+lf.on('node:click', (data) => {
+  console.log('node clicked', data);
+});
+
+lf.on('node:click,edge:click', (data) => {
+  console.log('element clicked', data);
+});
+
+lf.on('node:drag', ({ data }) => {
+  console.log('dragging', data.id, data.x, data.y);
+});
+
+lf.on('blank:click', ({ e }) => {
+  console.log('blank click', e.x, e.y);
+});
+```
+
+**Notes**
+
+- Multiple listeners stack for the same event.
+- Payload shape depends on the specific event.
+
+### off
+
+Remove a listener; pass the same function reference used with `on`.
+
+**Parameters**
+
+| Name | Type | Required | Default | Description |
+| :------- | :------------ | :--- | :----- | :----------------------------------- |
+| evt | string | Yes | - | Event name(s). |
+| callback | EventCallback | Yes | - | Handler to remove. |
+
+**Example**
+
+```ts
+const handleNodeClick = (data) => {
+  console.log('node clicked', data);
+};
+
+lf.on('node:click', handleNodeClick);
+lf.off('node:click', handleNodeClick);
+lf.off('node:click,edge:click', handleNodeClick);
+```
+
+### once
+
+Like `on`, but the handler fires once and is removed automatically.
+
+**Parameters**
+
+| Name | Type | Required | Default | Description |
+| :------- | :------------ | :--- | :----- | :----------------------------------- |
+| evt | string | Yes | - | Event name(s). |
+| callback | EventCallback | Yes | - | Handler. |
+
+**Example**
+
+```ts
+lf.once('node:click', (data) => {
+  console.log('first click only', data);
+});
+
+lf.once('graph:rendered', (data) => {
+  console.log('rendered', data);
+});
+```
+
+### emit
+
+Manually dispatch an event (mostly for custom channels).
+
+**Parameters**
+
+| Name | Type | Required | Default | Description |
+| :-------- | :-------- | :--- | :----- | :------- |
+| evt | string | Yes | - | Event name. |
+| eventArgs | EventArgs | Yes | - | Payload. |
+
+**Example**
+
+```ts
+lf.emit('custom:event', {
+  type: 'custom:event',
+  data: {
+    message: 'Hello World',
+  },
+});
+
+lf.on('custom:event', (data) => {
+  console.log(data);
+});
+
+lf.emit('node:click', {
+  type: 'node:click',
+  data: lf.getNodeDataById('node_1'),
+});
+```
+
+Avoid emitting built-in events unless you understand side effects.
+
+## Event index
+
+## Node events
+
+| Event | Description | Payload highlights |
+| :-------------------------------------------- | :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
+| element:click | Element click | data, e, position |
+| node:click | Node click | data, e, position |
+| node:dbclick | Node double click | data, e, position |
+| node:mousedown | Mouse down on node | data, e |
+| node:mouseup | Mouse up on node | data, e |
+| node:mousemove | Mouse move on node | data, e |
+| node:mouseenter | Pointer enters node | data, e |
+| node:mouseleave | Pointer leaves node | data, e |
+| node:delete | Node removed | data |
+| node:add | Node added | data |
+| node:dnd-add | External drag-and-drop completed | data |
+| node:dnd-drag | External drag in progress | data, e |
+| node:dragstart | Node drag start | data, e |
+| node:drag | Node dragging | data, e |
+| node:drop | Node drag end | data, e |
+| node:contextmenu | Context menu on node | data, e, position |
+| node:resize<Badge>2.0</Badge> | Resize handles | preData, data, model, deltaX, deltaY, index |
+| node:properties-change<Badge>2.0</Badge> | `properties` mutation | id, keys, preProperties, properties |
+
+Payload reference:
+
+| Field | Type | Meaning |
+| :------- | :--------- | :------------------------------------------------------------------------------------------------------------- |
+| data | Object | Node data fields ([data properties](../runtime-model/nodeModel.en.md#data-properties)). |
+| e | MouseEvent | Native mouse event. |
+| position | Object | Canvas coordinates (same shape as [`getPointByClient`](./canvas.en.md#getpointbyclient)). |
+
+## Edge events
+
+| Event | Description | Payload highlights |
+| :--------------------- | :---------------- | :---------------- |
+| element:click | Element click | data, e, position |
+| edge:click | Edge click | data, e, position |
+| edge:dbclick | Edge double click | data, e |
+| edge:mouseenter | Pointer enters edge | data, e |
+| edge:mouseleave | Pointer leaves edge | data, e |
+| edge:add | Edge created | data |
+| edge:delete | Edge removed | data |
+| edge:contextmenu | Context menu on edge | data, e, position |
+| edge:adjust | Polyline/endpoint adjusted | data |
+| edge:exchange-node | Edge endpoints swapped | data |
+| connection:not-allowed | Validation rejected a link | data, msg |
+
+| Field | Type | Meaning |
+| :------- | :--------- | :------------------------------------------------------------------------------------------------------------- |
+| data | Object | Edge data ([data properties](../runtime-model/edgeModel.en.md#data-properties)). |
+| e | MouseEvent | Native mouse event. |
+| position | Object | Canvas coordinates ([`getPointByClient`](./canvas.en.md#getpointbyclient)). |
+| msg | string | Validation message when connection fails. |
+
+## Anchor events
+
+| Event | Description | Payload |
+| :--------------- | :------------------------------------------------------------------------------------------------------ | :---------------------------- |
+| anchor:dragstart | Manual edge creation started | data, e, nodeModel |
+| anchor:drop | Edge successfully created from anchor drag | data, e, nodeModel, edgeModel |
+| anchor:drag | Anchor drag move | data, e, nodeModel |
+| anchor:dragend | Anchor gesture finished (success or cancel) | data, e, nodeModel |
+
+| Field | Type | Meaning |
+| :-------- | :--------- | :----------------- |
+| data | Object | Anchor payload. |
+| e | MouseEvent | Native mouse event. |
+| nodeModel | Object | Owner node model. |
+
+## Canvas events
+
+| Event | Description | Payload |
+| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |
+| blank:mousedown | Canvas mouse down | e |
+| blank:mousemove | Canvas mouse move | e |
+| blank:mouseup | Canvas mouse up | e |
+| blank:click | Canvas click | e |
+| blank:contextmenu | Canvas context menu | e, position |
+| blank:dragstart | Canvas drag start | e |
+| blank:drag | Canvas dragging | e |
+| blank:drop | Canvas drag end | e |
+| text:update | Label text updated | data |
+| graph:transform | Pan/zoom changed | data |
+| graph:rendered | After `lf.render` completes (`v1.1.0`) | graphData |
+| graph:updated | Any graph refresh (`v2.0.0`) | - |
+
+| Field | Type | Meaning |
+| :------- | :--------- | :------------------------------------------------------------------------------------------------------------- |
+| e | MouseEvent | Native mouse event. |
+| position | Object | Canvas coordinates ([`getPointByClient`](./canvas.en.md#getpointbyclient)). |
+
+## History events
+
+The history plugin emits when undo/redo stacks change.
+
+| Event | Description | Payload |
+| :------------- | :------- | :------- |
+| history:change | Stack snapshot updated | data |
+
+| Field | Type | Meaning |
+| :------- | :------ | :------------------ |
+| undos | Array | Undo snapshots. |
+| redos | Array | Redo snapshots. |
+| undoAble | boolean | Undo available. |
+| redoAble | boolean | Redo available. |
+
+## Selection events
+
+Emitted when marquee / multi-select plugins manipulate regions.
+
+| Event | Description | Payload |
+| :-------------------- | :------------- | :------------- |
+| selection:selected | Box selection finished | Selected elements |
+| selection:mousedown | Selection mouse down | e |
+| selection:dragstart | Selection drag start | e |
+| selection:drag | Selection dragging | e |
+| selection:drop | Selection drag end | e |
+| selection:mousemove | Selection pointer move | e, position |
+| selection:mouseup | Selection mouse up | e |
+| selection:contextmenu | Selection context menu | e |
+
+## Text events
+
+Inline text editing gestures.
+
+| Event | Description | Payload |
+| :------------- | :------------------- | :---------------------- |
+| text:mousedown | Mouse down on text | e, data |
+| text:dragstart | Start dragging label | e, data |
+| text:drag | Dragging label | e, data |
+| text:drop | Drop label | e, data |
+| text:click | Click text | e |
+| text:dbclick | Double click text | e |
+| text:blur | Editor blurred | e |
+| text:mousemove | Move inside editor | e, data, deltaX, deltaY |
+| text:mouseup | Mouse up inside editor | e, data |
+| text:update | Content updated | data |
+
+## Plugin-specific events
+
+### DndPanel
+
+| Event | Description | Payload |
+| :-------------------- | :--------------- | :------- |
+| dnd:panel-dbclick | Palette double click | e, data |
+| dnd:panel-click | Palette click | e, data |
+| dnd:panel-contextmenu | Palette context menu | e, data |
+
+### MiniMap
+
+| Event | Description | Payload |
+| :------------ | :--------------- | :------- |
+| miniMap:close | Mini map hidden | - |
+
+### SelectionSelect
+
+| Event | Description | Payload |
+| :---------------------- | :------------------------------------- | :------------------------------------------------------------------- |
+| selection:selected-area | Marquee bounds | topLeft, bottomRight |
+| selection:drop | Mouse up with hits | e |
+| selection:selected | Selection committed | elements, topLeft, bottomRight |
+
+### DynamicGroup / Group
+
+| Event | Description | Payload |
+| :-------------------------------------------- | :-------------------------------- | :-------------------------------------------- |
+| group:add-node | Child added | data, childId |
+| group:remove-node | Child removed | data, childId |
+| group:not-allowed | Join rejected | group, node |
+| dynamicGroup:collapse<Badge>2.1.0</Badge> | Collapse toggled | collapse, nodeModel |
+
+### Highlight
+
+| Event | Description | Payload |
+| :------------------- | :-------------------------------- | :------------------- |
+| highlight:single | Single-element highlight | data |
+| highlight:neighbours | Neighbour highlight | data, relateElements |
+| highlight:path | Path highlight | data, relateElements |
+
+### Label
+
+| Event | Description | Payload |
+| :-------------- | :------------------- | :---------------------- |
+| label:mousedown | Mouse down | e, data |
+| label:dragstart | Drag start | e, data |
+| label:drag | Dragging | e, data |
+| label:drop | Drop | e, data |
+| label:mousemove | Move inside label | e, data, deltaX, deltaY |
+| label:mouseup | Mouse up | e, data |