react-beautiful-dnd 无障碍(Accessibility)实践:让键盘、屏幕阅读器与焦点管理覆盖每一位用户

原创2026-09-18 14:37:191,863 阅读

react-beautiful-dnd 无障碍(Accessibility)实践:让键盘、屏幕阅读器与焦点管理覆盖每一位用户

本篇指南围绕 react-beautiful-dnd 的无障碍设计展开。传统的拖拽交互几乎只面向鼠标与触摸屏,而本库通过完整的键盘操作、屏幕阅读器实时播报、浏览器焦点智能管理以及 Lighthouse 自动化审计,把拖拽能力开放给了视障用户和纯键盘用户。读完本文,你将掌握 react-beautiful-dnd 无障碍能力的完整清单、底层实现机制(live region、aria-describedby、focus marshal、expiring announce),以及如何在你的列表应用中定制屏幕阅读器播报消息。

无障碍设计理念:拖拽不应只属于鼠标

长期以来,拖拽(drag and drop)交互被认为是“鼠标或触摸的专利”:按住、拖动、松开,这套物理手势对纯键盘用户和依赖屏幕阅读器的用户来说几乎无法完成。react-beautiful-dnd 在 无障碍文档 中明确表示,库投入了大量工程努力,确保每个人都能使用拖拽交互,而不是为无障碍用户提供一个降级方案。

值得强调的是,库没有使用 HTML5 原生拖拽 API。正如 屏幕阅读器指南 中所解释的,HTML5 拖拽 API 无法提供库想要实现的体验,且其无障碍能力需要开发者额外构建一套键盘交互组件;同时 aria-grabbed 与 aria-dropeffect 已在 WAI-ARIA 1.1 中被废弃,WAI-ARIA 1.2 也没有对应的替代属性。因此库选择了自研指针与键盘事件体系 + ARIA live region 播报的方案。

围绕这一理念,文档总结出六项核心投入,下文逐一展开:

  1. 完整的键盘支持(排序、合并、跨列表移动)
  2. 键盘多拖模式支持
  3. 键盘自动滚动
  4. 开箱即用的屏幕阅读器支持(内置英文播报消息)
  5. 浏览器焦点智能管理
  6. 基于 Google Lighthouse 的自动化无障碍审计

完整的键盘支持:从空格抬起开始

键盘操作是整套无障碍体验的地基。相关细节记录在 键盘传感器文档 中,其实现位于 use-keyboard-sensor.js。

当页面没有进行拖拽时,用户可以用标准 Tab(前进)与 Shift + Tab(后退)在所有 <Draggable /> 之间导航——库通过给拖拽手柄添加 tabindex 实现。当一个 <Draggable /> 获得焦点后:

  • 空格(space):抬起(lift)<Draggable />,开始拖拽;
  • 空格(space)(拖拽中):放下(drop)<Draggable />;
  • Esc(escape):取消拖拽。

方向键的行为取决于 <Draggable /> 当前所在 <Droppable /> 的类型:

方向键 垂直列表内 水平列表内
↑ 在列表内向上移动 移动到当前列表上方的 <Droppable />
↓ 在列表内向下移动 移动到当前列表下方的 <Droppable />
→ 移动到右侧的 <Droppable /> 在列表内向右移动
← 移动到左侧的 <Droppable /> 在列表内向左移动

也就是说,方向键同时承担了「列表内重排」和「跨列表移动」两种语义,且行为随列表方向自动切换。源码中键盘传感器对 keyCodes.escape、keyCodes.space 等按键做了专门分支处理(见 use-keyboard-sensor.js)。

拖拽期间,库会通过 event.preventDefault() 屏蔽部分标准浏览器快捷键,以保证交互连贯:

  • Tab:禁止拖拽中切换焦点;
  • Enter:禁止触发表单提交。

屏蔽逻辑的完整说明见 我们如何使用 DOM 事件指南。

键盘自动滚动:看不见也能在大列表中移动

拖拽中列表需要自动滚动才能让项到达目标位置,键盘用户同样依赖这一点。自动滚动指南 指出:当用户用键盘把 <Draggable /> 移向某个滚动容器的边缘时,库会综合运用 <Droppable /> 滚动、window 滚动与手动位移,将 <Draggable /> 精确送入目标位置。这使视障用户无需精确的鼠标定位,也能在大列表中移动条目。

  • 鼠标与触摸输入下,自动滚动基于容器宽高的百分比距离触发并加速(越靠近边缘越快,且采用缓动函数加速,最大值在距边缘一小段距离处达到,避免用户必须贴边才能获得最大速度);
  • 若 <Draggable /> 在某个轴上大于容器(如比窗口还高),则该轴禁止自动滚动,但另一轴仍可滚动;
  • iOS(webkit)上自动滚动存在已知的抖动问题,源自 webkit 的一个 bug,目前无已知规避方案。

屏幕阅读器支持:内置英文消息与 live region 机制

库默认内置了完整的英文屏幕阅读器消息,零配置即可使用;同时通过 Responders 提供的 announce 函数,允许开发者完全定制播报内容。这部分是 无障碍文档 中「Fantastic screen reader support」承诺的落点,完整指南见 屏幕阅读器指南。

焦点播报:让手柄“可读”

当用户聚焦到一个拖拽手柄(widget)时,屏幕阅读器需要知道「这是一个可拖拽的项,以及如何开始拖拽」。库通过以下方式实现(相关实现见 use-hidden-text-element.js):

  • tabindex="0":把原本语义上不可交互的元素标记为可聚焦的交互内容;
  • aria-describedby:指向一个库创建的隐藏元素(rbd-hidden-text-${contextId}-${uniqueId}),其默认文案为:"Press space bar to start a drag. When dragging you can use the arrow keys to move the item around and escape to cancel. Ensure your screen reader is in focus mode or forms mode"。该文案实际定义在 screen-reader-message-preset.js 中;
  • 库当前不会默认添加 role="button" 或 aria-roledescription="Draggable item",因为 aria-roledescription 目前无法通过 Google Lighthouse 的 axe 审计(官方已在 issue #1742 中跟踪该问题)。

拖拽生命周期播报:live region 与 expiring announce

拖拽的每个阶段(开始、移动、结束、取消)库都会通过 ARIA live region 立即播报消息。live region 元素的创建见 use-announcer.js:一个 id 为 rbd-announcement-${contextId} 的 div,设置 aria-live="assertive" 与 aria-atomic="true",并使用视觉隐藏样式挂载到 <body> 上。

库对 announce 有两个硬性约束(实现见 expiring-announce.js):

  1. 必须立即调用:announce 只在事件同步阶段有效,消息会被立即读出;若异步调用(如 setTimeout 之后),会打印警告且消息丢失;
  2. 同一次事件只能调用一次:同一事件内第二次调用会被忽略,并打印 "Announcement already made" 警告。

各阶段默认消息与定制示例

库内置消息全部定义在 screen-reader-message-preset.js,使用“位置 = 索引 + 1”(position = index + 1)而非索引,因为「You have moved an item to position 2」比「index 1」更自然。

拖拽开始(onDragStart)

默认消息:

You have lifted an item in position ${startPosition}

库不播报 1 of x,因为当前 API 无法获知列表总长度(虚拟列表尤其如此,同一时刻只渲染一部分)。你可以在自己的消息中补充:

You have lifted an item in position ${startPosition} of ${listLength} in the ${listName} list.

通过 onDragStart 定制:

onDragStart = (start, provided) => {
  provided.announce('My super cool message');
};

拖拽移动(onDragUpdate) —— 分为多个场景,默认消息分别如下:

场景 默认消息
同一列表内移动 You have moved the item from position ${startPosition} to position ${endPosition}
移动到另一个列表 You have moved the item from position ${startPosition} in list ${source.droppableId} to list ${destination.droppableId} in position ${endPosition}
同列表内合并(combine) The item ${source.draggableId} has been combined with ${combine.draggableId}
跨列表合并 The item ${source.draggableId} in list ${source.droppableId} has been combined with ${combine.draggableId} in list ${combine.droppableId}
未处于任何可放置区域 You are currently not dragging over a droppable area

定制方式:

onDragUpdate = (update, provided) => {
  provided.announce('Update message');
};

拖拽结束(onDragEnd) —— 依据 DropResult.reason(DROP 或 CANCEL)以及是否落在目标上,默认消息如下:

场景 默认消息
取消拖拽 Movement cancelled. The item has returned to its starting position of ${startPosition}
落回起始列表 You have dropped the item. It has moved from position ${startPosition} to ${endPosition}
落入其他列表 You have dropped the item. It has moved from position ${startPosition} in list ${result.source.droppableId} to position ${endPosition} in list ${result.destination.droppableId}
同列表合并 You have dropped the item. The item ${source.draggableId} has been combined with ${combine.draggableId}
跨列表合并 The item ${source.draggableId} in list ${source.droppableId} has been combined with ${combine.draggableId} in list ${combine.droppableId}
未落在可放置区域 The item has been dropped while not over a droppable location. The item has returned to its starting position of ${startPosition}

利用 reason 区分取消与正常落下的定制示例:

onDragEnd = (result, provided) => {
  if (result.reason === 'CANCEL') {
    provided.announce('Your cancel message');
    return;
  }
};

合并(combine)模式是上述部分场景的前提:在 <Droppable /> 上开启 isCombineEnabled 即可启用,详见 合并指南。

多拖模式下的播报建议

多拖(multi drag)当前需要开发者基于库自行搭建,库内部并不感知多拖,因此 多拖指南 明确建议:使用 ResponderProvided.announce 为多拖场景播报有意义的屏幕阅读器消息,具体做法即上文介绍的 announce 用法。

测试环境:VoiceOver 与 NVDA

无障碍指南建议在真实屏幕阅读器上验证:

  • Mac:使用内置 VoiceOver(cmd + F5 启动);
  • Windows 7 SP1+:使用免费的 NVDA。

浏览器焦点管理:拖拽前后焦点不丢失

键盘拖拽要求被拖拽项始终处于可聚焦状态,因此库实现了专门的 focus marshal(焦点调度器)来管理拖拽手柄的焦点,相关文档见 浏览器焦点指南,实现见 use-focus-marshal.js。

  • 拖拽开始时未聚焦:库不会强行把焦点给到被拖拽项(与 HTML5 原生拖拽行为一致)。如果你希望获得焦点,可以在 onDragStart 中自行调用 HTMLElement.focus();
  • 拖拽开始时已聚焦:库会在拖拽开始后、拖拽结束后,通过 tryGiveFocus 把焦点交还给与 DraggableId 匹配的拖拽手柄。这在重挂载(reparenting) 或跨列表移动导致 React 重建元素时尤为重要——原手柄元素可能已销毁,需要重新定位新的手柄元素;
  • 合并模式:拖拽结束后焦点会被给予 combine 目标,让键盘用户无需再手动找回焦点即可继续操作。

从源码看,focus marshal 维护了一个 id -> focus() 的注册表(entriesRef),并在卸载时通过 requestAnimationFrame 延迟恢复焦点(tryRestoreFocusRecorded),以避免在组件树尚未稳定时误操作(见 use-focus-marshal.js)。

Lighthouse 自动化审计与测试保障

无障碍文档 提到,项目通过 Google Lighthouse 的自动化构建来确保无障碍评分(至少按 Google 的评分标准)满分。这一承诺在测试侧也有印证:

  • 仓库中存在 axe 无障碍审计测试 axe-audit.spec.js,用于自动化检查渲染结果是否违反 WCAG/ARIA 规则;
  • 焦点管理行为通过 Cypress 等端到端测试验证,确保「拖拽开始/结束时焦点被正确维护」这一行为符合预期(参见 浏览器焦点指南 中关于 Cypress 测试的说明);
  • 屏幕阅读器相关的行为(如 announce 的使用约束)由响应者中间件测试覆盖,例如 responders 中间件测试 目录下的用例。

小结

react-beautiful-dnd 的无障碍能力是一套环环相扣的系统:键盘传感器提供了纯键盘的完整拖拽操作;自动滚动让键盘/视障用户也能在大列表中长距离移动;live region 播报(内置英文消息 + 可定制的 announce)让屏幕阅读器用户实时掌握拖拽状态;focus marshal 保证焦点在拖拽前后不丢失;最后,Lighthouse 与 axe 自动化测试持续守住无障碍质量底线。对于开发者而言,接入这些能力几乎零成本——库默认全部开启;而深度定制播报消息、补充“位置 1 of x”等信息,则是你可以在此基础上继续发挥的空间。

登录后查看全文
react-beautiful-dnd