feat: 补充文档和示例

Author: chengweiw

examples/feature-examples/src/pages/layout/custom/index.tsx

@@ -530,7 +530,7 @@ export default function SelectionSelectExample() {
  }
 
  const getData = () => {
- console.log('当前data数据', lfRef.current?.getGraphData())
+ console.log('当前data数据', lfRef.current?.getGraphRawData())
  }
 
  // 处理配置项变更

examples/feature-examples/src/pages/layout/custom/registerNodeConfig/nodes/baseNodeComponent.tsx

@@ -7,7 +7,7 @@ import { SmallDashOutlined } from '@ant-design/icons' // 引入更多图标
 export default function BaseNodeComponent(props: { node: any; graph: any }) {
  console.log('组件props', { ...props })
  const { node, graph } = props
- const data = node.getData()
+ const data = graph.getNodeModelById(node.id)
  if (!data.properties) data.properties = {}
 
  const updateJudgeNode = function () {

examples/feature-examples/src/pages/layout/default/index.tsx

@@ -909,11 +909,7 @@ export default function SelectionSelectExample() {
  }
 
  const getData = () => {
- console.log(
- '当前data数据',
- lfRef.current?.getDataById('b1bb3a79-0d8e-4d0b-a351-c742d70aab0f')
- ?.properties,
- )
+ console.log('当前data数据', lfRef.current?.getGraphRawData())
  }
 
  // 处理配置项变更

examples/feature-examples/src/pages/layout/default/registerNodeConfig/nodes/baseNodeComponent.tsx

@@ -4,7 +4,7 @@ import { SmallDashOutlined } from '@ant-design/icons' // 引入更多图标
 export default function BaseNodeComponent(props: { node: any; graph: any }) {
  console.log('组件props', props)
  const { node, graph } = props
- const data = node.getData()
+ const data = graph.getNodeModelById(node.id)
  if (!data.properties) data.properties = {}
 
  const addBranch = () => {

pnpm-lock.yaml

@@ -0,0 +1,113 @@
+---
+nav: Guide
+group:
+ title: Plug-in functionality
+ order: 3
+title: Automatic Layout
+order: 7
+toc: content
+tag: Enhancement
+---
+
+In complex flowcharts, manually arranging nodes and edges can be both time-consuming and difficult to keep tidy. LogicFlow provides an automatic layout plugin that can automatically calculate node positions and edge paths, resulting in structured and visually appealing diagrams.
+
+## Installation
+
+```shell
+# npm
+npm install @logicflow/layout
+
+# yarn
+yarn add @logicflow/layout
+
+# pnpm
+pnpm add @logicflow/layout
+```
+
+## Basic Usage
+
+### Register the Plugin
+
+Like other LogicFlow plugins, Layout supports both global and local registration:
+
+```tsx | pure
+import LogicFlow from "@logicflow/core";
+import { Dagre } from "@logicflow/layout";
+
+// Global registration
+LogicFlow.use(Dagre);
+
+// Local registration
+const lf = new LogicFlow({
+ container: document.getElementById('app'),
+ plugins: [Dagre]
+});
+```
+
+### Apply Layout
+
+After registration, you can access the dagre plugin through the LogicFlow instance's extension property:
+
+```tsx | pure
+// Use default configuration
+lf.extension.dagre.layout();
+
+// Use custom configuration
+lf.extension.dagre.layout({
+ rankdir: 'TB', // Top-to-bottom layout direction
+ align: 'UL', // Upper-left alignment
+ nodesep: 60, // Node spacing
+ ranksep: 70 // Rank spacing
+});
+```
+
+## Layout Configuration Options
+
+You can customize the appearance and behavior of the layout through various options:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| rankdir | string | 'LR' | Layout direction: 'LR'(left to right), 'TB'(top to bottom), 'BT'(bottom to top), 'RL'(right to left) |
+| align | string | 'UL' | Node alignment: 'UL'(upper left), 'UR'(upper right), 'DL'(down left), 'DR'(down right) |
+| nodesep | number | 100 | Horizontal spacing between nodes (pixels) |
+| ranksep | number | 150 | Vertical spacing between ranks (pixels) |
+| marginx | number | 120 | Horizontal margin of the graph (pixels) |
+| marginy | number | 120 | Vertical margin of the graph (pixels) |
+| ranker | string | 'tight-tree' | Ranking algorithm: 'network-simplex', 'tight-tree', 'longest-path' |
+| edgesep | number | 10 | Horizontal spacing between edges (pixels) |
+| acyclicer | string | undefined | If set to 'greedy', uses a greedy heuristic for finding a feedback arc set for making the graph acyclic |
+| isDefaultAnchor | boolean | false | Whether to use default anchors: when true, automatically adjusts edge anchors and calculates edge paths based on layout direction |
+
+## Advanced Features
+
+### Auto-fit View After Layout
+
+After adjusting the layout, you may need to adjust the view to show all nodes:
+
+```tsx | pure
+// First apply the layout
+lf.extension.dagre.layout();
+// Then fit the view
+lf.fitView();
+```
+
+## Live Demonstration
+
+### Default Anchors
+
+If nodes use LogicFlow's default anchors (i.e., top, bottom, left, and right anchors), and anchor information doesn't carry business meaning, you can set isDefaultAnchor to true to adjust connection start and end anchor positions during layout.
+
+<code id="react-portal-1" src="@/src/tutorial/extension/layout"></code>
+
+### Custom Anchors
+
+If nodes use custom anchors, or if anchors have actual business meaning, isDefaultAnchor is false by default, which means the layout will not adjust the connection's start and end anchors.
+
+<code id="react-portal-2" src="@/src/tutorial/extension/layout/custom"></code>
+
+## Usage Recommendations
+
+1. **Complex Graphs**: For large or complex flowcharts, use automatic layout to generate an initial arrangement, then make manual adjustments
+2. **Dynamic Updates**: Apply layout after adding/removing nodes to keep the graph tidy
+3. **Direction Selection**: Choose a suitable layout direction based on the actual meaning of your business process
+4. **Parameter Adjustment**: Find the layout that best suits your diagram by adjusting node spacing and rank spacing

sites/docs/docs/tutorial/extension/layout.en.md

@@ -0,0 +1,113 @@
+---
+nav: 指南
+group:
+ title: 插件功能
+ order: 3
+title: 自动布局 (Layout)
+order: 7
+toc: content
+tag: 增强
+---
+
+在复杂的流程图中，手动排列节点和边缘可能既耗时又难以保持整洁。LogicFlow 提供了自动布局插件，能够自动计算节点位置和边的路径，使图表呈现出结构化且美观的效果。
+
+## 安装
+
+```shell
+# npm
+npm install @logicflow/layout
+
+# yarn
+yarn add @logicflow/layout
+
+# pnpm
+pnpm add @logicflow/layout
+```
+
+## 基本使用
+
+### 注册插件
+
+与其他 LogicFlow 插件一样，Layout 支持全局和局部两种注册方式：
+
+```tsx | pure
+import LogicFlow from "@logicflow/core";
+import { Dagre } from "@logicflow/layout";
+
+// 全局注册
+LogicFlow.use(Dagre);
+
+// 局部注册
+const lf = new LogicFlow({
+ container: document.getElementById('app'),
+ plugins: [Dagre]
+});
+```
+
+### 应用布局
+
+注册完成后，您可以通过 LogicFlow 实例的 extension 属性访问 dagre 插件：
+
+```tsx | pure
+// 使用默认配置
+lf.extension.dagre.layout();
+
+// 使用自定义配置
+lf.extension.dagre.layout({
+ rankdir: 'TB', // 从上到下的布局方向
+ align: 'UL', // 上左对齐
+ nodesep: 60, // 节点间距
+ ranksep: 70 // 层级间距
+});
+```
+
+## 布局配置选项
+
+通过配置不同的选项，您可以自定义布局的外观和行为。以下是支持的选项：
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|-------|-----|-------|------|
+| rankdir | string | 'LR' | 布局方向，'LR'(左到右), 'TB'(上到下), 'BT'(下到上), 'RL'(右到左) |
+| align | string | 'UL' | 节点对齐方式，'UL'(上左), 'UR'(上右), 'DL'(下左), 'DR'(下右) |
+| nodesep | number | 100 | 节点间的水平间距(像素) |
+| ranksep | number | 150 | 层级间的垂直间距(像素) |
+| marginx | number | 120 | 图的水平边距(像素) |
+| marginy | number | 120 | 图的垂直边距(像素) |
+| ranker | string | 'tight-tree' | 排名算法，'network-simplex', 'tight-tree', 'longest-path' |
+| edgesep | number | 10 | 边之间的水平间距(像素) |
+| acyclicer | string | undefined | 如果设置为'greedy'，使用贪心算法查找反馈弧集，用于使图变为无环图 |
+| isDefaultAnchor | boolean | false | 是否使用默认锚点：true表示会自动调整连线锚点，根据布局方向计算边的路径 |
+
+## 高级功能
+
+### 应用布局后自动适配视图
+
+布局调整后，您可能需要调整视图以显示所有节点：
+
+```tsx | pure
+// 先应用布局
+lf.extension.dagre.layout();
+// 然后适配视图
+lf.fitView();
+```
+
+## 实际效果演示
+
+### 默认锚点
+
+如果节点是Logicflow的默认锚点（即上下左右4个锚点），且锚点信息并不具备业务含义。那么通过设置isDefaultAnchor 为true，就可以在布局中调整连线起终点锚点的位置。
+
+<code id="react-portal-1" src="@/src/tutorial/extension/layout"></code>
+
+### 自定义锚点
+
+如果节点的锚点是自定义的，或者锚点是具备实际业务含义的，isDefaultAnchor 默认为false，那么布局中就不会调整连线的起终点锚点。
+
+<code id="react-portal-2" src="@/src/tutorial/extension/layout/custom"></code>
+
+## 使用建议
+
+1. **复杂图形**：对于大型或复杂的流程图，先使用自动布局生成初始排列，然后进行手动微调
+2. **动态更新**：在添加/删除节点后应用布局，使图形保持整洁
+3. **方向选择**：根据业务流程的实际含义选择合适的布局方向
+4. **参数调整**：通过调整节点间距和层级间距，找到最适合您图表的布局

sites/docs/docs/tutorial/extension/layout.zh.md

@@ -34,6 +34,7 @@
  "@logicflow/dumi-theme-simple": "^1.0.0",
  "@logicflow/extension": "workspace:*",
  "@logicflow/react-node-registry": "workspace:*",
+ "@logicflow/layout": "workspace:*",
  "antd": "^5.25.0",
  "insert-css": "^2.0.0",
  "react": "18.2.0",