focus-fly

v2.1.0

Published

8 months ago

焦点管理。Focus management.

Downloads

0High
0Medium
0Low

wswmsword

focus focus-management accessibility keyboard tab-sequence focus-lock focus-trap

focus-fly

使用 focus-fly 管理和控制焦点，实现一个键盘可访问的用户界面，为用户带来流畅的键盘体验。focus-fly（v2.0.1）的压缩体积为 6.2kB。

键盘可访问的用户界面，会在用户丧失或暂时丧失使用鼠标能力的时候，依然保有用户使用键盘的能力。对于有能力同时使用鼠标和键盘的用户，他们可以自由地切换访问界面的设备。您可以任意选择鼠标和键盘来访问这个使用 focus-fly 的范例网站。

网页程序里有很多需要管理和控制焦点的场景，例如弹窗、菜单、选项卡、抽屉等等。焦点往往在多个元素之间相互关联，并且要有符合预期的移动轨迹。进行业务或组件开发的时候，如果不考虑焦点的影响，处处关联的焦点可能让程序变得混乱，如果遗漏处理某些情况，反应到用户界面上，则是不符预期的意外行为。

下面的文档会使用到几个关键词，分别是入口、封面、列表和出口，引入项目之后可以运用这几个关键词，来描述“焦点如何通过入口进入列表，进入列表后如何移动焦点，以及如何让焦点通过出口退出列表”。

例如开发一个模态对话框，对话框的背景应该对所有用户隐藏，对于鼠标用户，鼠标不能访问背景元素，对于键盘用户，键盘不能访问背景元素，对于使用辅助设备的用户，辅助设备也不能访问背景元素。

focus-fly 可以控制从“打开”按钮开始、到对话框内导航、到“关闭”按钮结束，这个流程中焦点的路径，通过确定的焦点路径，避免聚焦到背景元素上。

安装

npm 安装（yarn 则使用 yarn add focus-fly 进行安装）：

npm install focus-fly

使用

focus-fly 支持 ESM 和 CJS 导入，如果希望直接通过浏览器标签导入，可以下载本项目 output/ 文件夹内的 UMD 文件进行 <script> 标签引入。

添加下面这两行代码后，焦点将会在一个列表之间陷入循环，这个列表的头元素是 #firstTabbableNode，尾元素是 #lastTabbableNode：

import fFocus from "focus-fly"; // ESM 导入方式
// const focus = require("focus-fly"); // CJS 导入方式
fFocus(["#firstTabbableNode", "#lastTabbableNode"]);

这是最简洁的调用，以这种方式调用，焦点可以通过键盘（Tab）进入列表，但是无法通过键盘退出列表，下面对调用参数稍加修改，加入元素 #entryBtn 作为入口，元素 #lastTabbableNode 作为出口，这样焦点就能够通过键盘在入口、列表和出口间流动：

fFocus(["#firstTabbableNode", "#lastTabbableNode"], {
  entry: "#entryBtn",
  exit: "#lastTabbableNode",
  onEscape: true
});

上面的代码执行后，在浏览器中将会有这样的行为：在 #entryBtn 上按下 Enter，#firstTabbableNode 成为焦点，按住 Tab，焦点在 #firstTabbableNode 和 #lastTabbableNode 之间循环，在 #lastTabbableNode 上按下 Enter，或者在列表内的任意元素上按下 Esc，#entryBtn 成为焦点。查看一个在线范例。

这是一个简单，但是是比较完整的用法，解释了入口、列表和出口对焦点的管理与控制，继续阅读，查看关于延迟注册列表事件、触发焦点移动的钩子、自定义焦点矫正目标等更多特性的详细介绍。

focusFly(list[, options])

调用函数 focusFly 时可以传递 2 个参数，list 表示焦点列表，第二个入参 options 是可选的，用于设定若干选项，例如设定入口、封面、列表和出口相关的详细配置。

focusFly(root, list[, options])

调用函数 focusFly 时可以传递 3 个参数，root 是 list 内各元素的公共祖先元素，将会被用来监听键盘（keydown）之类的事件，如果不提供 root，focus-fly 将会通过 list 找到最小公共祖先元素，第二个入参 list 表示列表，第三个 options 是可选的，用于设定若干选项。

import fFocus from "focus-fly"; // esm 方式引入
// const fFocus = require("focus-fly"); // cjs 方式引入

const dialog = document.getElementById("dialog");

// 循环焦点的根元素，对话框
fFocus(dialog, ["#head", "#tail"], { // 根元素 root 是 #dialog，根元素用来监听诸如 keydown 之类的事件，列表 list 的范围是从 #head 到 #tail，焦点如果进入列表，就会在这个范围循环
  // 入口配置
  entry: {
    // 入口的选择器字符串，例如“打开”按钮
    node: "#open",
    // 点击 #open 后的行为
    on: onEntry,
  },
  // 出口配置
  exit: {
    // 退出列表的出口元素，例如“关闭”按钮
    node: "#close",
    // 点击 #close 后的行为
    on: onExit,
  },
  // 按下 Esc 的行为
  onEscape: true,
});

/** 设置触发入口的行为 */
function onEntry() {
  dialog.classList.add("opened");
  dialog.classList.remove("closed");
}

/** 设置触发出口的行为 */
function onExit() {
  dialog.classList.add("closed");
  dialog.classList.remove("opened");
}

您也可以进入范例文件夹，通过运行范例文件夹，进行本地预览：

cd examples/cjs
npm i
npm run start

root

root，string | Element，可以是一个 Element 对象，也可以是一个 DOMString（如 #container）。

根元素 root 是列表内各元素的公共祖先元素，将被用于监听键盘（keydown）事件以及和列表有关的其它事件，默认会监听按键 Tab 来控制焦点循环聚焦，如果开启了 options.onEscape，也会监听 Esc。

如果不提供这个参数，focus-fly 会取得列表 list 内元素的最小公共祖先作为根元素 root。

list

list，(string | Element)[]，是一个数组，数组内的元素可以是 Element 对象，也可以是 DOMString。

这个参数表示列表，文档里提到的“列表”都是指这里的 list，默认情况下，数组 list 表示范围，只需要两个元素，一个可聚焦的头元素，一个可聚焦的尾元素，如果传入的数组长度大于 2，将只取头和尾。

设置 options.sequence 为 true 后，list 表示序列，是一个长度大于 2 的数组，这时按下 Tab 后，焦点将以 list 中元素的顺序进行导航。在设置 options.next 或 options.prev 后，原来的 Tab 被自定义导航键取代，同时 options.sequence 被默认设为 true。

通过入口进入列表，如果有封面，则入口进入封面，封面再进入列表。通过出口退出列表，回到入口，如果有封面，出口会退出列表，回到封面，再通过封面回到入口。

options

下面的选项，除了 trigger、entry、exit 和 cover，其它选项基本都和列表相关。下面的每一个选项都是可选的。

关于组合键的设置，上面和下面的表格中，类型 Type 为 isKey 的，有便捷的字符串的设置方式：

直接传入字符串，例如 "Control-n"，表示同时按下 Control 和 n；
也可配合数组，用于多种按键组合完成同一个任务，例如 ["Control-n", 'j', "ArrowRight", "ArrowDown"]，表示按下 Control 和 n、按下 j、按下右方向键、按下向下方向键，这四种组合的功能都是一样的。

如果需要传入函数，也可将函数传入数组中，函数和字符串能够混合使用。

为了不影响排版阅读，下面 4 个名称过长的选项被单独制成一张表格：

options.next

| Name | Type | isRequired | Default | Desc | |:--|:--|:--|:--|:--| | key | isKey | N | null | 自定义在列表前进的组合键，可传入函数和字符串，如果是函数，则返回 true 代表应用这个组合键 | | on | handleNextOrPrev | N | null | 前进时被执行，前进时的行为 |

options.prev

| Name | Type | isRequired | Default | Desc | |:--|:--|:--|:--|:--| | key | isKey | N | null | 自定义在列表后退的组合键，可传入函数和字符串，如果是函数，则返回 true 代表应用这个组合键 | | on | handleNextOrPrev | N | null | 后退时被执行，后退时的行为 |

下面的代码演示了使用 →、↓ 和 ctrl-n 完成前进焦点（字符串形式），使用 ←、↑ 和 ctrl-p 完成后退焦点（函数形式）：

import fFocus from "focus-fly";

const dialog = document.getElementById("dialog");

const isBackward = e => (
  (e.ctrlKey && e.key === "p") ||
  e.key === "ArrowTop" ||
  e.key === "ArrowLeft");

fFocus(dialog, ["#head", "#second", "#tail"], {
  entry: {
    node: "#open",
    on() {
      dialog.classList.add("openedDialog");
      dialog.classList.remove("closedDialog");
    },
  },
  exit: {
    node: "#close",
    on() {
      dialog.classList.remove("openedDialog");
      dialog.classList.add("closedDialog");
    },
  },
  next: ["Control-n", "ArrowRight", "ArrowDown"], // <----- 自定义*前进*焦点的配置项
  prev: isBackward, // <---- 自定义*后退*焦点的配置项
});

options.entry

这些选项和入口相关，描述了如何通过入口进入封面或列表。下面的选项可以在一个对象里，也可以在由这个对象组成的数组里。下面的每一个选项都是可选的。

如果已经通过入口进入列表，则在退出列表前，不能再次触发入口进入列表。通过直接点击列表，也被算作进入列表。

入口定义的方式非常自由，例如 entry: "#entryBtn"，entry: { node: "#entryBtn", type: "click" }，entry: ["#entryBtn"]，entry: ["#entryBtn", { node: "#btn2", type: "click" }]，这四种写法都是允许的。

options.exit

这些选项和出口相关，描述了焦点如何从列表回到封面或入口。

和入口类似，在下次进入列表前，不能够重复触发出口退出列表。通过点击非列表的空白区域，也被算作退出列表。

出口定义的方式和入口一样，例如 exit: "#exitBtn"，exit: { node: "#exitBtn", type: "click" }，exit: ["#exitBtn"]，entry: ["#exitBtn", { node: "#btn2", type: "click" }]，这四种写法都是允许的。

options.cover

这些选项和封面有关，每个选项都是可选且默认值为空。

如果存在封面，焦点将通过入口进入封面，焦点又通过封面进入列表，焦点通过出口退出至封面，最后焦点通过封面退出至入口。也就是说，在进入列表的阶段时，封面在入口和列表之间，在退出列表的阶段，封面在出口和入口之间。

options.cover.exit 是一个有若干选项的对象，也可以是一个包含这类对象的数组。下面是 options.cover.exit 的所有选项，每一个选项都是可选的，且默认值为空：

Return

下面是调用函数 focusFly 后返回的属性。

import fFocus from "focus-fly";

const dialog = document.getElementById("dialog");
const openBtn = document.getElementById("#open");
const closeBtn = document.getElementById("#close");

const bagel = fFocus(dialog, ["#head", "#tail"]);

openBtn.addEventListener("click", e => {
  dialog.classList.add("openedDialog");
  dialog.classList.remove("closedDialog");
  bagel.enter(); // 聚焦 #head
})

closeBtn.addEventListener("click", e => {
  dialog.classList.remove("openedDialog");
  dialog.classList.add("closedDialog");
  bagel.exit(); // 聚焦 #dialog
})

查看使用 addForward 的一个范例，这个范例中，#grid_wrapper 是一个中转节点，通过按下 Tab 和反向 Tab，焦点中转到 #more_from。

范例与项目开发

查看和运行范例：

cd examples/cjs # 进入使用 cjs 模块的范例文件夹
npm i # 安装依赖
npm run start # 本地运行

进行项目开发：

npm i
npm run start

运行之后，修改根目录的 index.js（focus-fly 主文件）和 examples/run-start 下的文件，即可在浏览器看到实时修改结果。开发后，提交时请编写相应的单元测试。

单元测试

npm i
npm run test

常见问题

focus-fly 的主要任务是管理和控制焦点，如果有钩子不能满足需求，可以考虑在业务开发中自行监听事件，处理样式的变化。

原理

查看原理。

CHANGELOG

查看更新日志。

版本规则

查看语义化版本 2.0.0。

协议

查看 MIT License。

支持和赞助

请随意 Issue、PR 和 Star，通过爱发电进行赞助。

其它

focus-fly 支持的特性：

集中管理焦点；
通过指定范围或序列循环焦点；
按需监听、移除事件；
矫正不是从入口进入列表的焦点；
提供钩子函数完成诸如样式修改的任务。

假设准备开发一个弹窗，进行焦点管理，需要有下面的流程、考虑下面几种情况：

在“打开”按钮上按下 Enter，弹窗内第一个元素获得焦点；
在弹窗的内部按住 Tab，焦点（中幻术）不能逃出弹窗；
点击弹窗的空白区域，按下反向 Tab，弹窗内的最后一个元素获得焦点；
在“关闭”按钮上按下 Enter，“打开”按钮获得焦点；
按下 Esc，或者点击弹窗背后的半透明蒙层，“打开”按钮获得焦点；
管理弹窗、半透明蒙版、“打开”按钮、“关闭”按钮的点击和键盘事件。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

focus-fly

安装

使用

focusFly(list[, options])

focusFly(root, list[, options])

root

list

options

options.next

options.prev

options.entry

options.exit

options.cover

Return

范例与项目开发

单元测试

常见问题

原理

CHANGELOG

版本规则

协议

支持和赞助

其它