用于通过 RPC（远程过程调用）进行类型安全的 Web Worker 通信的工具。

该包提供了一种简单高效的方式，用于主线程与 Web Worker 之间的通信，并自动处理：

  • 基于 Promise 的异步方法调用
  • 自动可转移对象检测（ArrayBuffer 等）
  • 具备完整 TypeScript 支持的类型安全 API
  • 从 worker 到主线程的错误传播

安装

安装模块：

npm install @wordpress/worker-threads

用法

Worker 线程

创建一个 worker 文件，将方法暴露给主线程：

// worker.ts
import { expose } from '@wordpress/worker-threads/worker';

const api = {
    async processImage( buffer: ArrayBuffer, quality: number ): Promise<ArrayBuffer> {
        // ... 图像处理逻辑
        return resultBuffer;
    },

    async calculateSum( a: number, b: number ): Promise<number> {
        return a + b;
    },
};

expose( api );

// 导出类型，以便在主线程中使用 wrap()
export type WorkerAPI = typeof api;

主线程

包装 worker 以获取类型安全的代理：

// main.ts
import { wrap, terminate } from '@wordpress/worker-threads';
import type { WorkerAPI } from './worker';

// 创建 worker
const worker = new Worker( new URL( './worker.js', import.meta.url ), {
    type: 'module',
} );

// 包装它以获取 RPC 代理
const api = wrap<WorkerAPI>( worker );

// 以异步函数方式调用方法
const result = await api.processImage( imageBuffer, 0.82 );
const sum = await api.calculateSum( 1, 2 );

// 完成后清理
terminate( api );

API 参考

主线程 API

wrap<T>( worker: Worker ): Remote<T>

包装 Worker 以提供类型安全的 RPC 接口。返回的代理对象允许像调用本地异步函数一样调用 worker 中的方法。

terminate( remote: Remote<unknown> ): void

终止已包装的 worker 并清理资源。所有待处理的调用都会被拒绝。

Worker 线程 API

expose<T>( target: T ): void

暴露对象的方法，以便从主线程调用。应在 worker 脚本中调用一次。

类型

Remote<T>

一种类型，将 T 的所有方法转换为其异步版本。每个方法都返回 Promise<Awaited<ReturnType>>。

功能

自动可转移对象检测

该包会自动检测并转移 ArrayBuffer 和其他可转移对象，为大数据提供零复制性能：

// ArrayBuffer 会自动转移，而不是复制
const result = await api.processImage( largeImageBuffer );

错误处理

在 worker 中抛出的错误会被正确传播到主线程：

try {
    await api.riskyOperation();
} catch ( error ) {
    console.error( 'Worker error:', error.message );
}

TypeScript 支持

对方法签名提供完整类型推断：

// TypeScript 知道返回类型和参数类型
const result: ArrayBuffer = await api.processImage( buffer, 0.82 );

为这个包做贡献

这是一个独立包，属于 Gutenberg 项目。该项目以 monorepo 形式组织。它由多个自包含的软件包组成，每个包都有特定用途。此 monorepo 中的包发布到 npm，并被 WordPress 以及其他软件项目使用。

如需了解更多关于为这个包或整个 Gutenberg 项目做贡献的信息，请阅读项目的主要 贡献者指南。