# @expressive/router 中文文档

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

版本：0\.10\.4
npm 元数据更新时间：2026-11-11T06:48:16.134Z
中文译文更新时间：2026-11-14T16:13:18.429Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：145 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- peer 依赖：@expressive/mvc ^0\.94\.3
- 首次发布：2026-06-12T21:29:03.189Z
- 最新版本发布：2026-11-11T06:48:15.629Z
- 近 30 天下载量：1988（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

主机-不可知路由器基于Expressive MVC组件而建.

## 安装

```sh
npm install @expressive/router
```

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

## README

# @ 表达/ 路由器

基于Expressive MVC的分类声明路由器.

[![NPM](https://badge.fury.io/js/%40expressive%2Frouter.svg)](https://www.npmjs.com/package/@expressive/router)

* * *

一个主机不可知路由器 [表达式 MVC](https://github.com/gabeklein/expressive)路线被宣布为嵌入式JSX,匹配从树上按逻辑计算(不是单独的配置),导航状态生活在被动状态下 `Router` 任何组件都可以读取或驱动.

```bash
npm install @expressive/router @expressive/react react
```

## 宣布路线

路由巢以映射 URL . `to` 是图案段, `as` 是页面(或版式)组件。 一个布局通过 `children`。 。 。 .

```tsx
import '@expressive/react'; // registers the host adapter
import { BrowserRouter, Route } from '@expressive/router';

<BrowserRouter>
  <Route as={RootLayout}>
    <Route as={HomePage} /> {/* index - matches the parent path */}
    <Route to="blog" as={BlogLayout}>
      <Route as={BlogIndex} /> {/* /blog */}
      <Route to=":slug" as={BlogPost} /> {/* /blog/:slug */}
    </Route>
    <Route to="login" redirect="/" /> {/* matched -> redirects */}
    <Route none as={NotFound} /> {/* no sibling matched */}
  </Route>
</BrowserRouter>;
```

| Prop | 含义 |
| --- | --- |
| `to` | URL区段. `:name` 抓取了一个参数, `*` 是一个包罗万象。 输入索引路径 . |
| `as` | 匹配时提供组件( 作为布局, 接收) `children`) (中文(简体) ). |
| `none` | 匹配时没有兄弟姐妹 - 标注在父(root = app 404,巢= 第404节). |
| `redirect` | 匹配时, 将重定向到这里而不是渲染 . |
| `label` 编号 : `meta` | 显示 nav 和 badcrumbs 的名称/ 自由格式元数据( 通过匹配来标记) . |

参加同一档次仲裁的兄弟姐妹 **以声明顺序进行首对**没有祖先 `Router`页:1 `<Route>` 旋转出一个无头的记忆; `BrowserRouter` 绑在地址栏上.

## 读取匹配

页面读取最近的 `Route` 从上下文 `get()` 并使用其活性获取器:

```tsx
import { Route } from '@expressive/router';

const BlogPost = () => {
  const { match } = Route.get(); // nearest Route in context; subscribes
  return <article>post: {match!.slug}</article>;
};
```

读取 `matched` (boolean) 使同样的导航`/blog/a` → `/blog/b`) 调和到位,而不是重挂.

## 导航状态、查询和碎片

`Router` 暴露位置为被动 `path`, (中文(简体) ), `query`, (中文(简体) ), `hash`,并生成 `url` 表面 。 通过导航和历史 查询和分解状态.

```tsx
router.goto('/posts?page=2#comments'); // push
router.goto('/posts', true); // replace
router.url = '/posts?page=2#comments'; // assigning url navigates

router.query.get('page'); // read - subscribes to just this param
router.query.set('page', '2'); // write - pushes a new entry, like goto
router.query.delete('sort'); // delete - also navigates

router.hash; // '' or a leading-# string
router.hash = '#comments'; // pushes through the same settlement path

router.back(); // one entry back
router.go(-2); // move by an arbitrary history delta
```

地图是单值的(`string` 键和值; 重复的 URL 键崩溃 到最后一个值。 由 URL 驱动的更改调和同一地图。 散列 是一个不透明、%编码的字符串。 碎片导航不滚动或 自动聚焦元素.

`go(delta)` 将有限的分数三角形切换为整数级. 零号, 非无穷无尽,离地三角洲无所事事;它从未使用 `go(0)` 作为 重新装入信号.

## 暂停和航行结算

路线是悬疑边界. 过 `fallback` 用来装入冷气 并使用懒惰 页面通常:

```tsx
const Post = lazy(() => import('./Post'));

<Route to="posts/:id" fallback={<Spinner />} as={Post} />;
```

应用中导航通过受保护 `Router.navigate(work)`,其默认值 使用主机过渡调度器。 如果下一页或入口守卫暂停, 当前屏幕仍然可见,直到下一个屏幕准备好。 冷货还剩 调制 `fallback`。 。 。 .

`router.navigating` 以列报方式仍属真实。 在旁边或周围读 路由内容; 重叠的导航是最新赢的, 因此已取代 以后不能更改页面、历史或状态。 对于应用驱动的浏览器 导航,地址在屏幕结算后写出. 浏览器 后/前和外的历史 API 调用必须先更改它.

覆盖 `navigate(work)` 用于舞台演示的路由器子类 不一样 状态和命令将接合包起来, 因此重置只需运行 解决 `work`。 。 。 .

## 链接

`Link` 制作一个 `<a>` 导航内部目标 在正左键. 修改器/中键, 非`_self` 目标、下载和有计划或 协议相对目标仍然是浏览器拥有的。 它暴露了自己的匹配状态, 因此活动样式不需要单独的组件 :

```tsx
import { Link } from '@expressive/router';

<Link to="blog">Blog</Link>
<Link to="/posts?page=2" replace>Page 2</Link>
<Link to="https://example.com/docs">External docs</Link>
```

```tsx
// active links by subclassing - read `active` / `match`
class NavLink extends Link {
  render() {
    return (
      <a
        href={this.href}
        onClick={this.go}
        className={this.active ? 'active' : undefined}
        aria-current={this.active ? 'page' : undefined}>
        {this.props.children}
      </a>
    );
  }
}
```

## 重定向

`Redirect` 导航到 `to` 当挂起, 门打开 `when` (默认) `true`),而无所成. 这个 `Route` `redirect` 道具是它总替代的快手.

```tsx
import { Redirect } from '@expressive/router';

<Redirect to="/login" when={!user} />     {/* navigates on mount when `when` is true */}
<Redirect to="/home" replace />           {/* overwrite the current entry */}
```

`Route.redirect` 也接受同步或同步入门后卫. 无空 以替换方式重定向字符串,一个 falsy 值允许路径,以及 `null` 将路径切入最接近的范围 `none` 路线 :

```tsx
<Route
  to="admin"
  fallback={<Spinner />}
  redirect={async () => (session.authorize() ? undefined : '/login')}
  as={Admin}
/>
```

路由器协调导航,而不是应用数据. 继续取来, 路由/ 页面控制中的突变、 缓存和请求取消; async 字段通过路由边界暂停.

## 生成导航

`NavLinks` 使路径等级的导航树 - 它走已声明的路径并自动发送链接 。 它的渲染由 PascalCase 构建 **子组件** 以覆盖来塑造输出 :

| 成员 | 渲染器 |
| --- | --- |
| `Item` | 单一链接( 默认为 `Link` 使用路线 `label`) (中文(简体) ). |
| `List` | 容器包裹一层物品. |
| `Group` | 嵌入区块; 默认透明 - 将路由嵌入区块转换为主区块 . |

```tsx
import { NavLinks } from '@expressive/router';

class SideNav extends NavLinks {
  List = (props) => <ul className="side">{props.children}</ul>;
  Group = (props) => (
    <section>
      <h3>{props.route.label}</h3>
      {props.children}
    </section>
  );
}
```

这些成员是可支配的反应性子组成部分,与现场事件相连——同一个机制 `Component` 提供,通过 [子组件](https://github.com/gabeklein/expressive/blob/main/packages/react/README.md#subcomponents)。 。 。 .

## 运行时边界

-   `Router` 保持记忆历史 用它做测试 非浏览器主机.
-   `BrowserRouter` 绑定浏览器地址和历史 API.
-   服务器渲染不会在请求之间共享全局路由器,而是 软件包不是SSR路由/数据/水分系统.
-   本地反应可以使用 `Router`· ; `BrowserRouter`, (中文(简体) ), `Link`,以及 `NavLinks` 为: 浏览器/DOM-facing.

支持的位置模型是路径名,单值查询参数,以及 一个不透明的碎片。 底名挂起, 任意历史状态, 自动 滚动至锁定、滚动恢复、导航阻塞和数据路由API 目前尚未建置.

* * *

路线很平坦 `@expressive/mvc` 组件,所以它们在任何可表达的主机适配器下产生.

完整指南和实例 **[表示式.dev/docs/指针/路由器](https://expressive.dev/docs/guides/router)**

## 许可证

麻省理工学院

## 常见问题

### @expressive/router 是什么？

主机-不可知路由器基于Expressive MVC组件而建\.

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

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

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

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

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

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

### @expressive/router 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

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

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

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

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

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

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