Skip to content

Commit d32fa9b

Browse files
authored
feat: free-layout support multi inputs (bytedance#111)
* docs: update getting-started docs * feat: free-layout support multi inputs
1 parent e4ce96f commit d32fa9b

File tree

5 files changed

+168
-120
lines changed

5 files changed

+168
-120
lines changed

apps/docs/src/en/guide/getting-started/create-fixed-layout-simple.mdx

Lines changed: 71 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,41 @@
1+
# Creating a Fixed Layout Canvas
12

2-
# Create a Fixed Layout Canvas
3-
4-
This case can be installed by `npx @flowgram.ai/create-app@latest fixed-layout-simple`, the complete code and effect are as follows:
3+
This example can be installed using `npx @flowgram.ai/create-app@latest fixed-layout-simple`. For complete code and demo, see:
54

65
<div className="rs-tip">
76
<a className="rs-link" href="/en/examples/fixed-layout/fixed-layout-simple.html">
87
Fixed Layout Basic Usage
98
</a>
109
</div>
1110

11+
File structure:
12+
13+
```
14+
- hooks
15+
- use-editor-props.ts # Canvas configuration
16+
- components
17+
- base-node.tsx # Node rendering
18+
- tools.tsx # Canvas toolbar
19+
- initial-data.ts # Initialization data
20+
- node-registries.ts # Node configuration
21+
- app.tsx # Canvas entry
22+
```
1223

1324
### 1. Canvas Entry
1425

15-
- `FixedLayoutEditorProvider`: Canvas configurator, internally generates a react-context for consumption by child components
16-
- `EditorRenderer`: The final rendered canvas, can be wrapped in other components to customize the canvas position
26+
- `FixedLayoutEditorProvider`: Canvas configurator that generates react-context internally for child components to consume
27+
- `EditorRenderer`: The final rendered canvas that can be wrapped under other components for customizing canvas position
1728

1829
```tsx pure title="app.tsx"
19-
2030
import {
2131
FixedLayoutEditorProvider,
2232
EditorRenderer,
2333
} from '@flowgram.ai/fixed-layout-editor';
2434

25-
import { useEditorProps } from './use-editor-props' // Canvas detailed props configuration
26-
import { Tools } from './tools' // Canvas tools
35+
import '@flowgram.ai/fixed-layout-editor/index.css'; // Load styles
36+
37+
import { useEditorProps } from './hooks/use-editor-props' // Detailed canvas props configuration
38+
import { Tools } from './components/tools' // Canvas tools
2739
2840
function App() {
2941
const editorProps = useEditorProps()
@@ -38,15 +50,15 @@ function App() {
3850

3951
### 2. Configure Canvas
4052

41-
Canvas configuration uses declarative, providing data, rendering, event, plugin related configurations
53+
Canvas configuration is declarative, providing configurations for data, rendering, events, and plugins.
4254

43-
```tsx pure title="use-editor-props.tsx"
55+
```tsx pure title="hooks/use-editor-props.tsx"
4456
import { useMemo } from 'react';
4557
import { type FixedLayoutProps } from '@flowgram.ai/fixed-layout-editor';
4658
import { defaultFixedSemiMaterials } from '@flowgram.ai/fixed-semi-materials';
4759
import { createMinimapPlugin } from '@flowgram.ai/minimap-plugin';
4860

49-
import { intialData } from './initial-data' // Initial data
61+
import { initialData } from './initial-data' // Initialization data
5062
import { nodeRegistries } from './node-registries' // Node declaration configuration
5163
import { BaseNode } from './base-node' // Node rendering
5264
@@ -55,15 +67,16 @@ export function useEditorProps(
5567
return useMemo<FixedLayoutProps>(
5668
() => ({
5769
/**
58-
* Initial data
70+
* Initialization data
5971
*/
6072
initialData,
6173
/**
62-
* Canvas node definition
74+
* Canvas node definitions
6375
*/
6476
nodeRegistries,
6577
/**
66-
* Custom UI components can be defined by key, for example, add a button, here is a semi-component set for quick verification, if you need deep customization, refer to:
78+
* UI components can be customized through keys. Here, a set of semi components is provided for quick validation.
79+
* For deep customization, refer to:
6780
* https://github.com/bytedance/flowgram.ai/blob/main/packages/materials/fixed-semi-materials/src/components/index.tsx
6881
*/
6982
materials: {
@@ -75,31 +88,31 @@ export function useEditorProps(
7588
renderDefaultNode: BaseNode, // Node rendering component
7689
},
7790
/**
78-
* Node engine, used to render node form
91+
* Node engine for rendering node forms
7992
*/
8093
nodeEngine: {
8194
enable: true,
8295
},
8396
/**
84-
* Canvas history, used to control redo/undo
97+
* Canvas history record for controlling redo/undo
8598
*/
8699
history: {
87100
enable: true,
88-
enableChangeNode: true, // Used to listen to node form data changes
101+
enableChangeNode: true, // Monitor node form data changes
89102
},
90103
/**
91104
* Canvas initialization callback
92105
*/
93106
onInit: ctx => {
94-
// If you want to dynamically load data, you can execute it asynchronously by the following method
107+
// For dynamic data loading, use the following method asynchronously
95108
// ctx.docuemnt.fromJSON(initialData)
96109
},
97110
/**
98-
* Canvas first rendering completed callback
111+
* Callback when canvas first render completes
99112
*/
100113
onAllLayersRendered: (ctx) => {},
101114
/**
102-
* Canvas destruction callback
115+
* Canvas disposal callback
103116
*/
104117
onDispose: () => { },
105118
plugins: () => [
@@ -112,36 +125,33 @@ export function useEditorProps(
112125
[],
113126
);
114127
}
115-
116128
```
117129

118-
119130
### 3. Configure Data
120131

121-
Canvas document data uses a tree structure, supports nesting
132+
Canvas document data uses a tree structure that supports nesting.
122133

123-
:::note Document data basic structure:
134+
:::note Document Data Basic Structure:
124135

125136
- nodes `array` Node list, supports nesting
126137

127138
:::
128139

129-
:::note Node data basic structure:
140+
:::note Node Data Basic Structure:
130141

131-
132-
- id: `string` Node unique identifier, must be unique
133-
- meta: `object` Node ui configuration information, such as free layout `position` information
134-
- type: `string | number` Node type, will correspond to `type` in `nodeRegistries`
142+
- id: `string` Unique node identifier, must be unique
143+
- meta: `object` Node UI configuration information, such as position information for free layout
144+
- type: `string | number` Node type, corresponds to `type` in `nodeRegistries`
135145
- data: `object` Node form data
136-
- blocks: `array` Node branch, using `block` is more in line with `Gramming`
146+
- blocks: `array` Node branches, using `block` is closer to `Gramming`
137147

138148
:::
139149

140150
```tsx pure title="initial-data.tsx"
141151
import { FlowDocumentJSON } from '@flowgram.ai/fixed-layout-editor';
142152

143153
/**
144-
* Configure workflow data, data is in the format of nested blocks
154+
* Configure flow data, data is in blocks nested format
145155
*/
146156
export const initialData: FlowDocumentJSON = {
147157
nodes: [
@@ -155,7 +165,7 @@ export const initialData: FlowDocumentJSON = {
155165
},
156166
blocks: [],
157167
},
158-
// Branch node
168+
// Condition node
159169
{
160170
id: 'condition_0',
161171
type: 'condition',
@@ -176,7 +186,7 @@ export const initialData: FlowDocumentJSON = {
176186
type: 'custom',
177187
data: {
178188
title: 'Custom',
179-
content: 'custrom content'
189+
content: 'custom content'
180190
},
181191
},
182192
],
@@ -203,12 +213,11 @@ export const initialData: FlowDocumentJSON = {
203213
},
204214
],
205215
};
206-
207216
```
208217

209-
### 4. Declare Node
218+
### 4. Declare Nodes
210219

211-
Declare node can be used to determine the type and rendering method of the node
220+
Node declaration can be used to determine node types and rendering methods.
212221

213222
```tsx pure title="node-registries.tsx"
214223
import { FlowNodeRegistry, ValidateTrigger } from '@flowgram.ai/fixed-layout-editor';
@@ -223,30 +232,30 @@ export const nodeRegistries: FlowNodeRegistry[] = [
223232
*/
224233
type: 'condition',
225234
/**
226-
* Custom node extension:
227-
* - loop: Extended to loop node
228-
* - start: Extended to start node
229-
* - dynamicSplit: Extended to branch node
230-
* - end: Extended to end node
231-
* - tryCatch: Extended to tryCatch node
232-
* - default: Extended to normal node (default)
235+
* Custom node extensions:
236+
* - loop: Extend as loop node
237+
* - start: Extend as start node
238+
* - dynamicSplit: Extend as branch node
239+
* - end: Extend as end node
240+
* - tryCatch: Extend as tryCatch node
241+
* - default: Extend as normal node (default)
233242
*/
234243
extend: 'dynamicSplit',
235244
/**
236245
* Node configuration information
237246
*/
238247
meta: {
239-
// isStart: false, // Whether it is a start node
240-
// isNodeEnd: false, // Whether it is an end node, the node after the end node cannot be added
241-
// draggable: false, // Whether it can be dragged, such as the start node and the end node cannot be dragged
242-
// selectable: false, // The trigger start node cannot be selected
248+
// isStart: false, // Whether it's a start node
249+
// isNodeEnd: false, // Whether it's an end node, no nodes can be added after end node
250+
// draggable: false, // Whether draggable, start and end nodes cannot be dragged
251+
// selectable: false, // Triggers and start nodes cannot be box-selected
243252
// deleteDisable: true, // Disable deletion
244-
// copyDisable: true, // Disable copy
245-
// addDisable: true, // Disable addition
253+
// copyDisable: true, // Disable copying
254+
// addDisable: true, // Disable adding
246255
},
247256
/**
248-
* Configure node form validation and rendering,
249-
* Note: validate uses data and rendering separation, ensuring that even if the node is not rendered, the data can be validated
257+
* Configure node form validation and rendering
258+
* Note: validate uses data and rendering separation to ensure node validation even without rendering
250259
*/
251260
formMeta: {
252261
validateTrigger: ValidateTrigger.onChange,
@@ -269,22 +278,22 @@ export const nodeRegistries: FlowNodeRegistry[] = [
269278
},
270279
},
271280
];
272-
273281
```
274-
### 5. Render Node
275282

276-
The rendering node is used to add styles, events, and form rendering positions
283+
### 5. Render Nodes
284+
285+
Node rendering is used to add styles, events, and form rendering positions.
277286

278-
```tsx pure title="base-node.tsx"
287+
```tsx pure title="components/base-node.tsx"
279288
import { useNodeRender } from '@flowgram.ai/fixed-layout-editor';
280289

281290
export const BaseNode = () => {
282291
/**
283-
* Provides methods related to node rendering
292+
* Provides node rendering related methods
284293
*/
285294
const nodeRender = useNodeRender();
286295
/**
287-
* Forms can only be used when the node engine is enabled
296+
* Form can only be used when node engine is enabled
288297
*/
289298
const form = nodeRender.form;
290299

@@ -305,21 +314,19 @@ export const BaseNode = () => {
305314
}}
306315
>
307316
{
308-
// Form rendering is generated through formMeta
317+
// Form rendering generated through formMeta
309318
form?.render()
310319
}
311320
</div>
312321
);
313322
};
314-
315323
```
316324

317-
318325
### 6. Add Tools
319326

320-
Tools are mainly used to control canvas zooming and other operations. Tools are consolidated in `usePlaygroundTools`, while `useClientContext` is used to get the canvas context, which contains core modules such as `history`
327+
Tools are mainly used to control canvas zooming and other operations. Tools are collected in `usePlaygroundTools`, while `useClientContext` is used to get canvas context, which contains core modules like `history`.
321328

322-
```tsx pure title="tools.tsx"
329+
```tsx pure title="components/tools.tsx"
323330
import { useEffect, useState } from 'react'
324331
import { usePlaygroundTools, useClientContext } from '@flowgram.ai/fixed-layout-editor';
325332

@@ -347,9 +354,9 @@ export function Tools() {
347354
<span>{Math.floor(tools.zoom * 100)}%</span>
348355
</div>
349356
}
350-
351357
```
352-
### 7. Effect
358+
359+
### 7. Result
353360

354361
import { FixedLayoutSimple } from '../../../../components';
355362

0 commit comments

Comments
 (0)