@logicflow/core 2.2.0 → 2.2.2

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

@@ -0,0 +1,50 @@
+---
+nav: Guide
+group:
+  title: Basics
+  order: 1
+title: Background
+order: 5
+toc: content
+---
+
+### Provides methods to modify the background of the canvas, including background color or background image, which is located at the bottom of the canvas. <Badge>info</Badge>
+
+The `background` option sets the style of the background layer of the canvas when it is created, and
+supports passthrough of any style attribute to the background layer. The default value of `false`
+means no background.
+
+```tsx | pure
+const lf = new LogicFlow({
+  background: false | BackgroundConfig,
+})
+
+type BackgroundConfig = {
+  backgroundImage?: string,
+  backgroundColor?: string,
+  backgroundRepeat?: string,
+  backgroundPosition?: string,
+  backgroundSize?: string,
+  backgroundOpacity?: number,
+  filter?: string, // Filter
+  [key: string]: any,
+};
+```
+
+### Configuration items
+
+### Set the background image
+
+```tsx | pure
+const lf = new LogicFlow({
+  // ...
+  background: {
+    backgroundImage: "url(../asserts/img/grid.svg)",
+    backgroundRepeat: "repeat",
+  },
+});
+```
+
+## example
+
+<a href="https://codesandbox.io/embed/infallible-goldberg-mrwgz?fontsize=14&hidenavigation=1&theme=dark&view=preview" target="_blank"> Go to CodeSandbox for examples</a>

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

@@ -0,0 +1,164 @@
+---
+nav: Guide
+group:
+  title: Basics
+  order: 1
+title: Canvas
+order: 4
+toc: content
+---
+
+This page covers three canvas-related topics: **grid** (alignment and snapping), **background** (underlay styling), and **snaplines** (alignment guides while dragging nodes).
+
+## Grid
+
+The grid is the smallest step used when rendering or moving nodes. It keeps node centers on grid points so elements line up cleanly. Larger spacing makes alignment easier; smaller spacing feels smoother when dragging.
+
+By default the grid is off and the step is 1px. When enabled, the default size is 20px: rendering snaps to that step, and each move step is 20px.
+
+:::warning{title=Note}
+When you set node coordinates they are quantized to the grid. For example center `{ x: 124, y: 138 }` may become `{ x: 120, y: 140 }` on the canvas. Migrating from another designer may require normalizing historical coordinates.
+
+If you need both center alignment and edge alignment, prefer node widths and heights that are **even multiples** of the grid size (e.g. with a 20px grid use 20, 40, 80, 120, …).
+:::
+
+### Enable the grid
+
+Pass `grid` when constructing LogicFlow:
+
+```tsx | pure
+const lf1 = new LogicFlow({
+  grid: true,
+})
+
+// Equivalent to explicit defaults
+const lf2 = new LogicFlow({
+  grid: {
+    size: 20,
+    visible: true,
+    type: 'dot',
+    config: {
+      color: '#ababab',
+      thickness: 1,
+    },
+  },
+})
+```
+
+### Grid options
+
+You can control size, pattern, color, and line thickness.
+
+```tsx | pure
+export type GridOptions = {
+  size?: number
+  visible?: boolean
+  type?: 'dot' | 'mesh'
+  config?: {
+    color?: string
+    thickness?: number
+  }
+}
+```
+
+### Snap to grid (`snapGrid`)
+
+`grid` and `snapGrid` work together but differ:
+
+- **`grid`**: How the grid is drawn and its cell size (`size`, `visible`, `type`, …).
+- **`snapGrid`**: Whether dragging and placement snap to that grid.
+
+So `grid` is mostly visual and sizing; `snapGrid` is an editing behavior flag.
+
+#### Turning on snap
+
+`snapGrid` is part of edit config: set it at init or update at runtime:
+
+```tsx | pure
+const lf = new LogicFlow({
+  container: document.querySelector('#app'),
+  grid: {
+    size: 20,
+    visible: true,
+    type: 'dot',
+  },
+  snapGrid: true,
+})
+
+lf.updateEditConfig({
+  snapGrid: false,
+})
+```
+
+For more edit options (including `snapGrid`) see [`editConfigModel`](../../api/runtime-model/graphModel.en.md#editconfigmodel) on the runtime model page and [Edit config](../../api/logicflow-instance/edit-config.en.md) for `lf.updateEditConfig` / `lf.getEditConfig`.
+
+### Grid demo
+
+<a href="https://codesandbox.io/embed/logicflow-base8-hxtqr?fontsize=14&hidenavigation=1&theme=dark&view=preview" target="_blank">Open the CodeSandbox example</a>
+
+## Background
+
+LogicFlow can draw a background layer under the diagram (color, image, etc.). Use the `background` option; `false` disables the layer (default).
+
+```tsx | pure
+const lf = new LogicFlow({
+  background: false | BackgroundConfig,
+})
+
+type BackgroundConfig = {
+  backgroundImage?: string
+  backgroundColor?: string
+  backgroundRepeat?: string
+  backgroundPosition?: string
+  backgroundSize?: string
+  backgroundOpacity?: number
+  filter?: string
+  [key: string]: any
+}
+```
+
+### Background image
+
+```tsx | pure
+const lf = new LogicFlow({
+  background: {
+    backgroundImage: 'url(../asserts/img/grid.svg)',
+    backgroundRepeat: 'repeat',
+  },
+})
+```
+
+### Background demo
+
+<a href="https://codesandbox.io/embed/infallible-goldberg-mrwgz?fontsize=14&hidenavigation=1&theme=dark&view=preview" target="_blank">Open the CodeSandbox example</a>
+
+## Snaplines
+
+Snaplines help align a moving node with others by comparing centers and bounding boxes.
+
+### Usage
+
+Snaplines are on by default in normal edit mode and can be disabled via options. In [silent mode](../advanced/silent-mode.en.md#silent-mode) nodes cannot be moved, so snaplines stay off.
+
+```tsx | pure
+const lf = new LogicFlow({
+  snapline: false,
+})
+```
+
+### Styling
+
+Change color and width through the theme:
+
+```tsx | pure
+lf.setTheme({
+  snapline: {
+    stroke: '#1E90FF',
+    strokeWidth: 1,
+  },
+})
+```
+
+<example :height="400" ></example>
+
+More styling options: [Theme](./theme.en.md).

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

@@ -0,0 +1,183 @@
+---
+nav: 指南
+group:
+  title: 基础
+  order: 1
+title: 画布
+order: 4
+toc: content
+---
+
+本页介绍与画布外观和编辑辅助相关的三项能力：**网格**（对齐与吸附的最小单位）、**背景**（画布底层样式），以及**对齐线**（拖动节点时与其他节点对齐参考）。
+
+## 网格
+
+网格是指渲染/移动节点的最小单位。网格最主要的作用是在移动节点的时候，保证每个节点中心点的位置都是在网格上。这样更有利于节点之间的对齐。一般来说，网格的间隔越大，在编辑流程图的时候，节点就更好对齐；网格的间隔越小，拖动节点的感觉就更加流畅。
+
+网格默认关闭，渲染/移动最小单位为 1px，若开启网格，则网格默认大小为 20px，渲染节点时表示以 20
+为最小单位对齐到网格，移动节点时表示每次移动最小距离为 20px。
+
+:::warning{title=注意}
+在设置节点坐标时会按照网格的大小来对坐标进行转换，如设置中心点位置`{ x: 124, y: 138 }`
+的节点渲染到画布后的实际位置为 `{ x: 120, y: 140 }`。所以使用 LogicFlow
+替换项目中旧的流程设计器时，需要对历史数据的坐标进行处理。<br>
+在实际开发中，如果期望节点既可以中心对齐，也可以按照两边对齐。那么自定义节点的宽高需要是 grid
+的偶数倍。也就是假设 grid 为 20，那么所有的节点宽度最好是 20、40、80、120 这种偶数倍的宽度。
+:::
+
+### 开启网格
+
+在创建画布的时候通过配置 `grid` 来设置网格属性
+
+开启网格并应用默认属性：
+
+```tsx | pure
+const lf1 = new LogicFlow({
+  grid: true,
+})
+
+// 等同于默认属性如下
+const lf2 = new LogicFlow({
+  grid: {
+    size: 20,
+    visible: true,
+    type: 'dot',
+    config: {
+      color: '#ababab',
+      thickness: 1,
+    },
+  },
+})
+```
+
+### 设置网格属性
+
+支持设置网格大小、类型、网格线颜色和宽度等属性。
+
+```tsx | pure
+export type GridOptions = {
+  size?: number  // 设置网格大小
+  visible?: boolean,  // 设置是否可见，若设置为false则不显示网格线但是仍然保留size栅格的效果
+  type?: 'dot' | 'mesh', // 设置网格类型，目前支持 dot 点状和 mesh 线状两种
+  config?: {
+    color: string,  // 设置网格的颜色
+    thickness?: number,  // 设置网格线的宽度
+  }
+};
+```
+
+### 网格对齐（snapGrid）
+
+`grid` 和 `snapGrid` 是一组强关联配置，但职责不同：
+
+- `grid`：控制网格怎么显示，以及网格尺寸（`size`、`visible`、`type` 等）
+- `snapGrid`：控制节点拖拽、放置时是否吸附到网格
+
+也就是说，`grid` 偏“网格参数与视觉”，`snapGrid` 偏“编辑行为开关”。
+
+#### 如何开启网格对齐
+
+`snapGrid` 属于编辑配置，可以在初始化时传入，也可以在运行时动态更新：
+
+```tsx | pure
+const lf = new LogicFlow({
+  container: document.querySelector('#app'),
+  grid: {
+    size: 20,
+    visible: true,
+    type: 'dot',
+  },
+  snapGrid: true, // 初始化时开启网格吸附
+})
+
+// 运行时切换
+lf.updateEditConfig({
+  snapGrid: false,
+})
+```
+
+更多编辑配置（包含 `snapGrid`）见 [editConfigModel](../../api/runtime-model/graphModel.zh.md#editconfigmodel)。
+
+### 网格示例
+
+<a href="https://codesandbox.io/embed/logicflow-base8-hxtqr?fontsize=14&hidenavigation=1&theme=dark&view=preview" target="_blank"> 去 CodeSandbox 查看示例</a>
+
+## 背景
+
+LogicFlow 支持在画布最底层设置背景层样式，包括背景颜色或背景图片等。创建画布时，通过 `background` 选项来配置；默认值为 `false` 表示不启用背景层。
+
+```tsx | pure
+const lf = new LogicFlow({
+  background: false | BackgroundConfig,
+})
+
+type BackgroundConfig = {
+  backgroundImage?: string,
+  backgroundColor?: string,
+  backgroundRepeat?: string,
+  backgroundPosition?: string,
+  backgroundSize?: string,
+  backgroundOpacity?: number,
+  filter?: string, // 滤镜
+  [key: string]: any,
+};
+```
+
+### 设置背景图片
+
+```tsx | pure
+const lf = new LogicFlow({
+  // ...
+  background: {
+    backgroundImage: "url(../asserts/img/grid.svg)",
+    backgroundRepeat: "repeat",
+  },
+});
+```
+
+### 背景示例
+
+<a href="https://codesandbox.io/embed/infallible-goldberg-mrwgz?fontsize=14&hidenavigation=1&theme=dark&view=preview" target="_blank"> 去 CodeSandbox 查看示例</a>
+
+## 对齐线
+
+对齐线能够在节点移动过程中，将移动节点的位置与画布中其他节点位置进行对比，辅助位置调整。位置对比有如下两个方面。
+
+- 节点中心位置
+- 节点的边框
+
+### 对齐线使用
+
+普通编辑模式下，默认开启对齐线，也可通过配置进行关闭。
+在 [静默模式](../advanced/silent-mode.zh.md#静默模式) 下，无法移动节点，所以关闭了对齐线功能，无法通过配置开启。
+
+```tsx | pure
+// 关闭对齐线功能
+const lf = new LogicFlow({
+  snapline: false,
+})
+```
+
+### 对齐线样式设置
+
+对齐线的样式包括颜色和宽度，可以通过设置主题的方式进行修改。
+
+```tsx | pure
+// 默认配置
+// {
+//   stroke: '#1E90FF',
+//   strokeWidth: 1,
+// }
+
+// 修改对齐线样式
+lf.setTheme({
+  snapline: {
+    stroke: '#1E90FF', // 对齐线颜色
+    strokeWidth: 1, // 对齐线宽度
+  },
+})
+```
+
+<example :height="400" ></example>
+
+更多样式修改参见 [主题](./theme.zh.md)。

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

@@ -0,0 +1,106 @@
+---
+nav: Guide
+group:
+  title: Basics
+  order: 1
+title: Instance and graph data
+order: 0
+toc: content
+---
+
+This page answers two basics: **how to create a LogicFlow instance**, and **what the graph data passed to `render` looks like**.
+
+::::info{title=Reading guide}
+- If you only want to run the first example end-to-end, start with [Get started](../get-started.en.md).
+- If you have already run the minimal example, this page fills in the instance, initialization options, and `graphData` fundamentals.
+::::
+
+The LogicFlow instance is the main object for designing and managing flowcharts. It initializes, renders, operates, and manages all elements on the diagram, including nodes and edges. With it you can build and manipulate diagrams and implement richer business logic and interactions.
+
+## Creating an instance
+
+Each flow-design surface is one LogicFlow instance. Create one with `new LogicFlow`, for example:
+
+<iframe src="/initialized-demo.html" style="border: none; width: 100%; height: 400px; margin: auto;"></iframe>
+
+```html
+<style>
+  #container {
+    width: 1000px;
+    height: 500px
+  }
+</style>
+
+<div id="container"></div>
+```
+
+```js
+const lf = new LogicFlow({
+  container: document.querySelector('#container')
+});
+```
+
+:::info{title=Tip}
+For consistent terminology, we write LogicFlow instances as `lf` in code examples from here on.
+:::
+
+When creating an instance you pass initialization options. LogicFlow supports many options, but **`container`** (the DOM element that hosts the canvas) is the only required field. For the full option list see [Constructor options](../../api/logicflow-constructor/index.en.md).
+
+## Graph data
+
+Inside LogicFlow a flowchart is a graph made of nodes and edges. Graph data uses the following shape:
+
+```json
+{
+  "nodes": [
+    {
+      "id",
+      "type",
+      "x",
+      "y",
+      "text",
+      "properties"
+    }
+  ],
+  "edges": [
+    {
+      "id",
+      "type",
+      "sourceNodeId",
+      "targetNodeId"
+    }
+  ]
+}
+```
+
+- **`id`**: Optional for nodes and edges; generated when omitted.
+- **`type`**: Required; a built-in type such as `rect` / `polyline` or your custom type.
+- **`x` / `y`**: Required node coordinates.
+- **`text`**: Optional node or edge text.
+- **`properties`**: Custom data attached to the element.
+
+**`nodes`**: All nodes to render. Full field definitions: [Type guide](../../api/type/index.en.md).
+
+**`edges`**: All edges to render, linked by `sourceNodeId` and `targetNodeId`. Full field definitions: [Type guide](../../api/type/index.en.md).
+
+After data is passed into the instance, LogicFlow builds a `nodeModel` and `edgeModel` for each element to hold state, behavior, and rendering. See [NodeModel](../../api/runtime-model/nodeModel.en.md) and [EdgeModel](../../api/runtime-model/edgeModel.en.md) for details.
+
+## Rendering
+
+Call `render` with data in the format above:
+
+```js
+lf.render(graphData)
+```
+
+The example below shows how graph data is defined and passed in:
+
+<code id="graphData" src="../../../src/tutorial/basic/instance/graphData"></code>
+
+Beyond rendering, LogicFlow exposes many APIs. Start from the [API overview](../../api/logicflow-instance/index.en.md), then open the [full method index](../../api/logicflow-instance/index.en.md) as needed.
+
+## Next
+
+1. [Theme](theme.en.md): unify node, edge, and text styling
+2. [Events](event.en.md): listen to canvas, node, and edge interactions
+3. [Nodes](node.en.md) / [Edges](edge.en.md): move on to customization

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

@@ -0,0 +1,103 @@
+---
+nav: 指南
+group:
+  title: 基础
+  order: 1
+title: 实例与图数据
+order: 0
+toc: content
+---
+
+这页回答两个基础问题：**如何创建 LogicFlow 实例**，以及**传给 `render` 的图数据长什么样**。
+
+::::info{title=阅读提示}
+- 如果你只想先把第一个示例跑通，请先看 [快速上手](../get-started.zh.md)
+- 如果你已经跑通过最小示例，这一页会补上实例、初始化配置和 `graphData` 的基础认知
+::::
+
+LogicFlow 实例的定位是作为流程图设计和管理的核心对象。它负责初始化、渲染、操作和管理流程图中的所有元素，包括节点和边。
+使用 LogicFlow 实例，开发者可以方便地创建和操作流程图，实现复杂的业务逻辑和交互功能。
+
+## 创建实例
+
+一个流程设计界面，就是一个LogicFlow的实例。要创建一个实例我们只需要`new LogicFlow`一下，就像这样：
+
+<iframe src="/initialized-demo.html" style="border: none; width: 100%; height: 400px; margin: auto;"></iframe>
+
+```html
+<style>
+  #container {
+    width: 1000px;
+    height: 500px
+  }
+</style>
+
+<div id="container"></div>
+```
+
+```js
+const lf = new LogicFlow({
+  container: document.querySelector('#container')
+});
+```
+
+:::info{title=Tip}
+为了统一术语，我们后面统一在代码层面将`LogicFlow`
+的实例写作`lf`。
+:::
+
+当创建一个实例的时候，我们需要传递初始化 LogicFlow 实例的配置项。LogicFlow 支持非常丰富的初始化配置项，但 **container**（用于挂载画布的 DOM 节点）是唯一必填项。有关完整的配置项，请参阅 [初始化选项](../../api/logicflow-constructor/index.zh.md)。
+
+## 图数据
+
+在LogicFlow里面，我们把流程图看做是由节点和边组成的图。因此我们采用如下数据结构来表示LogicFlow的图数据：
+```json
+{
+  nodes: [ // 节点数据
+    {
+      id, // 节点ID，可选参数，不传时内部会自动生成
+      type, // 节点类型，必传，可以是LogicFlow内置的基础类型，也可以是用户自定义的类型
+      x, // 节点x坐标，必传
+      y, // 节点y坐标，必传
+      text, // 节点文本，可选参数
+      properties, // 自定义属性
+      // ...其他属性
+    }
+  ],
+  edges: [ // 边数据
+    {
+      id, // 边ID，可选参数，不传时内部会自动生成
+      type, // 边类型，必传，可以是LogicFlow内置的基础类型，也可以是用户自定义的类型
+      sourceNodeId, // 起始节点ID，必传
+      targetNodeId, // 目标节点ID，必传
+      // ...其他属性
+    }
+  ],
+}
+```
+
+**`nodes`**: 包含所有要渲染的节点，完整的字段配置项见 [类型导览](../../api/type/index.zh.md)
+
+**`edges`**: 包含所有要渲染的边，通过起始 `sourceNodeId` 和 `targetNodeId`
+将两个节点相连。完整的字段配置项见 [类型导览](../../api/type/index.zh.md)
+
+当图数据传入 LogicFlow 实例后，系统会为每个节点和边分别创建对应的数据模型：`nodeModel` 和 `edgeModel`，它用于管理节点的相关数据和行为，包括节点的属性、状态、交互逻辑以及与其他节点和边的关系，每个节点和边的实际表现（例如位置、样式等）都由对应的 model 来定义并控制。更多信息详见 [NodeModel](../../api/runtime-model/nodeModel.zh.md)、[EdgeModel](../../api/runtime-model/edgeModel.zh.md)
+
+## 图渲染
+
+接着只需要传入一个遵循格式的数据给`render`方法执行就可以渲染出图了。
+
+```js
+lf.render(graphData)
+```
+
+下面是一个图数据渲染的例子，从例子中你能看到实际图数据是如何定义和传递给实例的：
+<code id="graphData" src="../../../src/tutorial/basic/instance/graphData"></code>
+
+当然，除了渲染外 LogicFlow 还对外提供了很多 API 以支持开发者调用。建议先从 [API 导览](../../api/logicflow-instance/index.zh.md) 了解能力分组，再按需进入 [完整方法参考](../../api/logicflow-instance/index.zh.md)。
+
+## 下一步阅读
+
+1. [主题](theme.zh.md)：统一调整节点、边和文本样式
+2. [事件](event.zh.md)：监听画布、节点和边的交互
+3. [节点](node.zh.md) / [边](edge.zh.md)：开始进入业务自定义