啟動一個Worker

導入模塊

import worker from '@ohos.worker';

屬性

系統(tǒng)能力： SystemCapability.Utils.Lang

WorkerOptions

Worker構造函數(shù)的選項信息，用于為Worker添加其他信息。

系統(tǒng)能力： SystemCapability.Utils.Lang

ThreadWorker9+

使用以下方法前，均需先構造ThreadWorker實例，ThreadWorker類繼承WorkerEventTarget。

constructor9+

constructor(scriptURL: string, options?: WorkerOptions)

ThreadWorker構造函數(shù)。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

返回值：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

import worker from '@ohos.worker';
// worker線程創(chuàng)建

// 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規(guī)格：@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

宿主線程通過轉(zhuǎn)移對象所有權的方式向Worker線程發(fā)送消息。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

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

宿主線程通過轉(zhuǎn)移對象所有權或者拷貝數(shù)據(jù)的方式向Worker線程發(fā)送消息。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

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添加一個事件監(jiān)聽，該接口與addEventListener9+接口功能一致。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

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添加一個事件監(jiān)聽，事件監(jiān)聽只執(zhí)行一次便自動刪除。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

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的事件監(jiān)聽，該接口與removeEventListener9+接口功能一致。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

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

terminate9+

terminate(): void

銷毀Worker線程，終止Worker接收消息。

系統(tǒng)能力： SystemCapability.Utils.Lang

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

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

onexit9+

onexit?: (code: number) => void

Worker對象的onexit屬性表示W(wǎng)orker銷毀時被調(diào)用的事件處理程序，處理程序在宿主線程中執(zhí)行。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

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

// onexit被執(zhí)行兩種方式：
// 主線程：
workerInstance.terminate();

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

onerror9+

onerror?: (err: ErrorEvent) => void

Worker對象的onerror屬性表示W(wǎng)orker在執(zhí)行過程中發(fā)生異常被調(diào)用的事件處理程序，處理程序在宿主線程中執(zhí)行。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

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

onmessage9+

onmessage?: (event: MessageEvents) => void

Worker對象的onmessage屬性表示宿主線程接收到來自其創(chuàng)建的Worker通過workerPort.postMessage接口發(fā)送的消息時被調(diào)用的事件處理程序，處理程序在宿主線程中執(zhí)行。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

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對象接收到一條無法被序列化的消息時被調(diào)用的事件處理程序，處理程序在宿主線程中執(zhí)行。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

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添加一個事件監(jiān)聽，該接口與on9+接口功能一致。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

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的事件監(jiān)聽，該接口與off9+接口功能一致。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

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

分發(fā)定義在Worker的事件。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

返回值：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

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

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

分發(fā)事件（dispatchEvent）可與監(jiān)聽接口（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接口創(chuàng)建的事件執(zhí)行一次便會刪除。
workerInstance.dispatchEvent({type:"alert_once", timeStamp:0});//timeStamp暫未支持。
//on接口創(chuàng)建的事件可以一直被分發(fā)，不能主動刪除。
workerInstance.dispatchEvent({type:"alert_on", timeStamp:0});
workerInstance.dispatchEvent({type:"alert_on", timeStamp:0});
//addEventListener接口創(chuàng)建的事件可以一直被分發(fā)，不能主動刪除。
workerInstance.dispatchEvent({type:"alert_add", timeStamp:0});
workerInstance.dispatchEvent({type:"alert_add", timeStamp:0});

//用法二:
//event類型的type支持自定義，同時存在"message"/"messageerror"/"error"特殊類型，如下所示
//當type = "message"，onmessage接口定義的方法同時會執(zhí)行。
//當type = "messageerror"，onmessageerror接口定義的方法同時會執(zhí)行。
//當type = "error"，onerror接口定義的方法同時會執(zhí)行。
//若調(diào)用removeEventListener接口或者off接口取消事件時，能且只能取消使用addEventListener/on/once創(chuàng)建的事件。

workerInstance.addEventListener("message", (e)=>{
    console.log("message listener callback");
})
workerInstance.onmessage = function(e) {
    console.log("onmessage : message listener callback");
}
//調(diào)用dispatchEvent分發(fā)“message”事件，addEventListener和onmessage中定義的方法都會被執(zhí)行。
workerInstance.dispatchEvent({type:"message", timeStamp:0});

removeAllListener9+

removeAllListener(): void

刪除Worker所有的事件監(jiān)聽。

系統(tǒng)能力： 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監(jiān)聽事件。

addEventListener9+

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

向Worker添加一個事件監(jiān)聽，該接口與on9+接口功能一致。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

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的事件監(jiān)聽，該接口與off9+接口功能一致。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

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

分發(fā)定義在Worker的事件。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

返回值：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

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

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

分發(fā)事件（dispatchEvent）可與監(jiān)聽接口（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接口創(chuàng)建的事件執(zhí)行一次便會刪除。
workerInstance.dispatchEvent({type:"alert_once", timeStamp:0});//timeStamp暫未支持。
//on接口創(chuàng)建的事件可以一直被分發(fā)，不能主動刪除。
workerInstance.dispatchEvent({type:"alert_on", timeStamp:0});
workerInstance.dispatchEvent({type:"alert_on", timeStamp:0});
//addEventListener接口創(chuàng)建的事件可以一直被分發(fā)，不能主動刪除。
workerInstance.dispatchEvent({type:"alert_add", timeStamp:0});
workerInstance.dispatchEvent({type:"alert_add", timeStamp:0});

//用法二:
//event類型的type支持自定義，同時存在"message"/"messageerror"/"error"特殊類型，如下所示
//當type = "message"，onmessage接口定義的方法同時會執(zhí)行。
//當type = "messageerror"，onmessageerror接口定義的方法同時會執(zhí)行。
//當type = "error"，onerror接口定義的方法同時會執(zhí)行。
//若調(diào)用removeEventListener接口或者off接口取消事件時，能且只能取消使用addEventListener/on/once創(chuàng)建的事件。

workerInstance.addEventListener("message", (e)=>{
    console.log("message listener callback");
})
workerInstance.onmessage = function(e) {
    console.log("onmessage : message listener callback");
}
//調(diào)用dispatchEvent分發(fā)“message”事件，addEventListener和onmessage中定義的方法都會被執(zhí)行。
workerInstance.dispatchEvent({type:"message", timeStamp:0});

removeAllListener9+

removeAllListener(): void

刪除Worker所有的事件監(jiān)聽。

系統(tǒng)能力： 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接口發(fā)送消息給宿主線程、close接口銷毀Worker線程。ThreadWorkerGlobalScope類繼承GlobalScope9+。

postMessage9+

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

Worker線程通過轉(zhuǎn)移對象所有權的方式向宿主線程發(fā)送消息。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

// 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線程通過轉(zhuǎn)移對象所有權或者拷貝數(shù)據(jù)的方式向宿主線程發(fā)送消息。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

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

系統(tǒng)能力： 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屬性表示W(wǎng)orker線程收到來自其宿主線程通過postMessage接口發(fā)送的消息時被調(diào)用的事件處理程序，處理程序在Worker線程中執(zhí)行。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

// 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對象接收到一條無法被反序列化的消息時被調(diào)用的事件處理程序，處理程序在Worker線程中執(zhí)行。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

// 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>

事件監(jiān)聽類。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

返回值：

錯誤碼：

以下錯誤碼的詳細介紹請參見語言基礎類庫錯誤碼。

示例：

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

GlobalScope9+

Worker線程自身的運行環(huán)境，GlobalScope類繼承WorkerEventTarget。

屬性

系統(tǒng)能力： SystemCapability.Utils.Lang

onerror9+

onerror?: (ev: ErrorEvent) => void

GlobalScope的onerror屬性表示W(wǎng)orker在執(zhí)行過程中發(fā)生異常被調(diào)用的事件處理程序，處理程序在Worker線程中執(zhí)行。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

示例：

// 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線程間傳遞的數(shù)據(jù)。

系統(tǒng)能力： SystemCapability.Utils.Lang

Worker(deprecated)

使用以下方法前，均需先構造Worker實例，Worker類繼承EventTarget。

constructor(deprecated)

constructor(scriptURL: string, options?: WorkerOptions)

Worker構造函數(shù)。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

返回值：

示例：

import worker from '@ohos.worker';
// worker線程創(chuàng)建

// 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

宿主線程通過轉(zhuǎn)移對象所有權的方式向Worker線程發(fā)送消息。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

示例：

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

宿主線程通過轉(zhuǎn)移對象所有權或者拷貝數(shù)據(jù)的方式向Worker線程發(fā)送消息。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

示例：

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添加一個事件監(jiān)聽，該接口與addEventListener(deprecated)接口功能一致。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

示例：

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添加一個事件監(jiān)聽，事件監(jiān)聽只執(zhí)行一次便自動刪除。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

示例：

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的事件監(jiān)聽，該接口與removeEventListener(deprecated)接口功能一致。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

示例：

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

terminate(deprecated)

terminate(): void

銷毀Worker線程，終止Worker接收消息。

系統(tǒng)能力： SystemCapability.Utils.Lang

示例：

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

onexit(deprecated)

onexit?: (code: number) => void

Worker對象的onexit屬性表示W(wǎng)orker銷毀時被調(diào)用的事件處理程序，處理程序在宿主線程中執(zhí)行。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

示例：

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

//onexit被執(zhí)行兩種方式：
//主線程：
workerInstance.terminate();

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

onerror(deprecated)

onerror?: (err: ErrorEvent) => void

Worker對象的onerror屬性表示W(wǎng)orker在執(zhí)行過程中發(fā)生異常被調(diào)用的事件處理程序，處理程序在宿主線程中執(zhí)行。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

示例：

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

onmessage(deprecated)

onmessage?: (event: MessageEvent) => void

Worker對象的onmessage屬性表示宿主線程接收到來自其創(chuàng)建的Worker通過parentPort.postMessage接口發(fā)送的消息時被調(diào)用的事件處理程序，處理程序在宿主線程中執(zhí)行。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

示例：

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對象接收到一條無法被序列化的消息時被調(diào)用的事件處理程序，處理程序在宿主線程中執(zhí)行。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

示例：

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添加一個事件監(jiān)聽，該接口與on(deprecated)接口功能一致。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

示例：

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的事件監(jiān)聽，該接口與off(deprecated)接口功能一致。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

示例：

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

分發(fā)定義在Worker的事件。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

返回值：

示例：

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

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

分發(fā)事件（dispatchEvent）可與監(jiān)聽接口（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接口創(chuàng)建的事件執(zhí)行一次便會刪除。
workerInstance.dispatchEvent({type:"alert_once", timeStamp:0});//timeStamp暫未支持。
//on接口創(chuàng)建的事件可以一直被分發(fā)，不能主動刪除。
workerInstance.dispatchEvent({type:"alert_on", timeStamp:0});
workerInstance.dispatchEvent({type:"alert_on", timeStamp:0});
//addEventListener接口創(chuàng)建的事件可以一直被分發(fā)，不能主動刪除。
workerInstance.dispatchEvent({type:"alert_add", timeStamp:0});
workerInstance.dispatchEvent({type:"alert_add", timeStamp:0});

//用法二:
//event類型的type支持自定義，同時存在"message"/"messageerror"/"error"特殊類型，如下所示
//當type = "message"，onmessage接口定義的方法同時會執(zhí)行。
//當type = "messageerror"，onmessageerror接口定義的方法同時會執(zhí)行。
//當type = "error"，onerror接口定義的方法同時會執(zhí)行。
//若調(diào)用removeEventListener接口或者off接口取消事件時，能且只能取消使用addEventListener/on/once創(chuàng)建的事件。

workerInstance.addEventListener("message", (e)=>{
    console.log("message listener callback");
})
workerInstance.onmessage = function(e) {
    console.log("onmessage : message listener callback");
}
//調(diào)用dispatchEvent分發(fā)“message”事件，addEventListener和onmessage中定義的方法都會被執(zhí)行。
workerInstance.dispatchEvent({type:"message", timeStamp:0});

removeAllListener(deprecated)

removeAllListener(): void

刪除Worker所有的事件監(jiān)聽。

系統(tǒng)能力： 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接口發(fā)送消息給宿主線程、close接口銷毀Worker線程。DedicatedWorkerGlobalScope類繼承WorkerGlobalScope。

postMessage9+

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

Worker線程通過轉(zhuǎn)移對象所有權的方式向宿主線程發(fā)送消息。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

示例：

// 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線程通過轉(zhuǎn)移對象所有權的方式向宿主線程發(fā)送消息。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

postMessage(deprecated)

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

Worker線程通過轉(zhuǎn)移對象所有權或者拷貝數(shù)據(jù)的方式向宿主線程發(fā)送消息。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

示例：

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

系統(tǒng)能力： 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屬性表示W(wǎng)orker線程收到來自其宿主線程通過postMessage接口發(fā)送的消息時被調(diào)用的事件處理程序，處理程序在Worker線程中執(zhí)行。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

示例：

// 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對象接收到一條無法被反序列化的消息時被調(diào)用的事件處理程序，處理程序在Worker線程中執(zhí)行。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

示例：

// 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

明確數(shù)據(jù)傳遞過程中需要轉(zhuǎn)移所有權對象的類，傳遞所有權的對象必須是ArrayBuffer，發(fā)送它的上下文中將會變?yōu)椴豢捎茫瑑H在接收方可用。

系統(tǒng)能力： SystemCapability.Utils.Lang

Event

事件類。

系統(tǒng)能力： SystemCapability.Utils.Lang

EventListener(deprecated)

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

事件監(jiān)聽類。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

返回值：

示例：

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

ErrorEvent

錯誤事件類，用于表示W(wǎng)orker執(zhí)行過程中出現(xiàn)異常的詳細信息，ErrorEvent類繼承Event。

系統(tǒng)能力： SystemCapability.Utils.Lang

MessageEvent<T>

消息類，持有Worker線程間傳遞的數(shù)據(jù)。

系統(tǒng)能力： SystemCapability.Utils.Lang

WorkerGlobalScope(deprecated)

Worker線程自身的運行環(huán)境，WorkerGlobalScope類繼承EventTarget。

屬性

系統(tǒng)能力： SystemCapability.Utils.Lang

onerror(deprecated)

onerror?: (ev: ErrorEvent) => void

WorkerGlobalScope的onerror屬性表示W(wǎng)orker在執(zhí)行過程中發(fā)生異常被調(diào)用的事件處理程序，處理程序在Worker線程中執(zhí)行。

系統(tǒng)能力： SystemCapability.Utils.Lang

參數(shù)：

示例：

// 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創(chuàng)建出來的object時，不會發(fā)生序列化錯誤，但是自定義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發(fā)生序列化錯誤
    // workerPort.postMessage(obj1);  傳遞obj1發(fā)生序列化錯誤
    workerPort.postMessage(obj2);     // 傳遞obj2不會發(fā)生序列化錯誤
}
workerPort.onmessageerror = function(e) {
    console.log("worker.js onmessageerror");
}
workerPort.onerror = function(e) {
    console.log("worker.js onerror");
}

內(nèi)存模型

Worker基于Actor并發(fā)模型實現(xiàn)。在Worker的交互流程中，JS主線程可以創(chuàng)建多個Worker子線程，各個Worker線程間相互隔離，并通過序列化傳遞對象，等到Worker線程完成計算任務，再把結(jié)果返回給主線程。

Actor并發(fā)模型的交互原理：各個Actor并發(fā)地處理主線程任務，每個Actor內(nèi)部都有一個消息隊列及單線程執(zhí)行模塊，消息隊列負責接收主線程及其他Actor的請求，單線程執(zhí)行模塊則負責串行地處理請求、向其他Actor發(fā)送請求以及創(chuàng)建新的Actor。由于Actor采用的是異步方式，各個Actor之間相互隔離沒有數(shù)據(jù)競爭，因此Actor可以高并發(fā)運行。

注意事項

• Worker存在數(shù)量限制，當前支持最多同時存在8個Worker。
• 在API version 8及之前的版本，當Worker數(shù)量超出限制時，會拋出錯誤Error "Too many workers, the number of workers exceeds the maximum."。
• 從API version 9開始，當Worker數(shù)量超出限制時，會拋出錯誤BusinessError "Worker initialization failure, the number of workers exceeds the maximum."。
• 主動銷毀Worker可以調(diào)用新創(chuàng)建Worker對象的terminate()或workerPort.close()方法。
• 自API version 9版本開始，若Worker處于已經(jīng)銷毀或正在銷毀等非運行狀態(tài)時，調(diào)用其功能接口，會拋出相應的BusinessError。
• Worker的創(chuàng)建和銷毀耗費性能，建議管理已創(chuàng)建的Worker并重復使用。
• 創(chuàng)建Worker工程時，new worker.Worker構造函數(shù)和new worker.ThreadWorker構造函數(shù)不能同時使用，否則將導致工程中Worker的功能異常。自API version 9版本開始，建議使用new worker.ThreadWorker構造函數(shù)，在API version 8及之前的版本，建議使用new worker.Worker構造函數(shù)。
• 創(chuàng)建Worker工程時，在Worker線程的文件中（比如本文中worker.ts）不能導入任何有關構建UI的方法（比如ETS文件等），否則會導致Worker的功能失效。排查方式：解壓生成的Hap包，在創(chuàng)建Worker線程的文件目錄中找到"worker.js"，全局搜索"View"關鍵字。如果存在該關鍵字，說明在worker.js中打包進去了構建UI的方法，會導致Worker的功能失效，建議在創(chuàng)建Worker線程的文件中修改 "import “xxx” from src"中src的目錄層級。
• 線程間通信時傳遞的數(shù)據(jù)量最大限制為16M。

完整示例

FA模型

// main.js(同級目錄為例)
import worker from '@ohos.worker';
// 主線程中創(chuàng)建Worker對象
const workerInstance = new worker.ThreadWorker("workers/worker.ts");
// 創(chuàng)建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線程發(fā)送的信息
    let data = e.data;
    console.log("main.js onmessage");

    // 銷毀Worker對象
    workerInstance.terminate();
}

// 在調(diào)用terminate后，執(zhí)行回調(diào)onexit
workerInstance.onexit = function() {
    console.log("main.js terminate");
}

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

// 創(chuàng)建worker線程中與主線程通信的對象
const workerPort = worker.workerPort

// API version 9之前版本，創(chuàng)建worker線程中與主線程通信的對象
// const parentPort = worker.parentPort

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

    // worker線程向主線程發(fā)送信息
    workerPort.postMessage("123")
}

// worker線程發(fā)生error的回調(diào)
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';

// 主線程中創(chuàng)建Worker對象
const workerInstance = new worker.ThreadWorker("entry/ets/pages/workers/worker.ts");
// 創(chuàng)建js和ts文件都可以
// const workerInstance = new worker.ThreadWorker("entry/ets/pages/workers/worker.js");

// 主線程向worker線程傳遞信息
workerInstance.postMessage("123");

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

    // 銷毀Worker對象
    workerInstance.terminate();
}
// 在調(diào)用terminate后，執(zhí)行onexit
workerInstance.onexit = function() {
    console.log("main.js terminate");
}

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

// 創(chuàng)建worker線程中與主線程通信的對象
const workerPort = worker.workerPort

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

    // worker線程向主線程發(fā)送信息
    workerPort.postMessage("123")
}

// worker線程發(fā)生error的回調(diào)
workerPort.onerror= function(e) {
    console.log("worker.ts onerror");
}

build-profile.json5 配置:

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