harmony 鸿蒙@ohos.worker (启动一个Worker)

2025-06-12
浏览 (5)

@ohos.worker (启动一个Worker)

Worker是与主线程并行的独立线程。创建Worker的线程称之为宿主线程，Worker自身的线程称之为Worker线程。创建Worker传入的url文件在Worker线程中执行，可以处理耗时操作但不可以直接操作UI。

Worker主要作用是为应用程序提供一个多线程的运行环境，可满足应用程序在执行过程中与宿主线程分离，在后台线程中运行一个脚本处理耗时操作，极大避免类似于计算密集型或高延迟的任务阻塞宿主线程的运行。由于Worker一旦被创建则不会主动被销毁，若不处于任务状态一直运行，在一定程度上会造成资源的浪费，应及时关闭空闲的Worker。

Worker的上下文对象和UI主线程的上下文对象是不同的，Worker线程不支持UI操作。

Worker使用过程中的相关注意点请查看Worker注意事项。

说明：
本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import { worker } from '@kit.ArkTS';

属性

系统能力： SystemCapability.Utils.Lang

名称	类型	可读	可写	说明
workerPort⁹⁺	ThreadWorkerGlobalScope	是	是	worker线程用于与宿主线程通信的对象。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
parentPort^(deprecated)	DedicatedWorkerGlobalScope	是	是	worker线程用于与宿主线程通信的对象。此属性从API version 7开始支持，从API version 9开始被废弃。建议使用workerPort⁹⁺替代。

WorkerOptions

Worker构造函数的选项信息，用于为Worker添加其他信息。

系统能力： SystemCapability.Utils.Lang

名称	类型	只读	可选	说明
type	‘classic’ \|‘module’	是	是	Worker执行脚本的模式类型，暂不支持module类型，默认值为”classic”。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
name	string	是	是	Worker的名称，默认值为 undefined 。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
shared	boolean	是	是	表示Worker共享功能，此接口暂不支持。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
priority¹⁸⁺	ThreadWorkerPriority	是	是	表示Worker线程优先级。原子化服务API：从API version 18开始，该接口支持在原子化服务中使用。

ThreadWorkerPriority¹⁸⁺

Worker线程的优先级枚举，各优先级对应关系请参考QoS等级定义。

系统能力： SystemCapability.Utils.Lang

原子化服务API：从API version 18开始，该接口支持在原子化服务中使用。

名称	值	说明
HIGH	0	高优先级，对应QOS_USER_INITIATED。
MEDIUM	1	中优先级，对应QOS_DEFAULT。
LOW	2	低优先级，对应QOS_UTILITY。
IDLE	3	后台优先级，对应QOS_BACKGROUND。

ThreadWorker⁹⁺

使用以下方法前，均需先构造ThreadWorker实例，ThreadWorker类继承WorkerEventTarget。

constructor⁹⁺

constructor(scriptURL: string, options?: WorkerOptions)

ThreadWorker构造函数。

原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
scriptURL	string	是	Worker线程文件的路径。路径规则详细参考文件路径注意事项。
options	WorkerOptions	否	Worker构造的选项。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200003	Worker initialization failed.
10200007	The worker file path is invalid.

示例：

此处以在Stage模型的entry模块Index.ets文件中加载Worker文件为例，使用Library加载Worker线程文件的场景参考文件路径注意事项。

import { worker } from '@kit.ArkTS';

// worker文件所在路径："entry/src/main/ets/workers/worker.ets"
const workerInstance = new worker.ThreadWorker('entry/ets/workers/worker.ets', {name: "WorkerThread"});

postMessage⁹⁺

postMessage(message: Object, transfer: ArrayBuffer[]): void

宿主线程通过转移对象所有权的方式向Worker线程发送消息。

系统能力： SystemCapability.Utils.Lang

原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。

参数：

参数名	类型	必填	说明
message	Object	是	发送至Worker的数据，该数据对象必须是可序列化，序列化支持类型见其他说明。
transfer	ArrayBuffer[]	是	表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到Worker线程，在宿主线程中将会变为不可用，仅在Worker线程中可用，数组不可传入null。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200004	The Worker instance is not running.
10200006	An exception occurred during serialization.

示例：

// Worker.ets
import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS';

// 创建worker线程中与宿主线程通信的对象
const workerPort = worker.workerPort;

// worker线程接收宿主线程信息
workerPort.onmessage = (e: MessageEvents): void => {
  // data：宿主线程发送的信息
  let data: number = e.data;
  // 往收到的buffer里写入数据
  const view = new Int8Array(data).fill(3);
  // worker线程向宿主线程发送信息
  workerPort.postMessage(view);
}

// worker线程发生error的回调
workerPort.onerror = (err: ErrorEvent) => {
  console.error("worker.ets onerror" + err.message);
}

// Index.ets
import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS';

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            // 宿主线程中创建Worker对象
            const workerInstance = new worker.ThreadWorker("entry/ets/workers/Worker.ets");
            // 宿主线程向worker线程传递信息
            const buffer = new ArrayBuffer(8);
            workerInstance.postMessage(buffer, [buffer]);

            // 此时buffer的所有权转移到了worker线程，在宿主线程中不可用
            // const view = new Int8Array(buffer).fill(3);

            // 宿主线程接收worker线程信息
            workerInstance.onmessage = (e: MessageEvents): void => {
              // data：worker线程发送的信息
              let data: number = e.data;
              console.info("main thread data is  " + data);
              // 销毁Worker对象
              workerInstance.terminate();
            }
            // 在调用terminate后，执行onexit
            workerInstance.onexit = (code) => {
              console.info("main thread terminate");
            }

            workerInstance.onAllErrors = (err: ErrorEvent) => {
              console.error("main error message " + err.message);
            }
          })
      }
      .width('100%')
      .height('100%')
    }
  }
}

postMessage⁹⁺

postMessage(message: Object, options?: PostMessageOptions): void

宿主线程通过转移对象所有权或者拷贝数据的方式向Worker线程发送消息。在传递Sendable对象时使用拷贝数据的方式传递。

原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
message	Object	是	发送至Worker的数据，该数据对象必须是可序列化，序列化支持类型见其他说明。
options	PostMessageOptions	否	当填入该参数时，与传入ArrayBuffer[]的作用一致，该数组中对象的所有权会被转移到Worker线程，在宿主线程中将会变为不可用，仅在Worker线程中可用。若不填入该参数，默认设置为 undefined，通过拷贝数据的方式传输信息到Worker线程。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200004	The Worker instance is not running.
10200006	An exception occurred during serialization.

示例：

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

workerInstance.postMessage("hello world");

let buffer = new ArrayBuffer(8);

// 填入options参数，buffer的所有权会转移到worker线程，在宿主线程中将不可用
workerInstance.postMessage(buffer, [buffer]);

// 未填入options参数，默认值为undefined，通过拷贝数据的方式将buffer发送到worker线程
workerInstance.postMessage(buffer);

postMessageWithSharedSendable¹²⁺

postMessageWithSharedSendable(message: Object, transfer?: ArrayBuffer[]): void

宿主线程向Worker线程发送消息，消息中的Sendable对象通过引用传递，非Sendable对象通过拷贝数据的方式传递。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
message	Object	是	发送至Worker的数据，该数据对象必须是可序列化或可共享，序列化支持类型见序列化类型说明，共享支持类型见Sendable支持的数据类型。
transfer	ArrayBuffer[]	否	表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到Worker线程，在宿主线程中将会变为不可用，仅在Worker线程中可用，数组不可传入null。默认值为空数组。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200004	The Worker instance is not running.
10200006	An exception occurred during serialization.

示例：

// index.ets
// 新建SendableObject实例并通过宿主线程传递至worker线程

import { worker } from '@kit.ArkTS';
import { SendableObject } from './sendable';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/Worker.ets");
let object: SendableObject = new SendableObject();
workerInstance.postMessageWithSharedSendable(object);

// 使用postMessage接口传递Sendable对象，使用拷贝数据的方式传递
workerInstance.postMessage(object);

// sendable.ets
// 定义SendableObject

@Sendable
export class SendableObject {
  a:number = 45;
}

// worker文件路径为：entry/src/main/ets/workers/Worker.ets
// Worker.ets
// 接收宿主线程传递至worker线程的数据并访问

import { SendableObject } from '../pages/sendable';
import { worker, ThreadWorkerGlobalScope, MessageEvents, ErrorEvent } from '@kit.ArkTS';

const workerPort: ThreadWorkerGlobalScope = worker.workerPort;

workerPort.onmessage = (e: MessageEvents) => {
  let obj: SendableObject = e.data;
  console.info("sendable obj is: " + obj.a);
}

on⁹⁺

on(type: string, listener: WorkerEventListener): void

向Worker添加一个事件监听，该接口与addEventListener⁹⁺接口功能一致。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
type	string	是	监听的事件类型。
listener	WorkerEventListener	是	回调的事件。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

示例：

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

workerInstance.on("alert", () => {
    console.info("alert listener callback");
})

// 使用on添加的事件监听可以多次执行
workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持
workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持

once⁹⁺

once(type: string, listener: WorkerEventListener): void

向Worker添加一个事件监听，该事件监听只执行一次便自动删除。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
type	string	是	监听的事件类型。
listener	WorkerEventListener	是	回调的事件。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

示例：

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

workerInstance.once("alert", () => {
  console.info("alert listener callback");
})

workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持

// 使用once添加的事件监听在执行一次后自动删除，无法多次执行
// workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持

off⁹⁺

off(type: string, listener?: WorkerEventListener): void

删除类型为type的事件监听，该接口与removeEventListener⁹⁺接口功能一致。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
type	string	是	需要删除的事件类型。
listener	WorkerEventListener	否	需要删除的特定监听器回调函数。如果未传入此参数，则会删除该类型的所有监听器。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

示例：

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

const handler1 = () => console.info("Handler 1");
const handler2 = () => console.info("Handler 2");

// 注册两个监听器
workerInstance.on("alert", handler1);
workerInstance.on("alert", handler2);

// 首次触发：两个监听器都会执行
workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持

// 删除 handler1 监听器
workerInstance.off("alert", handler1);

// 再次触发：只剩 handler2 会执行
workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持

// 删除"alert"类型所有监听器
workerInstance.off("alert");

registerGlobalCallObject¹¹⁺

registerGlobalCallObject(instanceName: string, globalCallObject: Object): void

在宿主线程的ThreadWorker实例上注册一个对象，该对象上的方法可以在Worker线程中被调用，详细介绍请参见callGlobalCallObjectMethod。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
instanceName	string	是	注册对象时使用的键，调用时可以通过该键值找到相对应的被注册的对象。
globalCallObject	Object	是	被注册的对象，ThreadWorker实例会持有被注册对象的强引用。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200004	Worker instance is not running.

示例：

//Index.ets
const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
class TestObj {
  private message : string = "this is a message from TestObj";
  public getMessage() : string {
    return this.message;
  }
  public getMessageWithInput(str : string) : string {
    return this.message + " with input: " + str;
  }
}
let registerObj = new TestObj();
// 在ThreadWorker实例上注册registerObj
workerInstance.registerGlobalCallObject("myObj", registerObj);
workerInstance.postMessage("start worker");

// worker.ets
import { worker, MessageEvents } from '@kit.ArkTS';

const workerPort = worker.workerPort;
workerPort.onmessage = (e: MessageEvents): void => {
  try {
    // 调用方法无入参
    let res : string = workerPort.callGlobalCallObjectMethod("myObj", "getMessage", 0) as string;
    console.info("worker:", res) // worker: this is a message from TestObj
  } catch (error) {
    // 异常处理
    console.error("worker: error code is " + error.code + " error message is " + error.message);
  }
  try {
    // 调用方法有入参
    let res : string = workerPort.callGlobalCallObjectMethod("myObj", "getMessageWithInput", 0, "hello there!") as string;
    console.info("worker:", res); //worker: this is a message from TestObj with input: hello there!
  } catch (error) {
    // 异常处理
    console.error("worker: error code is " + error.code + " error message is " + error.message);
  }
}

unregisterGlobalCallObject¹¹⁺

unregisterGlobalCallObject(instanceName?: string): void

取消在宿主线程ThreadWorker实例上注册的对象，该方法会释放ThreadWorker实例中与该键相匹配的对象的强引用。如果没有匹配的对象，该方法不会报错。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
instanceName	string	否	注册对象时使用的键，此参数不填时，会释放ThreadWorker实例中所有已注册的对象。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200004	Worker instance is not running.

示例：

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
class TestObj {
  private message : string = "this is a message from TestObj";
  public getMessage() : string {
    return this.message;
  }
  public getMessageWithInput(str : string) : string {
    return this.message + " with input: " + str;
  }
}
let registerObj = new TestObj();
workerInstance.registerGlobalCallObject("myObj", registerObj);
// 取消对象注册
workerInstance.unregisterGlobalCallObject("myObj");
// 取消ThreadWorker实例上的所有对象注册
//workerInstance.unregisterGlobalCallObject();
workerInstance.postMessage("start worker");

terminate⁹⁺

terminate(): void

销毁Worker线程，终止Worker接收消息。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID	错误信息
10200004	The Worker instance is not running.

示例：

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.terminate();

onexit⁹⁺

onexit?: (code: number) => void

回调函数。表示Worker销毁时被调用的事件处理程序，处理程序在宿主线程中执行。其中回调函数中code类型为number，异常退出为1，正常退出为0。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1.Incorrect parameter types.
10200004	The Worker instance is not running.
10200005	The called API is not supported in the worker thread.

示例：

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.onexit = (code) => {
 console.info("onexit");
}

//onexit被执行两种方式：
// main thread：
workerInstance.terminate();

// worker线程：
//workerPort.close();

onerror⁹⁺

onerror?: (err: ErrorEvent) => void

回调函数。在执行onmessage回调函数中同步代码产生异常时被调用的事件处理程序，处理程序在宿主线程中执行。其中回调函数中err类型为ErrorEvent，表示收到的异常数据。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1.Incorrect parameter types.
10200004	The Worker instance is not running.
10200005	The called API is not supported in the worker thread.

示例：

// Index.ets
import { worker, ErrorEvent } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

// 注册onerror接口的回调
workerInstance.onerror = (err: ErrorEvent) => {
  // main thread onerror is:  "Error: error test"
  console.error("main thread onerror is: ", JSON.stringify(err.message));
}

workerInstance.postMessage(1);

// worker.ets
import { worker, ThreadWorkerGlobalScope, MessageEvents } from '@kit.ArkTS';

const workerPort: ThreadWorkerGlobalScope = worker.workerPort;

workerPort.onmessage = (e: MessageEvents) => {
  console.info("worker thread data is: ", e.data);
  // 在worker线程的onmessage回调中抛出异常
  throw new Error("error test");
}

onAllErrors¹⁸⁺

onAllErrors?: ErrorCallback

回调函数。表示Worker线程生命周期内发生异常被调用的事件处理程序，处理程序在宿主线程中执行。
onerror仅捕获onmessage回调中同步方法产生的异常，无法捕获多线程回调产生的异常和模块化相关异常，且onerror捕获异常后Worker线程进入销毁流程，不可以继续使用。
onAllErrors可以捕获Worker线程的onmessage回调、timer回调以及文件执行等过程中产生的全局异常，且onAllErrors捕获异常后Worker线程仍存活，可以继续使用。因此，推荐使用onAllErrors代替onerror。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID	错误信息
10200004	The Worker instance is not running.
10200005	The called API is not supported in the worker thread.

示例：

// Index.ets
import { worker, ErrorEvent } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

// 注册onerror接口的回调
workerInstance.onerror = (err: ErrorEvent) => {
  console.error("main thread onerror is: ", JSON.stringify(err.message));
}

// 当onerror与onAllErrors同时注册时只触发onAllErrors的回调
workerInstance.onAllErrors = (err: ErrorEvent) => {
  console.error("main thread onAllErrors is: ", JSON.stringify(err.message));
}

workerInstance.postMessage(1);

import { worker, ThreadWorkerGlobalScope, MessageEvents } from '@kit.ArkTS';

const workerPort: ThreadWorkerGlobalScope = worker.workerPort;
workerPort.onmessage = (e: MessageEvents) => {
  console.info("worker thread data is: ", e.data);
  // 在worker线程的onmessage回调中抛出异常
  throw new Error("error test");
}

onmessage⁹⁺

onmessage?: (event: MessageEvents) => void

回调函数。表示宿主线程接收到来自其创建的Worker通过workerPort.postMessage接口发送的消息时被调用的事件处理程序，处理程序在宿主线程中执行。其中回调函数中event类型为MessageEvents，表示收到的Worker消息数据。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1.Incorrect parameter types.
10200004	The Worker instance is not running.
10200005	The called API is not supported in the worker thread.

示例：

// Index.ets
import { worker, MessageEvents } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

workerInstance.onmessage = (e: MessageEvents) => {
  console.info("main thread recv data is: ", e.data);
}

workerInstance.postMessage("main thread postMessage to worker thread.");

// worker.ets
import { worker, ThreadWorkerGlobalScope, MessageEvents } from '@kit.ArkTS';

const workerPort: ThreadWorkerGlobalScope = worker.workerPort;

workerPort.onmessage = (e: MessageEvents) => {
  console.info("worker thread recv data is: ", e.data);
  workerPort.postMessage("worker thread postMessage to main thread.");
}

onmessageerror⁹⁺

onmessageerror?: (event: MessageEvents) => void

回调函数。表示当Worker对象接收到一条无法被序列化的消息时被调用的事件处理程序，处理程序在宿主线程中执行。其中回调函数中event类型为MessageEvents，表示收到的Worker消息数据。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1.Incorrect parameter types.
10200004	The Worker instance is not running.
10200005	The called API is not supported in the worker thread.

示例：

import { MessageEvents, worker, HashMap } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

// 注册onmessageerror回调
workerInstance.onmessageerror = (e: MessageEvents) => {
  console.error("main thread onmessageerror execute.");
}

let hashMap: HashMap<string, number> = new HashMap();
let result = hashMap.set("squirrel", 123);

try {
  workerInstance.postMessage(result);
} catch (err) {
  console.error("catch error is: ", JSON.stringify(err));
}

addEventListener⁹⁺

addEventListener(type: string, listener: WorkerEventListener): void

向Worker添加一个事件监听，该接口与on⁹⁺接口功能一致。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
type	string	是	监听的事件类型。
listener	WorkerEventListener	是	回调的事件。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

示例：

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

workerInstance.addEventListener("alert", () => {
  console.info("alert listener callback");
})

// 执行 alert 事件类型的回调
workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持

removeEventListener⁹⁺

removeEventListener(type: string, callback?: WorkerEventListener): void

删除Worker的事件监听，该接口与off⁹⁺接口功能一致。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
type	string	是	需要删除的监听事件类型。
callback	WorkerEventListener	否	删除监听事件后所执行的回调事件。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200004	Worker instance is not running.

示例：

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.addEventListener("alert", () => {
    console.info("alert listener callback");
})
workerInstance.removeEventListener("alert");

dispatchEvent⁹⁺

dispatchEvent(event: Event): boolean

将事件对象分发到Worker线程的事件系统。事件系统会自动触发该类型事件对应的所有监听器回调。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
event	Event	是	需要分发的事件。

返回值：

类型	说明
boolean	分发的结果。true表示分发成功，false表示分发失败。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200004	Worker instance is not running.

示例：

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

workerInstance.addEventListener("alert", () => {
  console.info("alert listener callback");
})

let result: Boolean = workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持

console.info("dispatchEvent result is: ", result);

分发事件（dispatchEvent）可与监听接口（on、once、addEventListener）搭配使用，示例如下：

import { worker, MessageEvents } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

// 用法一:
workerInstance.on("alert_on", () => {
    console.info("alert listener callback");
})
workerInstance.once("alert_once", () => {
    console.info("alert listener callback");
})
workerInstance.addEventListener("alert_add", () => {
    console.info("alert listener callback");
})

// once接口创建的事件执行一次便会删除。
workerInstance.dispatchEvent({type: "alert_once", timeStamp: 0}); // timeStamp暂未支持
// on接口创建的事件可以一直被分发，不能主动删除。
workerInstance.dispatchEvent({type: "alert_on", timeStamp: 0});
workerInstance.dispatchEvent({type: "alert_on", timeStamp: 0});
// addEventListener接口创建的事件可以一直被分发，不能主动删除。
workerInstance.dispatchEvent({type: "alert_add", timeStamp: 0});
workerInstance.dispatchEvent({type: "alert_add", timeStamp: 0});

// 用法二:
// event类型的type支持自定义，同时存在"message"/"messageerror"/"error"特殊类型，如下所示
// 当type = "message"，onmessage接口定义的方法同时会执行。
// 当type = "messageerror"，onmessageerror接口定义的方法同时会执行。
// 当type = "error"，onerror接口定义的方法同时会执行。
// 若调用removeEventListener接口或者off接口取消事件时，能且只能取消使用addEventListener/on/once创建的事件。

workerInstance.addEventListener("message", () => {
    console.info("message listener callback");
})
workerInstance.onmessage = (e: MessageEvents): void => {
    console.info("onmessage : message listener callback");
}
// 调用dispatchEvent分发“message”事件，addEventListener和onmessage中定义的方法都会被执行。
workerInstance.dispatchEvent({type: "message", timeStamp: 0});

removeAllListener⁹⁺

removeAllListener(): void

删除Worker所有的事件监听。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID	错误信息
10200004	Worker instance is not running.

示例：

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.addEventListener("alert", () => {
    console.info("alert listener callback");
})
workerInstance.removeAllListener();

WorkerEventTarget⁹⁺

处理Worker监听事件。

addEventListener⁹⁺

addEventListener(type: string, listener: WorkerEventListener): void

向Worker添加一个事件监听，该接口与on⁹⁺接口功能一致。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
type	string	是	监听的事件类型。
listener	WorkerEventListener	是	回调的事件。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200004	The Worker instance is not running.
10200005	The called API is not supported in the worker thread.

示例：

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.addEventListener("alert", () => {
    console.info("alert listener callback");
})

removeEventListener⁹⁺

removeEventListener(type: string, callback?: WorkerEventListener): void

删除Worker的事件监听，该接口与off⁹⁺接口功能一致。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
type	string	是	需要删除的监听事件类型。
callback	WorkerEventListener	否	删除监听事件后所执行的回调事件。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200004	The Worker instance is not running.

示例：

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.addEventListener("alert", () => {
    console.info("alert listener callback");
})
workerInstance.removeEventListener("alert");

dispatchEvent⁹⁺

dispatchEvent(event: Event): boolean

将事件对象分发到Worker线程的事件系统。事件系统会自动触发该类型事件对应的所有监听器回调。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
event	Event	是	需要分发的事件。

返回值：

类型	说明
boolean	分发的结果。true表示分发成功，false表示分发失败。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200004	The Worker instance is not running.

示例：

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

workerInstance.dispatchEvent({type:"eventType", timeStamp:0}); // timeStamp暂未支持

分发事件（dispatchEvent）可与监听接口（on、once、addEventListener）搭配使用，示例如下：

import { worker, MessageEvents } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

//用法一:
workerInstance.on("alert_on", () => {
    console.info("alert listener callback");
})
workerInstance.once("alert_once", () => {
    console.info("alert listener callback");
})
workerInstance.addEventListener("alert_add", () => {
    console.info("alert listener callback");
})

//once接口创建的事件执行一次便会删除。
workerInstance.dispatchEvent({type: "alert_once", timeStamp: 0});// timeStamp暂未支持
//on接口创建的事件可以一直被分发，不能主动删除。
workerInstance.dispatchEvent({type: "alert_on", timeStamp: 0});
workerInstance.dispatchEvent({type: "alert_on", timeStamp: 0});
//addEventListener接口创建的事件可以一直被分发，不能主动删除。
workerInstance.dispatchEvent({type: "alert_add", timeStamp: 0});
workerInstance.dispatchEvent({type: "alert_add", timeStamp: 0});

//用法二:
//event类型的type支持自定义，同时存在"message"/"messageerror"/"error"特殊类型，如下所示
//当type = "message"，onmessage接口定义的方法同时会执行。
//当type = "messageerror"，onmessageerror接口定义的方法同时会执行。
//当type = "error"，onerror接口定义的方法同时会执行。
//若调用removeEventListener接口或者off接口取消事件时，能且只能取消使用addEventListener/on/once创建的事件。

workerInstance.addEventListener("message", () => {
    console.info("message listener callback");
})
workerInstance.onmessage = (e: MessageEvents): void => {
    console.info("onmessage : message listener callback");
}
//调用dispatchEvent分发“message”事件，addEventListener和onmessage中定义的方法都会被执行。
workerInstance.dispatchEvent({type: "message", timeStamp: 0});

removeAllListener⁹⁺

removeAllListener(): void

删除Worker所有的事件监听。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID	错误信息
10200004	The Worker instance is not running.

示例：

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.addEventListener("alert", () => {
    console.info("alert listener callback");
})
workerInstance.removeAllListener();

ThreadWorkerGlobalScope⁹⁺

Worker线程用于与宿主线程通信的类，通过postMessage接口发送消息给宿主线程、close接口销毁Worker线程。ThreadWorkerGlobalScope类继承GlobalScope。

postMessage⁹⁺

postMessage(messageObject: Object, transfer: ArrayBuffer[]): void;

Worker线程通过转移对象所有权的方式向宿主线程发送消息。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
messageObject	Object	是	发送至宿主线程的数据，该数据对象必须是可序列化，序列化支持类型见其他说明。
transfer	ArrayBuffer[]	是	表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用，数组不可传入null。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200004	The Worker instance is not running.
10200006	An exception occurred during serialization.

示例：

// main thread
import { worker, MessageEvents } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.postMessage("hello world");
workerInstance.onmessage = (e: MessageEvents): void => {
    console.info("receive data from worker.ets");
}

// worker.ets
import { worker, MessageEvents } from '@kit.ArkTS';

const workerPort = worker.workerPort;
workerPort.onmessage = (e: MessageEvents): void => {
    let buffer = new ArrayBuffer(8);
    workerPort.postMessage(buffer, [buffer]);
}

postMessage⁹⁺

postMessage(messageObject: Object, options?: PostMessageOptions): void

Worker线程通过转移对象所有权或者拷贝数据的方式向宿主线程发送消息。在传递Sendable对象时使用拷贝数据的方式传递。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
messageObject	Object	是	发送至宿主线程的数据，该数据对象必须是可序列化，序列化支持类型见其他说明。
options	PostMessageOptions	否	当填入该参数时，与传入ArrayBuffer[]的作用一致，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用。若不填入该参数，默认设置为 undefined，通过拷贝数据的方式传输信息到宿主线程。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200004	The Worker instance is not running.
10200006	An exception occurred during serialization.

示例：

// main thread
import { worker, MessageEvents } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.postMessage("hello world");
workerInstance.onmessage = (e: MessageEvents): void => {
    console.info("receive data from worker.ets");
}

// worker.ets
import { worker, MessageEvents } from '@kit.ArkTS';

const workerPort = worker.workerPort;
workerPort.onmessage = (e: MessageEvents): void => {
    workerPort.postMessage("receive data from main thread");
}

postMessageWithSharedSendable¹²⁺

postMessageWithSharedSendable(message: Object, transfer?: ArrayBuffer[]): void

Worker线程向宿主线程发送消息，消息中的Sendable对象通过引用传递，非Sendable对象通过拷贝数据的方式传递。

原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
message	Object	是	发送至宿主线程的数据，该数据对象必须是可序列化或可共享，序列化支持类型见序列化类型说明，共享支持类型见Sendable支持的数据类型。
transfer	ArrayBuffer[]	否	表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用，数组不可传入null。默认值为空数组。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200004	The Worker instance is not running.
10200006	An exception occurred during serialization.

示例：

// worker文件路径为：entry/src/main/ets/workers/Worker.ets
// Worker.ets
// 新建SendableObject实例并通过worker线程传递至宿主线程

import { SendableObject } from '../pages/sendable';
import { worker, ThreadWorkerGlobalScope, MessageEvents, ErrorEvent } from '@kit.ArkTS';

const workerPort: ThreadWorkerGlobalScope = worker.workerPort;
workerPort.onmessage = (e: MessageEvents) => {
  let object: SendableObject = new SendableObject();
  workerPort.postMessageWithSharedSendable(object);
}

// sendable.ets
// 定义SendableObject

@Sendable
export class SendableObject {
  a:number = 45;
}

// Index.ets
// 接收worker线程传递至宿主线程的数据并访问其属性

import { worker, MessageEvents } from '@kit.ArkTS';
import { SendableObject } from './sendable';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/Worker.ets");
workerInstance.postMessage(1);
workerInstance.onmessage = (e: MessageEvents) => {
  let obj: SendableObject = e.data;
  console.info("sendable index obj is: " + obj.a);
}

callGlobalCallObjectMethod¹¹⁺

callGlobalCallObjectMethod(instanceName: string, methodName: string, timeout: number, …args: Object[]): Object

Worker线程调用注册在宿主线程上某个对象的指定方法，调用对于Worker线程是同步的，对于宿主线程是异步的，返回值通过拷贝数据的方式传递。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
instanceName	string	是	注册对象时使用的键，用于在宿主线程查找对象。
methodName	string	是	在已注册对象上调用的方法名，注意该方法不能为使用async或generator修饰的方法，或底层使用了异步机制等异步返回结果的方法，否则会抛出异常。
timeout	number	是	本次同步调用的等待时间单位为ms，取整数，取值范围为[1-5000]ms。也可取特殊值0，此时表示本次调用等待时间为5000ms。
args	Object[]	否	注册对象上所调用方法的参数数组。

返回值：

类型	说明
Object	返回值为调用方法在宿主线程的返回值，该返回值必须是可序列化的，具体可见序列化支持类型。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200004	Worker instance is not running.
10200006	An exception occurred during serialization.
10200019	The globalCallObject is not registered.
10200020	The method to be called is not callable or is an async method or a generator.
10200021	The global call exceeds the timeout.

示例：

//Index.ets
const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
class TestObj {
  private message : string = "this is a message from TestObj";
  public getMessage() : string {
    return this.message;
  }
  public getMessageWithInput(str : string) : string {
    return this.message + " with input: " + str;
  }
}
let registerObj = new TestObj();
// 在ThreadWorker实例上注册registerObj
workerInstance.registerGlobalCallObject("myObj", registerObj);
workerInstance.postMessage("start worker");

// worker.ets
import { worker, MessageEvents } from '@kit.ArkTS';

const workerPort = worker.workerPort;
workerPort.onmessage = (e: MessageEvents): void => {
  try {
    // 调用方法无入参
    let res : string = workerPort.callGlobalCallObjectMethod("myObj", "getMessage", 0) as string;
    console.info("worker:", res); // worker: this is a message from TestObj
  } catch (error) {
    // 异常处理
    console.error("worker: error code is " + error.code + " error message is " + error.message);
  }
  try {
    // 调用方法有入参
    let res : string = workerPort.callGlobalCallObjectMethod("myObj", "getMessageWithInput", 0, "hello there!") as string;
    console.info("worker:", res); //worker: this is a message from TestObj with input: hello there!
  } catch (error) {
    // 异常处理
    console.error("worker: error code is " + error.code + " error message is " + error.message);
  }
}

close⁹⁺

close(): void

销毁Worker线程，终止Worker接收消息。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID	错误信息
10200004	The Worker instance is not running.

示例：

// main thread
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

// worker.ets
import { worker, MessageEvents } from '@kit.ArkTS';

const workerPort = worker.workerPort;
workerPort.onmessage = (e: MessageEvents): void => {
    workerPort.close();
}

onmessage⁹⁺

onmessage?: (this: ThreadWorkerGlobalScope, ev: MessageEvents) => void

回调函数。ThreadWorkerGlobalScope的onmessage属性表示Worker线程收到来自其宿主线程通过postMessage接口发送的消息时被调用的事件处理程序，处理程序在Worker线程中执行。其中this指调用者对象本身ThreadWorkerGlobalScope，ev类型为MessageEvents，表示收到的Worker消息数据。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Incorrect parameter types.
10200004	The Worker instance is not running.
10200005	The called API is not supported in the worker thread.

示例：

// main thread
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.postMessage("hello world");

// worker.ets
import { worker, MessageEvents } from '@kit.ArkTS';

const workerPort = worker.workerPort;
workerPort.onmessage = (e: MessageEvents): void => {
    console.info("receive main thread message");
}

onmessageerror⁹⁺

onmessageerror?: (this: ThreadWorkerGlobalScope, ev: MessageEvents) => void

回调函数。ThreadWorkerGlobalScope的onmessageerror属性表示当Worker对象接收到一条无法被反序列化的消息时被调用的事件处理程序，处理程序在Worker线程中执行。其中this指调用者对象本身ThreadWorkerGlobalScope，ev类型为MessageEvents，表示收到的Worker消息数据。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Incorrect parameter types.
10200004	The Worker instance is not running.
10200005	The called API is not supported in the worker thread.

示例：

// main thread
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

// worker.ets
import { worker, MessageEvents } from '@kit.ArkTS';

const workerPort = worker.workerPort;
workerPort.onmessageerror = (err: MessageEvents) => {
    console.error("worker.ets onmessageerror");
}

WorkerEventListener⁹⁺

事件监听类。

(event: Event)⁹⁺

(event: Event): void|Promise<void>

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
event	Event	是	回调的事件类。

返回值：

类型	说明
void \| Promise<void>	无返回值或者以Promise形式返回。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

示例：

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

workerInstance.addEventListener("alert", (event: Event) => {
  console.info("event type is: ", JSON.stringify(event.type));
});

workerInstance.dispatchEvent({ type: "alert", timeStamp: 0 }); // timeStamp暂未支持

GlobalScope⁹⁺

Worker线程自身的运行环境，GlobalScope类继承WorkerEventTarget。

属性

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

名称	类型	可读	可写	说明
name	string	是	否	Worker的名字，new Worker时指定。
self	GlobalScope & typeof globalThis	是	否	GlobalScope本身。

onerror⁹⁺

onerror?: (ev: ErrorEvent) => void

回调函数。GlobalScope的onerror属性表示Worker在执行过程中发生异常被调用的事件处理程序，处理程序在Worker线程中执行。其中回调函数中ev类型为ErrorEvent，表示收到的异常数据。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

示例：

// main thread
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

// worker.ets
import { worker, ErrorEvent } from '@kit.ArkTS';

const workerPort = worker.workerPort;
workerPort.onerror = (err: ErrorEvent) => {
    console.error("worker.ets onerror" + err.message);
}

MessageEvents⁹⁺

消息类，持有Worker线程间传递的数据。

原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

名称	类型	可读	可写	说明
data	any	是	否	线程间传递的数据。

MessageType⁷⁺

type MessageType = ‘message’|‘messageerror’;

表示消息类型。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

类型	说明
‘message’	表示消息类型为message，值固定为’message’字符串。
‘messageerror’	表示消息类型为messageerror，值固定为’messageerror’字符串。

ErrorCallback¹⁸⁺

type ErrorCallback = (err: ErrorEvent) => void

表示异常回调类型。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
err	ErrorEvent	是	错误事件类，用于表示Worker执行过程中出现异常的详细信息。

Worker^(deprecated)

使用以下方法前，均需先构造Worker实例，Worker类继承EventTarget。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker⁹⁺替代。

constructor^(deprecated)

constructor(scriptURL: string, options?: WorkerOptions)

Worker构造函数。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.constructor⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
scriptURL	string	是	Worker线程文件的路径，路径规则详细参考文件路径注意事项。
options	WorkerOptions	否	Worker构造的选项。

示例：

此处以在Stage模型的entry模块Index.ets文件中加载Worker文件为例，使用Library加载Worker线程文件的场景参考文件路径注意事项。

import { worker } from '@kit.ArkTS';

// worker文件所在路径："entry/src/main/ets/workers/worker.ets"
const workerInstance = new worker.Worker('entry/ets/workers/worker.ets', {name: "WorkerThread"});

postMessage^(deprecated)

postMessage(message: Object, transfer: ArrayBuffer[]): void

宿主线程通过转移对象所有权的方式向Worker线程发送消息。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.postMessage⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
message	Object	是	发送至Worker的数据，该数据对象必须是可序列化，序列化支持类型见其他说明。
transfer	ArrayBuffer[]	是	表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到Worker线程，在宿主线程中将会变为不可用，仅在Worker线程中可用，数组不可传入null。

示例：

const workerInstance = new worker.Worker("workers/worker.ets");

let buffer = new ArrayBuffer(8);
workerInstance.postMessage(buffer, [buffer]);

postMessage^(deprecated)

postMessage(message: Object, options?: PostMessageOptions): void

宿主线程通过转移对象所有权或者拷贝数据的方式向Worker线程发送消息。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.postMessage⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
message	Object	是	发送至Worker的数据，该数据对象必须是可序列化，序列化支持类型见其他说明。
options	PostMessageOptions	否	当填入该参数时，与传入ArrayBuffer[]的作用一致，该数组中对象的所有权会被转移到Worker线程，在宿主线程中将会变为不可用，仅在Worker线程中可用。若不填入该参数，默认设置为 undefined，通过拷贝数据的方式传输信息到Worker线程。

示例：

const workerInstance = new worker.Worker("workers/worker.ets");

workerInstance.postMessage("hello world");

let buffer = new ArrayBuffer(8);
workerInstance.postMessage(buffer, [buffer]);

on^(deprecated)

on(type: string, listener: EventListener): void

向Worker添加一个事件监听，该接口与addEventListener^(deprecated)接口功能一致。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.on⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
type	string	是	监听的事件类型。
listener	EventListener	是	回调事件。

示例：

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.on("alert", () => {
    console.info("alert listener callback");
})

once^(deprecated)

once(type: string, listener: EventListener): void

向Worker添加一个事件监听，事件监听只执行一次便自动删除。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.once⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
type	string	是	监听的事件类型。
listener	EventListener	是	回调事件。

示例：

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.once("alert", () => {
    console.info("alert listener callback");
})

off^(deprecated)

off(type: string, listener?: EventListener): void

删除类型为type的事件监听，该接口与removeEventListener^(deprecated)接口功能一致。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.off⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
type	string	是	需要删除的事件类型。
listener	EventListener	否	删除监听事件后所执行的回调事件。

示例：

const workerInstance = new worker.Worker("workers/worker.ets");
//使用on接口、once接口或addEventListener接口创建“alert”事件，使用off接口删除事件。
workerInstance.off("alert");

terminate^(deprecated)

terminate(): void

销毁Worker线程，终止Worker接收消息。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.terminate⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

示例：

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.terminate();

onexit^(deprecated)

onexit?: (code: number) => void

回调函数。表示Worker销毁时被调用的事件处理程序，处理程序在宿主线程中执行。其中回调函数中code类型为number，异常退出为1，正常退出为0。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.onexit⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

示例：

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.onexit = (code) => {
    console.info("onexit");
}

//onexit被执行两种方式：
//main thread：
workerInstance.terminate();

//worker线程：
//parentPort.close()

onerror^(deprecated)

onerror?: (err: ErrorEvent) => void

回调函数。表示Worker在执行过程中发生异常被调用的事件处理程序，处理程序在宿主线程中执行。其中回调函数中err类型为ErrorEvent，表示收到的异常数据。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.onerror⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

示例：

import { worker, ErrorEvent } from '@kit.ArkTS';

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.onerror = (err: ErrorEvent) => {
  console.error("onerror" + err.message);
}

onmessage^(deprecated)

onmessage?: (event: MessageEvent) => void

回调函数。表示宿主线程接收到来自其创建的Worker通过workerPort.postMessage接口发送的消息时被调用的事件处理程序，处理程序在宿主线程中执行。其中回调函数中event类型为MessageEvent，表示收到的Worker消息数据。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.onmessage⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

示例：

import { worker } from '@kit.ArkTS';

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.onmessage = (): void => {
    console.info("onmessage");
}

onmessageerror^(deprecated)

onmessageerror?: (event: MessageEvent) => void

回调函数。表示当Worker对象接收到一条无法被序列化的消息时被调用的事件处理程序，处理程序在宿主线程中执行。其中回调函数中event类型为MessageEvent，表示收到的Worker消息数据。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.onmessageerror⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

示例：

import { worker } from '@kit.ArkTS';

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.onmessageerror = (err) => {
    console.error("onmessageerror");
}

EventTarget^(deprecated)

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用WorkerEventTarget⁹⁺替代。

addEventListener^(deprecated)

addEventListener(type: string, listener: EventListener): void

向Worker添加一个事件监听，该接口与on^(deprecated)接口功能一致。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用addEventListener⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
type	string	是	监听的事件类型。
listener	EventListener	是	回调的事件。

示例：

// worker.ets
import { DedicatedWorkerGlobalScope, ErrorEvent, MessageEvents, worker } from '@kit.ArkTS';

const workerPort: DedicatedWorkerGlobalScope = worker.parentPort;

workerPort.addEventListener("alert", () => {
  console.info("alert listener callback");
})

removeEventListener^(deprecated)

removeEventListener(type: string, callback?: EventListener): void

删除Worker的事件监听，该接口与off^(deprecated)接口功能一致。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用removeEventListener⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
type	string	是	需要删除的监听事件类型。
callback	EventListener	否	删除监听事件后所执行的回调事件。

示例：

// worker.ets
import { DedicatedWorkerGlobalScope, ErrorEvent, MessageEvents, worker } from '@kit.ArkTS';

const workerPort: DedicatedWorkerGlobalScope = worker.parentPort;

workerPort.addEventListener("alert", () => {
  console.info("alert listener callback");
})

workerPort.removeEventListener('alert');

dispatchEvent^(deprecated)

dispatchEvent(event: Event): boolean

分发定义在Worker的事件。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用dispatchEvent⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
event	Event	是	需要分发的事件。

返回值：

类型	说明
boolean	分发的结果。true表示分发成功，false表示分发失败。

示例：

// worker.ets
import { DedicatedWorkerGlobalScope, ErrorEvent, MessageEvents, worker } from '@kit.ArkTS';

const workerPort: DedicatedWorkerGlobalScope = worker.parentPort;

workerPort.addEventListener("alert_add", ()=>{
  console.info("alert listener callback");
})

workerPort.dispatchEvent({type: 'alert_add', timeStamp: 0}); // timeStamp暂未支持

分发事件（dispatchEvent）可与监听接口（addEventListener）搭配使用，示例如下：

// main thread
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.postMessage("hello world");
workerInstance.onmessage = (): void => {
    console.info("receive data from worker.ets");
}

// worker.ets
import { DedicatedWorkerGlobalScope, ErrorEvent, MessageEvents, worker } from '@kit.ArkTS';

const workerPort: DedicatedWorkerGlobalScope = worker.parentPort;

workerPort.addEventListener("alert", ()=>{
  console.info("alert listener callback");
})

workerPort.onmessage = (event: MessageEvents) => {
  workerPort.dispatchEvent({type:"alert", timeStamp:0}); // timeStamp暂未支持
}

removeAllListener^(deprecated)

removeAllListener(): void

删除Worker所有的事件监听。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用removeAllListener⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

示例：

// worker.ets
import { DedicatedWorkerGlobalScope, ErrorEvent, MessageEvents, worker } from '@kit.ArkTS';

const workerPort: DedicatedWorkerGlobalScope = worker.parentPort;

workerPort.addEventListener("alert_add", ()=>{
  console.info("alert listener callback");
})

workerPort.removeAllListener();

DedicatedWorkerGlobalScope^(deprecated)

Worker线程用于与宿主线程通信的类，通过postMessage接口发送消息给宿主线程、close接口销毁Worker线程。DedicatedWorkerGlobalScope类继承WorkerGlobalScope。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorkerGlobalScope⁹⁺替代。

postMessage^(deprecated)

postMessage(messageObject: Object, transfer: Transferable[]): void

Worker线程通过转移对象所有权的方式向宿主线程发送消息。

说明：
此接口暂不支持使用，从API version 9开始废弃，建议使用ThreadWorkerGlobalScope⁹⁺.postMessage⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
messageObject	Object	是	发送至宿主线程的数据，该数据对象必须是可序列化，序列化支持类型见其他说明。
transfer	Transferable[]	是	暂不支持该参数类型。

postMessage^(deprecated)

postMessage(messageObject: Object, transfer: ArrayBuffer[]): void

Worker线程通过转移对象所有权的方式向宿主线程发送消息。

说明：
DedicatedWorkerGlobalScope类自API version 9开始废弃，本接口建议使用ThreadWorkerGlobalScope⁹⁺.postMessage⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
messageObject	Object	是	发送至宿主线程的数据，该数据对象必须是可序列化，序列化支持类型见其他说明。
transfer	ArrayBuffer[]	是	表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用，数组不可传入null。

示例：

// main thread
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.postMessage("hello world");
workerInstance.onmessage = (): void => {
    // let data = e.data;
    console.info("receive data from worker.ets");
}

// worker.ets
import { worker } from '@kit.ArkTS';

const workerPort = worker.workerPort;
workerPort.onmessage = (): void => {
    // let data = e.data;
    let buffer = new ArrayBuffer(5)
    workerPort.postMessage(buffer, [buffer]);
}

postMessage^(deprecated)

postMessage(messageObject: Object, options?: PostMessageOptions): void

Worker线程通过转移对象所有权或者拷贝数据的方式向宿主线程发送消息。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorkerGlobalScope⁹⁺.postMessage⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
messageObject	Object	是	发送至宿主线程的数据，该数据对象必须是可序列化，序列化支持类型见其他说明。
options	PostMessageOptions	否	当填入该参数时，与传入ArrayBuffer[]的作用一致，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用。若不填入该参数，默认设置为 undefined，通过拷贝数据的方式传输信息到宿主线程。

示例：

// main thread
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.Worker("entry/ets/workers/worker.ets");
workerInstance.postMessage("hello world");
workerInstance.onmessage = (): void => {
    console.info("receive data from worker.ets");
}

// worker.ets
import { ErrorEvent, MessageEvents, worker } from '@kit.ArkTS';

const parentPort = worker.parentPort;
parentPort.onmessage = (e: MessageEvents) => {
  parentPort.postMessage("receive data from main thread");
}

close^(deprecated)

close(): void

销毁Worker线程，终止Worker接收消息。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorkerGlobalScope⁹⁺.close⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

示例：

// main thread
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.Worker("workers/worker.ets");

// worker.ets
import { worker } from '@kit.ArkTS';

const parentPort = worker.parentPort;
parentPort.onmessage = (): void => {
    parentPort.close()
}

onmessage^(deprecated)

onmessage?: (this: DedicatedWorkerGlobalScope, ev: MessageEvent) => void

回调函数，DedicatedWorkerGlobalScope的onmessage属性表示Worker线程收到来自其宿主线程通过postMessage接口发送的消息时被调用的事件处理程序，处理程序在Worker线程中执行。其中this指调用者对象本身DedicatedWorkerGlobalScope，ev类型为MessageEvent，表示收到的Worker消息数据。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorkerGlobalScope⁹⁺.onmessage⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

示例：

// main thread
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.postMessage("hello world");

// worker.ets
import { worker } from '@kit.ArkTS';

const parentPort = worker.parentPort;
parentPort.onmessage = (): void => {
    console.info("receive main thread message");
}

onmessageerror^(deprecated)

onmessageerror?: (this: DedicatedWorkerGlobalScope, ev: MessageEvent) => void

DedicatedWorkerGlobalScope的onmessageerror属性表示当Worker对象接收到一条无法被反序列化的消息时被调用的事件处理程序，处理程序在Worker线程中执行。其中this指调用者对象本身DedicatedWorkerGlobalScope，ev类型为MessageEvent，表示收到的Worker消息数据。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorkerGlobalScope⁹⁺.onmessageerror⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

示例：

// main thread
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.Worker("workers/worker.ets");

// worker.ets
import { worker } from '@kit.ArkTS';

const parentPort = worker.parentPort;
parentPort.onmessageerror = () => {
    console.error("worker.ets onmessageerror")
}

PostMessageOptions

明确数据传递过程中需要转移所有权对象的类，传递所有权的对象必须是ArrayBuffer，发送它的上下文中将会变为不可用，仅在接收方可用。

原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

名称	类型	可读	可写	说明
transfer	Object[]	是	是	ArrayBuffer数组，用于传递所有权。该数组中不可传入null。

Event

事件类。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

名称	类型	可读	可写	说明
type	string	是	否	指定事件的类型。
timeStamp	number	是	否	事件创建时的时间戳（精度为毫秒），暂未支持。

EventListener^(deprecated)

事件监听类。

说明：

从API version 7开始支持，从API version 9开始废弃，建议使用WorkerEventListener⁹⁺替代。

(evt: Event)^(deprecated)

(evt: Event): void|Promise<void>

说明：

从API version 7开始支持，从API version 9开始废弃，建议使用(event:Event)⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
evt	Event	是	回调的事件类。

返回值：

类型	说明
void \| Promise<void>	无返回值或者以Promise形式返回。

示例：

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.addEventListener("alert", ()=>{
    console.info("alert listener callback");
})

ErrorEvent

错误事件类，用于表示Worker执行过程中出现异常的详细信息，ErrorEvent类继承Event。

原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

名称	类型	可读	可写	说明
message	string	是	否	异常发生的错误信息。
filename	string	是	否	出现异常所在的文件。
lineno	number	是	否	异常所在的行数。
colno	number	是	否	异常所在的列数。
error	Object	是	否	异常类型。

MessageEvent<T>

消息类，持有Worker线程间传递的数据。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Utils.Lang

名称	类型	可读	可写	说明
data	T	是	否	线程间传递的数据。

WorkerGlobalScope^(deprecated)

Worker线程自身的运行环境，WorkerGlobalScope类继承EventTarget。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用GlobalScope⁹⁺替代。

属性

系统能力： SystemCapability.Utils.Lang

名称	类型	可读	可写	说明
name	string	是	否	Worker的名字，new Worker时指定。
self	WorkerGlobalScope & typeof globalThis	是	否	WorkerGlobalScope本身。

onerror^(deprecated)

onerror?: (ev: ErrorEvent) => void

WorkerGlobalScope的onerror属性表示Worker在执行过程中发生异常被调用的事件处理程序，处理程序在Worker线程中执行。其中回调函数中ev类型为ErrorEvent，表示收到的异常数据。

说明：
从API version 7开始支持，从API version 9开始废弃，建议使用GlobalScope⁹⁺.onerror⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

示例：

// main thread
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.Worker("workers/worker.ets")

// worker.ets
import { worker, ErrorEvent } from '@kit.ArkTS';

const parentPort = worker.parentPort
parentPort.onerror = (err: ErrorEvent) => {
    console.error("worker.ets onerror" + err.message)
}

其他说明

序列化支持类型

序列化支持类型包括：除Symbol之外的基础类型、Date、String、RegExp、Array、Map、Set、Object（仅限简单对象，比如通过”{}“或者”new Object”创建，普通对象仅支持传递属性，不支持传递其原型及方法）、ArrayBuffer、TypedArray。

特例：传递通过自定义class创建出来的object时，不会发生序列化错误，但是自定义class的属性（如Function）无法通过序列化传递。 > 说明：
> 以API version 9的FA工程为例。

// main thread
import { worker, MessageEvents } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("workers/worker.ets");
workerInstance.postMessage("message from main thread to worker");
workerInstance.onmessage = (d: MessageEvents): void => {
  // 当worker线程传递obj2时，data即为obj2。data没有Init、SetName的方法
  let data: string  = d.data;
}

// worker.ets
import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS';

const workerPort = worker.workerPort;
class MyModel {
    name = "undefined";
    Init() {
        this.name = "MyModel";
    }
}
workerPort.onmessage = (d: MessageEvents): void => {
  console.info("worker.ets onmessage");
  let data: string = d.data;
  let func1 = () => {
    console.info("post message is function");
  }
  // workerPort.postMessage(func1); 传递func1发生序列化错误
  let obj2 = new MyModel();
  workerPort.postMessage(obj2);     // 传递obj2不会发生序列化错误
}
workerPort.onmessageerror = () => {
    console.error("worker.ets onmessageerror");
}
workerPort.onerror = (err: ErrorEvent) => {
    console.error("worker.ets onerror" + err.message);
}

内存模型

Worker基于Actor并发模型实现。在Worker的交互流程中，JS宿主线程可以创建多个Worker子线程，各个Worker线程间相互隔离，并通过序列化传递对象，等到Worker线程完成计算任务，再把结果返回给宿主线程。

Actor并发模型的交互原理：各个Actor并发地处理宿主线程任务，每个Actor内部都有一个消息队列和单线程执行模块。消息队列负责接收宿主线程及其他Actor的请求，而单线程执行模块则负责串行地处理这些请求、向其他Actor发送请求以及创建新的Actor。由于Actor采用的是异步方式，各个Actor之间相互隔离且没有数据竞争，因此Actor可以高并发运行。

完整示例

说明：
API version 8及之前的版本仅支持FA模型，如需使用，注意更换构造Worker的接口和创建Worker线程中与宿主线程通信的对象的两个方法。

FA模型

此处以API version 9的工程为例。

// main thread(同级目录为例)
import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS';

// 宿主线程中创建Worker对象
const workerInstance = new worker.ThreadWorker("workers/worker.ets");

// 宿主线程向worker线程传递信息
const buffer = new ArrayBuffer(8);
workerInstance.postMessage(buffer, [buffer]);

// 宿主线程接收worker线程信息
workerInstance.onmessage = (e: MessageEvents): void => {
    // data：worker线程发送的信息
    let data: string = e.data;
    console.info("main thread onmessage");

    // 销毁Worker对象
    workerInstance.terminate();
}

// 在调用terminate后，执行回调onexit
workerInstance.onexit = (code) => {
    console.info("main thread terminate");
}

workerInstance.onerror = (err: ErrorEvent) => {
    console.error("main error message " + err.message);
}

// worker.ets
import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS';

// 创建worker线程中与宿主线程通信的对象
const workerPort = worker.workerPort;

// worker线程接收宿主线程信息
workerPort.onmessage = (e: MessageEvents): void => {
    // data：宿主线程发送的信息
    let data: number = e.data;
    const view = new Int8Array(data).fill(3);
    console.info("worker.ets onmessage");

    // worker线程向宿主线程发送信息
    workerPort.postMessage(view);
}

// worker线程发生error的回调
workerPort.onerror = (err: ErrorEvent) => {
    console.error("worker.ets onerror");
}

在模块级entry/build-profile.json5配置文件添加如下配置:

  "buildOption": {
    "sourceOption": {
      "workers": [
        "./src/main/ets/entryability/workers/worker.ets"
      ]
    }
  }

Stage模型

此处以API version 18的工程为例。

// Index.ets
import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS';

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';
  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            // 宿主线程中创建Worker对象
            const workerInstance = new worker.ThreadWorker("entry/ets/workers/Worker.ets");
            // 宿主线程向worker线程传递信息
            const buffer = new ArrayBuffer(8);
            workerInstance.postMessage(buffer);
            // 宿主线程接收worker线程信息
            workerInstance.onmessage = (e: MessageEvents): void => {
              // data：worker线程发送的信息
              let data: number = e.data;
              console.info("main thread data is  " + data);
              // 销毁Worker对象
              workerInstance.terminate();
            }
            // 在调用terminate后，执行onexit
            workerInstance.onexit = (code) => {
              console.info("main thread terminate");
            }

            workerInstance.onAllErrors = (err: ErrorEvent) => {
              console.error("main error message " + err.message);
            }
          })
      }
      .width('100%')
      .height('100%')
    }
  }
}

// Worker.ets
import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS';

// 创建worker线程中与宿主线程通信的对象
const workerPort = worker.workerPort;

// worker线程接收宿主线程信息
workerPort.onmessage = (e: MessageEvents): void => {
  // data：宿主线程发送的信息
  let data: number = e.data;
  // 往收到的buffer里写入数据
  const view = new Int8Array(data).fill(3);
  // worker线程向宿主线程发送信息
  workerPort.postMessage(view);
}

// worker线程发生error的回调
workerPort.onerror = (err: ErrorEvent) => {
  console.error("worker.ets onerror" + err.message);
}

在模块级entry/build-profile.json5配置文件添加如下配置:

  "buildOption": {
    "sourceOption": {
      "workers": [
        "./src/main/ets/workers/Worker.ets"
      ]
    }
  }

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkTS（方舟编程语言）

harmony 鸿蒙编译工具链错误码

harmony 鸿蒙Typescript Compiler错误码介绍

harmony 鸿蒙语言基础类库错误码

harmony 鸿蒙js-apis-arkts-collections

harmony 鸿蒙js-apis-arkts-decimal

harmony 鸿蒙@arkts.lang (ArkTS语言基础能力)

harmony 鸿蒙@arkts.utils (ArkTS工具库)

harmony 鸿蒙@ohos.util.ArrayList (线性容器ArrayList)

harmony 鸿蒙@ohos.buffer (Buffer)

0 赞

所属分类： 后端技术
本文标签：
版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/5vYdNI

harmony 鸿蒙@ohos.worker (启动一个Worker)

@ohos.worker (启动一个Worker)

导入模块

属性

WorkerOptions

ThreadWorkerPriority18+

ThreadWorker9+

constructor9+

postMessage9+

postMessage9+

postMessageWithSharedSendable12+

on9+

once9+

off9+

registerGlobalCallObject11+

unregisterGlobalCallObject11+

terminate9+

onexit9+

onerror9+

onAllErrors18+

onmessage9+

onmessageerror9+

addEventListener9+

removeEventListener9+

dispatchEvent9+

removeAllListener9+

WorkerEventTarget9+

addEventListener9+

removeEventListener9+

dispatchEvent9+

removeAllListener9+

ThreadWorkerGlobalScope9+

postMessage9+

postMessage9+

postMessageWithSharedSendable12+

callGlobalCallObjectMethod11+

close9+

onmessage9+

onmessageerror9+

WorkerEventListener9+

(event: Event)9+

GlobalScope9+

属性

onerror9+

MessageEvents9+

MessageType7+

ErrorCallback18+

Worker(deprecated)

constructor(deprecated)

postMessage(deprecated)

postMessage(deprecated)

on(deprecated)

once(deprecated)

off(deprecated)

terminate(deprecated)

onexit(deprecated)

onerror(deprecated)

onmessage(deprecated)

onmessageerror(deprecated)

EventTarget(deprecated)

addEventListener(deprecated)

removeEventListener(deprecated)

dispatchEvent(deprecated)

removeAllListener(deprecated)

DedicatedWorkerGlobalScope(deprecated)

postMessage(deprecated)

postMessage(deprecated)

postMessage(deprecated)

close(deprecated)

onmessage(deprecated)

onmessageerror(deprecated)

PostMessageOptions

Event

EventListener(deprecated)

(evt: Event)(deprecated)

ErrorEvent

MessageEvent<T>

WorkerGlobalScope(deprecated)

属性

onerror(deprecated)

ThreadWorkerPriority¹⁸⁺

ThreadWorker⁹⁺

constructor⁹⁺

postMessage⁹⁺

postMessage⁹⁺

postMessageWithSharedSendable¹²⁺

on⁹⁺

once⁹⁺

off⁹⁺

registerGlobalCallObject¹¹⁺

unregisterGlobalCallObject¹¹⁺

terminate⁹⁺

onexit⁹⁺

onerror⁹⁺

onAllErrors¹⁸⁺

onmessage⁹⁺

onmessageerror⁹⁺

addEventListener⁹⁺

removeEventListener⁹⁺

dispatchEvent⁹⁺

removeAllListener⁹⁺

WorkerEventTarget⁹⁺

addEventListener⁹⁺

removeEventListener⁹⁺

dispatchEvent⁹⁺

removeAllListener⁹⁺

ThreadWorkerGlobalScope⁹⁺

postMessage⁹⁺

postMessage⁹⁺

postMessageWithSharedSendable¹²⁺

callGlobalCallObjectMethod¹¹⁺

close⁹⁺

onmessage⁹⁺

onmessageerror⁹⁺

WorkerEventListener⁹⁺

(event: Event)⁹⁺

GlobalScope⁹⁺

onerror⁹⁺

MessageEvents⁹⁺

MessageType⁷⁺

ErrorCallback¹⁸⁺

Worker^(deprecated)

constructor^(deprecated)

postMessage^(deprecated)

postMessage^(deprecated)

on^(deprecated)

once^(deprecated)

off^(deprecated)

terminate^(deprecated)

onexit^(deprecated)

onerror^(deprecated)

onmessage^(deprecated)

onmessageerror^(deprecated)

EventTarget^(deprecated)

addEventListener^(deprecated)

removeEventListener^(deprecated)

dispatchEvent^(deprecated)

removeAllListener^(deprecated)

DedicatedWorkerGlobalScope^(deprecated)

postMessage^(deprecated)

postMessage^(deprecated)

postMessage^(deprecated)

close^(deprecated)

onmessage^(deprecated)

onmessageerror^(deprecated)

EventListener^(deprecated)

(evt: Event)^(deprecated)

WorkerGlobalScope^(deprecated)

onerror^(deprecated)