# @ammarahmed/react-native-workers 中文文档

规范地址：https://npmcn.com/package/%40ammarahmed/react-native-workers/

版本：1\.0\.0-alpha\.4
npm 元数据更新时间：2026-09-17T09:19:09.952Z
中文译文更新时间：2026-11-07T03:33:20.975Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ammarahmed/react-native-workers
原文对照：https://npmcn.com/package/%40ammarahmed/react-native-workers/?lang=original
项目主页：https://github.com/ammarahm-ed/react-native-workers#readme
源码仓库：https://github.com/ammarahm-ed/react-native-workers

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

- 包体积（解压后）：843 kB，174 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=19\.1\.0，react-native \>=0\.81\.4
- 首次发布：2026-07-26T17:22:14.838Z
- 最新版本发布：2026-09-17T09:19:09.721Z
- 近 30 天下载量：2067（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

反应本地工人运行时间

## 安装

```sh
npm install @ammarahmed/react-native-workers
```

也可以使用：`pnpm add @ammarahmed/react-native-workers`、`yarn add @ammarahmed/react-native-workers`、`bun add @ammarahmed/react-native-workers`

## README

![](https://raw.githubusercontent.com/ammarahm-ed/react-native-workers/HEAD/docs/static/img/logo.svg)

# 反动土著工人

**React Introduct 的真实线程 .** Web Worker - style API, 由单独的 API 支持 赫尔墨斯在自己的线条上运行时间——带有结构化的杂音信息,计时器, 共享内存, 和完整的本地模块访问.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://npmcn.com/package/%40ammarahmed/react-native-workers/LICENSE) [![Platforms](https://img.shields.io/badge/platforms-iOS%20%7C%20Android-lightgrey.svg)](https://npmcn.com/package/%40ammarahmed/react-native-workers/#) [![React Native](https://img.shields.io/badge/React%20Native-0.81.4%2B-61dafb.svg)](https://reactnative.dev/) [![New Architecture](https://img.shields.io/badge/New%20Architecture-Hermes-brightgreen.svg)](https://reactnative.dev/architecture/landing-page)

[文档](https://ammarahm-ed.github.io/react-native-workers/) • 妇女 [快开始](https://ammarahm-ed.github.io/react-native-workers/docs/quick-start) • 妇女 [API 参考](https://ammarahm-ed.github.io/react-native-workers/docs/api-reference) • 妇女 [实例](https://ammarahm-ed.github.io/react-native-workers/docs/examples)

* * *

React Industrial 运行您的 JavaScript 在一个 JS 线索上,并驱动 UI 从它更新。 长剖面、大图像过滤器或紧凑的模拟循环 屏蔽线程——所以它不能发送更新和您的UI摊位.

这个图书馆给你一个真实的:

```js
import { Worker } from '@ammarahmed/react-native-workers';

const worker = new Worker({
  inline: `self.onmessage = (e) => self.postMessage({ doubled: e.data * 2 });`,
});

worker.onmessage = (e) => console.log(e.data); // { doubled: 42 }
worker.postMessage(21);
```

无头回放原生:没有UI,但相同的JavaScript引擎,相同 计时器和保证, 以及您已经使用的本地模块 .

## 为什么不一样

|  |  |
| --- | --- |
| **真正的线程** | 它自己的赫尔墨斯跑步时间 与它自己的堆积和事件循环, 而不是你的时间一线. |
| **本地模块工作** | TurboModules, 遗留模块和硝基模块都在工人内部解决—— `react-native-mmkv`, (中文(简体) ), `react-native-blob-util` 而朋友的工作没有改变. |
| **共享记忆, 不只是消息** | 梯子从 `postMessage` 以锁定自由共享单元格和原始共享 `ArrayBuffer`选择你想付出的代价. |
| **双向RPC** | 像当地人一样叫他们越过边界 `async` 函数,双向,使用一个共享类型. |
| **小捆** | 工人捆绑船由~150 KB来代替~1.4 MB,因为React Industrial的UI半部从未入图. |
| **可调试** | 每个工人都是自己的DevTools目标——断点、踩出和 `console.log` 转发给东道主 `[Worker:name]` 标签. |

## 工人与工人

这些比较很多,所以简短地说,它们解决了不同的问题,而不是 竞争者:

-   **单位不同.** 工作间就是 _函数_ 加上它抓获的关闭,移动 进入另一个运行时间。 工人是个 _文件_ 有了自己的地铁捆绑图,所以你 `import` npm 包通常没有关闭- 抓取规则可以学习 .
-   **两个都给你真正的JS运行时间.** 工作运行时间有事件循环和计时器 bundle Mode 也允许您导入库。 那个部分不是 差别.
-   **API不同.** 工人们会说网络语谱—— `new Worker()`, (中文(简体) ), `postMessage`, (中文(简体) ), `onmessage`工作表对于安排工作来说是一种较低层次的必要原始内容 运行时间,它更灵活,更不熟悉.
-   **对于动画和手势,使用再动画 / Worklets.** 他们同步的UI 运行时间是专为驾驶UI而建造的并经过战斗测试的60-120英尺。 A 类 传递消息的工人不应该是你的动画层.
-   **为了"把这份工作从我的JS线上解开" 工人很合身.** 解析、加密、图像 工作、数据库访问、网络I/O——每个工人本地模块实例 发生在工人身上的事件.

长的版本,包括前面的 Worklets 和他们的团队的改正, 位于 [比较](https://ammarahm-ed.github.io/react-native-workers/docs/prior-art)。 。 。 .

## 安装

```sh
npm install @ammarahmed/react-native-workers
```

要求 **新建筑** 与 **赫尔墨斯** (RN 0.81.4+,针对 0.86 (英语). 本地代码自动链接; 运行 `pod install` (原始内容存档于2018-03-31). On iOS.

然后包好你的地铁配置——这就是工人的小捆绑:

```js
const { getDefaultConfig } = require('@react-native/metro-config');
const { withWorkers } = require('@ammarahmed/react-native-workers/metro');

module.exports = withWorkers(getDefaultConfig(__dirname));
```

完整的设置——包括基于文件的工人的 Babel 插件和一次性 Android本地模块注册——正在 [安装指南](https://ammarahm-ed.github.io/react-native-workers/docs/installation)。 。 。 .

## 参观

**档案工作者** ——自动捆绑,各出一幅地铁图

将 Babel 插件添加到 `babel.config.js`,然后相对引用一个文件:

```js
const worker = new Worker('./workers/heavy-task');
```

每个条目都汇编成自己的捆绑——从Metro开发中获取, 以 Hermes 字节码 资产装入发布 。 见 [捆绑指南](https://ammarahm-ed.github.io/react-native-workers/docs/guides/bundling) 财务报告和审定财务报表 [`design-docs/release-bundling.md`](https://npmcn.com/package/%40ammarahmed/react-native-workers/design-docs/release-bundling.md)。 。 。 .

**工人内部的本地模块**

C++(Cxx)模块和被窝工人默认工作. 平台(Java/ObjC) 模块是每个工人选择的,因为每个工人建造涡轮模块 管理器成本内存 :

```js
const worker = new Worker('./workers/task', { nativeModules: true });
```

-   **iOS系统** ——每个工人 `RCTTurboModuleManager` 解决已注册的 ObjC 模块。 应用程序不变 .
    
-   **机器人** 注册您的软件包一次,因为没有全球注册:
    
    ```kotlin
    reactHost.addReactInstanceEventListener(object : ReactInstanceEventListener {
      override fun onReactContextInitialized(context: ReactContext) {
        if (context is ReactApplicationContext) {
          WorkerTurboModules.initialize(context, PackageList(this@MainApplication).packages)
        }
      }
    })
    ```
    

RN的核心模块(`SourceCode`, (中文(简体) ), `PlatformConstants`, (中文(简体) ), `DeviceInfo`添加(...) 自动。 UI-Affine模块(UIManager and friends)被排除在外. [细节](https://ammarahm-ed.github.io/react-native-workers/docs/guides/native-modules)。 。 。 .

**土著活动** —— 说 `NativeEventEmitter` 在工人中

```js
// inside a worker
const emitter = new NativeEventEmitter(someNativeModule);
const sub = emitter.addListener('SomeEvent', (payload) => {
  // fires on the worker thread
});
```

联合国 **劳动者的** 模块—— C++、 Java 或 ObjC —— 交付 直接去找那个工人 永远不要碰应用的运行时间 联合国提出事件 **东道主** (应用程序是自己的) `DeviceEventEmitter`,或主机拥有的模块) 向登记了听众的工人转交. [细节](https://ammarahm-ed.github.io/react-native-workers/docs/guides/native-events)。 。 。 .

**共享状态** —— 说 `SharedStore`, (中文(简体) ), `SharedValue`, (中文(简体) ), `SharedBuffer`

`SharedStore` 是一个C++支持的商店,由宿主和每个工人共享,拥有 同步读取/写入和更改监视器 :

```js
const store = new SharedStore('session');
store.set('user', { id: 1, name: 'Ada' });
const off = store.subscribe('user', (key, value) => { /* any runtime wrote */ });
```

与 `postMessage`,存储值是一个可地址的树——读取并更新 _组件_ 在那棵树上,你应当观察一棵树

```js
store.setIn('doc', ['user', 'age'], 31);           // encodes only the new leaf
store.subscribeIn('doc', ['user'], (path, value) => { /* ['age'], 31 */ });
```

对于热道,有两个更瘦的原始人:

```ts
// A single synchronous cell — lock-free for numbers (~17M writes/sec).
const progress = new SharedValue('anim:progress', 0);
progress.value = 0.42;

// Raw shared memory — same bytes in every runtime, zero host calls per element.
const buf = new SharedBuffer('sim', 50_000 * Float64Array.BYTES_PER_ELEMENT);
const view = new Float64Array(buf.arrayBuffer);
```

`SharedValue` 是~2×比 `SharedStore` 单一价值; `SharedBuffer` 对大块数字工作来说,是~4x更快的。 整个梯子,有基准,在 [`design-docs/shared-data-primitives.md`](https://npmcn.com/package/%40ammarahmed/react-native-workers/design-docs/shared-data-primitives.md)。 。 。 .

**输入的 RPC** - 那个 `JSModule` 桥梁和 `defineModule`

划过工人边界,好像是本地人 `async` 函数—— a 双向JS-JS RPC:

```js
// worker (JSModule is a global in every worker)
new JSModule('calc', {
  add(a, b) { return a + b; },
  async fetchUser(id) { return await load(id); },
});
```

```ts
// host — fully typed
const calc = worker.module<Calc>('calc');
await worker.ready('calc');
const sum = await calc.add(2, 3); // 5
```

工人可以召回主机 模块发出事件 和大型抛物 最好通过 `SharedStore` 而不是每个调用克隆.

`defineModule` 把桥和反应状态叠成一个合同 执行下列部分:

```ts
export const calc = defineModule<{
  worker: { add(a: number, b: number): number };
  host:   { getConfig(): Config };
  events: { progress: { percent: number } };
  state:  { status: 'idle' | 'busy' };
}>('calc');
```

设计和电线协议 : [`design-docs/jsmodule-bridge.md`](https://npmcn.com/package/%40ammarahmed/react-native-workers/design-docs/jsmodule-bridge.md), (中文(简体) ), [`design-docs/jsmodule-defineModule.md`](https://npmcn.com/package/%40ammarahmed/react-native-workers/design-docs/jsmodule-defineModule.md)。 。 。 .

**`UIWorker`** - 一个UI线上的工人

一个在月台主线上工作的非光谱工人 可以打电话 UI-Affine本土方法无线跳. 与 API 相同 `Worker`; 支持在 两个平台。 节制使用——这里的工作与渲染竞争.

```js
const w = new UIWorker({ inline: `self.onmessage = (e) => { /* UI-thread JS */ };` });
```
**从本地代码**

工人可以在任何线程上通过 C++ 创建和驱动 [`cpp/api/NativeWorkers.h`](https://npmcn.com/package/%40ammarahmed/react-native-workers/cpp/api/NativeWorkers.h) (JSON信息桥) - 对本地事件引发的联署材料背景有用.

## 套装大小

每个工人都是自己的地铁图 所以 `import … from 'react-native'` 拉开 整个框架——渲染器,组件,动画,虚拟化列表——入到每个 工人到达它。 第三方本地模块 导入桶本身, 如此小心的工人代码 独自无法避免它.

`withWorkers()` 决定 `react-native` 对一个工人大小的shim **内部工人 只有图表**。在示例应用程序(Hermes bytecode,已修改)上测量:

| 劳动者 | 无 | 与 |
| --- | --- | --- |
| `react-native-gzip` (遗产单元) | 1.39 甲基溴 | **149个KB** |
| `react-native-mmkv` (尼特罗) | 1.42 甲基溴 | **302 KB (韩语)** |
| `react-native-blob-util` (图尔博摩多尔语) | 1.50甲基溴 | **264 KB (韩语)** |
| 一个没有进口的工人 | 17.8 KB 电话 | 17.8 KB 电话 |

工人不能使用的出口(`View`, (中文(简体) ), `StyleSheet`, (中文(简体) ), `Animated`钩子... ) 使用信件命名导出, 而不是保持沉默 `undefined`。 。 。 .

## 支持的东西

结构克隆(对象、阵列、周期、打入的阵列、, `ArrayBuffer`, (中文(简体) ), `Date`, (中文(简体) ), `Map`, (中文(简体) ), `Set`, (中文(简体) ), `RegExp`, (中文(简体) ), `Error`, (中文(简体) ), `BigInt`, (中文(简体) ), `self` 编号 : `postMessage` 编号 : `onmessage` 编号 : `close` 编号 : `addEventListener`计时者,应许者, `structuredClone`,错误 传播到 `onerror`, (中文(简体) ), `terminate`工人隔离,以及 `NativeEventEmitter`。 。 。 .

二进制数据传输而不是复制 : `postMessage(v, [buf])` 移动 支持商店,以及 `createTransferableBuffer(n)` 给你一个缓冲器 每跳一个零副本.

工人内部的本地模块 **单独** 他们的活动被送到 而不是在应用的运行时间和复制回,他们 机构从工人的JS线(Android)中脱落 给工人自己的情况。 一个工人的网络I/O不依赖于RN JS 线是自由的.

在一个工人内部: **展览模块** 通过 `requireNativeModule(...)` 两者 平台,以及实验 [`Thread`](https://ammarahm-ed.github.io/react-native-workers/docs/guides/threads) API用于在另一个线上运行工人自己的运行时间.

**限制值得知道.** 赫尔墨斯没有 `ArrayBuffer` 调离,所以调离 缓冲器不会被引擎中去子化——这个库拒绝再利用,而且 `.detached` 报告 `true`,但原始读取仍然成功,除非你打电话 `enableTransferGuard()`。 。 。 . `SharedArrayBuffer` 赫尔墨斯不存在; [`SharedBuffer`](https://npmcn.com/package/%40ammarahmed/react-native-workers/#readme-a-tour) 是共享记忆路径。 土著单元隔离 关于私人反动 土著内部, 全部列出—— 是什么让我 删除它们——在 [套接字和兼容接字](https://ammarahm-ed.github.io/react-native-workers/docs/compat-seams)。 。 。 .

## 示例应用程序

这个 [`example/`](https://npmcn.com/package/%40ammarahmed/react-native-workers/example) app是一个工作屏幕的画廊——搜索服务, 图像过滤、下载、传感器、平行解析、注释——加上符合性 覆盖 API 表面的套件 。 每个屏幕的分步积分都在 [教程](https://ammarahm-ed.github.io/react-native-workers/docs/category/tutorials)。 。 。 .

## 捐款

-   [发展工作流程](https://npmcn.com/package/%40ammarahmed/react-native-workers/CONTRIBUTING.md#development-workflow)
-   [发送拉动请求](https://npmcn.com/package/%40ammarahmed/react-native-workers/CONTRIBUTING.md#sending-a-pull-request)

## 许可证

麻省理工学院 Ammar Ahmed

* * *

制造的 [创建- 反应- 本土- 图书馆](https://github.com/callstack/react-native-builder-bob)

## 常见问题

### @ammarahmed/react-native-workers 是什么？

反应本地工人运行时间

### 如何安装 @ammarahmed/react-native-workers？

在项目目录运行 npm install @ammarahmed/react-native-workers，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19\.1\.0）、react-native（\>=0\.81\.4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 rn-workers-bundle，可以用 npx rn-workers-bundle 直接运行。

### @ammarahmed/react-native-workers 支持 TypeScript 吗？

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

### @ammarahmed/react-native-workers 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @ammarahmed/react-native-workers 可以商用吗？

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

### @ammarahmed/react-native-workers 的下载量有多少？

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

### @ammarahmed/react-native-workers 还在维护吗？

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