# @blockly/keyboard-navigation 中文文档

规范地址：https://npmcn.com/package/%40blockly/keyboard-navigation/

版本：3\.0\.5
npm 元数据更新时间：2026-08-05T20:56:20.081Z
中文译文更新时间：2026-11-08T07:23:22.928Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40blockly/keyboard-navigation
原文对照：https://npmcn.com/package/%40blockly/keyboard-navigation/?lang=original
项目主页：https://github.com/RaspberryPiFoundation/blockly-keyboard-experimentation#readme
源码仓库：https://github.com/RaspberryPiFoundation/blockly-keyboard-experimentation

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

- 包体积（解压后）：623 kB，96 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：blockly ^12\.3\.0
- 首次发布：2021-03-26T01:26:38.029Z
- 最新版本发布：2026-04-07T16:27:29.286Z
- 近 30 天下载量：11769（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：103（近 12 个月 1 个）

## 中文简介

键盘导航插件 .

## 安装

```sh
npm install @blockly/keyboard-navigation
```

也可以使用：`pnpm add @blockly/keyboard-navigation`、`yarn add @blockly/keyboard-navigation`、`bun add @blockly/keyboard-navigation`

## README

# @ blockly/ 键盘导航

Blockly 的这个插件允许键盘导航 。 它包括 可能对视力障碍和运动有帮助的不同行为 受伤的人在Blockly的工作空间航行.

键盘导航和屏幕阅读器支持紧密结合. 布莱克利 团队打算在2025年Q3中逐步增加屏幕阅读器支持, 我们验证了导航的一般方法.

有关规划和时间表的更多信息,请参见我们 [无障碍网站](https://developers.google.com/blockly/accessibility)。 。 。 .

## 最终用户指示

您可以探索当前插件在 [测试页面](https://raspberrypifoundation.github.io/blockly-keyboard-experimentation/)。 。 。 .

要使用键盘导航, 请点击工作空间或按下标签直到您 到达工作空间.

一旦浏览器聚焦于 Blockly 工作空间, 您可以使用箭头键到 移动 a **光标** 在工作空间周围 您可以使用键盘快捷键 在光标上采取行动.

例如,您可以将光标移动到 下拉字段并按下 `Enter` 键来编辑字段.

可用的动作取决于光标位置 。 例如,如果 光标在一块块上,您可以复制它 `Ctrl + C`。 。 。 .

您可以按下打开工具箱 `T` 或按键 `Tab` 直到工具箱打开 重点突出。 就像工作空间一样,你可以使用箭头键来移动 工具箱并选择一个块。 按键 `Enter` 将块放在 光标在工作空间的位置 .

如果你不知道有什么动作,你 可按键 `/` 以查看行动列表.

### 提供反馈

如果您使用测试页找到一个错误, 请打开一个问题让我们知道 放在这个仓库里! 包含如何复制错误的信息, 什么 坏的行为, 和你期望它做什么。 Blockly队会的 区分错误并添加到行进图中.

## 在您的应用程序中使用

### 安装

使用此插件至少需要使用 Blockly v12.2.0. 你可以找到那个 当前 Blockly 的最低版本 `peerDependencies` 页:1 `package.json` 用于插件的文件.

#### 雅伦

```
yarn add @blockly/keyboard-navigation
```

#### 无

```
npm install @blockly/keyboard-navigation --save
```

### 使用量

```js
import * as Blockly from 'blockly';
import {KeyboardNavigation} from '@blockly/keyboard-navigation';

// Register styles. Only do this once per page-load.
// Must be done before calling Blockly.inject.
KeyboardNavigation.registerKeyboardNavigationStyles();

// Register the default toolbox. Only do this once per page-load.
// Must be done before calling Blockly.inject.
// See instructions below if you don't use the default toolbox.
KeyboardNavigation.registerNavigationDeferringToolbox();

// Inject Blockly.
const workspace = Blockly.inject('blocklyDiv', {
  toolbox: toolboxCategories,
});
// Initialize plugin.
const keyboardNav = new KeyboardNavigation(workspace);
```

### 在页面上添加快捷键

要看到键盘在用户按出 / 时帮助弹出, 您需要在主机页面中添加一个带有 Blockly diiv 元素并带有 id "shortcuts" 的空 div 元素. 插件将注意布局和格式化.

```html
...
<div id="shortcuts"></div>
...
<div id="blockly"></div>
...
```

### 使用自定义工具箱

如果你提供自己的子类 `Toolbox`,您需要覆盖 `onKeyDown_` 方法使它成为一个不开放。 基础类有自己的键盘导航内置,需要禁用.

```js
class YourCustomToolbox extends Blockly.Toolbox {
  protected override onKeyDown_(e: KeyboardEvent) {
    // No-op, prevent keyboard handling by superclass in order to defer to
    // global keyboard navigation.
  }
}
```

### 使用跨标签复制插件

此插件增加了用于复制和粘贴的上下文菜单项 。 它还增加了反馈,将复制和粘贴作为土司,在成功复制或剪接时向用户显示. 它与 `@blockly/plugin-cross-tab-copy-paste` 通过以下步骤:

```js
import * as Blockly from 'blockly';
import {KeyboardNavigation} from '@blockly/keyboard-navigation';
import {CrossTabCopyPaste} from '@blockly/plugin-cross-tab-copy-paste';

// Register styles. Only do this once per page-load.
// Must be done before calling Blockly.inject.
KeyboardNavigation.registerKeyboardNavigationStyles();

// Inject Blockly.
const workspace = Blockly.inject('blocklyDiv', {
  toolbox: toolboxCategories,
});

// Initialize cross-tab-copy-paste
// Must be done before keyboard-navigation
const crossTabOptions = {
  // Don't use the context menu options from the ctcp plugin,
  // because the keyboard-navigation plugin provides its own.
  contextMenu: false,
  shortcut: true,
};
const plugin = new CrossTabCopyPaste();
plugin.init(crossTabOptions, () => {
  console.log('Use this error callback to handle TypeError while pasting');
});

// Initialize keyboard-navigation.
// You must pass the `allowCrossWorkspacePaste` option in order for paste
// to appear correctly enabled/disabled in the context menu.
const keyboardNav = new KeyboardNavigation(workspace, {
  allowCrossWorkspacePaste: true,
});
```

## 捐款

为了了解更多对该项目的贡献,请参见: [贡献页](https://github.com/google/blockly-keyboard-experimentation/blob/main/CONTRIBUTING.md)。 。 。 .

## 常见问题

### @blockly/keyboard-navigation 是什么？

键盘导航插件 \.

### 如何安装 @blockly/keyboard-navigation？

在项目目录运行 npm install @blockly/keyboard-navigation，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：blockly（^12\.3\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @blockly/keyboard-navigation 支持 TypeScript 吗？

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

### @blockly/keyboard-navigation 支持 ESM 还是 CommonJS？

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

### @blockly/keyboard-navigation 可以商用吗？

@blockly/keyboard-navigation 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @blockly/keyboard-navigation 的下载量有多少？

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

### @blockly/keyboard-navigation 还在维护吗？

最新版本 3\.0\.5 发布于 2026/04/08（7 个月前）；至今共发布 103 个版本，其中过去 12 个月发布了 1 个；首次发布于 2021/03/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。