diff --git a/zh-cn/application-dev/reference/apis/js-apis-worker.md b/zh-cn/application-dev/reference/apis/js-apis-worker.md index 5d1ffcb5c93d07f308505ff2c0de219101ddc49c..483a26e968c80663a800b432589434dd0e4440c9 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-worker.md +++ b/zh-cn/application-dev/reference/apis/js-apis-worker.md @@ -16,9 +16,10 @@ import worker from '@ohos.worker'; **系统能力：** SystemCapability.Utils.Lang -| 名称 | 参数类型 | 可读 | 可写 | 说明 | -| ---------- | --------------------------------------------------------- | ---- | ---- | ------------------------------------ | -| parentPort | [DedicatedWorkerGlobalScope](#dedicatedworkerglobalscope) | 是 | 是 | worker线程用于与宿主线程通信的对象。 | +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| --------------------------------- | --------------------------------------------------------- | ---- | ---- | ------------------------------------------------------------ | +| workerPort9+ | [ThreadWorkerGlobalScope](#threadworkerglobalscope9) | 是 | 是 | worker线程用于与宿主线程通信的对象。 | +| parentPort(deprecated) | [DedicatedWorkerGlobalScope](#dedicatedworkerglobalscope) | 是 | 是 | worker线程用于与宿主线程通信的对象。
此属性从api9开始被废弃，建议使用workerPort9+。 | ## WorkerOptions @@ -27,17 +28,641 @@ Worker构造函数的选项信息，用于为Worker添加其他信息。 **系统能力：** SystemCapability.Utils.Lang -| 名称 | 参数类型 | 可读 | 可写 | 说明 | -| ------ | --------- | ---- | ---- | ---------------------- | -| name | string | 是 | 是 | Worker的名称。 | +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| ---- | -------- | ---- | ---- | -------------- | +| name | string | 是 | 是 | Worker的名称。 | -## Worker +## ThreadWorker9+ + +使用以下方法前，均需先构造Worker实例，Worker类继承[WorkerEventTarget](#workereventtarget9)。 + +### constructor9+ + +constructor(scriptURL: string, options?: WorkerOptions) + +Worker构造函数。 + +**系统能力：** SystemCapability.Utils.Lang + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------------- | ---- | ------------------------------------------------------------ | +| scriptURL | string | 是 | Worker执行脚本的路径。
在FA和Stage模型下，DevEco Studio新建Worker工程路径分别存在以下两种情况：
(a) worker脚本所在目录与pages目录同级。
(b) worker脚本所在目录与pages目录不同级。 | +| options | [WorkerOptions](#workeroptions) | 否 | Worker构造的选项。 | + +**返回值：** + +| 类型 | 说明 | +| ------ | --------------------------------------------------------- | +| Worker | 执行Worker构造函数生成的Worker对象，失败则返回undefined。 | + +**示例：** + +```js +import worker from '@ohos.worker'; +// worker线程创建 + +// FA模型-目录同级 +const workerFAModel01 = new worker.ThreadWorker("workers/worker.js", {name:"first worker in FA model"}); +// FA模型-目录不同级（以workers目录放置pages目录前一级为例） +const workerFAModel02 = new worker.ThreadWorker("../workers/worker.js"); + +// Stage模型-目录同级 +const workerStageModel01 = new worker.ThreadWorker('entry/ets/workers/worker.ts', {name:"first worker in Stage model"}); +// Stage模型-目录不同级（以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: 表明当前使用的语言。 +``` + +同时，需在工程的模块级build-profile.json5文件的buildOption属性中添加配置信息，主要分为下面两种情况： + +(1) 目录同级 + +FA模型: + +```json + "buildOption": { + "sourceOption": { + "workers": [ + "./src/main/ets/MainAbility/workers/worker.ts" + ] + } + } +``` + +Stage模型: + +```json + "buildOption": { + "sourceOption": { + "workers": [ + "./src/main/ets/workers/worker.ts" + ] + } + } +``` + +(2) 目录不同级 + +FA模型: + +```json + "buildOption": { + "sourceOption": { + "workers": [ + "./src/main/ets/workers/worker.ts" + ] + } + } +``` + +Stage模型: + +```json + "buildOption": { + "sourceOption": { + "workers": [ + "./src/main/ets/pages/workers/worker.ts" + ] + } + } +``` + + +### postMessage9+ + +postMessage(message: Object, options?: PostMessageOptions): void + +向Worker线程发送数据，数据类型必须是序列化所支持的类型。序列化支持类型见其他说明。 + +**系统能力：** SystemCapability.Utils.Lang + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | +| message | Object | 是 | 发送至Worker的数据。 | +| options | [PostMessageOptions](#postmessageoptions) | 否 | 可转移对象是 ArrayBuffer 的实例对象。transferList数组中不可传入null。 | + +**示例：** + +```js +const workerInstance = new worker.ThreadWorker("workers/worker.js"); + +workerInstance.postMessage("hello world"); + +var buffer = new ArrayBuffer(8); +workerInstance.postMessage(buffer, [buffer]); +``` + + +### on9+ + +on(type: string, listener: WorkerEventListener): void + +向Worker添加一个事件监听。 + +**系统能力：** SystemCapability.Utils.Lang + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------------------- | ---- | ---------------------- | +| type | string | 是 | 监听的事件类型。 | +| listener | [WorkerEventListener](#workereventlistener9) | 是是 | 回调的事件。回调事件。 | + +**示例：** + +```js +const workerInstance = new worker.ThreadWorker("workers/worker.js"); +workerInstance.on("alert", (e)=>{ + console.log("alert listener callback"); +}) +``` + + +### once9+ + +once(type: string, listener: WorkerEventListener): void + +向Worker添加一个事件监听，事件监听只执行一次便自动删除。 + +**系统能力：** SystemCapability.Utils.Lang + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------------------- | ---- | ---------------------- | +| type | string | 是 | 监听的事件类型。 | +| listener | [WorkerEventListener](#workereventlistener9) | 是是 | 回调的事件。回调事件。 | + +**示例：** + +```js +const workerInstance = new worker.ThreadWorker("workers/worker.js"); +workerInstance.once("alert", (e)=>{ + console.log("alert listener callback"); +}) +``` + + +### off9+ + +off(type: string, listener?: WorkerEventListener): void + +删除类型为type的事件监听。 + +**系统能力：** SystemCapability.Utils.Lang + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------------------- | ---- | ---------------------------- | +| type | string | 是 | 需要删除的事件类型。 | +| listener | [WorkerEventListener](#workereventlistener9) | 是否 | 回调的事件。删除的回调事件。 | + +**示例：** + +```js +const workerInstance = new worker.ThreadWorker("workers/worker.js"); +workerInstance.off("alert"); +``` + + +### terminate9+ + +terminate(): void + +销毁Worker线程，终止Worker接收消息。 + +**系统能力：** SystemCapability.Utils.Lang + +**示例：** + +```js +const workerInstance = new worker.ThreadWorker("workers/worker.js"); +workerInstance.terminate(); +``` + + +### onexit9+ + +onexit?: (code: number) => void + +Worker对象的onexit属性表示Worker销毁时被调用的事件处理程序，处理程序在宿主线程中执行。 + +**系统能力：** SystemCapability.Utils.Lang + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------ | +| code | number | 否 | Worker退出的code。 | + +**示例：** + +```js +const workerInstance = new worker.ThreadWorker("workers/worker.js"); +workerInstance.onexit = function(e) { + console.log("onexit"); +} +``` + + +### onerror9+ + +onerror?: (err: ErrorEvent) => void + +Worker对象的onerror属性表示Worker在执行过程中发生异常被调用的事件处理程序，处理程序在宿主线程中执行。 + +**系统能力：** SystemCapability.Utils.Lang + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------------------- | ---- | ---------- | +| err | [ErrorEvent](#errorevent) | 否 | 异常数据。 | + +**示例：** + +```js +const workerInstance = new worker.ThreadWorker("workers/worker.js"); +workerInstance.onerror = function(e) { + console.log("onerror"); +} +``` + + +### onmessage9+ + +onmessage?: (event: MessageEvent\) => void + +Worker对象的onmessage属性表示宿主线程接收到来自其创建的Worker通过parentPort.postMessage接口发送的消息时被调用的事件处理程序，处理程序在宿主线程中执行。 + +**系统能力：** SystemCapability.Utils.Lang + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ----------------------------- | ---- | ---------------------- | +| event | [MessageEvent](#messageevent) | 否 | 收到的Worker消息数据。 | + +**示例：** + +```js +const workerInstance = new worker.ThreadWorker("workers/worker.js"); +workerInstance.onmessage = function(e) { + // e : MessageEvent, 用法如下： + // let data = e.data; + console.log("onmessage"); +} +``` + + +### onmessageerror9+ + +onmessageerror?: (event: MessageEvent\) => void + +Worker对象的onmessageerror属性表示当Worker对象接收到一条无法被序列化的消息时被调用的事件处理程序，处理程序在宿主线程中执行。 + +**系统能力：** SystemCapability.Utils.Lang + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ----------------------------- | ---- | ---------- | +| event | [MessageEvent](#messageevent) | 否 | 异常数据。 | + +**示例：** + +```js +const workerInstance = new worker.ThreadWorker("workers/worker.js"); +workerInstance.onmessageerror= function(e) { + console.log("onmessageerror"); +} +``` + + +## WorkerEventTarget9+ + +### addEventListener9+ + +addEventListener(type: string, listener: WorkerEventListener): void + +向Worker添加一个事件监听。 + +**系统能力：** SystemCapability.Utils.Lang + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------------------- | ---- | ---------------- | +| type | string | 是 | 监听的事件类型。 | +| listener | [WorkerEventListener](#workereventlistener9) | 是 | 回调的事件。 | + +**示例：** + +```js +const workerInstance = new worker.ThreadWorker("workers/worker.js"); +workerInstance.addEventListener("alert", (e)=>{ + console.log("alert listener callback"); +}) +``` + + +### removeEventListener9+ + +removeEventListener(type: string, callback?: WorkerEventListener): void + +删除Worker的事件监听。 + +**系统能力：** SystemCapability.Utils.Lang + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------------------- | ---- | ---------------------------- | +| type | string | 是 | 需要删除的监听事件类型。 | +| callback | [WorkerEventListener](#workereventlistener9) | 是否 | 回调的事件。删除的回调事件。 | + +**示例：** + +```js +const workerInstance = new worker.ThreadWorker("workers/worker.js"); +workerInstance.removeEventListener("alert"); +``` -使用以下方法前，均需先构造Worker实例，Worker类继承[EventTarget](#eventtarget)。 +### dispatchEvent9+ -### constructor +dispatchEvent(event: Event): boolean + +分发定义在Worker的事件。 + +**系统能力：** SystemCapability.Utils.Lang + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------------- | ---- | ---------------- | +| event | [Event](#event) | 是 | 需要分发的事件。 | + +**返回值：** + +| 类型 | 说明 | +| ------- | ------------------------------- | +| boolean | 分发的结果，false表示分发失败。 | + +**示例：** + +```js +const workerInstance = new worker.ThreadWorker("workers/worker.js"); +workerInstance.dispatchEvent({type:"alert"}); +``` + + +### removeAllListener9+ + +removeAllListener(): void + +删除Worker所有的事件监听。 + +**系统能力：** SystemCapability.Utils.Lang + +**示例：** + +```js +const workerInstance = new worker.ThreadWorker("workers/worker.js"); +workerInstance.removeAllListener(); +``` + + +## ThreadWorkerGlobalScope9+ + +Worker线程用于与宿主线程通信的类，通过postMessage接口发送消息给宿主线程、close接口销毁Worker线程。DedicatedWorkerGlobalScope类继承[GlobalScope9+](#globalscope9)。 + + +### postMessage9+ + +postMessage(messageObject: Object, options?: PostMessageOptions): void + +Worker线程向宿主线程发送消息。 + +**系统能力：** SystemCapability.Utils.Lang + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | +| message | Object | 是 | 发送至宿主线程的数据。 | +| options | [PostMessageOptions](#postmessageoptions) | 否 | 可转移对象是ArrayBuffer的实例对象。transferList数组中不可传入null。 | + +**示例：** + +```js +// main.js +import worker from '@ohos.worker'; +const workerInstance = new worker.ThreadWorker("workers/worker.js"); +workerInstance.postMessage("hello world"); +workerInstance.onmessage = function(e) { + // let data = e.data; + console.log("receive data from worker.js"); +} +``` + +```js +// worker.js +import worker from '@ohos.worker'; +const parentPort = worker.workerPort; +parentPort.onmessage = function(e){ + // let data = e.data; + parentPort.postMessage("receive data from main.js"); +} +``` + + +### close9+ + +close(): void + +销毁Worker线程，终止Worker接收消息。 + +**系统能力：** SystemCapability.Utils.Lang + +**示例：** + +```js +// main.js +import worker from '@ohos.worker'; +const workerInstance = new worker.ThreadWorker("workers/worker.js"); +``` + +```js +// worker.js +import worker from '@ohos.worker'; +const parentPort = worker.workerPort; +parentPort.onmessage = function(e) { + parentPort.close() +} +``` + + +### onmessage9+ + +onmessage?: (event: MessageEvent\) => void + +DedicatedWorkerGlobalScope的onmessage属性表示Worker线程收到来自其宿主线程通过postMessage接口发送的消息时被调用的事件处理程序，处理程序在Worker线程中执行。 + +**系统能力：** SystemCapability.Utils.Lang + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ----------------------------- | ---- | ------------------------ | +| event | [MessageEvent](#messageevent) | 否 | 收到宿主线程发送的数据。 | + +**示例：** + +```js +// main.js +import worker from '@ohos.worker'; +const workerInstance = new worker.ThreadWorker("workers/worker.js"); +workerInstance.postMessage("hello world"); +``` + +```js +// worker.js +import worker from '@ohos.worker'; +const parentPort = worker.workerPort; +parentPort.onmessage = function(e) { + console.log("receive main.js message"); +} +``` + + +### onmessageerror9+ + +onmessageerror?: (event: MessageEvent\) => void + +DedicatedWorkerGlobalScope的onmessageerror属性表示当Worker对象接收到一条无法被反序列化的消息时被调用的事件处理程序，处理程序在Worker线程中执行。 + +**系统能力：** SystemCapability.Utils.Lang + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ----------------------------- | ---- | ---------- | +| event | [MessageEvent](#messageevent) | 否 | 异常数据。 | + +**示例：** + +```js +// main.js +import worker from '@ohos.worker'; +const workerInstance = new worker.ThreadWorker("workers/worker.js"); +``` + +```js +// worker.js +import worker from '@ohos.worker'; +const parentPort = worker.workerPort; +parentPort.onmessageerror= function(e) { + console.log("worker.js onmessageerror") +} +``` + + +## WorkerEventListener9+ + +(event: Event): void | Promise<void> + +事件监听类。 + +**系统能力：** SystemCapability.Utils.Lang + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | --------------- | ---- | -------------- | +| event | [Event](#event) | 是 | 回调的事件类。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------- | ------------------------------- | +| void \| Promise<void> | 无返回值或者以Promise形式返回。 | + +**示例：** + +```js +const workerInstance = new worker.ThreadWorker("workers/worker.js"); +workerInstance.addEventListener("alert", (e)=>{ + console.log("alert listener callback"); +}) +``` + + +## GlobalScope9+ + +Worker线程自身的运行环境，WorkerGlobalScope类继承[WorkerEventTarget](#workereventtarget9)。 + +### 属性 + +**系统能力：** SystemCapability.Utils.Lang + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| ---- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------- | +| name | string | 是 | 否 | Worker的名字，new Worker时指定。 | +| self | [GlobalScope](#globalscope9) & typeof globalThis | 是 | 否 | GlobalScope本身。 | + + +### onerror9+ + +onerror?: (ev: ErrorEvent) => void + +GlobalScope的onerror属性表示Worker在执行过程中发生异常被调用的事件处理程序，处理程序在Worker线程中执行。 + +**系统能力：** SystemCapability.Utils.Lang + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------------------- | ---- | ---------- | +| ev | [ErrorEvent](#errorevent) | 否 | 异常数据。 | + +**示例：** + +```js +// main.js +import worker from '@ohos.worker'; +const workerInstance = new worker.ThreadWorker("workers/worker.js") +``` + +```js +// worker.js +import worker from '@ohos.worker'; +const parentPort = worker.workerPort +parentPort.onerror = function(e){ + console.log("worker.js onerror") +} +``` + + +## Worker(deprecated) + +> **说明：**
+> 从API version 9开始废弃，建议使用[ThreadWorker9+](#threadworker9)替代。 + +使用以下方法前，均需先构造Worker实例，Worker类继承[EventTarget](#eventtarget)。 + +### constructor(deprecated) +> **说明：**
+> 从API version 9开始废弃，建议使用[ThreadWorker.constructor9+](#constructor9)替代。 constructor(scriptURL: string, options?: WorkerOptions) @@ -49,7 +674,7 @@ Worker构造函数。 | 参数名 | 类型 | 必填 | 说明 | | --------- | ------------------------------- | ---- | ------------------------------------------------------------ | -| scriptURL | string | 是 | Worker执行脚本的路径。
在FA和Stage模型下，DevEco Studio新建Worker工程路径分别存在以下两种情况：
(a) worker脚本所在目录与pages目录同级。
(b) worker脚本所在目录与pages目录不同级。 +| scriptURL | string | 是 | Worker执行脚本的路径。
在FA和Stage模型下，DevEco Studio新建Worker工程路径分别存在以下两种情况：
(a) worker脚本所在目录与pages目录同级。
(b) worker脚本所在目录与pages目录不同级。 | | options | [WorkerOptions](#workeroptions) | 否 | Worker构造的选项。 | **返回值：** @@ -125,7 +750,10 @@ Stage模型: } } ``` -### postMessage +### postMessage(deprecated) + +> **说明：**
+> 从API version 9开始废弃，建议使用[ThreadWorker.postMessage9+](#postmessage9)替代。 postMessage(message: Object, options?: PostMessageOptions): void @@ -152,7 +780,10 @@ workerInstance.postMessage(buffer, [buffer]); ``` -### on +### on(deprecated) + +> **说明：**
+> 从API version 9开始废弃，建议使用[ThreadWorker.on9+](#on9)替代。 on(type: string, listener: EventListener): void @@ -165,7 +796,7 @@ on(type: string, listener: EventListener): void | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------- | ---- | ---------------- | | type | string | 是 | 监听的事件类型。 | -| listener | [EventListener](#eventlistener) | 是 | 回调事件。 | +| listener | [EventListener](#eventlistener) | 是 | 回调事件。 | **示例：** @@ -177,7 +808,10 @@ workerInstance.on("alert", (e)=>{ ``` -### once +### once(deprecated) + +> **说明：**
+> 从API version 9开始废弃，建议使用[ThreadWorker.once9+](#once9)替代。 once(type: string, listener: EventListener): void @@ -190,7 +824,7 @@ once(type: string, listener: EventListener): void | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------- | ---- | ---------------- | | type | string | 是 | 监听的事件类型。 | -| listener | [EventListener](#eventlistener) | 是 | 回调事件。 | +| listener | [EventListener](#eventlistener) | 是 | 回调事件。 | **示例：** @@ -202,7 +836,10 @@ workerInstance.once("alert", (e)=>{ ``` -### off +### off(deprecated) + +> **说明：**
+> 从API version 9开始废弃，建议使用[ThreadWorker.off9+](#off9)替代。 off(type: string, listener?: EventListener): void @@ -212,10 +849,10 @@ off(type: string, listener?: EventListener): void **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------- | ---- | ---------------------- | -| type | string | 是 | 需要删除的事件类型。 | -| listener | [EventListener](#eventlistener) | 否 | 删除的回调事件。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------- | ---- | -------------------- | +| type | string | 是 | 需要删除的事件类型。 | +| listener | [EventListener](#eventlistener) | 否 | 删除的回调事件。 | **示例：** @@ -225,7 +862,10 @@ workerInstance.off("alert"); ``` -### terminate +### terminate(deprecated) + +> **说明：**
+> 从API version 9开始废弃，建议使用[ThreadWorker.terminate9+](#terminate9)替代。 terminate(): void @@ -241,7 +881,10 @@ workerInstance.terminate(); ``` -### onexit +### onexit(deprecated) + +> **说明：**
+> 从API version 9开始废弃，建议使用[ThreadWorker.onexit9+](#onexit9)替代。 onexit?: (code: number) => void @@ -265,7 +908,10 @@ workerInstance.onexit = function(e) { ``` -### onerror +### onerror(deprecated) + +> **说明：**
+> 从API version 9开始废弃，建议使用[ThreadWorker.onerror9+](#onerror9)替代。 onerror?: (err: ErrorEvent) => void @@ -289,7 +935,10 @@ workerInstance.onerror = function(e) { ``` -### onmessage +### onmessage(deprecated) + +> **说明：**
+> 从API version 9开始废弃，建议使用[ThreadWorker.onmessage9+](#onmessage9)替代。 onmessage?: (event: MessageEvent\) => void @@ -315,7 +964,10 @@ workerInstance.onmessage = function(e) { ``` -### onmessageerror +### onmessageerror(deprecated) + +> **说明：**
+> 从API version 9开始废弃，建议使用[ThreadWorker.onmessageerror9+](#onmessageerror9)替代。 onmessageerror?: (event: MessageEvent\) => void @@ -339,10 +991,14 @@ workerInstance.onmessageerror= function(e) { ``` -## EventTarget +## EventTarget(deprecated) +> **说明：**
+> 从API version 9开始废弃，建议使用[WorkerEventTarget9+](#workereventtarget9)替代。 +### addEventListener(deprecated) -### addEventListener +> **说明：**
+> 从API version 9开始废弃，建议使用[addEventListener9+](#addeventlistener9)替代。 addEventListener(type: string, listener: EventListener): void @@ -367,7 +1023,10 @@ workerInstance.addEventListener("alert", (e)=>{ ``` -### removeEventListener +### removeEventListener(deprecated) + +> **说明：**
+> 从API version 9开始废弃，建议使用[removeEventListener9+](#removeeventlistener9)替代。 removeEventListener(type: string, callback?: EventListener): void @@ -377,10 +1036,10 @@ removeEventListener(type: string, callback?: EventListener): void **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------- | ---- | ---------------------- | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------- | ---- | ------------------------ | | type | string | 是 | 需要删除的监听事件类型。 | -| callback | [EventListener](#eventlistener) | 否 | 删除的回调事件。 | +| callback | [EventListener](#eventlistener) | 否 | 删除的回调事件。 | **示例：** @@ -390,7 +1049,10 @@ workerInstance.removeEventListener("alert"); ``` -### dispatchEvent +### dispatchEvent(deprecated) + +> **说明：**
+> 从API version 9开始废弃，建议使用[dispatchEvent9+](#dispatchevent9)替代。 dispatchEvent(event: Event): boolean @@ -418,7 +1080,10 @@ workerInstance.dispatchEvent({type:"alert"}); ``` -### removeAllListener +### removeAllListener(deprecated) + +> **说明：**
+> 从API version 9开始废弃，建议使用[removeAllListener9+](#removealllistener9)替代。 removeAllListener(): void @@ -434,12 +1099,18 @@ workerInstance.removeAllListener(); ``` -## DedicatedWorkerGlobalScope +## DedicatedWorkerGlobalScope(deprecated) + +> **说明：**
+> 从API version 9开始废弃，建议使用[ThreadWorkerGlobalScope9+](#threadworkerglobalscope9)替代。 Worker线程用于与宿主线程通信的类，通过postMessage接口发送消息给宿主线程、close接口销毁Worker线程。DedicatedWorkerGlobalScope类继承[WorkerGlobalScope](#workerglobalscope)。 -### postMessage +### postMessage(deprecated) + +> **说明：**
+> 从API version 9开始废弃，建议使用[ThreadWorkerGlobalScope9+](#threadworkerglobalscope9).postMessage9+替代。 postMessage(messageObject: Object, options?: PostMessageOptions): void @@ -451,7 +1122,7 @@ Worker线程向宿主线程发送消息。 | 参数名 | 类型 | 必填 | 说明 | | ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | -| message | Object | 是 | 发送至宿主线程的数据。 | +| message | Object | 是 | 发送至宿主线程的数据。 | | options | [PostMessageOptions](#postmessageoptions) | 否 | 可转移对象是ArrayBuffer的实例对象。transferList数组中不可传入null。 | **示例：** @@ -477,7 +1148,10 @@ parentPort.onmessage = function(e){ ``` -### close +### close(deprecated) + +> **说明：**
+> 从API version 9开始废弃，建议使用[ThreadWorkerGlobalScope9+](#threadworkerglobalscope9).close9+替代。 close(): void @@ -502,7 +1176,10 @@ parentPort.onmessage = function(e) { ``` -### onmessage +### onmessage(deprecated) + +> **说明：**
+> 从API version 9开始废弃，建议使用[ThreadWorkerGlobalScope9+](#threadworkerglobalscope9).onmessage9+替代。 onmessage?: (event: MessageEvent\) => void @@ -512,8 +1189,8 @@ DedicatedWorkerGlobalScope的onmessage属性表示Worker线程收到来自其宿 **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ----------------------------- | ---- | ---------------------- | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ----------------------------- | ---- | ------------------------ | | event | [MessageEvent](#messageevent) | 否 | 收到宿主线程发送的数据。 | **示例：** @@ -534,7 +1211,10 @@ parentPort.onmessage = function(e) { ``` -### onmessageerror +### onmessageerror(deprecated) + +> **说明：**
+> 从API version 9开始废弃，建议使用[ThreadWorkerGlobalScope9+](#threadworkerglobalscope9).onmessageerror9+替代。 onmessageerror?: (event: MessageEvent\) => void @@ -588,7 +1268,10 @@ parentPort.onmessageerror= function(e) { | timeStamp | number | 是 | 否 | 事件创建时的时间戳（精度为毫秒）。 | -## EventListener +## EventListener(deprecated) + +> **说明：**
+> 从API version 9开始废弃，建议使用[WorkerEventListener9+](#workereventlistener9)替代。 (evt: Event): void | Promise<void> @@ -644,7 +1327,10 @@ workerInstance.addEventListener("alert", (e)=>{ | data | T | 是 | 否 | 线程间传递的数据。 | -## WorkerGlobalScope +## WorkerGlobalScope(deprecated) + +> **说明：**
+> 从API version 9开始废弃，建议使用[GlobalScope9+](#globalscope9)替代。 Worker线程自身的运行环境，WorkerGlobalScope类继承[EventTarget](#eventtarget)。 @@ -652,13 +1338,16 @@ Worker线程自身的运行环境，WorkerGlobalScope类继承[EventTarget](#eve **系统能力：** SystemCapability.Utils.Lang -| 名称 | 参数类型 | 可读 | 可写 | 说明 | -| ---- | ------------------------------------------------------------ | ---- | ---- | --------------------------------------- | +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| ---- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------- | | name | string | 是 | 否 | Worker的名字，new Worker时指定。 | -| self | [WorkerGlobalScope](#workerglobalscope) & typeof globalThis | 是 | 否 | WorkerGlobalScope本身。 | +| self | [WorkerGlobalScope](#workerglobalscope) & typeof globalThis | 是 | 否 | WorkerGlobalScope本身。 | + +### onerror(deprecated) -### onerror +> **说明：**
+> 从API version 9开始废弃，建议使用[GlobalScope9+](#globalscope9).onerror替代。 onerror?: (ev: ErrorEvent) => void @@ -688,27 +1377,31 @@ parentPort.onerror = function(e){ } ``` + ## 其他说明 ### 序列化支持类型 -| Type | 备注 | 是否支持 | -| ------------------- | -------------------------------------------------------- | -------------------- | -| All Primitive Type | 不包括symbol | 是 | -| Date | | 是 | -| String | | 是 | -| RegExp | | 是 | -| Array | | 是 | -| Map | | 是 | -| Set | | 是 | -| Object | 只支持Plain Object，不支持带function的 | 是 | -| ArrayBuffer | 提供transfer能力 | 是 | -| TypedArray | | 是 | +| Type | 备注 | 是否支持 | +| ------------------ | -------------------------------------- | -------- | +| All Primitive Type | 不包括symbol | 是 | +| Date | | 是 | +| String | | 是 | +| RegExp | | 是 | +| Array | | 是 | +| Map | | 是 | +| Set | | 是 | +| Object | 只支持Plain Object，不支持带function的 | 是 | +| ArrayBuffer | 提供transfer能力 | 是 | +| TypedArray | | 是 | 特例：传递通过自定义class创建出来的object时，不会发生序列化错误，但是自定义class的属性（如Function）无法通过序列化传递。 +> **说明：**
+> 以API version 9的FA工程为例。 + ```js // main.js import worker from '@ohos.worker'; -const workerInstance = new worker.Worker("workers/worker.js"); +const workerInstance = new worker.Thread("workers/worker.js"); workerInstance.postMessage("message from main to worker"); workerInstance.onmessage = function(d) { // 当worker线程传递obj2时，data即为obj2。data没有Init、SetName的方法 @@ -718,7 +1411,7 @@ workerInstance.onmessage = function(d) { ```js // worker.js import worker from '@ohos.worker'; -const parentPort = worker.parentPort; +const parentPort = worker.workerPort; class MyModel { Init() { this.name = "wzy" @@ -761,18 +1454,26 @@ Actor并发模型的交互原理：各个Actor并发地处理主线程任务， ### 注意事项 - Worker存在数量限制，当前支持最多同时存在7个Worker。 -- 当Worker数量超出限制，会出现Error "Too many workers, the number of workers exceeds the maximum."。 +- 在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()或parentPort.close()方法。 +- 自API version 9版本开始，若Worker处于已经销毁或正在销毁等非运行状态时，调用其功能接口，会抛出相应的BusinessError。 - Worker的创建和销毁耗费性能，建议管理已创建的Worker并重复使用。 ## 完整示例 +> **说明：**
+> 以API version 9的工程为例。
API version 8及之前的版本仅支持FA模型，如需使用，注意更换构造Worker的接口和创建worker线程中与主线程通信的对象的两个方法。 ### FA模型 + ```js // main.js(同级目录为例) import worker from '@ohos.worker'; // 主线程中创建Worker对象 -const workerInstance = new worker.Worker("workers/worker.ts"); +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线程传递信息 @@ -798,7 +1499,10 @@ workerInstance.onexit = function() { import worker from '@ohos.worker'; // 创建worker线程中与主线程通信的对象 -const parentPort = worker.parentPort +const parentPort = worker.workerPort + +// API version 9之前版本，创建worker线程中与主线程通信的对象 +// const parentPort = worker.parentPort // worker线程接收主线程信息 parentPort.onmessage = function(e) { @@ -831,9 +1535,9 @@ build-profile.json5 配置 : import worker from '@ohos.worker'; // 主线程中创建Worker对象 -const workerInstance = new worker.Worker("entry/ets/pages/workers/worker.ts"); +const workerInstance = new worker.ThreadWorker("entry/ets/pages/workers/worker.ts"); // 创建js和ts文件都可以 -// const workerInstance = new worker.Worker("entry/ets/pages/workers/worker.js"); +// const workerInstance = new worker.ThreadWorker("entry/ets/pages/workers/worker.js"); // 主线程向worker线程传递信息 workerInstance.postMessage("123"); @@ -857,7 +1561,7 @@ workerInstance.onexit = function() { import worker from '@ohos.worker'; // 创建worker线程中与主线程通信的对象 -const parentPort = worker.parentPort +const parentPort = worker.workerPort // worker线程接收主线程信息 parentPort.onmessage = function(e) { @@ -883,4 +1587,4 @@ build-profile.json5 配置: ] } } -``` +``` \ No newline at end of file