@getoutline/react-roving-tabindex

中文文档
3.4.0发布于 2026/09/03MITTypeScriptESM + CJS近 30 天下载 2.7万

响应运行的标签索引, 现在得到网格支持

中文使用文档
文档目录16 节
  1. 背景情况
  2. 执行方面的考虑
  3. 不使用此软件包时
  4. 所需资源
  5. 安装
  6. 使用量
  7. 基本用途
  8. 选项
  9. 网格使用量
  10. 升级
  11. 从第2版到第3版
  12. 从第1版到第2版
  13. 从0.x到1版本
  14. 许可证
  15. 发展
  16. 出版

反应-巡回-tabindex

React Hooks 执行一个旋转的标签索引,现在有网格支持. 看故事书 这里 试试看.

bundlephobia NPM JavaScript Style Guide CircleCI Coverage Status

背景情况

漫游的标签索引是一组组合输入的可访问模式. 它帮助正在使用键盘浏览您网站的人。 一组中的所有输入都被当作一个能加速键盘导航的单制表站处理. 该组最后的重点投入也被记住. 它在用户标签返回组时再次接收焦点.

当组合中,ArrowLeft和ArrowRight键会在输入之间移动焦点. (您也可以配置此库, 这样ArrowUp 和ArrowDown 键就可以移动焦点 。) Home和End键(Fn+Left Arrow和Fn+RightArrow on macOS)将焦点分别移动到组的第一个和最后一个输入.

关于巡回制表符图案的更多信息 这里 财务报告和审定财务报表 这里。 。 。 .

这种模式也可以用于网格项目,例如: 此日历示例常规情况下,网格的内含元素应具有: grid 函数,每个网格项都应获得 gridcell 角色。 。 。 ArrowLeft和ArrowRight键用于将焦点移到一行输入之间,而ArrowUp和ArrowDown键则将焦点移到一行之间. Home和End键(Fn+LeftArrow和Fn+RightArrow on macOS)分别将焦点移动到一行的第一个和最后一个输入. 如果控制键在按下 Home 和 End 键时被持有,那么焦点将分别移动到电网中的第一个和最后一个输入上.

执行方面的考虑

有两个主要的建筑选择:

  • 是否应支持动态启用和不启用集团中的投入.
  • 如何确定某一组中的投入,包括是否需要作为该组集装箱的直接儿童.

此软件包选择支持动态启用和不启用 。 它还允许输入在子组件和包装元素内作必要的嵌入. 它使用React Control在管理组组件和嵌入输入之间进行交流.

此软件包不支持将一个旋转的标签索引组嵌入到另一个目录中 。 我认为这会使键盘导航过于复杂.

不使用此软件包时

此套件被设计为工具栏或小网格中旋转的标签索引的一般解决方案. 如果您需要在一个非常大的网格或表格(几百个单元格或以上)中显示一个旋转的标签索引,那么您就有可能得到更好的执行。 如果一揽子方案不包含任何不必要的灵活性,那么,你就应该建立更能发挥作用的执行。 例如,您可能不需要支持制表符的启用和不启用。 与软件包一起注册单元格也需要时间,为创建一网格的行索引映射也有一个间接费用.

所需资源

这个软件包是使用 React Hooks API 编写的,因此它只能与 React 版本16.8 从此使用. 它的同级依赖关系如下: react 财务报告和审定财务报表 react-dom。 。 。 .

安装

npm install @getoutline/react-roving-tabindex

# or

yarn add @getoutline/react-roving-tabindex

此套件包括TypeScript打字.

如果您需要支持 IE, 您还需要安装多填充器 Array.prototype.findIndex 财务报告和审定财务报表 Map。如果您正在使用 IE 反应,则 您已经需要使用 Map 多边填充如果您使用全局多填充, 如 核心 js 数据 或者说 宝宝-宝宝 然后,它应包括 findIndex 混合填充剂.

使用量

这个包有一个基本的故事手册 这里,有工具栏和网格使用示例.

基本用途

import { ReactNode, useRef } from "react";
import {
  RovingTabIndexProvider,
  useRovingTabIndex,
  useFocusEffect
} from "@getoutline/react-roving-tabindex";

type Props = {
  disabled?: boolean;
  children: ReactNode;
};

const ToolbarButton = ({ disabled = false, children }: Props) => {
  // The ref of the input to be controlled.
  const ref = useRef<HTMLButtonElement>(null);

  // onKeyDown and onClick are stable for the lifetime of the component:
  const { tabIndex, focused, onKeyDown, onClick, onFocus } = useRovingTabIndex(
    ref, // Don't change the value of this ref.
    disabled // But change this as you like throughout the lifetime of the component.
  );

  // Use some mechanism to set focus on the button if it gets focus.
  // In this case I use the included useFocusEffect hook:
  useFocusEffect(focused, ref);

  return (
    <button
      ref={ref}
      tabIndex={tabIndex} // tabIndex must be applied here
      disabled={disabled}
      onKeyDown={onKeyDown} // handler applied here
      onClick={onClick} // handler applied here
      onFocus={onFocus} // handler applied here
    >
      {children}
    </button>
  );
};

const SomeComponent = () => (
  // Wrap each roving tabindex group in a RovingTabIndexProvider.
  <RovingTabIndexProvider items={/* data for list items */}>
    {/*
      it's fine for the roving tabindex components to be nested
      in other DOM elements or React components.
    */}
    <ToolbarButton>First Button</ToolbarButton>
    <ToolbarButton>Second Button</ToolbarButton>
  </RovingTabIndexProvider>
);

如果你需要包含你自己的处理方式 onClick 和(或) onKeyDown 事件然后创建处理器以引用多个处理器:

return (
  <button
    ref={ref}
    tabIndex={tabIndex}
    disabled={disabled}
    onKeyDown={(event) => {
      onKeyDown(event); // handler from the hook
      someKeyDownHandler(event); // your handler
    }}
    onClick={(event) => {
      onClick(event); // handler from the hook
      someClickHandler(event); // your handler
    }}
  >
    {children}
  </button>
);

选项

这个 RovingTabIndexProvider 组件包括可选 options 用于调整库行为的道具 :

const SomeComponent = () => (
  <RovingTabIndexProvider
    options={{ direction: "vertical" }}
    items={/* data for list items */}
  >
    {/* whatever */}
  </RovingTabIndexProvider>
);

目前有三种选择: direction, (中文(简体) ), focusOnClick,以及 loopAround。请注意,创建一个新的 options 对象在每次渲染上 - 只有当实际选项值发生变化时, 而不是包含的选项值才会更新库的内部状态 options 对象.

方向

默认情况下,是ArrowLeft 和 ArrowRight 键分别用于移动到上项和下项. 这个 RovingTabIndexProvider 有可选的 direction 财产 options 允许您更改此选项的道具 :

const SomeComponent = () => (
  <RovingTabIndexProvider
    options={{ direction: "vertical" }}
    items={/* data for list items */}
  >
    {/* whatever */}
  </RovingTabIndexProvider>
);

通过设置方向来选择默认行为 horizontal如果方向设定为 vertical 然后是用于移动到上个和下个项目的“箭头向上”和“箭头向下”键。 如果方向设定为 both 然后,ArrowLeft和ArrowUp两个键都可用于向上项移动,而ArrowRight和ArrowDown两个键都可用于向下项移动。 你可以更新 direction 随时值.

环绕

默认情况下,如果您试图通过旋转标签索引的起始或结束来制取标签,那么来来来去去的标签就不会包起。 这个 RovingTabIndexProvider 有可选的 loopAround 财产 options 允许您更改此选项的道具 :

const SomeComponent = () => (
  <RovingTabIndexProvider
    options={{ loopAround: true }}
    items={/* data for list items */}
  >
    {/* whatever */}
  </RovingTabIndexProvider>
);

如果设置为 true 如果你到达 旋转的标签项的开始或结束, 而不是停止。 请注意, 如果正在用网格使用旋转标签索引, 此选项不适用 .

聚焦于点击

默认情况下,点击正在运行的标签索引项目将不会导致 focus() 在该项目上被援引 useFocusEffect) (中文(简体) ). 只有在您使用键盘移动到某个项目时 focus() 它被引用。 这个 RovingTabIndexProvider 有可选的 focusOnClick 财产 options 允许您更改此选项的道具 :

const SomeComponent = () => (
  <RovingTabIndexProvider
    options={{ focusOnClick: true }}
    items={/* data for list items */}
  >
    {/* whatever */}
  </RovingTabIndexProvider>
);

浏览器是 行为不统一 当单击按钮时,您将看到浏览器之间的一些差异,默认值为 false 用于此选项。 请设置此选项 true 如果您希望这个库能像第3版之前那样表现.

网格使用量

此软件包支持在网格中旋转的标签索引 。 用于每种用途 useRovingTabIndex 钩子在网格,你 必须 将一行索引值作为第三个参数传递到钩子:

const { tabIndex, focused, onKeyDown, onClick, onFocus } = useRovingTabIndex(
  ref,
  disabled,
  someRowIndexValue
);

行索引值必须是钩子所使用的网格项目的零基行索引. 因此,代表第一行网格项目的所有项目都应具备 0 传到钩子上,第二行 1,等等。 (笑声) 如果网格的形状可以动态地变化,那么更新行索引值是好的. 例如,网格最初可能每行有四个项目,但更新后每行有三个项目.

这个 direction 财产的财产 RovingTabIndexProvider 在提供行索引时被忽略。 这是因为"箭头向上"和"箭头向下"键总是用于行间移动.

升级

从第2版到第3版

请参看changeGELOG.md文件,以获取从第2版升级到第3版的指令.

从第1版到第2版

版本2有几处突破性修改.

这个包不再包括一个小马填充器 Array.prototype.findIndex 现在也使用 Map 课。 如果您需要支持 IE , 您需要为两者安装多填充 。 尽管如此,如果你现在支持IE,那么你几乎肯定已经在使用一个合适的全球多填充。 请参见本文件前面的安装部分,以了解进一步的指导.

作为第三个参数的可选 ID 参数 useRovingTabIndex 钩已替换为新可选行索引参数 。 包含ID参数是为了支持服务器侧渲染(SSR),但实际上并不需要. 默认情况下, 这个库会自动生成一个 ID 。 在SSR中这不是一个问题,因为它在服务器上从未被生成和序列化. 因此,即使需要支持安保部门改革,也可以自动生成。 所以,如果你以前用过以下的...

const {...} = useRovingTabIndex(ref, true, id);
//                                         ^^

...然后你就可以删除第三个论点:

const {...} = useRovingTabIndex(ref, true);

从0.x到1版本

第1版发布时与v. 9.0相比没有中断更改. 版本起伏是因为套件已经稳定了.

许可证

麻省理工学院 史蒂夫・杰伊

发展

如果您在本地创建故事本时存在错误, 您可能使用节点 v13 。 请使用Node v14+或Node v12.

出版

  • npm run build
  • 对于β版本,添加或凸起 a -rcX 后缀为 package.json 版本编号并运行 npm publish --tag next。 。 。 .
  • 对于释放,删除 -rcX package.json版本编号的后缀,然后运行 npm publish。 。 。 .

版本与发布记录

@getoutline/react-roving-tabindex 共发布 6 个版本,首次发布于 2024/06/10;过去 12 个月发布了 1 个版本。

版本发布日期距今
3.4.0latest2026/09/032 个月前
3.2.42024/06/212 年前
3.2.32024/06/212 年前
3.2.22024/06/132 年前
3.2.12024/06/102 年前
3.2.02024/06/102 年前

关于 @getoutline/react-roving-tabindex 的常见问题

@getoutline/react-roving-tabindex 是什么?

响应运行的标签索引, 现在得到网格支持

如何安装 @getoutline/react-roving-tabindex?

在项目目录运行 npm install @getoutline/react-roving-tabindex,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(>=16.8.0)、react-dom(>=16.8.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@getoutline/react-roving-tabindex 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@getoutline/react-roving-tabindex 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@getoutline/react-roving-tabindex 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=10。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@getoutline/react-roving-tabindex 可以商用吗?

@getoutline/react-roving-tabindex 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@getoutline/react-roving-tabindex 的下载量有多少?

根据 npm 官方下载统计,@getoutline/react-roving-tabindex 在 2026/10/17 – 2026/11/15 这 30 天内被下载 26,728 次,日均约 891 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@getoutline/react-roving-tabindex 还在维护吗?

最新版本 3.4.0 发布于 2026/09/03(2 个月前);至今共发布 6 个版本,其中过去 12 个月发布了 1 个;首次发布于 2024/06/10。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。