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

2022-08-09
浏览 (1625)

@ohos.worker (启动一个Worker)

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

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

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

说明：
本模块首批接口从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执行脚本的路径。在FA和Stage模型下，DevEco Studio新建Worker工程路径分别存在以下两种情况： (a) worker脚本所在目录与pages目录同级。 (b) worker脚本所在目录与pages目录不同级。
options	WorkerOptions	否	Worker构造的选项。

返回值：

类型	说明
ThreadWorker	执行ThreadWorker构造函数生成的ThreadWorker对象，失败则返回undefined。

错误码：

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

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

示例：

import worker from '@ohos.worker';

// worker线程创建
// FA模型-目录同级（entry模块下，workers目录与pages目录同级）
const workerFAModel01 = new worker.ThreadWorker("workers/worker.ts", {name:"first worker in FA model"});
// FA模型-目录不同级（entry模块下，workers目录与pages目录的父目录同级）
const workerFAModel02 = new worker.ThreadWorker("../workers/worker.ts");

// Stage模型-目录同级（entry模块下，workers目录与pages目录同级）
const workerStageModel01 = new worker.ThreadWorker('entry/ets/workers/worker.ts', {name:"first worker in Stage model"});
// Stage模型-目录不同级（entry模块下，workers目录是pages目录的子目录）
const workerStageModel02 = new worker.ThreadWorker('entry/ets/pages/workers/worker.ts');

// 理解Stage模型scriptURL的"entry/ets/workers/worker.ts"：
// entry: 为module.json5文件中module的name属性对应的值，ets: 表明当前使用的语言。
// scriptURL与worker文件所在的workers目录层级有关，与new worker所在文件无关。

// Stage模型工程esmodule编译场景下，支持新增的scriptURL规格：@bundle:bundlename/entryname/ets/workerdir/workerfile
// @bundle:为固定标签，bundlename为当前应用包名，entryname为当前模块名，ets为当前使用语言
// workerdir为worker文件所在目录，workerfile为worker文件名
// Stage模型-目录同级（entry模块下，workers目录与pages目录同级），假设bundlename是com.example.workerdemo
const workerStageModel03 = new worker.ThreadWorker('@bundle:com.example.workerdemo/entry/ets/workers/worker');
// Stage模型-目录不同级（entry模块下，workers目录是pages目录的子目录），假设bundlename是com.example.workerdemo
const workerStageModel04 = new worker.ThreadWorker('@bundle:com.example.workerdemo/entry/ets/pages/workers/worker');

同时，需在工程的模块级build-profile.json5文件的buildOption属性中添加配置信息，主要分为下面两种情况：

(1) 目录同级

FA模型:

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

Stage模型:

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

(2) 目录不同级

FA模型:

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

Stage模型:

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

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.ts");

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.ts");

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

terminate⁹⁺

terminate(): void

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

系统能力： SystemCapability.Utils.Lang

错误码：

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

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

示例：

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

onexit⁹⁺

onexit?: (code: number) => void

Worker对象的onexit属性表示Worker销毁时被调用的事件处理程序，处理程序在宿主线程中执行。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
code	number	是	Worker退出的code。

错误码：

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

错误码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.ts");
workerInstance.onexit = () => {
 console.log("onexit");
}

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

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

onerror⁹⁺

onerror?: (err: ErrorEvent) => void

Worker对象的onerror属性表示Worker在执行过程中发生异常被调用的事件处理程序，处理程序在宿主线程中执行。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
err	ErrorEvent	是	异常数据。

错误码：

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

错误码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.ts");
workerInstance.onerror = () => {
    console.log("onerror");
}

onmessage⁹⁺

onmessage?: (event: MessageEvents) => void

Worker对象的onmessage属性表示宿主线程接收到来自其创建的Worker通过workerPort.postMessage接口发送的消息时被调用的事件处理程序，处理程序在宿主线程中执行。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
event	MessageEvents	是	收到的Worker消息数据。

错误码：

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

错误码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.ts");
workerInstance.onmessage = (e: MessageEvents): void => {
 // e : MessageEvents, 用法如下：
 // let data = e.data;
 console.log("onmessage");
}

onmessageerror⁹⁺

onmessageerror?: (event: MessageEvents) => void

Worker对象的onmessageerror属性表示当Worker对象接收到一条无法被序列化的消息时被调用的事件处理程序，处理程序在宿主线程中执行。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
event	MessageEvents	是	异常数据。

错误码：

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

错误码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.ts");
workerInstance.onmessageerror= () => {
    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.ts");
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.ts");
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.ts");

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.ts");

//用法一:
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.ts");
workerInstance.addEventListener("alert", (e)=>{
    console.log("alert listener callback");
})
workerInstance.removeAllListener();

WorkerEventTarget⁹⁺

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.ts");
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.ts");
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.ts");

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.ts");

//用法一:
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.ts");
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

参数：

参数名	类型	必填	说明
message	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.ts");
workerInstance.postMessage("hello world");
workerInstance.onmessage = (e: MessageEvents): void => {
    console.log("receive data from worker.ts");
}

// worker.ts
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

参数：

参数名	类型	必填	说明
message	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.ts");
workerInstance.postMessage("hello world");
workerInstance.onmessage = (e: MessageEvents): void => {
    console.log("receive data from worker.ts");
}

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

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

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.ts");

// worker.ts
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线程中执行。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
this	ThreadWorkerGlobalScope	是	指向调用者对象。
ev	MessageEvents	是	收到宿主线程发送的数据。

错误码：

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

错误码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.ts");
workerInstance.postMessage("hello world");

// worker.ts
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线程中执行。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
this	ThreadWorkerGlobalScope	是	指向调用者对象。
ev	MessageEvents	是	异常数据。

错误码：

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

错误码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.ts");

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

const workerPort = worker.workerPort;
workerPort.onmessageerror = () => {
    console.log("worker.ts 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.ts");
workerInstance.addEventListener("alert", ()=>{
    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线程中执行。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
ev	ErrorEvent	是	异常数据。

示例：

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

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

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

const workerPort = worker.workerPort
workerPort.onerror = () => {
    console.log("worker.ts onerror")
}

MessageEvents⁹⁺

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

系统能力： SystemCapability.Utils.Lang

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

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执行脚本的路径。在FA和Stage模型下，DevEco Studio新建Worker工程路径分别存在以下两种情况： (a) worker脚本所在目录与pages目录同级。 (b) worker脚本所在目录与pages目录不同级。
options	WorkerOptions	否	Worker构造的选项。

返回值：

类型	说明
Worker	执行Worker构造函数生成的Worker对象，失败则返回undefined。

示例：

import worker from '@ohos.worker';

// worker线程创建

// FA模型-目录同级
const workerFAModel01 = new worker.Worker("workers/worker.ts", {name:"first worker in FA model"});
// FA模型-目录不同级（以workers目录放置pages目录前一级为例）
const workerFAModel02 = new worker.Worker("../workers/worker.ts");

// Stage模型-目录同级
const workerStageModel01 = new worker.Worker('entry/ets/workers/worker.ts', {name:"first worker in Stage model"});
// Stage模型-目录不同级（以workers目录放置pages目录后一级为例）
const workerStageModel02 = new worker.Worker('entry/ets/pages/workers/worker.ts');

// 理解Stage模型scriptURL的"entry/ets/workers/worker.ts"：
// entry: 为module.json5文件中module的name属性对应的值；
// ets: 表明当前使用的语言。

同时，需在工程的模块级build-profile.json5文件的buildOption属性中添加配置信息，主要分为下面两种情况：

(1) 目录同级

FA模型:

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

Stage模型:

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

(2) 目录不同级

FA模型:

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

Stage模型:

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

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.ts");

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.ts");

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.ts");
workerInstance.on("alert", ()=>{
    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.ts");
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.ts");
//使用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.ts");
workerInstance.terminate();

onexit^(deprecated)

onexit?: (code: number) => void

Worker对象的onexit属性表示Worker销毁时被调用的事件处理程序，处理程序在宿主线程中执行。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
code	number	是	Worker退出的code。

示例：

const workerInstance = new worker.Worker("workers/worker.ts");
workerInstance.onexit = () => {
    console.log("onexit");
}

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

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

onerror^(deprecated)

onerror?: (err: ErrorEvent) => void

Worker对象的onerror属性表示Worker在执行过程中发生异常被调用的事件处理程序，处理程序在宿主线程中执行。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
err	ErrorEvent	是	异常数据。

示例：

const workerInstance = new worker.Worker("workers/worker.ts");
workerInstance.onerror = function() {
    console.log("onerror");
}

onmessage^(deprecated)

onmessage?: (event: MessageEvent) => void

Worker对象的onmessage属性表示宿主线程接收到来自其创建的Worker通过parentPort.postMessage接口发送的消息时被调用的事件处理程序，处理程序在宿主线程中执行。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
event	MessageEvent<T>	是	收到的Worker消息数据。

示例：

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

const workerInstance = new worker.Worker("workers/worker.ts");
workerInstance.onmessage = (e: MessageEvents): void => {
    console.log("onmessage");
}

onmessageerror^(deprecated)

onmessageerror?: (event: MessageEvent) => void

Worker对象的onmessageerror属性表示当Worker对象接收到一条无法被序列化的消息时被调用的事件处理程序，处理程序在宿主线程中执行。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
event	MessageEvent<T>	是	异常数据。

示例：

const workerInstance = new worker.Worker("workers/worker.ts");
workerInstance.onmessageerror= () => {
    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.ts");
workerInstance.addEventListener("alert", ()=>{
    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.ts");
workerInstance.addEventListener("alert", ()=>{
    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.ts");

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

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

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

//用法一:
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.ts");
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

参数：

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

示例：

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

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

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

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

参数：

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

示例：

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

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

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

const parentPort = worker.parentPort;
parentPort.onmessage = (e: MessageEvents): 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.ts");

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

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

onmessage^(deprecated)

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

DedicatedWorkerGlobalScope的onmessage属性表示Worker线程收到来自其宿主线程通过postMessage接口发送的消息时被调用的事件处理程序，处理程序在Worker线程中执行。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
this	DedicatedWorkerGlobalScope	是	指向调用者对象。
ev	MessageEvent<T>	是	收到宿主线程发送的数据。

示例：

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

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

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

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

onmessageerror^(deprecated)

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

DedicatedWorkerGlobalScope的onmessageerror属性表示当Worker对象接收到一条无法被反序列化的消息时被调用的事件处理程序，处理程序在Worker线程中执行。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
this	DedicatedWorkerGlobalScope	是	指向调用者对象。
ev	MessageEvent<T>	是	异常数据。

示例：

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

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

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

const parentPort = worker.parentPort;
parentPort.onmessageerror = () => {
    console.log("worker.ts 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.ts");
workerInstance.addEventListener("alert", ()=>{
    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线程中执行。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
ev	ErrorEvent	是	异常数据。

示例：

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

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

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

const parentPort = worker.parentPort
parentPort.onerror = () => {
    console.log("worker.ts onerror")
}

其他说明

序列化支持类型

序列化支持类型包括：除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.ts");
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.ts
import worker, { MessageEvents } from '@ohos.worker';

const workerPort = worker.workerPort;
class MyModel {
    name = "undefined"
    Init() {
        this.name = "MyModel"
    }
}
workerPort.onmessage = (d: MessageEvents): void => {
    console.log("worker.ts onmessage");
    let data: string = d.data;
    let func1 = () => {
        console.log("post message is function");
    }
    let obj1 = {
        "index": 2,
        "name1": "zhangshan",
        setName() {
            this.index = 3;
        }
    }
    let obj2 = new MyModel();
    // workerPort.postMessage(func1); 传递func1发生序列化错误
    // workerPort.postMessage(obj1);  传递obj1发生序列化错误
    workerPort.postMessage(obj2);     // 传递obj2不会发生序列化错误
}
workerPort.onmessageerror = () => {
    console.log("worker.ts onmessageerror");
}
workerPort.onerror = () => {
    console.log("worker.ts onerror");
}

内存模型

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

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

// 主线程向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 = () => {
    console.log("main thread terminate");
}

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

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

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

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

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

build-profile.json5 配置 :

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

Stage模型

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

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

// 主线程向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 = () => {
    console.log("main thread terminate");
}

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

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

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

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

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

build-profile.json5 配置:

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

你可能感兴趣的鸿蒙文章

harmony 鸿蒙接口

harmony 鸿蒙系统公共事件定义(待停用)

harmony 鸿蒙系统公共事件定义

harmony 鸿蒙开发说明

harmony 鸿蒙企业设备管理概述（仅对系统应用开放）

harmony 鸿蒙BundleStatusCallback

harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager模块)

harmony 鸿蒙@ohos.distributedBundle (分布式包管理)

harmony 鸿蒙@ohos.bundle (Bundle模块)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (企业设备管理扩展能力)

0 赞

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

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

@ohos.worker (启动一个Worker)

导入模块

属性

WorkerOptions

ThreadWorker9+

constructor9+

postMessage9+

postMessage9+

on9+

once9+

off9+

terminate9+

onexit9+

onerror9+

onmessage9+

onmessageerror9+

addEventListener9+

removeEventListener9+

dispatchEvent9+

removeAllListener9+

WorkerEventTarget9+

addEventListener9+

removeEventListener9+

dispatchEvent9+

removeAllListener9+

ThreadWorkerGlobalScope9+

postMessage9+

postMessage9+

close9+

onmessage9+

onmessageerror9+

WorkerEventListener9+

GlobalScope9+

属性

onerror9+

MessageEvents9+

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

terminate⁹⁺

onexit⁹⁺

onerror⁹⁺

onmessage⁹⁺

onmessageerror⁹⁺

addEventListener⁹⁺

removeEventListener⁹⁺

dispatchEvent⁹⁺

removeAllListener⁹⁺

WorkerEventTarget⁹⁺

addEventListener⁹⁺

removeEventListener⁹⁺

dispatchEvent⁹⁺

removeAllListener⁹⁺

ThreadWorkerGlobalScope⁹⁺

postMessage⁹⁺

postMessage⁹⁺

close⁹⁺

onmessage⁹⁺

onmessageerror⁹⁺

WorkerEventListener⁹⁺

GlobalScope⁹⁺

onerror⁹⁺

MessageEvents⁹⁺

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)