# @barefootjs/router 中文文档

规范地址：https://npmcn.com/package/%40barefootjs/router/

版本：0\.40\.2
npm 元数据更新时间：2026-11-02T02:54:59.356Z
中文译文更新时间：2026-11-07T17:23:20.255Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：127 kB，30 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@barefootjs/client \>=0\.14\.0
- 首次发布：2026-06-19T13:33:04.119Z
- 最新版本发布：2026-11-02T02:54:58.963Z
- 近 30 天下载量：3719（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：84（近 12 个月 84 个）

## 中文简介

后端-不可知部分导航用户端路由器为BarefootJS——只互换页面区域并重新给其中的岛屿取水

## 安装

```sh
npm install @barefootjs/router
```

也可以使用：`pnpm add @barefootjs/router`、`yarn add @barefootjs/router`、`bun add @barefootjs/router`

## README

# @barefootjs/路由器

后端-不可知,为BarefootJS逐步增强客户端路由器. 这个 拦截同源导航,获取 **普通全页 HTML** 任意 后端已经返回( 没有协议头, 没有 JSON 端点), 仅交换 页 次 **区域**并处理/再水合物 仅仅是其中的岛屿。 壳 保留挂载; 区域外的一切都保持其DOM, 滚动和状态.

```ts
import { startRouter } from '@barefootjs/router'

startRouter() // install once on the client
```

在您的布局中标记可互换区域 `<Region>` (编为: `[bf-region]`,参见 `spec/router.md`);路由器互换了第一个匹配.

## 公共 API

-   `startRouter(options?): Router` - 安装一次; 回返 `{ stop, navigate, prefetch }`。 。 。 .
-   `navigate(href, { history? }): Promise<void>` ——方案导航.
-   `BF_REGION` - 货物再出口 `bf-region` 标记服务器侧助手.

### 选项

| 选项 | 默认 | 目的 |
| --- | --- | --- |
| `region` | `[bf-region]` | 交换点的选择器 |
| `rehydrate` 编号 : `dispose` | 运行时间倒转链 | 超过岛屿生命周期 |
| `loadModule` | `import(src)` | 岛屿模块如何加载 |
| `shouldIntercept` | 同源, 直接点击 | 每个锁定者选择退出(`data-bf-router="false"`, (中文(简体) ), `download`, (中文(简体) ), `target`, (中文(简体) ), `rel=external`(中文(简体) ) |
| `prefetch` 编号 : `prefetchDelay` | `true` 编号 : `65` | 盘旋/ 聚焦/ 指针倒置 + `modulepreload` |
| `cacheFreshMs` 编号 : `cacheStaleMs` 编号 : `cacheCap` | `15000` 编号 : `60000` 编号 : `30` | SWR + LRU 缓存 |
| `scrollToTop` | `true` | 互换后立即向上滚动( ignores) `scroll-behavior: smooth`(中文(简体) ) |
| `manageFocus` | `true` | 将焦点移入互换内容( 首个互换区域, 标题) + 宣布路径 |
| `morph` | `true` | 保护 `[data-bf-permanent]` 横跨互换的活节点(无时不开放); `false` 强制平原 `replaceChildren` |

## 默认更正

客户端运行时间是 **选项对等点**:完全静止的外壳 0 的路由器 `@barefootjs/client`当岛屿存在时, `dispose` 财务报告和审定财务报表 `rehydrate` 在同一倒转链中降解 (单位:千美元)`window.__bf_*` 缝合 □ `@barefootjs/client/runtime`是因为 `disposeScope`编号 :`rehydrateScope`永远不要沉默不语 没有选择权 设置步骤.

## 行为

-   **最后赢** 跨越相重叠的导航(较新的导航中止了老年人).
-   **SWR 缓存** 存储承诺(预选 + 点击共享一个请求); 年龄 条目立即服务并在背景中刷新; 失败不会被缓存 .
-   **模块意识**:一个响应的新岛屿模块被导入 _在此之前_ 页:1 再加水再行走,然后在航行中除尘.
-   **重定向意识**:历史承诺在响应的最终URL上.
-   **页面主播保留浏览器**: 同页 `#hash` 链接不是 被拦截的,还有 `popstate` 浏览器为它起火(和用于 反向/前向这些条目之间)无任何交换——页面已经 显示, 因此保留岛国和滚动位置 .
-   **历史、国家保存**: 路由器取代合并而不是分解 已存在状态(螺旋-恢复 libs,框架状态).
-   **A11y (英语)**:焦点移动到互换的内容中——第一个互换的区域 在标题上有一个标题——新标题以礼貌方式宣布 生活区。 因此,兄弟地区可以维持其自然文件秩序 (通航先于内容) 无焦点登陆通航.
-   **主元数据**:标题、说明、, `og:`编号 :`twitter:`{\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}犬科医生和朋友 与接入的页面对齐; 头 _资源_ (见下文).
-   **持久性** (单位:千美元)`data-bf-permanent`: 标记的元素 `<div data-bf-permanent="player">` 保留它 _现场直播_ 交换的节点 状态、媒体回放、卷轴和水合瞄准镜存活下来——相匹配 按属性值(或 `id`) (中文(简体) ). 在未标出元素时禁用; 通过 `morph: false` 做一个简单的交换.
-   **在飞行中交换** (单位:千美元)`data-bf-navigating`: 设置 `<html>` 有效期 a 区域交换。 新加价是互换 _在此之前_ 再给它浇水,所以 "在DOM中存在"和"互动"是两个瞬间——直到这个澄清,a 互换入岛可能仍然是服务器标记,没有处理器,点击 它不见了。 用于加载指示器的样式, 或等待其缺失 在驱动新内容之前. `NAVIGATING_ATTR` 被导出, 因此调用者不需要 硬码字符串。 查询唯能导航无所取换而未设.

## `<head>`:元数据调和,资源没有

一个地区是一个 **机构** 树,所以 `<head>` 不交换批发。 它会分裂 分两分,就整个合同.

### 页面元数据——在每次互换时调节,始终

页面元数据被定义为页面范围,所以路由器带来一个已关闭的 根据收到的文档列出允许列表。 总是这样 无法禁用它: stale `<meta name="description">` 你错了 _无法看见_ 正在开发( 不同于标签标题), 而此软件包不 离开这班的选入.

| 头节点 | 键 |
| --- | --- |
| `<title>` | —— 说 |
| `<meta name="description | keywords | robots | author | theme-color">` | `name` |
| `<meta property="og:*">` 编号 : `<meta name="twitter:*">` | `name` 或者说 `property` |
| `<link rel="canonical | alternate | prev | next">` | `rel` + 键 `hreflang`编号 :`type`编号 :`media` |

两个文档中的一键被替换(当节点已经相等时跳出, 因此,跨路共享的元数据不会导致 DOM churn; 仅在 输入的页面被添加; 仅在活页中的密钥是 **删除**,所以它无法 漏入以后的每一个路线.

任何没有钥匙在桌子上的东西 都不会被读取、替换或删除 运行时间注入分析标记, CSP `<meta http-equiv>`, (中文(简体) ), `<link rel=preconnect>` 朋友通过建筑是安全的。 (这是故意与 Turbo,它移除了所有未跟踪的头部元素. ) 打开一个节点 `data-bf-head="false"` 当页本身拥有它.

### 头资源——未动用

`<link rel="stylesheet">`, (中文(简体) ), `<script>`,以及 `<style>` 内 `<head>` 独自一人 两个方向。 不是疏忽, 资源寿命不能来自 文档。 贝壳,一个 `[data-bf-permanent]` 节点、门户或 超过这个区域的岛屿 仍然可能取决于下一页的页 不列出,所以"下游出没"不是"不再需要"的证据.

这说明 **路由范围样式表 `<head>`** 一个真正的陷阱: 导航 _输入_ 路由使其无法样式化( 重新装入“ 修补” , 而 将调查指向缓存或建筑物而不是导航) 导航 _关闭_ 保留工作表的链接, 因此它的规则适用于每个路径 后结.

放进去 **内部** 以互换方式进出的区域:

```tsx
<Region>
  {isEditor ? <link rel="stylesheet" href="/editor.css" /> : null}
  {children}
</Region>
```

`rel="stylesheet"` 每个 HTML 是正文, 所以这是有效的, 这是正确的 根据区域交换合同安排,而不是绕行。 得到两个订单 对 _建筑业_ (工作表是随其样式和内容而插入的) 用它去除,在航道上没有等待负载。 工作表为 真正的全球停留在 `<head>`永远不要碰他们 这正是你 想要吗.

## 范围

A 类 **单一作者区域** (范围最广) `[bf-region]` 匹配),通过 默认. `searchParams()` (仅限航行而不进行互换) `@barefootjs/client` (v0.5); 路由器通过 `__bf_pushSearch` 连接,所以一旦有消费者在场,只使用查询导航短路. `data-bf-permanent` 持久性为 v1. 编译器 **筑巢** 区域 (最深分互换,兄弟会主-详细)为v2.

## 常见问题

### @barefootjs/router 是什么？

后端-不可知部分导航用户端路由器为BarefootJS——只互换页面区域并重新给其中的岛屿取水

### 如何安装 @barefootjs/router？

在项目目录运行 npm install @barefootjs/router，或使用 pnpm add / yarn add / bun add。

### @barefootjs/router 支持 TypeScript 吗？

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

### @barefootjs/router 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @barefootjs/router 可以商用吗？

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

### @barefootjs/router 的下载量有多少？

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

### @barefootjs/router 还在维护吗？

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

