自定义节点

¥Custom Nodes

React Flow 的一个强大功能是能够创建自定义节点。这让你可以灵活地在节点内渲染任何你想要的内容。我们通常建议创建自己的自定义节点，而不是依赖内置节点。使用自定义节点，你可以根据需要添加任意数量的源和目标句柄，甚至可以嵌入表单输入、图表和其他交互元素。

¥A powerful feature of React Flow is the ability to create custom nodes. This gives you the flexibility to render anything you want within your nodes. We generally recommend creating your own custom nodes rather than relying on built-in ones. With custom nodes, you can add as many source and target handles as you like—or even embed form inputs, charts, and other interactive elements.

在本节中，我们将介绍如何创建一个自定义节点，该节点具有一个输入字段，用于更新应用其他地方的文本。有关更多示例，我们建议查看我们的 自定义节点示例。

¥In this section, we’ll walk through creating a custom node featuring an input field that updates text elsewhere in your application. For further examples, we recommend checking out our Custom Node Example.

实现自定义节点

¥Implementing a Custom Node

要创建自定义节点，你需要做的就是创建一个 React 组件。React Flow 会自动将其封装在一个交互式容器中，该容器注入节点的 id、位置和数据等基本属性，并提供选择、拖动和连接句柄的功能。有关所有可用自定义节点属性的完整参考，请参阅 自定义节点属性。

¥To create a custom node, all you need to do is create a React component. React Flow will automatically wrap it in an interactive container that injects essential props like the node’s id, position, and data, and provides functionality for selection, dragging, and connecting handles. For a full reference on all available custom node props, see the Custom Node Props.

让我们通过创建一个名为 TextUpdaterNode 的自定义节点来深入研究一个示例。为此，我们添加了一个带有更改处理程序的简单输入字段。React Flow 有几个方便的 预构建组件 来简化创建自定义节点的过程。我们将使用 Handle 组件 允许我们的自定义节点与其他节点连接。

¥Let’s dive into an example by creating a custom node called TextUpdaterNode. For this, we’ve added a simple input field with a change handler. React Flow has a few handy pre-built components to simplify the process of creating custom nodes. We will use the Handle component to allow our custom node to connect with other nodes.

import { useCallback } from 'react';
import { Handle, Position } from '@xyflow/react';
 
const handleStyle = { left: 10 };
 
function TextUpdaterNode({ data }) {
  const onChange = useCallback((evt) => {
    console.log(evt.target.value);
  }, []);
 
  return (
    <>
      <Handle type="target" position={Position.Top} />
      <div>
        <label htmlFor="text">Text:</label>
        <input id="text" name="text" onChange={onChange} className="nodrag" />
      </div>
      <Handle type="source" position={Position.Bottom} id="a" />
      <Handle type="source" position={Position.Bottom} id="b" style={handleStyle} />
    </>
  );
}

添加节点类型

¥Adding the Node Type

你可以通过将新节点类型添加到 nodeTypes 属性来向 React Flow 添加新节点类型，如下所示。我们在组件外部定义 nodeTypes 以防止重新渲染。

¥You can add a new node type to React Flow by adding it to the nodeTypes prop like below. We define the nodeTypes outside of the component to prevent re-renderings.

const nodeTypes = {
  textUpdater: TextUpdaterNode
};
 
function Flow() {
  ...
  return (
    <ReactFlow
      nodes={nodes}
      edges={edges}
      onNodesChange={onNodesChange}
      onEdgesChange={onEdgesChange}
      onConnect={onConnect}
      nodeTypes={nodeTypes}
      fitView
      style={rfStyle}
    />
  );
}

如果 nodeTypes 在组件内定义，则必须对其进行记忆。否则，React 会在每次渲染时创建一个新对象，这会导致性能问题和错误。以下是使用 useMemo 钩子记忆组件内部 nodeTypes 对象的方法：

¥If nodeTypes are defined inside a component, they must be memoized. Otherwise, React creates a new object on every render, which leads to performance issues and bugs. Here’s how you can memoize the nodeTypes object inside a component using the useMemo hook:

const nodeTypes = useMemo(() => ({ textUpdater: TextUpdaterNode }), []);
 
return <ReactFlow nodeTypes={nodeTypes} />;

定义新节点类型后，你可以使用 type 节点选项使用它：

¥After defining your new node type, you can use it by using the type node option:

const nodes = [
  {
    id: 'node-1',
    type: 'textUpdater',
    position: { x: 0, y: 0 },
    data: { value: 123 },
  },
];

将所有内容放在一起并添加一些基本样式后，我们得到了一个将文本打印到控制台的自定义节点：

¥After putting all together and adding some basic styles we get a custom node that prints text to the console:

import { useCallback, useState } from 'react';
import {
  ReactFlow,
  addEdge,
  applyEdgeChanges,
  applyNodeChanges,
} from '@xyflow/react';
import '@xyflow/react/dist/style.css';
 
import TextUpdaterNode from './TextUpdaterNode';
 
const rfStyle = {
  backgroundColor: '#B8CEFF',
};
 
const initialNodes = [
  {
    id: 'node-1',
    type: 'textUpdater',
    position: { x: 0, y: 0 },
    data: { value: 123 },
  },
];
// we define the nodeTypes outside of the component to prevent re-renderings
// you could also use useMemo inside the component
const nodeTypes = { textUpdater: TextUpdaterNode };
 
function Flow() {
  const [nodes, setNodes] = useState(initialNodes);
  const [edges, setEdges] = useState([]);
 
  const onNodesChange = useCallback(
    (changes) => setNodes((nds) => applyNodeChanges(changes, nds)),
    [setNodes],
  );
  const onEdgesChange = useCallback(
    (changes) => setEdges((eds) => applyEdgeChanges(changes, eds)),
    [setEdges],
  );
  const onConnect = useCallback(
    (connection) => setEdges((eds) => addEdge(connection, eds)),
    [setEdges],
  );
 
  return (
    <ReactFlow
      nodes={nodes}
      edges={edges}
      onNodesChange={onNodesChange}
      onEdgesChange={onEdgesChange}
      onConnect={onConnect}
      nodeTypes={nodeTypes}
      fitView
      style={rfStyle}
    />
  );
}
 
export default Flow;

实用程序类

¥Utility Classes

React Flow 提供了几个内置的实用 CSS 类，可帮助你微调自定义节点内的交互工作方式。

¥React Flow provides several built-in utility CSS classes to help you fine-tune how interactions work within your custom nodes.

nodrag

在上面的示例中，我们将类 nodrag 添加到输入中。这可确保与输入字段的交互不会触发拖动，从而允许你选择字段内的文本。

¥In the example above, we added the class nodrag to the input. This ensures that interacting with the input field doesn’t trigger a drag, allowing you to select the text within the field.

默认情况下，节点具有 drag 类名。但是，这个类名会影响自定义节点内事件监听器的行为。为了防止意外行为，请向具有事件监听器的元素添加 nodrag 类名。当单击具有此类的元素时，这会阻止默认拖动行为以及默认节点选择行为。

¥Nodes have a drag class name in place by default. However, this class name can affect the behaviour of the event listeners inside your custom nodes. To prevent unexpected behaviours, add a nodrag class name to elements with an event listener. This prevents the default drag behavior as well as the default node selection behavior when elements with this class are clicked.

export default function CustomNode(props: NodeProps) {
  return (
    <div>
      <input className="nodrag" type="range" min={0} max={100} />
    </div>
  );
}

nowheel

如果你的自定义节点包含可滚动内容，则可以应用 nowheel 类。当你在自定义节点内滚动时，这会禁用画布的默认平移行为，确保只有内容滚动而不是移动整个画布。

¥If your custom node contains scrollable content, you can apply the nowheel class. This disables the canvas’ default pan behavior when you scroll inside your custom node, ensuring that only the content scrolls instead of moving the entire canvas.

export default function CustomNode(props: NodeProps) {
  return (
    <div className="nowheel" style={{ overflow: 'auto' }}>
      <p>Scrollable content...</p>
    </div>
  );
}

应用这些实用程序类可帮助你在粒度级别上控制交互。你可以在 React Flow 的 样式属性 中自定义这些类名。

¥Applying these utility classes helps you control interaction on a granular level. You can custimize these class names inside React Flow’s style props.

使用多个句柄

¥Using Multiple Handles

使用这些句柄定义与其他节点的边缘连接时，仅使用节点 id 是不够的。你还需要指定一个句柄 id。在本例中，我们为一个源句柄分配一个 id a，为另一个源句柄分配一个 id b。

¥When defining edge connections to other nodes using these handles, simply using the node id isn’t enough. You will also need to specify a handle id. In this case, we assign an id a to one source handle and an id b to the other source handle.

在 React Flow 中，可以使用属性 sourceHandle（用于边的起点）和 targetHandle（用于边的终点）将边连接到节点内的特定句柄。当节点上有多个句柄时 - 例如，两个标记为“a”和“b”的源句柄，仅指定节点的 id 不足以让 React Flow 知道要使用哪个连接点。通过使用适当的句柄 id 定义 sourceHandle 或 targetHandle，你可以指示 React Flow 将边附加到该特定句柄，确保在你想要的位置建立连接。

¥In React Flow, edges can be connected to specific handles within a node using the properties sourceHandle (for the edge’s starting point) and targetHandle (for the edge’s ending point). When you have multiple handles on a node—for example, two source handles labeled “a” and “b”, simply specifying the node’s id isn’t enough for React Flow to know which connection point to use. By defining sourceHandle or targetHandle with the appropriate handle id, you instruct React Flow to attach the edge to that specific handle, ensuring that connections are made where you intend.

const initialEdges = [
  { id: 'edge-1', source: 'node-1', sourceHandle: 'a', target: 'node-2' },
  { id: 'edge-2', source: 'node-1', sourceHandle: 'b', target: 'node-3' },
];

在这种情况下，两个句柄的源节点都是 node-1，但句柄 id 不同。一个来自句柄 ID "a"，另一个来自 "b"。两个边也有不同的目标节点：

¥In this case, the source node is node-1 for both handles but the handle ids are different. One comes from handle id "a" and the other one from "b". Both edges also have different target nodes:

import { useCallback, useState } from 'react';
import {
  ReactFlow,
  addEdge,
  applyEdgeChanges,
  applyNodeChanges,
} from '@xyflow/react';
import '@xyflow/react/dist/style.css';
 
import TextUpdaterNode from './TextUpdaterNode';
 
const rfStyle = {
  backgroundColor: '#B8CEFF',
};
 
const initialNodes = [
  {
    id: 'node-1',
    type: 'textUpdater',
    position: { x: 0, y: 0 },
    data: { value: 123 },
  },
  {
    id: 'node-2',
    type: 'output',
    targetPosition: 'top',
    position: { x: 0, y: 200 },
    data: { label: 'node 2' },
  },
  {
    id: 'node-3',
    type: 'output',
    targetPosition: 'top',
    position: { x: 200, y: 200 },
    data: { label: 'node 3' },
  },
];
 
const initialEdges = [
  { id: 'edge-1', source: 'node-1', target: 'node-2', sourceHandle: 'a' },
  { id: 'edge-2', source: 'node-1', target: 'node-3', sourceHandle: 'b' },
];
 
// we define the nodeTypes outside of the component to prevent re-renderings
// you could also use useMemo inside the component
const nodeTypes = { textUpdater: TextUpdaterNode };
 
function Flow() {
  const [nodes, setNodes] = useState(initialNodes);
  const [edges, setEdges] = useState(initialEdges);
 
  const onNodesChange = useCallback(
    (changes) => setNodes((nds) => applyNodeChanges(changes, nds)),
    [setNodes],
  );
  const onEdgesChange = useCallback(
    (changes) => setEdges((eds) => applyEdgeChanges(changes, eds)),
    [setEdges],
  );
  const onConnect = useCallback(
    (connection) => setEdges((eds) => addEdge(connection, eds)),
    [setEdges],
  );
 
  return (
    <ReactFlow
      nodes={nodes}
      edges={edges}
      onNodesChange={onNodesChange}
      onEdgesChange={onEdgesChange}
      onConnect={onConnect}
      nodeTypes={nodeTypes}
      fitView
      style={rfStyle}
    />
  );
}
 
export default Flow;

如果你以编程方式更改自定义节点中句柄的位置或数量，则需要使用 useUpdateNodeInternals 钩子正确地通知 React Flow 更改。

¥If you are programmatically changing the position or number of handles in your custom node, you will need to use the useUpdateNodeInternals hook to properly notify React Flow of changes.