启动一个Worker

导入模块

import worker from '@ohos.worker';

属性

系统能力： SystemCapability.Utils.Lang

WorkerOptions

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

系统能力： SystemCapability.Utils.Lang

ThreadWorker9+

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

constructor9+

constructor(scriptURL: string, options?: WorkerOptions)

ThreadWorker构造函数。

系统能力： SystemCapability.Utils.Lang

参数：

返回值：

错误码：

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

示例：

import worker from '@ohos.worker';
// worker线程创建

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

// 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/MainAbility/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"
      ]
    }
  }

postMessage9+

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

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

系统能力： SystemCapability.Utils.Lang

参数：

错误码：

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

示例：

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

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

postMessage9+

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

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

系统能力： SystemCapability.Utils.Lang

参数：

错误码：

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

示例：

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

workerInstance.postMessage("hello world");

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

on9+

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

向Worker添加一个事件监听，该接口与addEventListener9+接口功能一致。

系统能力： SystemCapability.Utils.Lang

参数：

错误码：

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

示例：

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

once9+

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

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

系统能力： SystemCapability.Utils.Lang

参数：

错误码：

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

示例：

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

off9+

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

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

系统能力： SystemCapability.Utils.Lang

参数：

错误码：

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

示例：

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

terminate9+

terminate(): void

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

系统能力： SystemCapability.Utils.Lang

错误码：

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

示例：

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

onexit9+

onexit?: (code: number) => void

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

系统能力： SystemCapability.Utils.Lang

参数：

错误码：

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

示例：

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");
workerInstance.onexit = function(e) {
    console.log("onexit");
}

// onexit被执行两种方式：
// 主线程：
workerInstance.terminate();

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

onerror9+

onerror?: (err: ErrorEvent) => void

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

系统能力： SystemCapability.Utils.Lang

参数：

错误码：

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

示例：

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");
workerInstance.onerror = function(e) {
    console.log("onerror");
}

onmessage9+

onmessage?: (event: MessageEvents) => void

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

系统能力： SystemCapability.Utils.Lang

参数：

错误码：

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

示例：

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

onmessageerror9+

onmessageerror?: (event: MessageEvents) => void

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

系统能力： SystemCapability.Utils.Lang

参数：

错误码：

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

示例：

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");
workerInstance.onmessageerror= function(e) {
    console.log("onmessageerror");
}

addEventListener9+

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

向Worker添加一个事件监听，该接口与on9+接口功能一致。

系统能力： SystemCapability.Utils.Lang

参数：

错误码：

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

示例：

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

removeEventListener9+

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

删除Worker的事件监听，该接口与off9+接口功能一致。

系统能力： SystemCapability.Utils.Lang

参数：

错误码：

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

示例：

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

dispatchEvent9+

dispatchEvent(event: Event): boolean

分发定义在Worker的事件。

系统能力： SystemCapability.Utils.Lang

参数：

返回值：

错误码：

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

示例：

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

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

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

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

removeAllListener9+

removeAllListener(): void

删除Worker所有的事件监听。

系统能力： SystemCapability.Utils.Lang

错误码：

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

示例：

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

WorkerEventTarget9+

处理Worker监听事件。

addEventListener9+

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

向Worker添加一个事件监听，该接口与on9+接口功能一致。

系统能力： SystemCapability.Utils.Lang

参数：

错误码：

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

示例：

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

removeEventListener9+

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

删除Worker的事件监听，该接口与off9+接口功能一致。

系统能力： SystemCapability.Utils.Lang

参数：

错误码：

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

示例：

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

dispatchEvent9+

dispatchEvent(event: Event): boolean

分发定义在Worker的事件。

系统能力： SystemCapability.Utils.Lang

参数：

返回值：

错误码：

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

示例：

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

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

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

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

removeAllListener9+

removeAllListener(): void

删除Worker所有的事件监听。

系统能力： SystemCapability.Utils.Lang

错误码：

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

示例：

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

ThreadWorkerGlobalScope9+

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

postMessage9+

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

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

系统能力： SystemCapability.Utils.Lang

参数：

错误码：

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

示例：

// main.js
import worker from '@ohos.worker';
const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");
workerInstance.postMessage("hello world");
workerInstance.onmessage = function(e) {
    // let data = e.data;
    console.log("receive data from worker.js");
}

// worker.ts
import worker from '@ohos.worker';
const workerPort = worker.workerPort;
workerPort.onmessage = function(e){
    // let data = e.data;
    var buffer = new ArrayBuffer(8);
    workerPort.postMessage(buffer, [buffer]);
}

postMessage9+

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

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

系统能力： SystemCapability.Utils.Lang

参数：

错误码：

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

示例：

// main.js
import worker from '@ohos.worker';
const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");
workerInstance.postMessage("hello world");
workerInstance.onmessage = function(e) {
    // let data = e.data;
    console.log("receive data from worker.js");
}

// worker.ts
import worker from '@ohos.worker';
const workerPort = worker.workerPort;
workerPort.onmessage = function(e){
    // let data = e.data;
    workerPort.postMessage("receive data from main.js");
}

close9+

close(): void

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

系统能力： SystemCapability.Utils.Lang

错误码：

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

示例：

// main.js
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.onmessage = function(e) {
    workerPort.close()
}

onmessage9+

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

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

系统能力： SystemCapability.Utils.Lang

参数：

错误码：

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

示例：

// main.js
import worker from '@ohos.worker';
const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts");
workerInstance.postMessage("hello world");

// worker.ts
import worker from '@ohos.worker';
const workerPort = worker.workerPort;
workerPort.onmessage = function(e) {
    console.log("receive main.js message");
}

onmessageerror9+

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

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

系统能力： SystemCapability.Utils.Lang

参数：

错误码：

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

示例：

// main.js
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 = function(e) {
    console.log("worker.js onmessageerror")
}

WorkerEventListener9+

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

事件监听类。

系统能力： SystemCapability.Utils.Lang

参数：

返回值：

错误码：

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

示例：

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

GlobalScope9+

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

属性

系统能力： SystemCapability.Utils.Lang

onerror9+

onerror?: (ev: ErrorEvent) => void

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

系统能力： SystemCapability.Utils.Lang

参数：

示例：

// main.js
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 = function(e){
    console.log("worker.js onerror")
}

MessageEvents9+

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

系统能力： SystemCapability.Utils.Lang

Worker(deprecated)

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

constructor(deprecated)

constructor(scriptURL: string, options?: WorkerOptions)

Worker构造函数。

系统能力： SystemCapability.Utils.Lang

参数：

返回值：

示例：

import worker from '@ohos.worker';
// worker线程创建

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

// 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/MainAbility/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线程发送消息。

系统能力： SystemCapability.Utils.Lang

参数：

示例：

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

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

postMessage(deprecated)

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

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

系统能力： SystemCapability.Utils.Lang

参数：

示例：

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

workerInstance.postMessage("hello world");
var buffer = new ArrayBuffer(8); 
workerInstance.postMessage(buffer, [buffer]);

on(deprecated)

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

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

系统能力： SystemCapability.Utils.Lang

参数：

示例：

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

once(deprecated)

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

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

系统能力： SystemCapability.Utils.Lang

参数：

示例：

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

off(deprecated)

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

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

系统能力： SystemCapability.Utils.Lang

参数：

示例：

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

terminate(deprecated)

terminate(): void

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

系统能力： SystemCapability.Utils.Lang

示例：

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

onexit(deprecated)

onexit?: (code: number) => void

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

系统能力： SystemCapability.Utils.Lang

参数：

示例：

const workerInstance = new worker.Worker("workers/worker.js");
workerInstance.onexit = function(e) {
    console.log("onexit");
}

//onexit被执行两种方式：
//主线程：
workerInstance.terminate();

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

onerror(deprecated)

onerror?: (err: ErrorEvent) => void

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

系统能力： SystemCapability.Utils.Lang

参数：

示例：

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

onmessage(deprecated)

onmessage?: (event: MessageEvent) => void

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

系统能力： SystemCapability.Utils.Lang

参数：

示例：

const workerInstance = new worker.Worker("workers/worker.js");
workerInstance.onmessage = function(e) {
    // e : MessageEvent, 用法如下：
    // let data = e.data;
    console.log("onmessage");
}

onmessageerror(deprecated)

onmessageerror?: (event: MessageEvent) => void

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

系统能力： SystemCapability.Utils.Lang

参数：

示例：

const workerInstance = new worker.Worker("workers/worker.js");
workerInstance.onmessageerror= function(e) {
    console.log("onmessageerror");
}

EventTarget(deprecated)

addEventListener(deprecated)

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

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

系统能力： SystemCapability.Utils.Lang

参数：

示例：

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

removeEventListener(deprecated)

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

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

系统能力： SystemCapability.Utils.Lang

参数：

示例：

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

dispatchEvent(deprecated)

dispatchEvent(event: Event): boolean

分发定义在Worker的事件。

系统能力： SystemCapability.Utils.Lang

参数：

返回值：

示例：

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

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

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

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

//用法一:
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所有的事件监听。

系统能力： SystemCapability.Utils.Lang

示例：

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

DedicatedWorkerGlobalScope(deprecated)

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

postMessage9+

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

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

系统能力： SystemCapability.Utils.Lang

参数：

示例：

// main.js
import worker from '@ohos.worker';
const workerInstance = new worker.Worker("workers/worker.js");
workerInstance.postMessage("hello world");
workerInstance.onmessage = function(e) {
    // let data = e.data;
    console.log("receive data from worker.js");
}

// worker.js
import worker from '@ohos.worker';
const workerPort = worker.workerPort;
workerPort.onmessage = function(e){
    // let data = e.data;
    let buffer = new ArrayBuffer(5)
    workerPort.postMessage(buffer, [buffer]);
}

postMessage(deprecated)

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

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

系统能力： SystemCapability.Utils.Lang

参数：

postMessage(deprecated)

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

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

系统能力： SystemCapability.Utils.Lang

参数：

示例：

// main.js
import worker from '@ohos.worker';
const workerInstance = new worker.Worker("workers/worker.js");
workerInstance.postMessage("hello world");
workerInstance.onmessage = function(e) {
    // let data = e.data;
    console.log("receive data from worker.js");
}

// worker.js
import worker from '@ohos.worker';
const parentPort = worker.parentPort;
parentPort.onmessage = function(e){
    // let data = e.data;
    parentPort.postMessage("receive data from main.js");
}

close(deprecated)

close(): void

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

系统能力： SystemCapability.Utils.Lang

示例：

// main.js
import worker from '@ohos.worker';
const workerInstance = new worker.Worker("workers/worker.js");

// worker.js
import worker from '@ohos.worker';
const parentPort = worker.parentPort;
parentPort.onmessage = function(e) {
    parentPort.close()
}

onmessage(deprecated)

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

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

系统能力： SystemCapability.Utils.Lang

参数：

示例：

// main.js
import worker from '@ohos.worker';
const workerInstance = new worker.Worker("workers/worker.js");
workerInstance.postMessage("hello world");

// worker.js
import worker from '@ohos.worker';
const parentPort = worker.parentPort;
parentPort.onmessage = function(e) {
    console.log("receive main.js message");
}

onmessageerror(deprecated)

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

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

系统能力： SystemCapability.Utils.Lang

参数：

示例：

// main.js
import worker from '@ohos.worker';
const workerInstance = new worker.Worker("workers/worker.js");

// worker.js
import worker from '@ohos.worker';
const parentPort = worker.parentPort;
parentPort.onmessageerror = function(e) {
    console.log("worker.js onmessageerror")
}

PostMessageOptions

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

系统能力： SystemCapability.Utils.Lang

Event

事件类。

系统能力： SystemCapability.Utils.Lang

EventListener(deprecated)

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

事件监听类。

系统能力： SystemCapability.Utils.Lang

参数：

返回值：

示例：

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

ErrorEvent

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

系统能力： SystemCapability.Utils.Lang

MessageEvent<T>

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

系统能力： SystemCapability.Utils.Lang

WorkerGlobalScope(deprecated)

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

属性

系统能力： SystemCapability.Utils.Lang

onerror(deprecated)

onerror?: (ev: ErrorEvent) => void

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

系统能力： SystemCapability.Utils.Lang

参数：

示例：

// main.js
import worker from '@ohos.worker';
const workerInstance = new worker.Worker("workers/worker.js")

// worker.js
import worker from '@ohos.worker';
const parentPort = worker.parentPort
parentPort.onerror = function(e){
    console.log("worker.js onerror")
}

其他说明

序列化支持类型

特例：传递通过自定义class创建出来的object时，不会发生序列化错误，但是自定义class的属性（如Function）无法通过序列化传递。

// main.js
import worker from '@ohos.worker';
const workerInstance = new worker.ThreadWorker("workers/worker.js");
workerInstance.postMessage("message from main to worker");
workerInstance.onmessage = function(d) {
  // 当worker线程传递obj2时，data即为obj2。data没有Init、SetName的方法
  let data = d.data;
}

// worker.js
import worker from '@ohos.worker';
const workerPort = worker.workerPort;
class MyModel {
    name = "undefined"
    Init() {
        this.name = "MyModel"
    }
}
workerPort.onmessage = function(d) {
    console.log("worker.js onmessage");
    let data = d.data;
    let func1 = function() {
        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 = function(e) {
    console.log("worker.js onmessageerror");
}
workerPort.onerror = function(e) {
    console.log("worker.js onerror");
}

内存模型

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

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

注意事项

• Worker存在数量限制，当前支持最多同时存在8个Worker。
• 在API version 8及之前的版本，当Worker数量超出限制时，会抛出错误Error "Too many workers, the number of workers exceeds the maximum."。
• 从API version 9开始，当Worker数量超出限制时，会抛出错误BusinessError "Worker initialization failure, the number of workers exceeds the maximum."。
• 主动销毁Worker可以调用新创建Worker对象的terminate()或workerPort.close()方法。
• 自API version 9版本开始，若Worker处于已经销毁或正在销毁等非运行状态时，调用其功能接口，会抛出相应的BusinessError。
• Worker的创建和销毁耗费性能，建议管理已创建的Worker并重复使用。
• 创建Worker工程时，new worker.Worker构造函数和new worker.ThreadWorker构造函数不能同时使用，否则将导致工程中Worker的功能异常。自API version 9版本开始，建议使用new worker.ThreadWorker构造函数，在API version 8及之前的版本，建议使用new worker.Worker构造函数。
• 创建Worker工程时，在Worker线程的文件中（比如本文中worker.ts）不能导入任何有关构建UI的方法（比如ETS文件等），否则会导致Worker的功能失效。排查方式：解压生成的Hap包，在创建Worker线程的文件目录中找到"worker.js"，全局搜索"View"关键字。如果存在该关键字，说明在worker.js中打包进去了构建UI的方法，会导致Worker的功能失效，建议在创建Worker线程的文件中修改 "import “xxx” from src"中src的目录层级。
• 线程间通信时传递的数据量最大限制为16M。

完整示例

FA模型

// main.js(同级目录为例)
import worker from '@ohos.worker';
// 主线程中创建Worker对象
const workerInstance = new worker.ThreadWorker("workers/worker.ts");
// 创建js和ts文件都可以
// const workerInstance = new worker.ThreadWorker("workers/worker.js");

// API version 9之前版本，worker对象的构造方法
// const workerInstance = new worker.Worker("workers/worker.js");

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

// 主线程接收worker线程信息
workerInstance.onmessage = function(e) {
    // data：worker线程发送的信息
    let data = e.data;
    console.log("main.js onmessage");

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

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

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

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

// API version 9之前版本，创建worker线程中与主线程通信的对象
// const parentPort = worker.parentPort

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

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

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

build-profile.json5 配置 :

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

Stage模型

// main.js（以不同目录为例）
import worker from '@ohos.worker';

// 主线程中创建Worker对象
const workerInstance = new worker.ThreadWorker("entry/ets/pages/workers/worker.ts");
// 创建js和ts文件都可以
// const workerInstance = new worker.ThreadWorker("entry/ets/pages/workers/worker.js");

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

// 主线程接收worker线程信息
workerInstance.onmessage = function(e) {
    // data：worker线程发送的信息
    let data = e.data;
    console.log("main.js onmessage");

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

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

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

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

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

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

build-profile.json5 配置:

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