# @bbc/tv-lrud-spatial 中文文档

规范地址：https://npmcn.com/package/%40bbc/tv-lrud-spatial/

版本：0\.0\.18
npm 元数据更新时间：2026-11-05T12:36:58.665Z
中文译文更新时间：2026-11-07T18:48:29.951Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40bbc/tv-lrud-spatial
原文对照：https://npmcn.com/package/%40bbc/tv-lrud-spatial/?lang=original
项目主页：https://github.com/bbc/lrud-spatial#readme
源码仓库：https://github.com/bbc/lrud-spatial

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

- 包体积（解压后）：110 kB，40 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2023-07-13T10:09:18.656Z
- 最新版本发布：2026-07-09T13:43:23.527Z
- 近 30 天下载量：29385（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 1 个）

## 中文简介

空间导航图书馆

## 安装

```sh
npm install @bbc/tv-lrud-spatial
```

也可以使用：`pnpm add @bbc/tv-lrud-spatial`、`yarn add @bbc/tv-lrud-spatial`、`bun add @bbc/tv-lrud-spatial`

## README

![LRUD spatial](https://github.com/bbc/lrud-spatial/blob/master/.github/lrud.svg?raw=true)

使用左、右、上、下键将焦点围绕 HTML 文档移动.

## API 密码

getNextFocus(_currentFocus_, _keyOrKeyCode_, _\[scope\]_)

### 参数

-   `currentFocus` 应该是一个 [`HTMLElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement) 您想要将 LRUD 空间考虑为您正在导航的元素 _从_。 。 。 . 在简单的应用中,这只能是参考 `document.activeElement`。 。 。 .
-   `keyOrKeyCode` 应该是一个 [`key`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) 字符串或 (单位:千美元) [`keyCode`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode) 代表方向键的小数按下.
-   `scope` 是可选的 `HTMLElement` 您只想要寻找内部的焦点候选人。 如果不提供则默认为整页.

### 回返

一个 `HTMLElement` lRUD空间认为你应该 导航 _改为_。 。 。 .

## 可聚焦

LRUD空间将可聚焦元素定义为与其中任何元素相匹配的元素 以下 CSS 选择器 :

-   `[tabindex]` (关于分页索引 qq 0)
-   `a`
-   `button`
-   `input`

### 忽略焦点

任何潜在的候选人 `lrud-ignore` 类别,或者在父母中的任何 `lrud-ignore` 分类, 将不被视为可聚焦, 将被跳过 。 默认情况下, LRUD 将不会忽略有 `opacity: 0` 或有一个父母 `opacity: 0`,因此这一类可以用于此.

可聚焦于 `tabindex="-1"` 属性将被跳过, 但是在任何父目录中可聚焦 `tabindex="-1"` 将仍然被视为可聚焦.

潜在候选人 `disabled` 或者说 `aria-disabled="true"` 属性将不被视为可聚焦.

### 可焦点重叠

默认情况下,LRUD将对所有向前进方向的候选者进行测量. 它还会包括与当前焦点相重叠可达30%的候选人,例如允许一个"右"运动包含一些高于当前焦点的东西,但有一半的大小扩展为右.

该门槛值可按每个要素调整,其中: `data-lrud-overlap-threshold` 属性,作为从 0.0 到 1.0 的浮点。 0.0的重叠将使候选人只有在找到时才得到考虑 _完全没有_ 在移动的方向.

也请注意,LRUD不考虑Z轴线,这种轴线可以造成令人惊讶的结果,其内容以这种方式重叠,包括对现有UI的全屏幕覆盖。 以上属性可以帮助缓解这一问题.

## 集装箱

焦能用容器包裹. 容器可以追踪最后的 使用 `data-focus` 属性.

> 应当被跟踪的可聚焦器必须具有独特的ID属性.

当容器没有先前的焦点状态时,它的第一个可焦点元素是 改为使用.

此时,容器被定义为匹配 CSS 选择器 : `nav`, (中文(简体) ), `section` 或者说 `.lrud-container`。 。 。 .

### 块出入口

在某些情况下,最好防止lrud-spaceal选择另一种 "最佳人选",以列表底部为例. 要做到这一点,一个容器元素 应添加一个额外的 `data-block-exit` 属性以防止在 那个方向 此列表应为空格分隔列表 .

举个例子.

```html
<div class="lrud-container" data-block-exit="up down">...</div>
```

### 可重点集装箱

默认情况下,LRUD只测量可聚焦物的距离,而不考虑其容器的边界位置. 添加属性 `data-lrud-consider-container-distance` 将它和它的子孙纳入距离计算中.

如果容器是所有可能的可聚焦器中最接近的,则LRUD将返回其一个儿童----即使他们不一定是空间最接近可聚焦器.

以上集装箱焦点逻辑仍将被使用,如果有一个焦点,则移动到一个可聚焦的集装箱中去,在集装箱内的任何深度都移动到最后一个焦点儿童.

## 怎么会这样?

确定下一个重点要素;

1.  使用密钥代码获取移动方向
2.  从当前聚焦的 DOM 元素获取边缘坐标 对应您正在移动的方向
3.  对于所有其他可聚焦元素,请获取相向边缘的坐标 (你进入的边缘)
4.  查找最短的出入口坐标之间的线条 长度

## 发展中国家

要求:节点.js 18

要开始,就跑 `npm ci`。 。 。 .

### 大楼

`npm run build` 将发出一个转录和精密的图书馆版本. 这是在中央情报局期间进行的,目的是准备向国家预防机制公布的文物。 也可能是这样 与另一个本地项目合并 `npm link`。 。 。 .

### 测试

这个 `test/layouts` 目录包含 HTML , 设计用于反射各种 现实世界使用案例,并允许对图书馆进行行为定性 诸如容器和网格等特性.

重要的新特征应具有相应的布局,对其进行检验.

使用 `npm test` 进行测试.

#### 调试

测试使用 [木偶师](https://github.com/puppeteer/puppeteer) 转起来 无头浏览器. 浏览器加载上述布局并运行 来自 [rud.test.js (英语)](https://npmcn.com/package/%40bbc/tv-lrud-spatial/test/lrud.test.js) 反对无名氏 代码从 `lib/`。 。 。 .

调查为什么测试失败 或者只是黑客 一些变化... 运行 `npm run server`。然后转到 [http://localhost:305 (英语)](http://localhost:3005/) 财务报告和审定财务报表 选择一个布局.

## 联系人

[电视开放来源@bbc.co.uk](mailto:TVOpenSource@bbc.co.uk) - 我们的目标是一周内回复电子邮件.

## 常见问题

### @bbc/tv-lrud-spatial 是什么？

空间导航图书馆

### 如何安装 @bbc/tv-lrud-spatial？

在项目目录运行 npm install @bbc/tv-lrud-spatial，或使用 pnpm add / yarn add / bun add。

### @bbc/tv-lrud-spatial 支持 TypeScript 吗？

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

### @bbc/tv-lrud-spatial 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @bbc/tv-lrud-spatial 可以商用吗？

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

### @bbc/tv-lrud-spatial 的下载量有多少？

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

### @bbc/tv-lrud-spatial 还在维护吗？

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