# @basenative/router 中文文档

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

版本：3\.0\.0
npm 元数据更新时间：2026-10-31T13:47:20.566Z
中文译文更新时间：2026-10-31T16:16:03.210Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40basenative/router
原文对照：https://npmcn.com/package/%40basenative/router/?lang=original
项目主页：https://github.com/DuganLabs/BaseNative/tree/main/packages/router#readme
源码仓库：https://github.com/DuganLabs/BaseNative

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

- 包体积（解压后）：30.1 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-03-20T05:27:53.151Z
- 最新版本发布：2026-10-31T13:47:20.266Z
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

具有命名参数、通配符和历史记录API集成的SSR感知路径路由

## 安装

```sh
npm install @basenative/router
```

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

## README

# @basenative /路由器

> 具有SSR感知路径匹配的基于信号的客户端路由器

部分 [BaseNative](https://github.com/DuganLabs/basenative) 生态系统——基于信号的web运行时，基于原生HTML。

## 安装

```bash
npm install @basenative/router
```

## 快速入门

```js
import { createRouter, interceptLinks } from '@basenative/router';

const router = createRouter([
  { path: '/', name: 'home' },
  { path: '/users/:id', name: 'user' },
  { path: '/blog/:slug*', name: 'blog' },
]);

// Read reactive current route
import { effect } from '@basenative/runtime';

effect(() => {
  const route = router.currentRoute();
  console.log(route.name, route.params, route.query);
});

// Navigate programmatically
router.navigate('/users/42');

// Intercept <a> clicks for client-side navigation
interceptLinks(router);
```

## API

### `createRouter(routes, options?)`

创建路由器实例。返回一个对象:

-   `currentRoute` -计算信号 `{ name, path, params, query, matched }`.
-   `navigate(to, options?)` -将新条目推入历史(`replace: true` 改为替换)。
-   `back()` -导航回浏览器历史记录。
-   `forward()` -在浏览器历史记录中向前导航。

#### 选项

-   `base` -应用于所有路由的路径前缀(例如： `'/app'`）。

### `resolveRoute(routes, path)`

根据路由列表解析路径，而不创建路由器实例。对SSR有用。

### `compilePattern(pattern)`

将路由模式字符串编译为匹配器对象。支持 `:param`， `:param*` (通配符) 和精确段。

### `matchRoute(compiled, path)`

针对路径测试已编译的模式。在匹配时返回一个参数对象， `null` 没有比赛。

### `parseQuery(search)` / `buildQuery(params)`

将查询字符串解析为对象，或将对象序列化为查询字符串。

### `interceptLinks(router, options?)`

附加一个 `click` 侦听器到 `document` ,拦截 `<a href>` 点击和呼叫 `router.navigate()` 而不是触发一个完整的页面加载。尊重 `target`， `download`和外部链接。

## 〇航行警卫 `@basenative/router/guards`

选择- - - - - - `createRouter()` 它返回的路由器不受影响，除非你包装它。从 `/guards` 子路径 (也从包根目录重新导出):

```js
import { createRouter } from '@basenative/router';
import { withGuards, redirect } from '@basenative/router/guards';

const router = withGuards(createRouter(routes));

router.beforeEach(({ to, from }) => {
  if (to.name === 'dashboard' && !isAuthenticated()) {
    return redirect('/login'); // or: return '/login'; or: return false;
  }
});

router.afterEach(({ to }) => {
  document.title = to.matched?.title ?? 'App';
});

const ok = await router.navigate('/dashboard'); // Promise<boolean>
```

### `withGuards(router)`

包装路由器实例 (从 `createRouter()`)，并返回 `GuardedRouter` 与相同的 `pathname` / `query` / `currentRoute` / `back()` / `forward()` / `routes`,再加上:

-   `navigate(to, options?)` -与封装的路由器相同，但返回 `Promise<boolean>`： `true` 一次导航和所有 `afterEach` 处理程序已运行， `false` 如果警卫中止或重定向。
-   `beforeEach(guard)` -注册防护，在URL更改之前，针对目标路由的预览按注册顺序运行。返回取消注册它的处置器。
-   `afterEach(handler)` -注册一个调用的处理程序 `{ to, from, options }`) 一旦导航提交。返回一个处置器。

一名警卫接到 `{ to, from, options }` （`to`/`from` 是 `ResolvedRoute`秒； `from` 是 `null` 在第一次导航时)，并可能返回：

-   `undefined` /什么都不做——让导航继续进行。
-   `false` -没有重定向的中止导航。
-   路径字符串，或 `{ redirect, replace? }` -中止并重定向到该路径。
-   扔 `redirect(to, replace?)` (或 `RedirectError` 直接)-与上述相同，可从防护装置内部深处使用。
-   抛出其他任何东西——传播并拒绝 `navigate()` 调用; 它不被视为中止。

守卫按顺序运行; 第一个中止的守卫停止链-以后的守卫不运行。开始一个新的 `navigate()` 在前一个警卫仍在运行时呼叫中止正在进行的呼叫，然后解决 `false`.

### `redirect(to, replace = true)`

抛出一个 `RedirectError` 那 `withGuards()`他的后卫跑垒手接住了球，转了个方向。从来没有回报。

### `RedirectError`

错误类 `redirect()` 抛出。有 `to: string` 和 `replace: boolean` 属性;也可以直接用扔 `throw new RedirectError(to, replace)`.

## 许可证

apache - 2.0

## 常见问题

### @basenative/router 是什么？

具有命名参数、通配符和历史记录API集成的SSR感知路径路由

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

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

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

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

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

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

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

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

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

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