迁移到 React Flow v10

¥Migrate to React Flow v10

你可以在此处找到旧版本的 React Flow 的文档：v11 , v10 , v9

¥You can find the docs for old versions of React Flow here: v11 , v10 , v9

欢迎使用 React Flow v10！随着主要版本的更新，将出现许多新功能，但也会出现一些重大变化。

¥Welcome to React Flow v10! With the major version update, there are coming many new features but also some breaking changes.

新功能

¥New Features

子流程：你现在可以将节点添加到父节点并创建组和嵌套流

¥Sub Flows: You can now add nodes to a parent node and create groups and nested flows
节点类型 ‘group’：一种没有句柄的新节点类型，可以用作组节点

¥Node Type ‘group’: A new node type without handles that can be used as a group node
触摸设备支持：现在可以在触摸设备上连接节点

¥Touch Device Support: It is now possible to connect nodes on touch devices
初始化时适合视图：你可以使用新的 fitView prop 来适应初始视图

¥Fit View on Init: You can use the new fitView prop to fit the initial view
关键处理：现在不仅可以使用单个键，还可以使用多个键和组合键

¥Key Handling: Not only single keys but also multiple keys and key combinations are possible now
useKeyPress 钩子：用于处理键盘事件的实用钩子

¥useKeyPress hook: A util hook for handling keyboard events
useReactFlow 钩子：返回一个 React Flow 实例，该实例公开了用于操作流程的函数

¥useReactFlow hook: Returns a React Flow instance that exposes functions to manipulate the flow
useNodes、useEdges 和 useViewport 钩子：用于接收节点、边缘和视口的钩子

¥useNodes, useEdges and useViewport hooks: Hooks for receiving nodes, edges and the viewport
边缘标记：更多选项用于配置边缘的开始和结束标记

¥Edge Marker: More options to configure the start and end markers of an edge

重大变化

¥Breaking Changes

TLDR:

将 elements 数组拆分为 nodes 和 edges 数组并实现 onNodesChange 和 onEdgesChange 处理程序（详细指南见核心概念部分）

¥Split the elements array into nodes and edges arrays and implement onNodesChange and onEdgesChange handlers (detailed guide in the core concepts section)
记住你的自定义 nodeTypes 和 edgeTypes

¥Memoize your custom nodeTypes and edgeTypes
将 onLoad 重命名为 onInit

¥Rename onLoad to onInit
将 paneMoveable 重命名为 panOnDrag

¥Rename paneMoveable to panOnDrag
将 useZoomPanHelper 重命名为 useReactFlow（将 setTransform 重命名为 setViewport）

¥Rename useZoomPanHelper to useReactFlow (and setTransform to setViewport)
将节点和边选项 isHidden 重命名为 hidden

¥Rename node and edge option isHidden to hidden

重大变化的详细说明：

¥Detailed explanation of breaking changes:

1. Elements - 节点和边

¥ ~~Elements~~ - Nodes and Edges

我们看到很多人在使用半控制 elements 属性时遇到困难。将本地用户状态与 React Flow 的内部状态同步总是有点混乱。有些人使用了从未记录过的内部存储，并且始终是一种黑客解决方案。对于新版本，我们提供了两种使用 React Flow 的方法 - 不受控制和受控制。

¥We saw that a lot of people struggle with the semi controlled elements prop. It was always a bit messy to sync the local user state with the internal state of React Flow. Some of you used the internal store that was never documented and always a kind of hacky solution. For the new version we offer two ways to use React Flow - uncontrolled and controlled.

1.1.受控 `nodes` 和 `edges`

¥1.1. Controlled nodes and edges

如果你想要完全控制并使用本地状态或存储中的节点和边缘，则可以将 nodes、edges 属性与 onNodesChange 和 onEdgesChange 处理程序结合使用。你需要为交互式流程实现这些处理程序（如果你只对平移和缩放感到满意，则不需要它们）。当节点初始化、拖动、选择或删除时，你将收到更改。这意味着你始终知道节点的确切位置和尺寸，或者例如是否选择了它。我们导出你应该用来应用更改的辅助函数 applyNodeChanges 和 applyEdgeChanges。

¥If you want to have the full control and use nodes and edges from your local state or your store, you can use the nodes, edges props in combination with the onNodesChange and onEdgesChange handlers. You need to implement these handlers for an interactive flow (if you are fine with just pan and zoom you don’t need them). You’ll receive a change when a node(s) gets initialized, dragged, selected or removed. This means that you always know the exact position and dimensions of a node or if it’s selected for example. We export the helper functions applyNodeChanges and applyEdgeChanges that you should use to apply the changes.

旧 API

¥Old API


import { useState, useCallback } from 'react';
import { ReactFlow, removeElements, addEdge } from 'react-flow-renderer';
 
const initialElements = [
  { id: '1', data: { label: 'Node 1' }, position: { x: 250, y: 0 } },
  { id: '2', data: { label: 'Node 2' }, position: { x: 150, y: 100 } },
  { id: 'e1-2', source: '1', target: '2' },
];
 
const BasicFlow = () => {
  const [elements, setElements] = useState(initialElements);
  const onElementsRemove = useCallback(
    (elementsToRemove) =>
      setElements((els) => removeElements(elementsToRemove, els)),
    [],
  );
  const onConnect = useCallback((connection) =>
    setElements((es) => addEdge(connection, es)),
  );
 
  return (
    <ReactFlow
      elements={elements}
      onElementsRemove={onElementsRemove}
      onConnect={onConnect}
    />
  );
};
 
export default BasicFlow;

新 API

¥New API


import { useState, useCallback } from 'react';
import {
  ReactFlow,
  applyNodeChanges,
  applyEdgeChanges,
  addEdge,
} from 'react-flow-renderer';
 
const initialNodes = [
  { id: '1', data: { label: 'Node 1' }, position: { x: 250, y: 0 } },
  { id: '2', data: { label: 'Node 2' }, position: { x: 150, y: 100 } },
];
 
const initialEdges = [{ id: 'e1-2', source: '1', target: '2' }];
 
const BasicFlow = () => {
  const [nodes, setNodes] = useState(initialNodes);
  const [edges, setEdges] = useState(initialEdges);
 
  const onNodesChange = useCallback(
    (changes) => setNodes((ns) => applyNodeChanges(changes, ns)),
    [],
  );
  const onEdgesChange = useCallback(
    (changes) => setEdges((es) => applyEdgeChanges(changes, es)),
    [],
  );
  const onConnect = useCallback((connection) =>
    setEdges((eds) => addEdge(connection, eds)),
  );
 
  return (
    <ReactFlow
      nodes={nodes}
      edges={edges}
      onNodesChange={onNodesChange}
      onEdgesChange={onEdgesChange}
      onConnect={onConnect}
    />
  );
};
 
export default BasicFlow;

你还可以使用新的钩子 useNodesState 和 useEdgesState 快速入门：

¥You can also use the new hooks useNodesState and useEdgesState for a quick start:


const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);

1.2 不受控制的 `defaultNodes` 和 `defaultEdges`

¥1.2 Uncontrolled defaultNodes and defaultEdges

最简单的入门方法是使用 defaultNodes 和 defaultEdges 属性。当你设置这些 props 时，所有操作都在内部处理。你无需添加任何其他处理程序即可获得完全交互式流程，并能够拖动节点、连接节点和删除节点和边：

¥The easiest way to get started is to use the defaultNodes and defaultEdges props. When you set these props, all actions are handled internally. You don’t need to add any other handlers to get a fully interactive flow with the ability to drag nodes, connect nodes and remove nodes and edges:

新 API

¥New API


import ReactFlow from 'react-flow-renderer';
 
const defaultNodes = [
  { id: '1', data: { label: 'Node 1' }, position: { x: 250, y: 0 } },
  { id: '2', data: { label: 'Node 2' }, position: { x: 150, y: 100 } },
];
 
const defaultEdges = [{ id: 'e1-2', source: '1', target: '2' }];
 
const BasicFlow = () => {
  return <ReactFlow defaultNodes={defaultNodes} defaultEdges={defaultEdges} />;
};
 
export default BasicFlow;

如果你想要添加、删除或更新节点或边，你只能通过使用 ReactFlow 实例来执行此操作，你可以使用新的 useReactFlow 钩子接收该 ReactFlow 实例，也可以使用将实例作为函数参数获取的 onInit 处理程序来执行此操作。

¥If you want to add, remove or update a node or edge you can only do this by using the ReactFlow instance that you can receive either with the new useReactFlow hook or by using the onInit handler that gets the instance as a function param.

2. 记住你的自定义 `nodeTypes` 和 `edgeTypes`

¥ Memoize your custom nodeTypes and edgeTypes

每当你传递新的节点或边缘类型时，我们都会在后台创建封装的节点或边缘组件类型。这意味着你不应该在每次渲染时都创建一个新的 nodeType 或 edgeType 对象。当它们不变时，记住你的 nodeTypes 和 edgeTypes 或在组件外部定义它们。

¥Whenever you pass new node or edge types, we create wrapped node or edge component types in the background. This means that you should not create a new nodeType or edgeType object on every render. Memoize your nodeTypes and edgeTypes or define them outside of the component when they don’t change.

不要这样做：

¥Don’t do this:

这会在每次渲染时创建一个新对象，并导致错误和性能问题：

¥This creates a new object on every render and leads to bugs and performance issues:


// this is bad! Don't do it.
<ReactFlow
  nodes={[]}
  nodeTypes={{
    specialType: SpecialNode, // bad!
  }}
/>

执行以下操作：

¥Do this:


function Flow() {
  const nodeTypes = useMemo(() => ({ specialType: SpecialNode }), []);
 
  return <ReactFlow nodes={[]} nodeTypes={nodeTypes} />;
}

或者在组件外部创建类型（当它们不变时）：

¥or create the types outside of the component when they don’t change:


const nodeTypes = { specialType: SpecialNode };
 
function Flow() {
  return <ReactFlow nodes={[]} nodeTypes={nodeTypes} />;
}

3. Redux - Zustand

我们将状态管理库从 Redux 切换到 Zustand 。通过这一改变，我们可以从与状态相关的代码中删除大约 300LOC。如果你需要访问内部存储，则可以使用 useStore 钩子：

¥We switched our state management library from Redux to Zustand . With this change we could remove about 300LOC from our state related code. If you need to access the internal store, you can use the useStore hook:

旧 API

¥Old API


import { useStoreState, useStoreActions } from 'react-flow-renderer';
 
...
 
const transform = useStoreState((store) => store.transform);

新 API

¥New API


import { useStore } from 'react-flow-renderer';
 
...
const transform = useStore((store) => store.transform);

如果你想访问内部存储，你仍然需要用 <ReactFlowProvider /> 封装你的组件。

¥You still need to wrap your component with the <ReactFlowProvider /> if you want to access the internal store.

如果你需要在事件处理程序中获取存储，例如不触发重新渲染，我们还会导出 useStoreApi。

¥We are also exporting useStoreApi if you need to get the store in an event handler for example without triggering re-renders.


import { useStoreApi } from 'react-flow-renderer';
 
...
 
const store = useStoreApi();
 
...
// in an event handler
const [x, y, zoom] = store.getState().transform;

4. onLoad - onInit

onLoad 回调已重命名为 onInit，现在在初始化节点时触发。

¥The onLoad callback has been renamed to onInit and now fires when the nodes are initialized.

旧 API

¥Old API


const onLoad = (reactFlowInstance: OnLoadParams) => reactFlowInstance.zoomTo(2);
...
<ReactFlow
   ...
  onLoad={onLoad}
/>

新 API

¥New API


const onInit = (reactFlowInstance: ReactFlowInstance) => reactFlowInstance.zoomTo(2);
...
<ReactFlow
   ...
  onInit={onInit}
/>

5. paneMoveable - panOnDrag

这与其他 API（panOnScroll、zoomOnScroll 等）更加一致

¥This is more consistent with the rest of the API (panOnScroll, zoomOnScroll, etc.)

旧 API

¥Old API


<ReactFlow
   ...
  paneMoveable={false}
/>

新 API

¥New API


<ReactFlow
   ...
  panOnDrag={false}
/>

6. useZoomPanHelper transform - 在 `useReactFlow` 中统一

¥ ~~useZoomPanHelper transform~~ - unified in useReactFlow

由于 “transform” 也是存储中转换的变量名，并且不清楚 transform 是否是 setter，因此我们将其重命名为 setViewport。这也与其他功能更加一致。此外，所有 useZoomPanHelper 函数都已移至你从 useReactFlow 钩子或 onInit 处理程序获得的 React Flow 实例。

¥As “transform” is also the variable name of the transform in the store and it’s not clear that transform is a setter we renamed it to setViewport. This is also more consistent with the other functions. Also, all useZoomPanHelper functions have been moved to the React Flow instance that you get from the useReactFlow hook or the onInit handler.

旧 API

¥Old API


const { transform, setCenter, setZoom  } = useZoomPanHelper();
...
transform({ x: 100, y: 100, zoom: 2 });

新 API

¥New API


const { setViewport, setCenter, setZoom } = useReactFlow();
...
setViewport({ x: 100, y: 100, zoom: 2 });

新视口功能：

¥New viewport functions:

getZoom
getViewport

7. isHidden - hidden

我们混合了前缀（is...）和非前缀布尔选项名称。所有节点和边缘选项都不再带前缀。所以它是 hidden、animated、selected、draggable、selectable 和 connectable。

¥We mixed prefixed (is...) and non-prefixed boolean option names. All node and edge options are not prefixed anymore. So it’s hidden, animated, selected, draggable, selectable and connectable.

旧 API

¥Old API


const hiddenNode = { id: '1', isHidden: true, position: { x: 50, y: 50 } };

新 API

¥New API


const hiddenNode = { id: '1', hidden: true, position: { x: 50, y: 50 } };

8. arrowHeadType markerEndId - markerStart / markerEnd

我们改进了用于自定义边缘标记的 API。使用新 API，你可以在边的开始和结束处设置单个标记，并使用颜色、strokeWidth 等自定义它们。你仍然可以设置 markerEndId，但 markerStart 和 markerEnd 属性不是使用不同的属性，而是接受字符串（你需要自己定义的 svg 标记的 id）或配置对象，以使用内置的 arrowClosed 或箭头标记。

¥We improved the API for customizing the markers for an edge. With the new API you are able to set individual markers at the start and the end of an edge as well as customizing them with colors, strokeWidth etc. You still have the ability to set a markerEndId but instead of using different properties, the markerStart and markerEnd property accepts either a string (id for the svg marker that you need to define yourself) or a configuration object for using the built in arrowClosed or arrow markers.

旧 API

¥Old API


const markerEdge = { source: '1', target: '2', arrowHeadType: 'arrow' };

新 API

¥New API


const markerEdge = {
  source: '1',
  target: '2',
  markerStart: 'myCustomSvgMarker',
  markerEnd: { type: 'arrow', color: '#f00' },
};

9. ArrowHeadType - MarkerType

这只是一个措辞变化，以使标记 API 更加一致。由于我们现在能够为边缘的起点设置标记，名称类型 ArrowHeadType 已重命名为 MarkerType。将来，这不仅可以包含箭头形状，还可以包含其他形状，如圆形、菱形等。

¥This is just a wording change for making the marker API more consistent. As we are now able to set markers for the start of the edge, the name type ArrowHeadType has been renamed to MarkerType. In the future, this can also not only contain arrow shapes but others like circles, diamonds etc.

10 . 归因

¥. Attribution

这实际上并不是对 API 的重大更改，而是对 React Flow 整体外观的一点改变。我们在右下角添加了一个微小的 “React Flow” 属性（位置可通过 attributionPosition 属性配置）。此更改随新的 “React Flow Pro” 订阅模型而来。如果你想在商业应用中删除属性，请订阅 “React Flow Pro” 。

¥This is not really a breaking change to the API but a little change in the general appearance of React Flow. We added a tiny “React Flow” attribution to the bottom right (the position is configurable via the attributionPosition prop). This change comes with the new “React Flow Pro” subscription model. If you want to remove the attribution in a commercial application, please subscribe to “React Flow Pro” .

迁移到 React Flow v10

新功能

重大变化

1. Elements - 节点和边

1.1.受控 nodes 和 edges

旧 API

新 API

1.2 不受控制的 defaultNodes 和 defaultEdges

新 API

2. 记住你的自定义 nodeTypes 和 edgeTypes

3. Redux - Zustand

旧 API

新 API

4. onLoad - onInit

旧 API

新 API

5. paneMoveable - panOnDrag

旧 API

新 API

6. useZoomPanHelper transform - 在 useReactFlow 中统一

旧 API

新 API

7. isHidden - hidden

旧 API

新 API

8. arrowHeadType markerEndId - markerStart / markerEnd

旧 API

新 API

9. ArrowHeadType - MarkerType

10 . 归因

1.1.受控 `nodes` 和 `edges`

1.2 不受控制的 `defaultNodes` 和 `defaultEdges`

2. 记住你的自定义 `nodeTypes` 和 `edgeTypes`

6. useZoomPanHelper transform - 在 `useReactFlow` 中统一