@ohos.worker (启动一个Worker)

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

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

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

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

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

导入模块

import worker from '@ohos.worker';

属性

系统能力： SystemCapability.Utils.Lang

名称	类型	可读	可写	说明
workerPort⁹⁺	ThreadWorkerGlobalScope	是	是	worker线程用于与宿主线程通信的对象。
parentPort^(deprecated)	DedicatedWorkerGlobalScope	是	是	worker线程用于与宿主线程通信的对象。此属性从API version 7开始支持,从API version 9 开始被废弃。建议使用workerPort⁹⁺替代。

WorkerOptions

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

系统能力： SystemCapability.Utils.Lang

名称	类型	只读	必填	说明
type	"classic" \| "module"	是	否	Worker执行脚本的模式类型，暂不支持module类型，默认值为"classic"。
name	string	是	否	Worker的名称，默认值为 undefined 。
shared	boolean	是	否	表示Worker共享功能，此接口暂不支持。

ThreadWorker⁹⁺

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

constructor⁹⁺

constructor(scriptURL: string, options?: WorkerOptions)

ThreadWorker构造函数。

系统能力： SystemCapability.Utils.Lang

参数：

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

错误码：

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

错误码ID	错误信息
10200003	Worker initialization failure.
10200007	The worker file patch is invalid path.

示例：

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

import worker from '@ohos.worker';

// 主要说明以下两种场景：

// 场景1： worker文件所在路径："entry/src/main/ets/workers/worker.ets"
const workerStageModel01 = new worker.ThreadWorker('entry/ets/workers/worker.ets', {name:"first worker in Stage model"});

// 场景2： worker文件所在路径："phone/src/main/ets/ThreadFile/workers/worker.ets"
const workerStageModel02 = new worker.ThreadWorker('phone/ets/ThreadFile/workers/worker.ets');

postMessage⁹⁺

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

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

系统能力： SystemCapability.Utils.Lang

参数：

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

错误码：

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

错误码ID	错误信息
10200004	Worker instance is not running.
10200006	An exception occurred during serialization.

示例：

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

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

postMessage⁹⁺

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

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

系统能力： SystemCapability.Utils.Lang

参数：

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

错误码：

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

错误码ID	错误信息
10200004	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);
workerInstance.postMessage(buffer, [buffer]);

on⁹⁺

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

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

系统能力： SystemCapability.Utils.Lang

参数：

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

错误码：

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

错误码ID	错误信息
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", (e)=>{
    console.log("alert listener callback");
})

once⁹⁺

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

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

系统能力： SystemCapability.Utils.Lang

参数：

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

错误码：

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

错误码ID	错误信息
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", (e)=>{
    console.log("alert listener callback");
})

off⁹⁺

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

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

系统能力： SystemCapability.Utils.Lang

参数：

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

错误码：

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

错误码ID	错误信息
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");
//使用on接口、once接口或addEventListener接口创建“alert”事件，使用off接口删除事件。
workerInstance.off("alert");

registerGlobalCallObject¹¹⁺

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

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

系统能力： SystemCapability.Utils.Lang

参数：

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

错误码：

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

错误码ID	错误信息
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();
// 在ThreadWorker实例上注册registerObj
workerInstance.registerGlobalCallObject("myObj", registerObj);
workerInstance.postMessage("start worker")

unregisterGlobalCallObject¹¹⁺

unregisterGlobalCallObject(instanceName?: string): void

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

系统能力： SystemCapability.Utils.Lang

参数：

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

错误码：

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

错误码ID	错误信息
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接收消息。

系统能力： SystemCapability.Utils.Lang

错误码：

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

错误码ID	错误信息
10200004	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。

系统能力： SystemCapability.Utils.Lang

错误码：

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

错误码ID	错误信息
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.onexit = (code) => {
 console.log("onexit");
}

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

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

onerror⁹⁺

onerror?: (err: ErrorEvent) => void

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

系统能力： SystemCapability.Utils.Lang

错误码：

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

错误码ID	错误信息
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

示例：

import worker, { ErrorEvent } from '@ohos.worker';

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

onmessage⁹⁺

onmessage?: (event: MessageEvents) => void

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

系统能力： SystemCapability.Utils.Lang

错误码：

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

错误码ID	错误信息
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

示例：

import worker, { MessageEvents } from '@ohos.worker';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.onmessage = (e: MessageEvents): void => {
 // e : MessageEvents, 用法如下：
 // let data = e.data;
 console.log("onmessage");
}

onmessageerror⁹⁺

onmessageerror?: (event: MessageEvents) => void

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

系统能力： SystemCapability.Utils.Lang

错误码：

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

错误码ID	错误信息
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

示例：

import worker, { MessageEvents } from '@ohos.worker';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.onmessageerror = (err: MessageEvents) => {
  console.log("onmessageerror");
}

addEventListener⁹⁺

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

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

系统能力： SystemCapability.Utils.Lang

参数：

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

错误码：

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

错误码ID	错误信息
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", (e)=>{
    console.log("alert listener callback");
})

removeEventListener⁹⁺

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

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

系统能力： SystemCapability.Utils.Lang

参数：

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

错误码：

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

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

示例：

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

dispatchEvent⁹⁺

dispatchEvent(event: Event): boolean

分发定义在Worker的事件。

系统能力： SystemCapability.Utils.Lang

参数：

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

返回值：

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

错误码：

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

错误码ID	错误信息
10200004	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 '@ohos.worker';

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

//用法一:
workerInstance.on("alert_on", (e)=>{
    console.log("alert listener callback");
})
workerInstance.once("alert_once", (e)=>{
    console.log("alert listener callback");
})
workerInstance.addEventListener("alert_add", (e)=>{
    console.log("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", (e)=>{
    console.log("message listener callback");
})
workerInstance.onmessage = (e: MessageEvents): void => {
    console.log("onmessage : message listener callback");
}
//调用dispatchEvent分发“message”事件，addEventListener和onmessage中定义的方法都会被执行。
workerInstance.dispatchEvent({type:"message", timeStamp:0});

removeAllListener⁹⁺

removeAllListener(): void

删除Worker所有的事件监听。

系统能力： SystemCapability.Utils.Lang

错误码：

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

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

示例：

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

WorkerEventTarget⁹⁺

处理Worker监听事件。

addEventListener⁹⁺

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

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

系统能力： SystemCapability.Utils.Lang

参数：

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

错误码：

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

错误码ID	错误信息
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", (e)=>{
    console.log("alert listener callback");
})

removeEventListener⁹⁺

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

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

系统能力： SystemCapability.Utils.Lang

参数：

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

错误码：

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

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

示例：

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

dispatchEvent⁹⁺

dispatchEvent(event: Event): boolean

分发定义在Worker的事件。

系统能力： SystemCapability.Utils.Lang

参数：

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

返回值：

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

错误码：

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

错误码ID	错误信息
10200004	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 '@ohos.worker';

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

//用法一:
workerInstance.on("alert_on", (e)=>{
    console.log("alert listener callback");
})
workerInstance.once("alert_once", (e)=>{
    console.log("alert listener callback");
})
workerInstance.addEventListener("alert_add", (e)=>{
    console.log("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", (e)=>{
    console.log("message listener callback");
})
workerInstance.onmessage = (e: MessageEvents): void => {
    console.log("onmessage : message listener callback");
}
//调用dispatchEvent分发“message”事件，addEventListener和onmessage中定义的方法都会被执行。
workerInstance.dispatchEvent({type:"message", timeStamp:0});

removeAllListener⁹⁺

removeAllListener(): void

删除Worker所有的事件监听。

系统能力： SystemCapability.Utils.Lang

错误码：

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

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

示例：

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

ThreadWorkerGlobalScope⁹⁺

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

postMessage⁹⁺

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

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

系统能力： SystemCapability.Utils.Lang

参数：

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

错误码：

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

错误码ID	错误信息
10200004	Worker instance is not running.
10200006	An exception occurred during serialization.

示例：

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

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

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

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线程通过转移对象所有权或者拷贝数据的方式向宿主线程发送消息。

系统能力： SystemCapability.Utils.Lang

参数：

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

错误码：

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

错误码ID	错误信息
10200004	Worker instance is not running.
10200006	An exception occurred during serialization.

示例：

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

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

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

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

callGlobalCallObjectMethod¹¹⁺

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

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

系统能力： SystemCapability.Utils.Lang

参数：

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

返回值：

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

错误码：

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

错误码ID	错误信息
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.

示例：

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

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接收消息。

系统能力： SystemCapability.Utils.Lang

错误码：

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

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

示例：

// main thread
import worker from '@ohos.worker';

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

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

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消息数据。

系统能力： SystemCapability.Utils.Lang

错误码：

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

错误码ID	错误信息
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

示例：

// main thread
import worker from '@ohos.worker';

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

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

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

onmessageerror⁹⁺

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

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

系统能力： SystemCapability.Utils.Lang

错误码：

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

错误码ID	错误信息
10200004	Worker instance is not running.
10200005	The invoked API is not supported in workers.

示例：

// main thread
import worker from '@ohos.worker';

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

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

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

WorkerEventListener⁹⁺

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

事件监听类。

系统能力： SystemCapability.Utils.Lang

参数：

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

返回值：

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

错误码：

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

错误码ID	错误信息
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", (e)=>{
    console.log("alert listener callback");
})

GlobalScope⁹⁺

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

属性

系统能力： SystemCapability.Utils.Lang

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

onerror⁹⁺

onerror?: (ev: ErrorEvent) => void

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

系统能力： SystemCapability.Utils.Lang

示例：

// main thread
import worker from '@ohos.worker';

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

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

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

MessageEvents⁹⁺

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

系统能力： SystemCapability.Utils.Lang

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

RestrictedWorker¹¹⁺

RestrictedWorker类继承ThreadWorker⁹⁺，具有ThreadWorker中所有的方法。 RestrictedWorker主要作用是提供受限的Worker线程运行环境，该线程运行环境中只允许导入Worker模块，不允许导入其他API。

constructor¹¹⁺

constructor(scriptURL: string, options?: WorkerOptions)

RestrictedWorker构造函数。使用以下方法前，均需先构造RestrictedWorker实例。

系统能力： SystemCapability.Utils.Lang

参数：

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

错误码：

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

错误码ID	错误信息
10200003	Worker initialization failure.
10200007	The worker file patch is invalid path.

示例：

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

受限的Worker线程文件只允许导入Worker模块，不允许导入任何其他API，以下为示例代码：

import worker from '@ohos.worker';

// 主要说明以下两种场景：

// 场景1： worker文件所在路径："entry/src/main/ets/workers/worker.ets"
const workerStageModel01 = new worker.RestrictedWorker('entry/ets/workers/worker.ets', {name:"first worker in Stage model"});

// 场景2： worker文件所在路径："phone/src/main/ets/ThreadFile/workers/worker.ets"
const workerStageModel02 = new worker.RestrictedWorker('phone/ets/ThreadFile/workers/worker.ets');

// 受限worker线程文件
import worker, { MessageEvents } from '@ohos.worker';

//import process from '@ohos.process'; // 受限Worker线程内不允许导入除了worker之外的API。

const workerPort = worker.workerPort;

workerPort.onmessage = (e : MessageEvents) : void => {
  console.info("worker:: This is worker thread.")
  //console.info("worker:: worker tid: " + process.tid) // 执行process.tid，主线程会有对应的TypeError报出。
}

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模型中Ability加载Worker文件为例，使用Library加载Worker线程文件的场景参考文件路径注意事项。

import worker from '@ohos.worker';

// 主要说明以下两种场景：

// 场景1： worker文件所在路径："entry/src/main/ets/workers/worker.ets"
const workerStageModel01 = new worker.ThreadWorker('entry/ets/workers/worker.ets', {name:"first worker in Stage model"});

// 场景2： worker文件所在路径："phone/src/main/ets/ThreadFile/workers/worker.ets"
const workerStageModel02 = new worker.ThreadWorker('phone/ets/ThreadFile/workers/worker.ets');

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", (e)=>{
    console.log("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", (e)=>{
    console.log("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.log("onexit");
}

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

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

onerror^(deprecated)

onerror?: (err: ErrorEvent) => void

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

系统能力： SystemCapability.Utils.Lang

示例：

import worker, { ErrorEvent } from '@ohos.worker';

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.onerror = (err: ErrorEvent) => {
  console.log("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 '@ohos.worker';

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.onmessage = (e): void => {
    console.log("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 '@ohos.worker';

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.onmessageerror = (err) => {
    console.log("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	是	回调的事件。

示例：

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.addEventListener("alert", (e)=>{
    console.log("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	否	删除监听事件后所执行的回调事件。

示例：

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

dispatchEvent^(deprecated)

dispatchEvent(event: Event): boolean

分发定义在Worker的事件。

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

系统能力： SystemCapability.Utils.Lang

参数：

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

返回值：

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

示例：

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

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

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

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

//用法一:
workerInstance.on("alert_on", (e)=>{
    console.log("alert listener callback");
})
workerInstance.once("alert_once", (e)=>{
    console.log("alert listener callback");
})
workerInstance.addEventListener("alert_add", (e)=>{
    console.log("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", (e)=>{
    console.log("message listener callback");
})
workerInstance.onmessage = function(e) {
    console.log("onmessage : message listener callback");
}
//调用dispatchEvent分发“message”事件，addEventListener和onmessage中定义的方法都会被执行。
workerInstance.dispatchEvent({type:"message", timeStamp:0});

removeAllListener^(deprecated)

removeAllListener(): void

删除Worker所有的事件监听。

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

系统能力： SystemCapability.Utils.Lang

示例：

const workerInstance = new worker.Worker("workers/worker.ets");
workerInstance.addEventListener("alert", (e)=>{
    console.log("alert listener callback");
})
workerInstance.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⁹⁺

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 '@ohos.worker';

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

// worker.ets
import worker from '@ohos.worker';

const workerPort = worker.workerPort;
workerPort.onmessage = (e): 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 '@ohos.worker';

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

// worker.ets
import worker from '@ohos.worker';

const parentPort = worker.parentPort;
parentPort.onmessage = (e): void => {
    // let data = e.data;
    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 '@ohos.worker';

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

// worker.ets
import workerfrom '@ohos.worker';

const parentPort = worker.parentPort;
parentPort.onmessage = (e): 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 '@ohos.worker';

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

// worker.ets
import worker from '@ohos.worker';

const parentPort = worker.parentPort;
parentPort.onmessage = (e): void => {
    console.log("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 '@ohos.worker';

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

// worker.ets
import worker from '@ohos.worker';

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

PostMessageOptions

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

系统能力： SystemCapability.Utils.Lang

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

Event

事件类。

系统能力： SystemCapability.Utils.Lang

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

EventListener^(deprecated)

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

事件监听类。

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

系统能力： SystemCapability.Utils.Lang

参数：

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

返回值：

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

示例：

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

ErrorEvent

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

系统能力： SystemCapability.Utils.Lang

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

MessageEvent<T>

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

系统能力： 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 '@ohos.worker';

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

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

const parentPort = worker.parentPort
parentPort.onerror = (err: ErrorEvent) => {
    console.log("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 '@ohos.worker';

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 '@ohos.worker';

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

内存模型

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

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

完整示例

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

FA模型

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

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

// 主线程向worker线程传递信息
workerInstance.postMessage("123");

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

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

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

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

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

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

// worker线程接收主线程信息
workerPort.onmessage = (e: MessageEvents): void => {
    // data：主线程发送的信息
    let data: string = e.data;
    console.log("worker.ets onmessage");

    // worker线程向主线程发送信息
    workerPort.postMessage("123")
}

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

build-profile.json5 配置 :

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

Stage模型

// main thread（以不同目录为例）
import worker, { MessageEvents, ErrorEvent } from '@ohos.worker';

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

// 主线程向worker线程传递信息
workerInstance.postMessage("123");

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

    // 销毁Worker对象
    workerInstance.terminate();
}
// 在调用terminate后，执行onexit
workerInstance.onexit = (code) => {
    console.log("main thread terminate");
}

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

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

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

// worker线程接收主线程信息
workerPort.onmessage = (e: MessageEvents): void => {
    // data：主线程发送的信息
    let data: string = e.data;
    console.log("worker.ets onmessage");

    // worker线程向主线程发送信息
    workerPort.postMessage("123")
}

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

build-profile.json5 配置:

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

@ohos.worker (启动一个Worker)

导入模块

属性

WorkerOptions

ThreadWorker9+

constructor9+

postMessage9+

postMessage9+

on9+

once9+

off9+

registerGlobalCallObject11+

unregisterGlobalCallObject11+

terminate9+

onexit9+

onerror9+

onmessage9+

onmessageerror9+

addEventListener9+

removeEventListener9+

dispatchEvent9+

removeAllListener9+

WorkerEventTarget9+

addEventListener9+

removeEventListener9+

dispatchEvent9+

removeAllListener9+

ThreadWorkerGlobalScope9+

postMessage9+

postMessage9+

callGlobalCallObjectMethod11+

close9+

onmessage9+

onmessageerror9+

WorkerEventListener9+

GlobalScope9+

属性

onerror9+

MessageEvents9+

RestrictedWorker11+

constructor11+

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)

postMessage9+

postMessage(deprecated)

close(deprecated)

onmessage(deprecated)

onmessageerror(deprecated)

PostMessageOptions

Event

EventListener(deprecated)

ErrorEvent

MessageEvent<T>

WorkerGlobalScope(deprecated)

属性

onerror(deprecated)

其他说明

序列化支持类型

内存模型

完整示例

FA模型

Stage模型

ThreadWorker⁹⁺

constructor⁹⁺

postMessage⁹⁺

postMessage⁹⁺

on⁹⁺

once⁹⁺

off⁹⁺

registerGlobalCallObject¹¹⁺

unregisterGlobalCallObject¹¹⁺

terminate⁹⁺

onexit⁹⁺

onerror⁹⁺

onmessage⁹⁺

onmessageerror⁹⁺

addEventListener⁹⁺

removeEventListener⁹⁺

dispatchEvent⁹⁺

removeAllListener⁹⁺

WorkerEventTarget⁹⁺

addEventListener⁹⁺

removeEventListener⁹⁺

dispatchEvent⁹⁺

removeAllListener⁹⁺

ThreadWorkerGlobalScope⁹⁺

postMessage⁹⁺

postMessage⁹⁺

callGlobalCallObjectMethod¹¹⁺

close⁹⁺

onmessage⁹⁺

onmessageerror⁹⁺

WorkerEventListener⁹⁺

GlobalScope⁹⁺

onerror⁹⁺

MessageEvents⁹⁺

RestrictedWorker¹¹⁺

constructor¹¹⁺

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⁹⁺

postMessage^(deprecated)

close^(deprecated)

onmessage^(deprecated)

onmessageerror^(deprecated)

EventListener^(deprecated)

WorkerGlobalScope^(deprecated)

onerror^(deprecated)