可访问性

¥Accessibility

React Flow 提供键盘和屏幕阅读器支持，以帮助满足无障碍标准。默认情况下，所有节点和边均可通过键盘聚焦和操作。你可以使用以下属性启用或禁用这些功能：nodesFocusable、edgesFocusable 和 disableKeyboardA11y 像这样通过 <ReactFlow /> 传递：

¥React Flow provides keyboard and screen-reader support to help meet accessibility standards. By default, all nodes and edges are keyboard-focusable and operable. You can enable or disable these features with props including: nodesFocusable, edgesFocusable, and disableKeyboardA11y which are passed through <ReactFlow /> like this:

<ReactFlow
  nodesFocusable={true}
  edgesFocusable={true}
  disableKeyboardA11y={false}
  nodes={nodes}
  edges={edges}
>
  {/* ...other components like Controls, MiniMap... */}
</ReactFlow>

内置功能

¥Built-in Features

• 标签导航：按 Tab 键会将焦点移动到所有可聚焦的节点和边。这些元素接收 tabIndex={0} 和默认的 role="group" 来处理交互。

  ¥Tab navigation: Pressing Tab moves focus through all focusable nodes and edges. These elements receive tabIndex={0} and, by default, role="group" to handle interactivity.

• 选择/取消选择：按 Enter 或 Space 选择焦点节点/边，按 Escape 清除选择。

  ¥Select/Deselect: Press Enter or Space to select the focused node/edge, and Escape to clear the selection.

• 使用箭头键移动节点：如果 nodesDraggable 和 nodesFocusable 都为 true（默认值），则可以使用箭头键移动选定的节点。你可以按住 Shift 来增加移动速度。如果你设置了 disableKeyboardA11y={true}，则箭头键移动将被禁用（但 Tab 键聚焦和选择仍然有效）。

  ¥Move nodes with arrow keys: If nodesDraggable and nodesFocusable are both true (default), you can move the selected node with the arrow keys. You can hold Shift to increase movement speed. If you set disableKeyboardA11y={true}, arrow-key movement is disabled (but tab-focus and selection still work).

• 自动平移：当一个节点获得焦点时，React Flow 会自动平移画布以将该节点放入视图中。这确保了焦点节点对用户可见。此行为可以通过 autoPanOnNodeFocus 属性切换。

  ¥Automatic panning: When a node receives focus, React Flow automatically pans the canvas to bring that node into view. This ensures focused nodes are visible to the user. This behavior can be toggled via the autoPanOnNodeFocus prop.

• ARIA 描述：React Flow 自动添加 ARIA 描述，用于键盘导航。这些都可以通过使用 ariaLabelConfig 进行配置。

  ¥ARIA descriptions: React Flow automatically adds ARIA descriptions for keyboard guidance. These can be configured by using ariaLabelConfig.

ARIA 节点和边的角色

¥ARIA Roles for Nodes and Edges

默认情况下，React Flow 使用语义 ARIA 角色来处理交互元素。你可以使用 ariaRole 属性覆盖节点的角色。例如：

¥By default, React Flow uses semantic ARIA roles for interactive elements. You can override a node’s role using the ariaRole prop. For example:

const nodes = [
  {
    id: '1',
    data: { label: 'Hello' },
    ariaRole: 'button',
  },
];
<ReactFlow nodes={nodes} edges={[]} />;

默认情况下，如果你未设置角色，则应用 role="group"。自定义 ariaRole 可让你匹配任何相关的 ARIA 角色（例如 "listitem"、"region" 等），从而改进辅助技术的语义信息。

¥By, default, if you don’t set a role, role="group" is applied. Customizing ariaRole lets you match any relevant ARIA role (e.g. "listitem", "region", etc.), improving semantic information for assistive technology.

注意：ariaRole 应用于节点封装器。如果自定义节点包含交互元素，请避免在节点上设置 ariaRole: 'button' 本身。而是将相应的 ARIA 角色直接应用于交互元素。

¥Note: The ariaRole is applied to the node wrapper. If a custom node includes interactive elements, avoid setting ariaRole: 'button' on the node itself. Instead, apply the appropriate ARIA role directly to the interactive element.

DOM 属性

¥DOM Attributes

要传递自定义 ARIA 属性或其他 DOM 级属性（例如 aria-roledescription、data-\*、tabIndex 等），你可以使用 domAttributes 属性。这适用于节点和边：

¥To pass custom ARIA attributes or other DOM-level attributes (e.g., aria-roledescription, data-\*,tabIndex, etc.), you can use the domAttributes prop. This is available for both nodes and edges:

// Example for a node
{
  id: '2',
  data: { label: 'Accessible Node' },
  domAttributes: {
    'aria-roledescription': 'collapsible node',
    tabIndex: 0,
    'data-test-id': 'node-2',
  },
}

这使你可以完全控制与可访问性相关的属性，同时保留 React Flow 的内置角色和行为。

¥This gives you full control over accessibility-related attributes while maintaining React Flow’s built-in roles and behaviors.

本地化无障碍消息

¥Localizing Accessibility Messages

React Flow 的内置无障碍文本（例如键盘指令和实时更新）可以通过 ariaLabelConfig 属性 on<ReactFlow> 进行自定义或本地化。此属性接受一个将消息键映射到字符串或函数的对象。按键包括：

¥React Flow’s built-in accessibility text (such as keyboard instructions and live updates) can be customized or localized via the ariaLabelConfig prop on<ReactFlow>. This prop takes an object mapping message keys to strings or functions. Keys include:

例如，要提供自定义或本地化的文本：

¥For example, to provide custom or localized text:

const ariaLabels = {
  'node.a11yDescription.default': 'Press [Enter] to select this node',
  'node.a11yDescription.keyboardDisabled': 'Keyboard navigation is disabled',
};
<ReactFlow nodes={nodes} edges={edges} ariaLabelConfig={ariaLabels}>
  <MiniMap />
  <Controls />
</ReactFlow>;

这会告诉 React Flow 使用你的文本而不是默认值。通过 ariaLabelConfig 提供本地化字符串，你可以确保屏幕阅读器以用户的语言。

¥This tells React Flow to use your text instead of the defaults. By supplying localized strings via ariaLabelConfig, you ensure screen readers announce messages in the user’s language.

WCAG 2.1 AA

React Flow 提供的功能在正确实现后可帮助你满足 WCAG 2.1 AA 的关键标准：

¥React Flow provides features that can help you meet key WCAG 2.1 AA criteria when properly implemented:

• 键盘：React Flow 支持通过 Tab 导航到节点和边缘的键盘操作，通过 Enter/Space 进行交互，以及通过箭头键移动节点。这些功能有助于满足键盘可访问性的要求。

  ¥Keyboard: React Flow supports keyboard operability with Tab navigation to nodes and edges, interaction via Enter/Space, and arrow key movement for nodes. These features help satisfy requirements for keyboard accessibility.

• 屏幕阅读器：借助语义 ARIA 角色和标签（例如 role="group"、aria-label 和 aria-roledescription），React Flow 使你能够创建有意义的图形节点/边。边组件包含一个可自定义的 aria-label，并且可以为节点指定相应的 aria-label 文本。

  ¥Screen Reader: With semantic ARIA roles and labels (e.g. role="group", aria-label, and aria-roledescription), React Flow enables you to create meaningfully announced graphical nodes/edges. Edge components include a customizable aria-label and nodes can be given appropriate aria-label text.

• ARIA 实时区域：动态更新通过 aria-live 区域进行声明。A11yDescriptions 组件包含一个带有 aria-live="assertive" 的元素，用于通知用户节点的移动，帮助你满足状态消息的要求。

  ¥ARIA Live Regions: Dynamic updates are announced through an aria-live region. The A11yDescriptions component includes an element with aria-live="assertive" that notifies users of node movements, helping you meet requirements for status messages.

• 说明和焦点管理：React Flow 提供上下文帮助和清晰的说明，例如 “按 Enter 键或空格键选择节点……”。自动焦点管理功能可确保节点在获得焦点时滚动到视图中，从而满足输入辅助的需求。

  ¥Instructions and Focus Management: React Flow provides contextual help with clear instructions like “Press enter or space to select a node…”. The automatic focus management ensures nodes scroll into view when focused, helping satisfy requirements for input assistance.

本指南有助于了解 ARIA 最佳实践 。

¥This guide is helpful for learning about ARIA best practices .