📝 feat(doc): 新增使用文档与组件文档 (#31)

* 🐛 fix: build * ✨ feat: 新增flowDataAdapter * ✨ feat: 新增节点选中相关hook * 📝 feat: 为什么选择ProFlow.doc * 📝 feat: flowview and floweditor demo doc * 📝 feat: pending to write text * 📝 fix: demo index import * 📝 fix: demo import link * 🐛 fix: ci * 📝 feat: add useFlowViewer hook * ✨ feat: zoom hook * ✨ feat: demo import path * 📝 feat: demos path * 📝 feat: useFlowView demo * 📝 feat: useFlowEditor doc * 📝 feat: useFlowView hook doc * 📝 feat: useFlowView hook doc * ✨ feat: nodetype * ✨ feat: group node type refactor * ✨ feat: edge click * ✨ feat: darge rule * ✨ feat: auto layout switch * ✨ feat: handles doc * 📝 feat: edges and custom edges doc * 📝 feat: custom node doc * 📝 feat: custom node set select type * 📝 feat: demo fix * 📝 feat: auto layout doc * 📝 feat: yuyan pipeline demo * 📝 feat: techui pipeline deme * 🐛 fix: ci --------- Co-authored-by: jiangchu <[email protected]>
ant-design · Nov 23, 2023 · fd563ef · fd563ef
1 parent d13b430
commit fd563ef
Show file tree

Hide file tree

Showing 46 changed files with 2,361 additions and 263 deletions.
diff --git a/docs/useDocs/autoLayout.md b/docs/useDocs/autoLayout.md
@@ -0,0 +1,143 @@
+---
+nav: 使用文档
+group:
+  title: 进阶使用
+  order: 2
+title: 自动布局
+description:
+---
+
+## 自动布局
+
+当你使用 FlowView 组件传入 nodes 和 edges 列表后，FlowView 会自动梳理节点之间的逻辑关系，并给出一个自动布局结果渲染在画布上,比如下面这段关系渲染后的结果如下。
+
+```js
+const nodes = [
+  {
+    id: 'a1',
+    data: {
+      title: '节点1',
+    },
+  },
+  {
+    id: 'a2',
+    data: {
+      title: '节点2',
+    },
+  },
+  {
+    id: 'a3',
+    data: {
+      title: '节点3',
+    },
+  },
+  {
+    id: 'a4',
+    data: {
+      title: '节点4',
+    },
+  },
+  {
+    id: 'a5',
+    data: {
+      title: '节点5',
+    },
+  },
+  {
+    id: 'a6',
+    data: {
+      title: '节点6',
+    },
+  },
+];
+
+const edges = [
+  {
+    source: 'a1',
+    target: 'a2',
+  },
+  {
+    source: 'a1',
+    target: 'a3',
+  },
+  {
+    source: 'a2',
+    target: 'a3',
+  },
+  {
+    source: 'a3',
+    target: 'a6',
+  },
+  {
+    source: 'a2',
+    target: 'a4',
+  },
+  {
+    source: 'a3',
+    target: 'a5',
+  },
+  {
+    source: 'a2',
+    target: 'a6',
+  },
+];
+
+function App() {
+  return (
+    <Container>
+      <FlowView nodes={nodes} edges={edges} miniMap={false} />
+    </Container>
+  );
+}
+
+export default App;
+```
+
+布局效果如下所示：
+<code src="./demos/autoLayoutDemo1.tsx"></code>
+
+## 自定义布局
+
+如果希望自己设置坐标，可以给节点添加 position 属性来控制。
+
+```js
+const nodes = [
+  {
+    id: 'a1',
+    position: {
+      x: 100,
+      y: 300,
+    },
+    data: {
+      title: '节点1',
+    },
+  },
+  {
+    id: 'a2',
+    position: {
+      x: 300,
+      y: 600,
+    },
+    data: {
+      title: '节点2',
+    },
+  },
+  ...
+];
+```
+
+<code src="./demos/autoLayoutDemo2.tsx"></code>
+
+## 关闭自动布局
+
+你也可以在 FlowView 中直接关闭自动布局功能
+
+```js
+<FlowView nodes={nodes} edges={edges} miniMap={false} autoLayout={false} />
+```
+
+:::info
+当你关掉自动布局能力，并且没有为节点单独设置坐标，那么 FlowView 会将节点的坐标初始化为 1,1。效果上就是所有的节点重合在一起。
+:::
+
+<code src="./demos/autoLayoutDemo3.tsx"></code>
diff --git a/docs/useDocs/baseInrro.md b/docs/useDocs/baseInrro.md
@@ -7,3 +7,42 @@ title: 根本性概念
 order: 1
 description:
 ---
+
+## 术语和定义
+
+### Nodes
+
+ProFlow 中的节点是一个 React 组件。这意味着它可以渲染您喜欢的任何内容。每个节点都有一个 x 和 y 坐标，这告诉它它在视口中的位置。在不设置 type 的情况下，FlowView 组件默认会把组件设置为[Lineage](/components/lineage-node)类型的节点。你也可以自定义节点类型。
+
+<code src="./demos/CoreNode.tsx"></code>
+
+### Custom Nodes
+
+[自定义节点使用说明](/components/customNodeDoc)
+<code src="./demos/CustomerNode.tsx"></code>
+
+### Handles
+
+`Handle` 可以翻译为 “**句柄**” 或者 “**端口**”，是边缘连接到节点的位置。`Handle`可以放置在任何地方。
+
+可以用以下方式式引入 `Handle` 与 `Position`，来自定义 `Handle` 在节点中的位置。
+
+```ts
+import { Handle, type Position } from '@ant-design/pro-flow';
+```
+
+<code src="./demos/CoreHandle.tsx"></code>
+
+### Edges
+
+一条 Edge 连接两个节点。每个边缘都需要一个`source` 和 一个`target`。 ProFlow 内置了五种边缘类型：
+
+- 'straight'
+- 'step'
+  -'smoothstep'
+  -'bezier'
+- 'radius' 。
+
+FlowView 把 `smoothstep` 设置为默认类型。 你也可以自定义边缘类型。
+
+<code src="./demos/CoreEdge.tsx"></code>
diff --git a/docs/useDocs/customNodeDoc.md b/docs/useDocs/customNodeDoc.md
@@ -0,0 +1,161 @@
+---
+nav: 使用文档
+group:
+  title: 进阶使用
+  order: 2
+title: 自定义节点
+description:
+---
+
+## 自定义节点
+
+ProFlow 的一个强大功能是能够添加自定义节点。在自定义节点中，您可以渲染所需的所有内容。例如，您可以定义多个源句柄和目标句柄，并呈现表单输入或图表。在本节中，我们将实现一个带有输入字段的节点，该输入字段更新应用程序另一部分中的一些文本。
+
+## 实现自定义节点
+
+让我们开始实现：声明一个自定义节点`TextUpdaterNode`组件，它的结构由 3 个 Handle 组件和一块内容区组成。其中一个 Handle 的位置在顶部，两个在底部。
+
+```js
+import { useCallback } from 'react';
+import { Handle, Position } from '@ant-design/pro-flow';
+
+const handleStyle = { left: 10 };
+
+function TextUpdaterNode({ data }) {
+  const onChange = useCallback((evt) => {
+    console.log(evt.target.value);
+  }, []);
+
+  return (
+    <>
+      <Handle type="target" position={Position.Top} />
+      <div className="content">
+        <label htmlFor="text">Text:</label>
+        <input id="text" name="text" onChange={onChange} />
+      </div>
+      <Handle type="source" position={Position.Bottom} id="a" />
+      <Handle type="source" position={Position.Bottom} id="b" style={handleStyle} />
+    </>
+  );
+}
+```
+
+## 添加节点类型
+
+你可以将新的节点类型添加到 prop 中传递给 FlowView。
+
+:::warning
+**在组件外部定义或缓存`nodeTypes`非常重要。** 否则 React 会在每次渲染时创建一个新的对象，这会导致性能问题和错误。
+:::
+
+```js
+const nodeTypes = useMemo(() => ({ textUpdater: TextUpdaterNode }) ,[]);
+
+return <FlowView nodeTypes={nodeTypes}>
+```
+
+定义新节点类型后，可以在 nodes 列表中使用这个类型了。
+
+```js
+const nodes = [
+  {
+    id: 'n1',
+    type: 'textUpdater',
+    data: { value: 123 },
+  },
+];
+```
+
+然后你就可以得到如下的自定义节点效果。
+<code src="./demos/CustomerNode.tsx"></code>
+
+## 使用多个 Handle
+
+当一个节点拥有多个 Handle 时，在连接时只传递节点 Id 是不够的，还需要传递特定的 HandleId。
+
+```js
+const initialEdge = [
+  { id: 'edge-1', source: 'n1', sourceHandle: 'a', target: 'n2' },
+  { id: 'edge-2', source: 'n1', sourceHandle: 'b', target: 'n3' },
+];
+```
+
+效果如下：
+<code src="./demos/multiHandle.tsx"></code>
+
+## 添加节点交互
+
+在自定义节点的 data 中，FlowView 还会透传 2 个属性 selectType 与 zoom。你可以通过这两个属性来给节点配置一些交互。
+
+```js
+import {
+  FlowView,
+  FlowViewProvider,
+  Handle,
+  Position,
+  SelectType,
+  useFlowViewer,
+} from '@ant-design/pro-flow';
+
+const edges = [
+  { id: 'edge-1', source: 'n1', target: 'n2', sourceHandle: 'a' },
+  { id: 'edge-2', source: 'n1', target: 'n3', sourceHandle: 'b' },
+];
+
+const CustomNode: FC<{
+  data: {
+    title: string,
+    selectType: SelectType,
+  },
+}> = ({ data }) => {
+  console.log(data);
+  const onChange = useCallback((evt) => {
+    console.log(evt.target.value);
+  }, []);
+
+  return (
+    <Wrap className={data.selectType === SelectType.SELECT ? 'select' : 'default'}>
+      <Handle type="target" position={Position.Top} />
+      <div>
+        <label htmlFor="text">{data.title}</label>
+        <input id="text" name="text" onChange={onChange} />
+      </div>
+      <Handle type="source" position={Position.Bottom} id="a" />
+      <Handle type="source" position={Position.Bottom} id="b" style={{ left: 10 }} />
+    </Wrap>
+  );
+};
+
+const nodeTypes = { customNode: CustomNode };
+
+function App() {
+  const flowViewer = useFlowViewer();
+
+  return (
+    <Container>
+      <FlowView
+        onNodeClick={(e, n) => {
+          flowViewer?.selectNode(n.id, SelectType.SELECT);
+        }}
+        onPaneClick={() => {
+          flowViewer?.selectNodes(['n1', 'n2', 'n3'], SelectType.DEFAULT);
+        }}
+        nodes={nodes}
+        edges={edges}
+        nodeTypes={nodeTypes}
+        miniMap={false}
+      />
+    </Container>
+  );
+}
+function ProApp() {
+  return (
+    <FlowViewProvider>
+      <App />
+    </FlowViewProvider>
+  );
+}
+```
+
+效果如下：
+<code src="./demos/multiHandle.tsx"></code>