# @getoutline/react-roving-tabindex 中文文档

规范地址：https://npmcn.com/package/%40getoutline/react-roving-tabindex/

版本：3\.4\.0
npm 元数据更新时间：2026-09-03T05:35:30.942Z
中文译文更新时间：2026-11-16T06:33:02.576Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40getoutline/react-roving-tabindex
原文对照：https://npmcn.com/package/%40getoutline/react-roving-tabindex/?lang=original
项目主页：https://github.com/outline/react-roving-tabindex#readme
源码仓库：https://github.com/outline/react-roving-tabindex

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：17.8 kB，3 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=10
- 运行依赖：1 个
- peer 依赖：react \>=16\.8\.0，react-dom \>=16\.8\.0
- 首次发布：2024-06-10T13:44:31.125Z
- 最新版本发布：2026-09-03T05:35:30.770Z
- 近 30 天下载量：26728（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 1 个）

## 中文简介

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

## 安装

```sh
npm install @getoutline/react-roving-tabindex
```

也可以使用：`pnpm add @getoutline/react-roving-tabindex`、`yarn add @getoutline/react-roving-tabindex`、`bun add @getoutline/react-roving-tabindex`

## README

# 反应-巡回-tabindex

> React Hooks 执行一个旋转的标签索引,现在有网格支持. 看故事书 [这里](https://stevejay.github.io/react-roving-tabindex/) 试试看.

[![bundlephobia](https://img.shields.io/bundlephobia/minzip/react-roving-tabindex)](https://bundlephobia.com/result?p=react-roving-tabindex) [![NPM](https://img.shields.io/npm/v/react-roving-tabindex.svg)](https://www.npmjs.com/package/react-roving-tabindex) [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com/) [![CircleCI](https://img.shields.io/circleci/project/github/stevejay/react-roving-tabindex/master.svg)](https://circleci.com/gh/stevejay/react-roving-tabindex/tree/master) [![Coverage Status](https://coveralls.io/repos/github/stevejay/react-roving-tabindex/badge.svg?branch=master)](https://coveralls.io/github/stevejay/react-roving-tabindex?branch=master)

## 背景情况

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

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

关于巡回制表符图案的更多信息 [这里](https://www.stefanjudis.com/today-i-learned/roving-tabindex/) 财务报告和审定财务报表 [这里](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Keyboard-navigable_JavaScript_widgets#Managing_focus_inside_groups)。 。 。 .

这种模式也可以用于网格项目,例如: [此日历示例](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/Grid_Role#Calendar_example)常规情况下,网格的内含元素应具有: `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`。 。 。 .

## 安装

```bash
npm install @getoutline/react-roving-tabindex

# or

yarn add @getoutline/react-roving-tabindex
```

此套件包括TypeScript打字.

如果您需要支持 IE, 您还需要安装多填充器 `Array.prototype.findIndex` 财务报告和审定财务报表 `Map`。如果您正在使用 IE 反应,则 [您已经需要使用 `Map` 多边填充](https://reactjs.org/docs/javascript-environment-requirements.html)如果您使用全局多填充, 如 [核心 js 数据](https://github.com/zloirock/core-js) 或者说 [宝宝-宝宝](https://babeljs.io/docs/usage/polyfill/) 然后,它应包括 `findIndex` 混合填充剂.

## 使用量

这个包有一个基本的故事手册 [这里](https://stevejay.github.io/react-roving-tabindex/),有工具栏和网格使用示例.

### 基本用途

```tsx
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` 事件然后创建处理器以引用多个处理器:

```ts
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` 用于调整库行为的道具 :

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

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

#### 方向

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

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

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

#### 环绕

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

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

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

#### 聚焦于点击

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

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

浏览器是 [行为不统一](https://zellwk.com/blog/inconsistent-button-behavior/) 当单击按钮时,您将看到浏览器之间的一些差异,默认值为 `false` 用于此选项。 请设置此选项 `true` 如果您希望这个库能像第3版之前那样表现.

### 网格使用量

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

```ts
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中这不是一个问题,因为它在服务器上从未被生成和序列化. 因此,即使需要支持安保部门改革,也可以自动生成。 所以,如果你以前用过以下的...

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

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

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

### 从0.x到1版本

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

## 许可证

麻省理工学院 [史蒂夫・杰伊](https://github.com/stevejay)

## 发展

如果您在本地创建故事本时存在错误, 您可能使用节点 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 是什么？

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

### 如何安装 @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 和提交记录判断。

