# @embra/reactivity 中文文档

规范地址：https://npmcn.com/package/%40embra/reactivity/

版本：0\.0\.8
npm 元数据更新时间：2026-04-08T11:56:03.687Z
中文译文更新时间：2026-11-13T15:09:43.235Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：348 kB，51 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@types/react \>=18\.0\.0，react \>=18\.0\.0
- 首次发布：2025-08-01T18:58:38.810Z
- 最新版本发布：2026-04-08T11:56:03.364Z
- 近 30 天下载量：12290（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 2 个）

## 中文简介

一种轻量级,可堆肥和明显的反应系统.

## 安装

```sh
npm install @embra/reactivity
```

也可以使用：`pnpm add @embra/reactivity`、`yarn add @embra/reactivity`、`bun add @embra/reactivity`

## README

# [@embra/反应](https://github.com/embrajs/reactivity)

![](https://raw.githubusercontent.com/embrajs/reactivity/main/assets/embra.svg)

[![Docs](https://img.shields.io/badge/Docs-read-%23fdf9f5)](https://embrajs.github.io/reactivity) [![Build Status](https://github.com/embrajs/reactivity/actions/workflows/build.yml/badge.svg)](https://github.com/embrajs/reactivity/actions/workflows/build.yml) [![npm-version](https://img.shields.io/npm/v/@embra/reactivity.svg)](https://www.npmjs.com/package/@embra/reactivity) [![Coverage Status](https://embrajs.github.io/reactivity/coverage-badges/@embra/reactivity.svg)](https://embrajs.github.io/reactivity/coverage/)

一种轻量级,可堆肥和明显的反应系统.

## 特征

### 完全反应 没有代理,没有魔法.

它不将数值转换为 `Object.defineProperty` 也没有 `Proxy`. 将一切保持为平版JavaScript值使得与其他库一起工作更加容易,并方便JavaScript引擎优化.

```ts
import { writable, readable, type Readable } from "@embra/reactivity";

const count$ = writable(0);
count$.set(1);

const [count2$, setCount] = readable(0);
setCount(1);
```

### 明确的反应。 没有隐藏的依赖,没有惊喜.

与基于信号的库不同, `@embra/reactivity` 不自动跟踪依赖关系。 您明确定义了观看的内容以及如何对变化作出反应。 这一点比较容易说明依赖性,也减少了复杂隐含依赖性计算的成本.

使用类似回放钩子的API,计算可以是更能与一般非回放函数相兼容的纯函数.

```ts
import { writable, derive } from "@embra/reactivity";

const count$ = writable(0);

const isPositive = (value: number): boolean => value > 0;

const positiveCount$ = derive(count$, isPositive);
```

可使用 `get` 内 `compute` 或者说 `watch`。 。 。 .

```ts
import { writable, compute, watch } from "@embra/reactivity";

const count$ = writable(0);
const doubleCount$ = compute(get => get(count$) * 2);

watch(get => {
  const count = get(count$);
  console.log(`Count is ${count}, double is ${get(doubleCount$)}`);
});
```

### QQ零成本所有制模式. 类型安全生命周期管理.

实际上,我们在反应库中遇到的最大问题之一是反应值的生命周期管理. 单位 `@embra/reactivity`,反应依赖性被弱地引用,所以一般不需要手动处理. 然而,明确的生命周期管理仍然是避免出乎意料的行为的良好做法.

`@embra/reactivity` 提供零成本所有权模式,允许您创建具有明确所有权的被动值.

默认情况下,创建的活性值与类型 `OwnedReadable` 或者说 `OwnedWritable`,它暴露一个 `dispose()` 清除用户的方法。 当将被动值传递到其他模块时,您可以使用 `Readable` 或者说 `Writable` 类型来隐藏 `dispose()` 方法,确保不意外地处理该值.

```ts
import { writable, readable, type Readable, type OwnedWritable } from "@embra/reactivity";

const count$: OwnedWritable<number> = writable(0);
count$.set(1);

// Hide the setter by typing
function logCount(count$: Readable<number>) {
  count$.subscribe(console.log);

  // @ts-expect-error
  count$.set(2);
}
logCount(count$);

// Hide the setter in runtime
const [count2$, setCount] = readable(0);
setCount(1);

// @ts-expect-error
count2$.set(2);
```

### 国家与行动的灵活抽象.

在"Flux reductioner"模式的年代,我们经常使用单商店来持有状态和动作来改变状态. 这对关于该州的推理是不错的,但也引入了许多锅炉板代码.

后来,引入了状态和动作粘合在一起的模式,比如 `redux-actions`。 。 。 . `@embra/reactivity` 通过简单而灵活地抽象国家与行动,进一步推进这一步.

在下面的例子中,我们创建了Writable `count$` 这看起来像一个 `Writable<number>`,但内部来源于更大的应用状态 `appState$`。这使其他模块依赖于 `Writable<number>` 并不知道申请状态的细节.

```ts
import { writable, derive, toWritable } from "@embra/reactivity";
import { trace } from "@embra/reactivity/debug";

const appState$ = writable({
  count: 0,
  user: null,
});

const count$ = toWritable(
  derive(appState$, state => state.count),
  count => appState$.set({ ...appState$.value, count }),
);

// when debugging, you can trace the reactive value
trace(count$);
```

### QQ 控制更新的调度机制 .

`@embra/reactivity` 包括调度器机制和内置调度器,允许您在被动更新处理时进行控制. 这对批量更新和推迟计算很有用.

```ts
import { writable, MicrotaskScheduler } from "@embra/reactivity";

const rapidChangeCount$ = writable(0);

rapidChangeCount$.reaction(console.log, MicrotaskScheduler);

count$.set(1);
count$.set(2);

await Promise.resolve();
// Logs "2" once after a microtask tick, reducing unnecessary computations.
```

您也可以轻松提供您自定义的调度器功能 .

```ts
import { writable, asyncScheduler } from "@embra/reactivity";

const MicrotaskScheduler = asyncScheduler(flush => Promise.resolve().then(flush));
const AnimationFrameScheduler = asyncScheduler(requestAnimationFrame);
```

### 框架不可知论。 头等支持回放.

`@embra/reactivity` 被设计为框架不可知论。 它可用于支持JavaScript的任何框架或库. 它还为React提供一等支持.

-   作为组件道具的活性值只是简单而高效.
    -   `value` =: `Readable`
    -   `value` + 键 `onChange` =: `Writable`
    -   `state` + 键 `action` =: `toWritable(derive(rootState$, selector), action)` (见 [国家与行动](https://npmcn.com/package/%40embra/reactivity/#readme--flexible-abstractions-of-state-and-actions)(中文(简体) )
-   在道具下传回反应值时,可以避免出很多回放. 您只需要订阅组件中实际使用的活性值 .

```tsx
import { writable } from "@embra/reactivity";
import { useValue, useDerived, useCombined } from "@embra/reactivity/react";

const count$ = writable(0);

function Counter({ count$ }) {
  const count = useValue(count$);
  const countDouble = useDerived(count$, count => count * 2);
  return (
    <div>
      <button onClick={() => count$.set(count - 1)}>-</button>
      <span>{count}</span>
      <button onClick={() => count$.set(count + 1)}>+</button>
      <span>{countDouble}</span>
    </div>
  );
}
```

### 小捆绑大小。 注重表现和简洁.

![export size](https://embrajs.github.io/reactivity/assets/export-size.svg)

## 安装

```bash
npm add @embra/reactivity
```

## 调试

### 追踪

`@embra/reactivity` 页:1 `trace()` 函数帮助调试反应值和手表。 它跟踪价值和依赖性的变化,并将其记录到控制台.

```js
import { writable, watch } from "@embra/reactivity";
import { trace } from "@embra/reactivity/debug";

const count$ = writable(0);

// trace a reactive value
trace(count$);

// trace a watch function
watch(trace(get => get(count$)));

count$.set(1);
```

### Chrome Devtools 自定义格式

`@embra/reactivity` 支持 Chrome DevTools 软件 [自定义格式化](https://www.mattzeunert.com/2016/02/19/custom-chrome-devtools-object-formatters.html)。您可以通过检查 DevTools 常规设置中的“ Console” 部分中的“ 可启用自定义格式化器” 选项来启用它.

它默认在开发中启用。 您也可以通过呼叫手动启用 `customFormatter()`。 。 。 .

```js
import { customFormatter } from "@embra/reactivity/debug";
customFormatter();
```

## 常见问题

### @embra/reactivity 是什么？

一种轻量级,可堆肥和明显的反应系统\.

### 如何安装 @embra/reactivity？

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

### @embra/reactivity 支持 TypeScript 吗？

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

### @embra/reactivity 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @embra/reactivity 可以商用吗？

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

### @embra/reactivity 的下载量有多少？

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

### @embra/reactivity 还在维护吗？

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