Draggable Focusable 插件解析:为拖拽元素与容器自动注入 tabindex 的可访问性增强方案

原创2026-09-21 10:03:491,700 阅读
文章标签:前端UI组件Web框架

Draggable Focusable 插件解析:为拖拽元素与容器自动注入 tabindex 的可访问性增强方案

Focusable 是 Draggable 拖拽库内置的四个默认插件(Announcement、Focusable、Mirror、Scrollable)之一,其核心职责是在拖拽库初始化时,为所有 draggable 容器与可拖拽元素自动补全 tabindex 属性,使它们能够通过键盘获得焦点,从而让鼠标拖拽交互具备键盘可达性基础。阅读完本文,你将掌握 Focusable 的 API 用法、它与 Draggable 生命周期的绑定关系、其"只增不覆盖、可完整回滚"的装饰策略,以及如何用测试用例验证插件行为。

Focusable 插件是什么

按照 src/Draggable/Plugins/Focusable/README.md 的定位,Focusable 插件在初始化时查找所有 draggable 容器和 draggable 元素,并为它们装饰 tabindex 属性:

  • 它不会覆盖元素上已存在的 tabindex 属性;
  • 它会使 draggable 元素和容器变得可聚焦(focusable),为后续接入键盘拖拽、屏幕阅读器辅助等无障碍能力打下基础。

从 src/Draggable/Plugins/index.js 可以看到,Focusable 与 Announcement、Mirror、Scrollable 一同作为默认插件导出;而在 Draggable 核心实现中,它被挂载到静态属性 Draggable.Plugins 上:

static Plugins = {Announcement, Focusable, Mirror, Scrollable};

这意味着默认情况下每个 new Draggable(...) 实例都会自动装载 Focusable 插件,无需任何额外配置。

工作原理:初始化装饰、销毁还原

Focusable 的实现位于 src/Draggable/Plugins/Focusable/Focusable.js,它继承自共享抽象基类 AbstractPlugin。整个生命周期分两个阶段:

1. 监听 Draggable 生命周期事件

插件通过 attach() 注册两个事件监听,通过 detach() 注销并主动执行清理:

attach() {
  this.draggable
    .on('draggable:initialize', this[onInitialize])
    .on('draggable:destroy', this[onDestroy]);
}

detach() {
  this.draggable
    .off('draggable:initialize', this[onInitialize])
    .off('draggable:destroy', this[onDestroy]);
  // Remove modified elements when detach
  this[onDestroy]();
}

即:拖拽库初始化时装饰 tabindex,销毁时还原;即使插件被手动 removePlugin 移除(走 detach()),也会同步触发还原逻辑,不会留下残留属性。

2. 下一帧执行,避免阻塞首屏

两个处理函数都用 requestAnimationFrame 延迟到下一渲染帧执行,避免初始化阶段对页面造成可见的布局抖动:

[onInitialize]() {
  requestAnimationFrame(() => {
    this.getElements().forEach((element) => decorateElement(element));
  });
}

[onDestroy]() {
  requestAnimationFrame(() => {
    this.getElements().forEach((element) => stripElement(element));
  });
}

3. 装饰与还原的核心算法

decorateElement 与 stripElement 配合一个模块级数组 elementsWithMissingTabIndex,实现"只增不覆盖、精准回滚":

function decorateElement(element) {
  const hasMissingTabIndex = Boolean(
    !element.getAttribute('tabindex') && element.tabIndex === -1,
  );

  if (hasMissingTabIndex) {
    elementsWithMissingTabIndex.push(element);
    element.tabIndex = 0;
  }
}

function stripElement(element) {
  const tabIndexElementPosition = elementsWithMissingTabIndex.indexOf(element);

  if (tabIndexElementPosition !== -1) {
    element.tabIndex = -1;
    elementsWithMissingTabIndex.splice(tabIndexElementPosition, 1);
  }
}

这段逻辑非常关键,它保证了三种边界情况的正确性:

  • 已显式设置 tabindex 属性的元素(element.getAttribute('tabindex') 非空):不装饰、不记录,销毁时原样保留;
  • 本身可聚焦的原生控件(如 <button>,其 tabIndex 默认为 0):不满足 element.tabIndex === -1,同样被跳过;
  • 真正缺失 tabindex 的普通元素(如 <li>、<div>,tabIndex 为 -1):才被记录并设为 tabIndex = 0,销毁时精确还原为 -1。

由于只有被记录进 elementsWithMissingTabIndex 的元素才会在 stripElement 中被还原,插件销毁时绝不会误伤开发者自己的 tabindex 配置。

API 参考

依据插件文档,Focusable 对外暴露两个 API:

new Focusable(draggable: Draggable): Focusable

创建一个 Focusable 插件实例。正常情况下无需手动实例化——Draggable 构造时会把 Draggable.Plugins 中的默认插件自动 addPlugin(见 Draggable.js),用户传参中的 options.plugins 会被追加到默认插件之后。若确实需要手动创建,可仿照框架内部的用法:

import {Draggable, Plugins} from 'draggable';

const draggable = new Draggable(containers, {
  plugins: [/* 自定义插件 */],
});

const focusable = new Plugins.Focusable(draggable);
focusable.attach();

focusable.getElements(): HTMLElement[]

返回容器与 draggable 元素的并集,这也是内部装饰逻辑所作用的元素集合:

getElements() {
  return [
    ...this.draggable.containers,
    ...this.draggable.getDraggableElements(),
  ];
}

其中 draggable.containers 是构造时传入的容器数组,draggable.getDraggableElements() 则是在每个容器内按 options.draggable 选择器(默认 .draggable-source)查找并过滤掉 mirror 与原始源元素(见 Draggable.js 的 getDraggableElements 实现)。你可以用它主动获取被装饰的元素列表,例如在无障碍测试中断言焦点顺序。

Options:无配置项

插件文档明确标注 No options,源码也证实了这一点——Focusable.js 中的 defaultOptions = {},虽然实现了 getOptions()(读取 this.draggable.options.focusable || {})以兼容未来的配置扩展,但目前没有任何可调参数。行为完全由 Draggable 实例的 containers 与 draggable 选择器决定:传入的容器越精确、选择器越具体,被装饰的元素范围就越可控。

如果你希望禁用该插件(例如你已经在业务侧自行管理 tabindex),可以通过 Draggable 的 exclude.plugins 选项排除:

import {Draggable, Plugins} from 'draggable';

const draggable = new Draggable(containers, {
  exclude: {
    plugins: [Plugins.Focusable],
  },
});

Draggable 构造时会用 !this.options.exclude.plugins.includes(Plugin) 过滤默认插件(Draggable.js),被排除的插件将不会被实例化。

测试验证:四类行为断言

Focusable.test.js 用一组沙箱 DOM 完整验证了插件行为,可作为理解与回归的权威依据:

测试用例 断言内容 说明
is included by default new Draggable 后能在 draggable.plugins 中找到 Focusable 实例 验证默认装载行为
sets tabindex properties 容器与 draggable 元素在初始化后 tabIndex === 0 验证装饰逻辑
removes tabindex properties draggable.destroy() 后元素 tabIndex === -1 验证还原逻辑
does not remove tabindex properties for natively focusable elements <button> 销毁后 tabIndex 仍为 0 验证不误伤原生可聚焦元素
does not remove tabindex properties for element with tabindex attribute 带 tabindex="1" 的元素销毁后值不变 验证不覆盖显式属性

测试中通过 waitForRequestAnimationFrame() 等待装饰/还原动作完成,与源码中 requestAnimationFrame 的异步设计相呼应。

使用建议与注意事项

  1. 它是键盘可达性的前提,而非完整键盘拖拽方案:Focusable 只负责让容器与可拖拽元素获得焦点(tabindex=0),真正用键盘触发拖拽还需结合 draggable:start 等事件的按键监听,可在 DragEvent 文档 中进一步了解事件体系。
  2. 尽量缩小容器范围:Focusable 会装饰所有容器及其内所有匹配选择器的元素,若容器过大,被装饰元素数量也会随之膨胀。
  3. 销毁顺序:调用 draggable.destroy() 或 removePlugin(Plugins.Focusable) 都会触发还原,且还原是异步(下一帧)的,需要即时断言时应等待一帧。
  4. 与自定义 tabindex 和平共处:正因为"不覆盖、只还原自己动过的元素"这一设计,Focusable 可以放心与业务侧的手动 tabindex 管理共存。

综上,Focusable 是 Draggable 无障碍体系中的"地基"插件:体积小、零配置,通过一次初始化扫描为整套拖拽界面补齐键盘焦点入口,并在销毁时干净利落地还原现场——这份"增得克制、撤得彻底"的实现,值得在需要键盘可达性的拖拽交互中放心使用。

<输出文章>

登录后查看全文
draggable