迁移到 React Flow 12

¥Migrate to React Flow 12

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

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

在使用 React Flow 12 附带的新功能（如服务器端渲染、计算流程和夜间模式）之前，你必须先解决以下重大更改。我们试图将重大更改保持在最低限度，但其中一些更改对于实现新功能是必要的。

¥Before you can use the new features that come with React Flow 12 like server side rendering, computing flows, and dark mode, here are the breaking changes you’ll have to address first. We tried to keep the breaking changes to a minimum, but some of them were necessary to implement the new features.

迁移指南

¥Migration guide

在开始迁移之前，你需要安装新软件包。

¥Before you start to migrate, you need to install the new package.


npm install @xyflow/react


pnpm add @xyflow/react


yarn add @xyflow/react


bun add @xyflow/react

1. 新的 npm 包名称

¥ A new npm package name

包 reactflow 已重命名为 @xyflow/react，不再是默认导入。你还需要调整样式导入。在 v12 之前，React Flow 被分成多个包。现在情况已经不同了。如果你只是使用核心，现在需要安装 @xyflow/react 包。

¥The package reactflow has been renamed to @xyflow/react and it’s not a default import anymore. You also need to adjust the style import. Before v12, React Flow was divided into multiple packages. That’s not the case anymore. If you just used the core, you now need to install the @xyflow/react package.

旧 API

¥Old API


// npm install reactflow
import ReactFlow from 'reactflow';

新 API

¥New API


// npm install @xyflow/react
import { ReactFlow } from '@xyflow/react';
 
// you also need to adjust the style import
import '@xyflow/react/dist/style.css';
 
// or if you just want basic styles
import '@xyflow/react/dist/base.css';

2. 用于测量 `width` 和 `height` 的节点 `measured` 属性

¥ Node measured attribute for measured width and height

所有测量的节点值现在都存储在 node.measured 中。除了新的包名称外，这是最大的变化。在 React Flow 测量你的节点后，它会将尺寸写入 node.measured.width 和 node.measured.height。如果你正在使用任何布局库（如 dagre 或 elk），你现在需要从 node.measured 而不是 node 获取尺寸。如果你使用的是 width 和 height，这些值现在将用作内联样式来指定节点尺寸。

¥All measured node values are now stored in node.measured. Besides the new package name, this is the biggest change. After React Flow measures your nodes, it writes the dimensions to node.measured.width and node.measured.height. If you are using any layouting library like dagre or elk, you now need to take the dimensions from node.measured instead of node. If you are using width and height, those values will now be used as inline styles to specify the node dimensions.

旧 API

¥Old API


// getting the measured width and height
const nodeWidth = node.width;
const nodeHeight = node.height;

新 API

¥New API


// getting the measured width and height
const nodeWidth = node.measured?.width;
const nodeHeight = node.measured?.height;

3. 新维度处理 `node.width` / `node.height` 与 `node.measured.width` / `node.measured.height`

¥ New dimension handling node.width / node.height vs node.measured.width / node.measured.height

为了支持服务器端渲染，我们必须稍微重构 API，以便用户可以更轻松地传递节点维度。为此，我们改变了 node.width 和 node.height 属性的行为。在 React Flow 11 中，这些属性是测量值，仅用作参考。在 React Flow 12 中，这些属性用作内联样式来指定节点尺寸。如果你从数据库加载节点，你可能希望从节点中删除 width 和 height 属性，因为现在的行为略有不同。使用 width 和 height 现在意味着尺寸不是基于内容动态的，而是固定的。

¥In order to support server side rendering we had to restructure the API a bit, so that users can pass node dimensions more easily. For this we changed the behavior of the node.width and node.height attributes. In React Flow 11, those attributes were measured values and only used as a reference. In React Flow 12 those attributes are used as inline styles to specify the node dimensions. If you load nodes from a database, you probably want to remove the width and height attributes from your nodes, because the behavior is slightly different now. Using width and height now means that the dimensions are not dynamic based on the content but fixed.

旧 API

¥Old API


// in React Flow 11 you might used node.style to set the dimensions
const nodes = [
  {
    id: '1',
    type: 'input',
    data: { label: 'input node' },
    position: { x: 250, y: 5 },
    style: { width: 180, height: 40 },
  },
];

新 API

¥New API


// in React Flow 12 you can used node.width and node.height to set the dimensions
const nodes = [
  {
    id: '1',
    type: 'input',
    data: { label: 'input node' },
    position: { x: 250, y: 5 },
    width: 180,
    height: 40,
  },
];

如果你想了解有关如何配置 React Flow 进行服务器端渲染的更多信息，你可以在服务器端渲染指南中阅读相关内容。

¥If you want to read more about how to configure React Flow for server side rendering, you can read about it in the server side rendering guide.

4. 更新节点和边

¥ Updating nodes and edges

我们不再支持使用对象突变进行节点和边缘更新。如果你想更新某个属性，则需要创建一个新节点/边。

¥We are not supporting node and edge updates with object mutations anymore. If you want to update a certain attribute, you need to create a new node / edge.

旧 API

¥Old API


setNodes((currentNodes) =>
  currentNodes.map((node) => {
    node.hidden = true;
    return node;
  }),
);

新 API

¥New API


setNodes((currentNodes) =>
  currentNodes.map((node) => ({
    ...node,
    hidden: true,
  })),
);

5. 将 `onEdgeUpdate`（及相关 API）重命名为 `onReconnect`

¥ Rename onEdgeUpdate (and related APIs) to onReconnect

我们将 onEdgeUpdate 函数重命名为 onReconnect 以及所有相关 API（如下所述）。新名称更具描述性，并清楚地表明该函数用于重新连接边。

¥We renamed the onEdgeUpdate function to onReconnect and all related APIs (mentioned below). The new name is more descriptive and makes it clear that the function is used to reconnect edges.

updateEdge 重命名为 reconnectEdge

¥updateEdge renamed to reconnectEdge
onEdgeUpdateStart 重命名为 onReconnectStart

¥onEdgeUpdateStart renamed to onReconnectStart
onEdgeUpdate 重命名为 onReconnect

¥onEdgeUpdate renamed to onReconnect
onEdgeUpdateEnd 重命名为 onReconnectEnd

¥onEdgeUpdateEnd renamed to onReconnectEnd
edgeUpdaterRadius 重命名为 reconnectRadius

¥edgeUpdaterRadius renamed to reconnectRadius
edge.updatable 重命名为 edge.reconnectable

¥edge.updatable renamed to edge.reconnectable
edgesUpdatable 重命名为 edgesReconnectable

¥edgesUpdatable renamed to edgesReconnectable

旧 API

¥Old API


<ReactFlow
  onEdgeUpdate={onEdgeUpdate}
  onEdgeUpdateStart={onEdgeUpdateStart}
  onEdgeUpdateEnd={onEdgeUpdateEnd}
/>

新 API

¥New API


<ReactFlow
  onReconnect={onReconnect}
  onReconnectStart={onReconnectStart}
  onReconnectEnd={onReconnectEnd}
/>

6. 将 `parentNode` 重命名为 `parentId`

¥ Rename parentNode to parentId

如果你正在使用子流，则需要将 node.parentNode 重命名为 node.parentId。parentNode 属性有点误导，因为它不是对父节点的引用，而是父节点的 id。

¥If you are working with subflows, you need to rename node.parentNode to node.parentId. The parentNode attribute was a bit misleading, because it was not a reference to the parent node, but the id of the parent node.

旧 API

¥Old API


const nodes = [
  // some nodes ...
  {
    id: 'xyz-id',
    position: { x: 0, y: 0 },
    type: 'default',
    data: {},
    parentNode: 'abc-id',
  },
];

新 API

¥New API


const nodes = [
  // some nodes ...
  {
    id: 'xyz-id',
    position: { x: 0, y: 0 },
    type: 'default',
    data: {},
    parentId: 'abc-id',
  },
];

7. 自定义节点属性

¥ Custom node props

我们将 xPos 和 yPos 属性重命名为 positionAbsoluteX 和 positionAbsoluteY

¥We renamed the xPos and yPos props to positionAbsoluteX and positionAbsoluteY

旧 API

¥Old API


function CustomNode({ xPos, yPos }) {
  ...
}

新 API

¥New API


function CustomNode({ positionAbsoluteX, positionAbsoluteY }) {
  ...
}

8. 处理组件类名

¥ Handle component class names

我们重命名了一些用于定义句柄当前状态的类。

¥We renamed some of the classes used to define the current state of a handle.

react-flow__handle-connecting 重命名为 connectingto / connectingfrom

¥react-flow__handle-connecting renamed to connectingto / connectingfrom
react-flow__handle-valid 重命名为 valid

¥react-flow__handle-valid renamed to valid

9. `getNodesBounds` 选项

¥ getNodesBounds options

第二个参数的类型从 nodeOrigin 更改为 options.nodeOrigin

¥The type of the second param changed from nodeOrigin to options.nodeOrigin

旧 API

¥Old API


const bounds = getNodesBounds(nodes: Node[], nodeOrigin)

新 API

¥New API


const bounds = getNodesBounds(nodes: Node[], { nodeOrigin })

10 . 用于定义节点和边的 Typescript 更改

¥. Typescript changes for defining nodes and edges

我们简化了类型并修复了有关用户可以传递 NodeData 泛型的函数的问题。新方法是使用所有节点的联合来定义你自己的节点类型。通过这一改变，你现在可以拥有具有不同数据结构的多种节点类型，并且始终能够通过检查 node.type 属性来区分。

¥We simplified types and fixed issues about functions where users could pass a NodeData generic. The new way is to define your own node type with a union of all your nodes. With this change, you can now have multiple node types with different data structures and always be able to distinguish by checking the node.type attribute.

新 API

¥New API


type NumberNode = Node<{ value: number }, 'number'>;
type TextNode = Node<{ text: string }, 'text'>;
type AppNode = NumberNode | TextNode;

然后，你可以按如下方式使用 AppNode 类型：

¥You can then use the AppNode type as the following:


const nodes: AppNode[] = [
  { id: '1', type: 'number', data: { value: 1 }, position: { x: 100, y: 100 } },
  { id: '2', type: 'text', data: { text: 'Hello' }, position: { x: 200, y: 200 } },
];


const onNodesChange: onNodesChange<AppNode> = useCallback((changes) => setNodes(nds => applyChanges(changes, nds)), []);

你可以在 Typescript 指南中阅读更多相关信息。

¥You can read more about this in the Typescript guide.

11 . 重命名 `nodeInternals`

¥. Rename nodeInternals

如果你使用的是 nodeInternals，则需要将其重命名为 nodeLookup。

¥If you are using nodeInternals you need to rename it to nodeLookup.

旧 API

¥Old API


const node = useStore((s) => s.nodeInternals.get(id));

新 API

¥New API


const node = useStore((s) => s.nodeLookup.get(id));

12 . 删除已弃用的函数

¥. Removal of deprecated functions

我们删除了以下弃用的函数：

¥We removed the following deprecated functions:

getTransformForBounds（由 getViewportForBounds 替换）

¥getTransformForBounds (replaced by getViewportForBounds)
getRectOfNodes（由 getNodesBounds 替换）

¥getRectOfNodes (replaced by getNodesBounds)
project（由 screenToFlowPosition 替换）

¥project (replaced by screenToFlowPosition)
getMarkerEndId
updateEdge（由 reconnectEdge 替换）

¥updateEdge (replaced by reconnectEdge)

13 . 自定义 `applyNodeChanges` 和 `applyEdgeChanges`

¥. Custom applyNodeChanges and applyEdgeChanges

如果你编写了自己的函数来应用更改，则需要处理新的 “replace” 事件。我们删除了 “reset” 事件并添加了替换特定节点或边的 “replace” 事件。

¥If you wrote your own function for applying changes, you need to handle the new “replace” event. We removed the “reset” event and added a “replace” event that replaces specific nodes or edges.

新功能

¥New features

现在你已成功迁移到 v12，你可以使用所有花哨的功能。如上所述，v12 的最大更新是：

¥Now that you successfully migrated to v12, you can use all the fancy features. As mentioned above, the biggest updates for v12 are:

1. 服务器端渲染

¥ Server side rendering

你可以为节点定义 width、height 和 handles。这使得可以在服务器上渲染流并在客户端上进行水合：服务器端渲染指南。

¥You can define width, height and handles for the nodes. This makes it possible to render a flow on the server and hydrate on the client: server side rendering guide.

详细信息：在 v11 中，width 和 height 在节点测量后立即由库设置。这种情况仍然会发生，但我们现在使用 measured.width 和 measured.height 来存储此信息。在以前的版本中，人们对 width 和 height 总是有很多困惑。很难理解，你不能用它来传递实际的宽度或高度。这些属性是由库添加的，这一点也不明显。我们认为新的实现解决了这两个问题：width 和 height 是可选属性，可用于定义尺寸，库设置的所有内容都存储在 measured 中。

¥Details: In v11, width and height were set by the library as soon as the nodes got measured. This still happens, but we are now using measured.width and measured.height to store this information. In the previous versions there was always a lot of confusion about width and height. It’s hard to understand, that you can’t use it for passing an actual width or height. It’s also not obvious that those attributes get added by the library. We think that the new implementation solves both of the problems: width and height are optional attributes that can be used to define dimensions and everything that is set by the library, is stored in measured.

2. 计算流程

¥ Computing flows

新的钩子 useHandleConnections 和 useNodesData 以及新的 updateNode 和 updateNodeData 函数（两者都是 useReactFlow 的一部分）可用于管理节点之间的数据流：计算流程指南。我们还为边 (updateEdge 和 updateEdgeData) 添加了那些助手！

¥The new hooks useHandleConnections and useNodesData and the new updateNode and updateNodeData functions (both are part of useReactFlow) can be used to manage the data flow between your nodes: computing flows guide. We also added those helpers for edges (updateEdge and updateEdgeData)!

详细信息：使用一个节点数据依赖于另一个节点的流非常常见。你更新节点 A 并希望对连接的节点 B 中的这些更改做出反应。到目前为止，每个人都必须想出一个自定义解决方案。我们希望通过此版本改变这种情况，并为你提供高性能助手来处理此类用例。

¥Details: Working with flows where one node data relies on another node is super common. You update node A and want to react on those changes in the connected node B. Until now everyone had to come up with a custom solution. With this version we want to change this and give you performant helpers to handle use cases like this.

3. 夜间模式和 CSS 变量

¥ Dark mode and CSS variables

React Flow 现在带有内置夜间模式，可以使用新的 colorMode 属性（“light”、“dark”或“system”）切换：夜间模式示例

¥React Flow now comes with a built-in dark mode, that can be toggled by using the new colorMode prop (”light”, “dark” or “system”): dark mode example

详细信息：我们希望通过此版本让你更轻松地在夜间模式和亮模式之间切换，并为你提供更好的暗流起点。如果你传递 colorMode="dark"，我们会将类名 “dark” 添加到封装器并使用它来调整样式。为了使我们更容易实现此新功能，我们将大多数样式切换为 CSS 变量。这些变量还可以在用户空间中用于自定义流程。

¥Details: With this version we want to make it easier to switch between dark and light modes and give you a better starting point for dark flows. If you pass colorMode="dark", we add the class name “dark” to the wrapper and use it to adjust the styling. To make the implementation for this new feature easier on our ends, we switched to CSS variables for most of the styles. These variables can also be used in user land to customize a flow.

4. 使用 TSDoc 的更好的 DX

¥ A better DX with TSDoc

我们开始使用 TSDoc 来获得更好的 DX。在开发 IDE 时，现在将向你显示 props 和 hooks 的文档。这是我们使库更易于访问和更易于使用的一大步。我们还将在不久的将来使用 TSDoc 来生成文档。

¥We started to use TSDoc for a better DX. While developing your IDE will now show you the documentation for the props and hooks. This is a big step for us to make the library more accessible and easier to use. We will also use TSDoc in the near future to generate the documentation.

内部更改

¥Internal changes

这些更改实际上并不是面向用户的，但对于使用内部 React Flow 存储的人来说可能很重要：

¥These changes are not really user-facing, but it could be important for folks who are working with the internal React Flow store:

最大的内部变化是我们创建了一个新的包 @xyflow/system，其中包含框架无关的辅助程序，可供 React Flow 和 Svelte Flow 使用

¥The biggest internal change is that we created a new package @xyflow/system with framework agnostic helpers that can be used by React Flow and Svelte Flow
- XYDrag 用于处理拖动节点和选择
  
  ¥XYDrag for handling dragging node(s) and selection
- XYPanZoom 用于控制视口平移和缩放
  
  ¥XYPanZoom for controlling the viewport panning and zooming
- XYHandle 用于管理新连接
  
  ¥XYHandle for managing new connections
我们将 nodeInternals 重命名为 nodeLookup。该地图用作查找，但我们不会在任何更改上创建新的地图对象，因此它实际上仅用作查找。

¥We renamed nodeInternals to nodeLookup. That map serves as a lookup, but we are not creating a new map object on any change so it’s really only useful as a lookup.
我们删除了内部 “reset” 事件并添加了 “replace” 事件以便能够更新特定节点。

¥We removed the internal “reset” event and added a “replace” event to be able to update specific nodes.
我们从存储中删除了 connectionNodeId、connectionHandleId、connectionHandleType，并添加了 connection.fromHandle.nodeId、connection.fromHandle.id、…

¥We removed connectionNodeId, connectionHandleId, connectionHandleType from the store and added connection.fromHandle.nodeId, connection.fromHandle.id, …
将 data-id 添加到边缘

¥add data-id to edges
当用户拖动选择时，onNodeDragStart、onNodeDrag 和 onNodeDragStop 也会被调用（除了 onSelectionDragStart、onSelectionDrag、onSelectionDragStop）

¥onNodeDragStart, onNodeDrag and onNodeDragStop also get called when user drags a selection (in addition to onSelectionDragStart, onSelectionDrag, onSelectionDragStop)

迁移到 React Flow 12

迁移指南

1. 新的 npm 包名称

2. 用于测量 width 和 height 的节点 measured 属性

3. 新维度处理 node.width / node.height 与 node.measured.width / node.measured.height

4. 更新节点和边

5. 将 onEdgeUpdate（及相关 API）重命名为 onReconnect

6. 将 parentNode 重命名为 parentId

7. 自定义节点属性

8. 处理组件类名

9. getNodesBounds 选项

10 . 用于定义节点和边的 Typescript 更改

11 . 重命名 nodeInternals

12 . 删除已弃用的函数

13 . 自定义 applyNodeChanges 和 applyEdgeChanges

新功能

1. 服务器端渲染

2. 计算流程

3. 夜间模式和 CSS 变量

4. 使用 TSDoc 的更好的 DX

更多功能和更新

内部更改

2. 用于测量 `width` 和 `height` 的节点 `measured` 属性

3. 新维度处理 `node.width` / `node.height` 与 `node.measured.width` / `node.measured.height`

5. 将 `onEdgeUpdate`（及相关 API）重命名为 `onReconnect`

6. 将 `parentNode` 重命名为 `parentId`

9. `getNodesBounds` 选项

11 . 重命名 `nodeInternals`

13 . 自定义 `applyNodeChanges` 和 `applyEdgeChanges`