# @equinor/fusion-framework-react-router 中文文档

规范地址：https://npmcn.com/package/%40equinor/fusion-framework-react-router/

版本：2\.4\.8
npm 元数据更新时间：2026-11-12T09:57:15.785Z
中文译文更新时间：2026-11-13T20:37:08.920Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40equinor/fusion-framework-react-router
原文对照：https://npmcn.com/package/%40equinor/fusion-framework-react-router/?lang=original
源码仓库：https://github.com/equinor/fusion-framework

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

- 包体积（解压后）：364 kB，70 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，@types/react ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2025-12-04T12:14:37.127Z
- 最新版本发布：2026-11-12T09:57:15.349Z
- 近 30 天下载量：6672（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 30 个）

## 中文简介

DSL API 用于定义具有类型安全的回放路由器 v7 路由

## 安装

```sh
npm install @equinor/fusion-framework-react-router
```

也可以使用：`pnpm add @equinor/fusion-framework-react-router`、`yarn add @equinor/fusion-framework-react-router`、`bun add @equinor/fusion-framework-react-router`

## README

# @equinor/核聚变-框架-反应-路由器

Pointed React Router v7 为Fusion Framework应用程序集成. 这个软件包不是将导航历史、底名和上下文用手来连接,而是为您做,将所有东西都显示为输入 `fusion` 每个加载器、动作和组件中的对象.

包裹运送三样东西 一起工作:

-   **`Router` 组件** - 替换人员 `RouterProvider`阅读 `history` 财务报告和审定财务报表 `basename` 从Fusion导航模块和注入 `fusion.modules` 财务报告和审定财务报表 `fusion.context` 进入每一个路线.
-   **文件路由 DSL** —— 说 `layout`, (中文(简体) ), `index`, (中文(简体) ), `route`,以及 `prefix` 帮助构建 `RouteObject` 来自文件路径而不是原始对象的树。 Vite插件在构建时将它们转化为懒惰的数据路由.
-   **路由计划生成** —— 说 `toRouteSchema` 转换 `handle.route` 元数据变成一个固定的、机器可读的列表。 用于门户导航树和应用程序文档.

## 特征

-   **Fusion导航集成** - 读取 `history` 财务报告和审定财务报表 `basename` 自动从 Fusion 导航模块.
-   **类型 `fusion` 各地的背景** - 装载器、动作、组件和出错元素收到 `fusion.modules` 财务报告和审定财务报表 `fusion.context` 没有线性道具或反应上下文.
-   **文件样式路由 DSL** —— 说 `layout`, (中文(简体) ), `index`, (中文(简体) ), `route`, (中文(简体) ), `prefix` 帮助替换手建 `RouteObject` 树.
-   **路由计划生成** —— 说 `handle.route` 元数据可以变成一个平坦的、机器可读的表单、出入口和文件计划.
-   **模块增强** - 延长 `RouterContext` 财务报告和审定财务报表 `RouterHandle` 键入您的上下文并处理字段.
-   **Vite 插件** ——静态地将DSL调用转换为构建时最优化的React Router数据路由.

## 安装

```bash
pnpm add @equinor/fusion-framework-react-router
```

**先决条件**

-   反应 18 + (`react` 需要同伴依赖)
-   `react-dom` 18+ (可选的对等依赖, 浏览器渲染所需的)

所有其他融合框架软件包`@equinor/fusion-framework-module-navigation`, (中文(简体) ), `@equinor/fusion-framework-react-module`)是捆绑的依赖——它们自动安装.

> \[大 安装 `@equinor/fusion-framework-module-navigation` 这还不够。 一定也一样 **在您的应用程序配置器中启用** 通过 `enableNavigation(configurator, ...)`。 。 。 . `Router` 读取 `history` 财务报告和审定财务报表 `basename` 在运行时从模块中跳出,如果模块不在场,则会扔出. 见 [正在获取指南](https://npmcn.com/package/%40equinor/fusion-framework-react-router/docs/getting-started.md) 为完整的配置设置.

## 快开始

> \[注\] 以下示例跳过 Fusion app配置器设置 。 见 [正在获取指南](https://npmcn.com/package/%40equinor/fusion-framework-react-router/docs/getting-started.md) 完全设置指令.

### 1\. 定义页面模块

一个页面模块是一个普通的TypeScript或TSX文件,在路由匹配时反应路由器会懒散地加载. 导出默认组件以渲染页面 。 Vite 插件扫描每个文件以获取额外的命名导出,并将它们自动接入——你不需要在任何地方注册.

兹确认下列出口品:

| 导出 | 说明 |
| --- | --- |
| `default` | **要求.** 页面组件 . |
| `clientLoader` | 路线装载器——在制成前呼叫、接收 `fusion` 上下文. |
| `action` | 路由动作——处理格式提交和变异. |
| `handle` | 路由处理元数据,可通过 `useMatches()`。 。 。 . |
| `ErrorElement` | 当路由抛出时, 边界组件出错 . |
| `HydrateFallback` | 水合时显示 `clientLoader` 决定. |
| `shouldRevalidate` | 控制路由在导航或动作后重新运行其装载器。 返回时 `false` 以压制再验证. |

> \[注\] 任何其它命名导出都被插件默默忽略. 您可以在同一文件中共建公用设施、钩子和帮助者,而不产生副作用.

```tsx
// src/pages/ProductPage.tsx
import type {
  LoaderFunctionArgs,
  RouteComponentProps,
  RouterHandle,
} from '@equinor/fusion-framework-react-router';

export const handle = {
  route: {
    description: 'Product page',
    params: { id: 'Product identifier' },
  },
} satisfies RouterHandle;

export async function clientLoader({ params, fusion }: LoaderFunctionArgs<{ id: string | undefined }>) {
  const client = fusion.modules.http.createHttpClient('products');
  return client.json(`/products/${params.id}`);
}

export default function ProductPage({ loaderData }: RouteComponentProps<{ name: string }>) {
  return <h1>{loaderData.name}</h1>;
}
```

### 2\. 建立路线树

路由 DSL 允许您描述 `RouteObject` 树使用文件路径,而不是从前面导入每个组件. `layout` 将儿童包装在一个共享组件(头、导航、外壳)中, `index` 声明默认的孩子路径, `route` 将路径段映射到文件,以及 `prefix` 在没有布局组件的共同路段下分组路线.

> \[TIP\] 文件路径已解决 **相对于调用它们的文件**,而不是项目根. `'./ProductPage.tsx'` 内 `src/pages/index.ts` 决定: `src/pages/ProductPage.tsx`。 。 。 .

> \[叹息\] 使用 `prefix` 当您只需要将路由分组到 URL 段时。 使用 `layout` 只有当这些路线也有一个包装组件时。 包装在一个 `layout` 没有真实的布局文件会添加不必要的渲染边界.

```ts
// src/pages/index.ts
import { layout, index, route, prefix } from '@equinor/fusion-framework-react-router/routes';

export const pages = layout('./MainLayout.tsx', [
  index('./HomePage.tsx'),
  prefix('products', [
    index('./ProductsPage.tsx'),
    route(':id', './ProductPage.tsx'),
  ]),
]);
```

### 3\. 上路由器

`Router` 是一个薄薄的包装 周围反应路由器 `RouterProvider`它写着: `history` 财务报告和审定财务报表 `basename` 从 Fusion 导航模块中选择,所以您不需要手动配置它们。 从第二步传出路由树为 `routes`。 。 。 .

```tsx
// src/Router.tsx
import { Router } from '@equinor/fusion-framework-react-router';
import { pages } from './pages';

export default function AppRouter() {
  return <Router routes={pages} />;
}
```

### 通过自定义上下文

这个 `fusion` 装入器、动作和组件中可用的对象 `fusion.modules`。如果您还需要通过应用程序级别依赖性 — 一个查询客户端, 一个 API 实例, 环境配置 — 将它们添加到 `fusion.context` 使用类型脚本模块增强和 `context` 打开道具 `Router`。 。 。 .

宣布额外财产日期: `RouterContext` 在一个 `.d.ts` 文件 :

> \[TIP\] 将增量放入 `.d.ts` 文件(例如:. `router-context.d.ts`TypeScript 通过您的 `tsconfig.json` `include` 盖布, **没有** 在一个普通的 `.ts` 从软件包中导入的文件。 放在一个 `.ts` 文件可以创建循环类型依赖.

```ts
// router-context.d.ts
declare module '@equinor/fusion-framework-react-router' {
  interface RouterContext {
    queryClient: import('@tanstack/react-query').QueryClient;
  }
}
```

```tsx
import { Router } from '@equinor/fusion-framework-react-router';
import { QueryClient } from '@tanstack/react-query';
import { pages } from './pages';

const queryClient = new QueryClient();
export default function AppRouter() {
  return <Router routes={pages} context={{ queryClient }} />;
}
```

装入器和组件然后访问 `fusion.context.queryClient` 和完全类型的安全.

### 生成路径计划

`toRouteSchema` 沿路由树走并转换每个 `handle.route` 对象为路由描述符的平面列表。 产出是一个机器可以读取的列表,门户网站和文档工具可以消耗——例如用于给一个导航侧边栏填充,或者在门户网站注册处注册应用路由.

```ts
import { toRouteSchema } from '@equinor/fusion-framework-react-router/schema';
import { pages } from './pages';

const schema = await toRouteSchema(pages);
```

### Vite 插件

在使用文件路由DSL时需要Vite插件. Fusion Framework CLI 应用程序可以自动启用. 如果您配置了维特, 请安装 `@equinor/fusion-framework-vite-plugin-react-router` 作为开发依赖,并在您的 Vite 配置中添加插件.

> \[尖叫声\] 没有Vite插件, **文件路由 DSL 无效**。DSL 对象(`layout`, (中文(简体) ), `route`, (中文(简体) ), `index`)只携带一个 `file` 路径字符串——没有 `Component`, (中文(简体) ), `loader`,或 `action` 接通电话 Vite 插件在构建时执行此转换 。 没有它,路线就会变成空白页。 代码分享是一种额外的好处,而不是主要的好处.

```ts
// vite.config.ts
import { reactRouterPlugin } from '@equinor/fusion-framework-vite-plugin-react-router';

export default defineConfig({
  plugins: [react(), reactRouterPlugin()],
});
```

遗产 `@equinor/fusion-framework-react-router/vite-plugin` 入境点仍可作为兼容性再出口.

## 入境点

| 入境点 | 目的 |
| --- | --- |
| `@equinor/fusion-framework-react-router` | 主要的—— `Router`、钩子、上下文帮助器、类型和反应路由器再导出 |
| `/routes` | 路由 DSL - `layout`, (中文(简体) ), `index`, (中文(简体) ), `route`, (中文(简体) ), `prefix` |
| `/schema` | 司马相代—— `toRouteSchema` |
| `/context` | 直接上下文进口——相同 `routerContext`, (中文(简体) ), `FusionRouterContextProvider`, (中文(简体) ), `useRouterContext` 作为主; 需要导入而不拉入时使用 `Router` (如测试、定制供应商) |
| `/vite-plugin` | 兼容性再出口 `@equinor/fusion-framework-vite-plugin-react-router` |
| `/interop` | 中途移民队的中间再出口——见 [文件/临时文件](https://npmcn.com/package/%40equinor/fusion-framework-react-router/docs/interop.md) |

## 文档

-   [移徙指南——从 `react-router` 转换到离子路由器](https://npmcn.com/package/%40equinor/fusion-framework-react-router/docs/migration.md)
-   [中间入口](https://npmcn.com/package/%40equinor/fusion-framework-react-router/docs/interop.md)
-   [端到端烹饪本](https://npmcn.com/cookbooks/app-react-router/)

## 常见问题

### @equinor/fusion-framework-react-router 是什么？

DSL API 用于定义具有类型安全的回放路由器 v7 路由

### 如何安装 @equinor/fusion-framework-react-router？

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

### @equinor/fusion-framework-react-router 支持 TypeScript 吗？

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

### @equinor/fusion-framework-react-router 支持 ESM 还是 CommonJS？

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

### @equinor/fusion-framework-react-router 可以商用吗？

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

### @equinor/fusion-framework-react-router 的下载量有多少？

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

### @equinor/fusion-framework-react-router 还在维护吗？

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