# @equinor/fusion-observable 中文文档

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

版本：9\.2\.6
npm 元数据更新时间：2026-11-12T09:53:56.804Z
中文译文更新时间：2026-11-13T20:09:53.605Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：303 kB，121 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，@types/react ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2022-04-11T07:48:08.129Z
- 最新版本发布：2026-11-12T09:53:56.496Z
- 近 30 天下载量：14860（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：121（近 12 个月 23 个）

## 中文简介

妇女

## 安装

```sh
npm install @equinor/fusion-observable
```

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

## README

# @equinor/聚变-可观测

反应状态管理公用设施基于RxJS和Immer for Fusion Framework应用程序. 提供由动作驱动、可观察的国家容器(`FlowSubject`),动作创建器,还原器构建器,RxJS操作器,以及用于订阅可观测状态的回放钩.

## 特征

-   **流程对象** ——一个可观测到的状态容器,通过一个还原器处理动作,类似于Redux,但与RxJS完全反应.
-   **创建缩小器** 利用Immer动力发作的变异和建筑型式的API(`addCase`, (中文(简体) ), `addMatcher`, (中文(简体) ), `addDefaultCase`) (中文(简体) ).
-   **创建动作/ 创建同步动作** ——具有可选有效载荷准备的型号安全动作制造厂,包括主动请求/成功/失败模式.
-   **创建状态** - 装有电线的便利工厂 `FlowSubject`,动作定义,和发送函数在一个呼叫.
-   **RxJS 运算符** —— 说 `filterAction`, (中文(简体) ), `mapAction`, (中文(简体) ), `switchMapAction`, (中文(简体) ), `mapProp` 简洁的动作流转换.
-   **反应钩** —— 说 `useObservable`, (中文(简体) ), `useObservableState`, (中文(简体) ), `useObservableSelector`, (中文(简体) ), `useObservableEffect`, (中文(简体) ), `useObservableFlow`, (中文(简体) ), `useDebounce`还有更多.
-   **工具函数** —— 说 `isObservableInput` 财务报告和审定财务报表 `toObservable` 用于将多种输入类型规范化为RxJS可观测.

## 安装

```sh
pnpm add @equinor/fusion-observable
```

## 使用量

### 创建状态容器

```ts
import { createAction, createReducer, FlowSubject } from '@equinor/fusion-observable';

// Define actions
const increment = createAction<number>('increment');
const decrement = createAction<number>('decrement');

// Build a reducer with Immer support
const reducer = createReducer({ count: 0 }, (builder) =>
  builder
    .addCase(increment, (state, action) => { state.count += action.payload; })
    .addCase(decrement, (state, action) => { state.count -= action.payload; }),
);

// Create the observable state container
const counter = new FlowSubject(reducer);
counter.subscribe((state) => console.log('Count:', state.count));
counter.next(increment(1)); // Count: 1
counter.next(increment(5)); // Count: 6
```

### 使用 `createState` 快速设置

```ts
import { createState, createAction } from '@equinor/fusion-observable';

const actions = {
  setName: createAction<string>('setName'),
};

const { subject, dispatch } = createState(actions, {
  initial: { name: '' },
  builder: (builder, actions) => {
    builder.addCase(actions.setName, (state, action) => {
      state.name = action.payload;
    });
  },
});

dispatch.setName('Alice');
console.log(subject.value); // { name: 'Alice' }
```

### 同步动作

```ts
import { createAsyncAction, isSuccessAction, isFailureAction } from '@equinor/fusion-observable';

const fetchUser = createAsyncAction(
  'fetchUser',
  (id: string) => ({ payload: { id } }),
  (user: User) => ({ payload: user }),
  (error: Error) => ({ payload: error }),
);

// fetchUser('123')           → { type: 'fetchUser::request', payload: { id: '123' } }
// fetchUser.success(user)    → { type: 'fetchUser::success', payload: user }
// fetchUser.failure(error)   → { type: 'fetchUser::failure', payload: error }
```

### 使输入与 `toObservable`

```ts
import { toObservable } from '@equinor/fusion-observable';

// Works with values, promises, functions, iterables, and observables
toObservable(42).subscribe(console.log);                        // 42
toObservable(Promise.resolve('hello')).subscribe(console.log);  // 'hello'
toObservable(() => 'computed').subscribe(console.log);           // 'computed'
```

### 反应钩

```tsx
import { useObservable, useObservableState } from '@equinor/fusion-observable/react';

function Counter() {
  const subject = useObservable(reducer, { count: 0 });
  const { value } = useObservableState(subject);

  return (
    <div>
      <p>Count: {value.count}</p>
      <button onClick={() => subject.next(increment(1))}>+1</button>
    </div>
  );
}
```

### RxJS 运算符

```ts
import { filterAction, mapAction, switchMapAction } from '@equinor/fusion-observable/operators';

// Filter to specific actions
action$.pipe(filterAction('increment')).subscribe(handleIncrement);

// Filter + map in one step
action$.pipe(mapAction('fetchSuccess', (a) => a.payload.data)).subscribe(setData);

// Filter + switchMap for async flows
action$.pipe(switchMapAction('search', (a) => fetchResults(a.payload))).subscribe(setResults);
```

## API 参考

### 核心项目`@equinor/fusion-observable`(中文(简体) )

| 导出 | 说明 |
| --- | --- |
| `FlowSubject<S, A>` | 通过动作和减压器驱动的可观察状态容器 |
| `createReducer(initial, builder)` | 构建带有构建器模式的 Immer 功率压缩器 |
| `createAction<P>(type)` | 创建类型安全动作创建者 |
| `createAsyncAction(type, request, success, failure?)` | 创建请求/ 成功/ 失败动作创建者 |
| `createState(actions, reducer)` | 电线 `FlowSubject` + 动作 + 在一个电话中发送 |
| `actionMapper(actions, subject)` | 捆绑动作创建者到一个主题作为调度功能 |
| `ActionError` | 将动作与因果错误联系起来的错误类 |
| `ActionReducerMapBuilder` | 用于定义大小写的构建器接口 |
| `enableMapSet()` | 启用对起草的 Immer 支持 `Map` 财务报告和审定财务报表 `Set` 数值 |
| `isObservableInput(input)` | RxJS 的护卫类型 `ObservableInput` 数值 |
| `toObservable(input, ...args)` | 将值/功能/承诺转换为 `Observable` |

### 运算符( O)`@equinor/fusion-observable/operators`(中文(简体) )

| 导出 | 说明 |
| --- | --- |
| `filterAction(...types)` | 按类型过滤动作流 |
| `mapAction(type, fn)` | 按类型过滤并映射结果 |
| `switchMapAction(type, fn)` | 按类型过滤并切换到内在可观察 |
| `mapProp(path)` | 通过点路径字符串提取嵌入属性 |

### 反应钩子( R)`@equinor/fusion-observable/react`(中文(简体) )

| 导出 | 说明 |
| --- | --- |
| `useObservable(reducer, initial?)` | 创建纪念 `FlowSubject` |
| `useObservableState(subject, options?)` | 跟踪可观测值/误差/完成 |
| `useObservableSelector(subject, selector)` | 给一个观察到的孩子带来 `distinctUntilChanged` |
| `useObservableEffect(subject, effect)` | 附加副作用于 a `FlowSubject` |
| `useObservableFlow(subject, flow)` | 将史诗风格的流接入 `FlowSubject` |
| `useObservableSubscription(obs, observer)` | 管理可观察到的订阅生命周期 |
| `useObservableRef(subject)` | 与可观测排放保持对接同步 |
| `useObservableInput(input)` | 转换 `ObservableInput` 改为 `Observable` |
| `useObservableInputState(input)` | 组合 `useObservableInput` + 键 `useObservableState` |
| `useDebounce(fn, options)` | 跳出一个函数并曝光结果为可观察到 |

### 行动( E)`@equinor/fusion-observable/actions`(中文(简体) )

再出口行动类型, `ActionError`,以及只需要动作层的消费者的动作创造工具.

## 常见问题

### @equinor/fusion-observable 是什么？

妇女

### 如何安装 @equinor/fusion-observable？

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

### @equinor/fusion-observable 支持 TypeScript 吗？

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

### @equinor/fusion-observable 支持 ESM 还是 CommonJS？

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

### @equinor/fusion-observable 可以商用吗？

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

### @equinor/fusion-observable 的下载量有多少？

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

### @equinor/fusion-observable 还在维护吗？

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