# @equinor/fusion-framework-module-navigation 中文文档

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

版本：8\.0\.0
npm 元数据更新时间：2026-11-12T09:56:01.945Z
中文译文更新时间：2026-11-13T20:17:19.274Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：403 kB，127 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：rxjs ^7\.0\.0，@remix-run/router ^1\.0\.0，@equinor/fusion-observable ^9\.2\.6，@equinor/fusion-framework-module ^6\.2\.0
- 首次发布：2022-11-17T15:22:28.476Z
- 最新版本发布：2026-11-12T09:56:01.679Z
- 近 30 天下载量：12114（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：103（近 12 个月 24 个）

## 中文简介

利用反应路由器7提供路由和导航能力的融合框架导航模块

## 安装

```sh
npm install @equinor/fusion-framework-module-navigation
```

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

## README

# @equinor/核聚变-框架-模块-导航

运行和导航模块 **融合框架** 具有可观察到的状态管理和自动基名本地化.

## 特征

-   **路径本地化** 消费者采用清洁道路(`/users`),而历史堆栈则收到完整的路径(`/apps/my-app/users`) (中文(简体) ).
-   **可观察状态** ——作为RxJS观测器暴露的导航状态(`state$`与 `shareReplay` 语义.
-   **多历史类型** ——浏览器(路径名),散列(`#/path`),和内存(没有 URL 更改).
-   **路由器兼容性** —— 说 `createRouter()` 创建 `@remix-run/router` 与框架历史连接的实例.
-   **导航屏蔽** - 拦截导航 `history.block()` 并随意重试.
-   **遥测事件( E)** ——发出 `NavigateEvent` 编号 : `NavigatedEvent` 通过遥测模块跟踪动作.

## 安全操作遥测

`INavigationProvider` 扩展共享 `TelemetryConnectable` 合同。 导航保留 现有 `Navigation::*` 而不是采用新的业务记录名称.

初始化后,导航无需等待即可连接可用的主机遥测 在启动时。 明确 `setTelemetry(provider)` 优先; `setTelemetry(undefined)` 禁用自动连接。 自动接线报告 `Navigation::navigated` 没有每个动作调试聊天.

遥测不再包括地点、以前地点、路由状态或动作 载荷。 使用静态的清晰提供器动作事件 `Navigation::action` 名称只包含受控动作类型。 更新旧动态名称的消费者 或有效载荷场。 导航商务事件和通路行为不变. 见 [操作遥测](https://npmcn.com/package/%40equinor/telemetry/docs/operational-telemetry.md)。 。 。 .

## 安装

```sh
pnpm add @equinor/fusion-framework-module-navigation
```

## 使用量

### 启用模块

```ts
import { enableNavigation } from '@equinor/fusion-framework-module-navigation';

// Minimal — basename only
enableNavigation(configurator, '/apps/my-app');

// Advanced — full configuration
enableNavigation(configurator, {
  configure: (config) => {
    config.setBasename('/apps/my-app');
    config.setHistory(createHistory('browser'));
  },
});
```

### 程序导航

```ts
const navigation = framework.modules.navigation;

navigation.push('/users');             // adds history entry
navigation.replace('/login');          // replaces current entry
navigation.push('/users', { id: 1 }); // with state

console.log(navigation.path.pathname); // '/users' — basename removed
```

### 可观测导航状态

```ts
import { filter } from 'rxjs';

navigation.state$.subscribe(({ action, location }) => {
  console.log(action, location.pathname); // 'PUSH' '/users'
});

navigation.state$.pipe(
  filter(({ action }) => action === 'POP'),
).subscribe(({ location }) => {
  console.log('Back/forward to', location.pathname);
});
```

### 创建 href / URL

```ts
// basename = '/apps/my-app'
navigation.createHref('/users');
// → '/apps/my-app/users'

navigation.createURL('/users');
// → URL { pathname: '/apps/my-app/users', ... }
```

### 路由器整合(遗产)

> **说明:** 偏爱 `@equinor/fusion-framework-react-router` 新申请.

```ts
import type { AgnosticRouteObject } from '@remix-run/router';

const routes: AgnosticRouteObject[] = [
  { path: '/', element: <Home /> },
  { path: '/users/:id', element: <UserDetail /> },
];

const router = navigation.createRouter(routes);
```

> 总是使用 `navigation.createRouter()` 改为 `createBrowserRouter()` 直接在提供者外创建路由器 .

### 历史类型

| 工厂论证 | 类 | 说明 |
| --- | --- | --- |
| `'browser'` | `BrowserHistory` | 基于路径名的路由通过历史API. **默认.** |
| `'hash'` | `BrowserHistory` (哈什堆叠) | 散裂道(`#/path`) (中文(简体) ). 不需要服务器配置 . |
| `'memory'` | `MemoryHistory` | 内相史. 理想的部件,测试,和SSSR. |

```ts
import { createHistory } from '@equinor/fusion-framework-module-navigation';

const browserHistory = createHistory('browser');
const hashHistory    = createHistory('hash');
const memoryHistory  = createHistory('memory');
```

### 导航屏蔽

```ts
const unblock = navigation.history.block((transition) => {
  if (hasUnsavedChanges) {
    showConfirmDialog(() => {
      unblock();          // remove blocker first
      transition.retry(); // then retry navigation
    });
  } else {
    unblock();
    transition.retry();
  }
});
```

## API 参考

### 职能

| 导出 | 说明 |
| --- | --- |
| `enableNavigation(configurator, opts?)` | 在配置器上注册导航模块. |
| `createHistory(type, ...args)` | 工厂 `BrowserHistory`,基于散列 `BrowserHistory`,或 `MemoryHistory`。 。 。 . |

### 类

| 导出 | 说明 |
| --- | --- |
| `NavigationProvider` | 模块提供者——管理状态,本地化和生命周期. |
| `NavigationConfigurator` | 有Zod验证的流利配置构建器. |
| `BrowserHistory` | 由浏览器支持的历史 `pushState` 编号 : `replaceState`。 。 。 . |
| `MemoryHistory` | 历史以内存为后盾. |

### 接口类型( T)

| 导出 | 说明 |
| --- | --- |
| `INavigationProvider` | 通航供应商的公开合同. |
| `INavigationConfigurator` | 配置形状( E)`basename`, (中文(简体) ), `history`, (中文(简体) ), `telemetry`, (中文(简体) ), `eventProvider`) (中文(简体) ). |
| `History` | 历史实例合同(可观察状态+导航方法). |
| `Path` | `{ pathname, search, hash }` |
| `Location` | `Path` 以 `state` 财务报告和审定财务报表 `key`。 。 。 . |
| `To` | `string | Partial<Path>` ——导航作业目标. |
| `Action` | 数字 : `Pop`, (中文(简体) ), `Push`, (中文(简体) ), `Replace`。 。 。 . |
| `NavigationUpdate` | `{ delta, action, location }` 发射者 `state$`。 。 。 . |

### 活动

| 活动 | 何时 | 可取消 |
| --- | --- | --- |
| `NavigateEvent` (单位:千美元)`onNavigate`(中文(简体) ) | 导航前 | 对 |
| `NavigatedEvent` (单位:千美元)`onNavigated`(中文(简体) ) | 导航后 | 没有 |

## 配置

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `basename` | `string` | `undefined` | URL 路径前缀从 / 准备到消费者路径 . |
| `history` | `History` | 浏览器历史( 或节点内存) | 通过 `createHistory()`。 。 。 . |
| `telemetry` | `ITelemetryProvider` | 自动解析 | 跟踪导航事件和错误. |
| `eventProvider` | `IEventModuleProvider` | 自动解析 | 调度 `onNavigate` 编号 : `onNavigated` 事件. |

## 另见

-   [`@equinor/fusion-framework-react-router`](https://github.com/equinor/fusion-framework/tree/main/packages/react/router) ——反应路由器集成
-   [导航烹饪本](https://github.com/equinor/fusion-framework/tree/main/cookbooks/app-react-router) - 带有路由的示例应用程序

## 常见问题

### @equinor/fusion-framework-module-navigation 是什么？

利用反应路由器7提供路由和导航能力的融合框架导航模块

### 如何安装 @equinor/fusion-framework-module-navigation？

在项目目录运行 npm install @equinor/fusion-framework-module-navigation，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：rxjs（^7\.0\.0）、@remix-run/router（^1\.0\.0）、@equinor/fusion-observable（^9\.2\.6）、@equinor/fusion-framework-module（^6\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @equinor/fusion-framework-module-navigation 支持 TypeScript 吗？

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

### @equinor/fusion-framework-module-navigation 支持 ESM 还是 CommonJS？

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

### @equinor/fusion-framework-module-navigation 可以商用吗？

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

### @equinor/fusion-framework-module-navigation 的下载量有多少？

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

### @equinor/fusion-framework-module-navigation 还在维护吗？

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