1# @ohos.worker (启动一个Worker) 2<!--Kit: ArkTS--> 3<!--Subsystem: CommonLibrary--> 4<!--Owner: @lijiamin2025--> 5<!--Designer: @weng-changcheng--> 6<!--Tester: @kirl75; @zsw_zhushiwei--> 7<!--Adviser: @ge-yafang--> 8 9Worker是与主线程并行的独立线程。创建Worker的线程称为宿主线程，Worker自身的线程称为Worker线程。创建Worker时传入的URL文件在Worker线程中执行，可以处理耗时操作，但不能直接操作UI。 10 11Worker的主要作用是为应用程序提供多线程运行环境，使应用程序在执行过程中与宿主线程分离，在后台线程中运行脚本处理耗时操作，避免计算密集型或高延迟任务阻塞宿主线程。由于Worker一旦创建不会主动销毁，若不处于任务状态会一直运行，造成资源浪费，应及时销毁空闲的Worker。 12 13Worker的上下文环境和UI线程的上下文环境是独立的，Worker线程不支持UI操作。 14 15请查看[Worker注意事项](../../arkts-utils/worker-introduction.md#worker注意事项)，了解Worker使用过程中的相关注意点。 16 17> **说明：**<br/> 18> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 19 20## 导入模块 21 22```ts 23import { worker } from '@kit.ArkTS'; 24``` 25 26 27## 属性 28 29**系统能力：** SystemCapability.Utils.Lang 30 31| 名称 | 类型 | 只读 | 可选 | 说明 | 32| --------------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 33| workerPort<sup>9+</sup> | [ThreadWorkerGlobalScope](#threadworkerglobalscope9) | 否 | 否 | Worker线程用于与宿主线程通信的对象。<br/>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 34| parentPort<sup>(deprecated)</sup> | [DedicatedWorkerGlobalScope](#dedicatedworkerglobalscopedeprecated) | 否 | 否 | Worker线程用于与宿主线程通信的对象。<br/>此属性从API version 7开始支持，从API version 9开始被废弃。<br/>建议使用workerPort<sup>9+</sup>替代。 | 35 36 37## WorkerOptions 38 39Worker构造函数的选项，用于为Worker添加其他信息。 40 41**系统能力：** SystemCapability.Utils.Lang 42 43| 名称 | 类型 | 只读 | 可选 | 说明 | 44| ---- | -------- | ---- | ---- | -------------- | 45| type | 'classic' \| 'module' | 否 | 是 | Worker执行脚本的模式类型，暂不支持module类型，默认值为"classic"。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 46| name | string | 否 | 是 | Worker的名称，默认值为undefined。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 47| shared | boolean | 否 | 是 | 表示Worker共享功能，此接口暂不支持。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 48| priority<sup>18+</sup> | [ThreadWorkerPriority](#threadworkerpriority18) | 否 | 是 | 表示Worker线程优先级。默认值为MEDIUM。 <br/>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。| 49 50 51## ThreadWorkerPriority<sup>18+</sup> 52 53Worker线程的优先级枚举，各优先级对应关系请参考[QoS等级定义](../../napi/qos-guidelines.md#qos等级定义)。 54 55**系统能力：** SystemCapability.Utils.Lang 56 57| 名称 | 值 | 说明 | 58| -------- | -------- | -------- | 59| HIGH | 0 | 适用于打开文档等用户触发并且可以看到进展的任务，任务在几秒钟之内完成。对应QOS_USER_INITIATED。<br>**原子化服务API**：从API version 18开始，该接口支持在原子化服务中使用。 | 60| MEDIUM | 1 | 任务完成需要几秒钟。是[ThreadWorkerPriority](#threadworkerpriority18)的默认值。对应QOS_DEFAULT。<br>**原子化服务API**：从API version 18开始，该接口支持在原子化服务中使用。 | 61| LOW | 2 | 适用于下载等不需要立即看到响应效果的任务，任务完成需要几秒到几分钟。对应QOS_UTILITY。<br>**原子化服务API**：从API version 18开始，该接口支持在原子化服务中使用。 | 62| IDLE | 3 | 适用于数据同步等用户不可见的后台任务，任务完成需要几分钟甚至几小时。对应QOS_BACKGROUND。<br>**原子化服务API**：从API version 18开始，该接口支持在原子化服务中使用。 | 63| DEADLINE<sup>20+</sup> | 4 | 适用于页面加载等越快越好的关键任务，任务几乎是瞬间完成的。对应QOS_DEADLINE_REQUEST。<br>**原子化服务API**：从API version 20开始，该接口支持在原子化服务中使用。 | 64| VIP<sup>20+</sup> | 5 | 适用于UI线程、动画渲染等用户交互任务，任务是即时的。对应QOS_USER_INTERACTIVE。<br>**原子化服务API**：从API version 20开始，该接口支持在原子化服务中使用。 | 65 66 67 68## ThreadWorker<sup>9+</sup> 69 70使用以下方法前，需先构造ThreadWorker实例。ThreadWorker类继承自[WorkerEventTarget](#workereventtarget9)。 71 72### 属性 73 74**系统能力：** SystemCapability.Utils.Lang 75 76| 名称 | 类型 | 只读 | 可选 | 说明 | 77| ------ | ---------------------- | ---- | --- | ------------------------------------------------------------ | 78| onexit<sup>9+</sup> | (code: number) => void | 否 | 是 | 回调函数。表示Worker线程销毁时被调用的事件处理程序，该处理程序在宿主线程中执行。回调函数的code参数类型为number，异常退出时code为1，正常退出时code为0。默认值为undefined。<br/>**原子化服务API**：从API version 11开始，该属性支持在原子化服务中使用。| 79| onerror<sup>9+</sup> | (err: [ErrorEvent](#errorevent)) => void | 否 | 是 | 回调函数，用于处理onmessage回调函数中同步代码产生的异常，处理程序在宿主线程中执行。回调函数的err类型为[ErrorEvent](#errorevent)，表示收到的异常数据。默认值为undefined。<br/>**原子化服务API**：从API version 11开始，该属性支持在原子化服务中使用。| 80| onAllErrors<sup>18+</sup> | [ErrorCallback](#errorcallback18) | 否 | 是 | 回调函数。表示Worker线程生命周期内发生异常被调用的事件处理程序，处理程序在宿主线程中执行。<br/>**原子化服务API**：从API version 18开始，该属性支持在原子化服务中使用。| 81| onmessage<sup>9+</sup> | (event: [MessageEvents](#messageevents9)) => void | 否 | 是 | 回调函数。表示宿主线程接收到来自其创建的Worker通过workerPort.[postMessage](#postmessage9-3)或workerPort.[postMessageWithSharedSendable](#postmessagewithsharedsendable12-1)接口发送的消息时被调用的事件处理程序，处理程序在宿主线程中执行。其中回调函数中event类型为[MessageEvents](#messageevents9)，表示收到的Worker线程发送的消息数据。默认值为undefined。<br/>**原子化服务API**：从API version 11开始，该属性支持在原子化服务中使用。| 82| onmessageerror<sup>9+</sup> | (event: [MessageEvents](#messageevents9)) => void | 否 | 是 | 回调函数。用于处理Worker对象接收到的无法被序列化的消息。该处理程序在宿主线程中执行，event类型为[MessageEvents](#messageevents9)，表示收到的Worker消息数据。默认值为undefined。<br/>**原子化服务API**：从API version 11开始，该属性支持在原子化服务中使用。| 83 84请查看[onAllErrors接口与onerror接口之间的行为差异](../../arkts-utils/worker-introduction.md#onallerrors接口与onerror接口之间的行为差异)以了解onerror与onAllErrors的差异。 85 86### constructor<sup>9+</sup> 87 88constructor(scriptURL: string, options?: WorkerOptions) 89 90ThreadWorker构造函数。 91 92**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 93 94**系统能力：** SystemCapability.Utils.Lang 95 96**参数：** 97 98| 参数名 | 类型 | 必填 | 说明 | 99| --------- | ------------------------------- | ---- | ------------------------------------------------------------ | 100| scriptURL | string | 是 | Worker线程文件的路径。<br/>路径规则详细参考[文件路径注意事项](../../arkts-utils/worker-introduction.md#文件路径注意事项)。 | 101| options | [WorkerOptions](#workeroptions) | 否 | Worker构造的选项。 | 102 103**错误码：** 104 105以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 106 107| 错误码ID | 错误信息 | 108| -------- | -------- | 109| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 110| 10200003 | Worker initialization failed. | 111| 10200007 | The worker file path is invalid. | 112 113**示例：** 114 115以下示例展示了在Stage模型的entry模块Index.ets文件中加载Worker文件的方法，使用Library加载Worker线程文件的场景参考[文件路径注意事项](../../arkts-utils/worker-introduction.md#文件路径注意事项)。 116 117```ts 118// Index.ets 119import { worker } from '@kit.ArkTS'; 120 121// worker文件所在路径："entry/src/main/ets/workers/worker.ets" 122const workerInstance = new worker.ThreadWorker('entry/ets/workers/worker.ets', {name: "WorkerThread"}); 123``` 124 125 126### postMessage<sup>9+</sup> 127 128postMessage(message: Object, transfer: ArrayBuffer[]): void 129 130宿主线程通过转移对象所有权的方式向Worker线程发送消息。 131 132**系统能力：** SystemCapability.Utils.Lang 133 134**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 135 136**参数：** 137 138| 参数名 | 类型 | 必填 | 说明 | 139| -------- | ------------- | ---- | ------------------------------------------------------------ | 140| message | Object | 是 | 发送至Worker的数据，该数据对象必须是可序列化对象，序列化支持类型见[其他说明](#序列化支持类型)。 | 141| transfer | ArrayBuffer[] | 是 | 表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到Worker线程，在宿主线程中将会变为不可用，仅在Worker线程中可用，数组不可传入null。 | 142 143**错误码：** 144 145以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 146 147| 错误码ID | 错误信息 | 148| -------- | ----------------------------------------- | 149| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 150| 10200004 | The Worker instance is not running. | 151| 10200006 | An exception occurred during serialization. | 152 153**示例：** 154 155```ts 156// Worker.ets 157import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS'; 158 159// 创建worker线程中与宿主线程通信的对象 160const workerPort = worker.workerPort; 161 162// worker线程接收宿主线程信息 163workerPort.onmessage = (e: MessageEvents): void => { 164 // data：宿主线程发送的信息 165 let data: ArrayBuffer = e.data; 166 // 往收到的buffer里写入数据 167 const view = new Int8Array(data).fill(3); 168 // worker线程向宿主线程发送信息 169 workerPort.postMessage(view); 170} 171 172// worker线程发生error的回调 173workerPort.onerror = (err: ErrorEvent) => { 174 console.error("worker.ets onerror" + err.message); 175} 176``` 177```ts 178// Index.ets 179import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS'; 180 181@Entry 182@Component 183struct Index { 184 @State message: string = 'Hello World'; 185 186 build() { 187 Row() { 188 Column() { 189 Text(this.message) 190 .fontSize(50) 191 .fontWeight(FontWeight.Bold) 192 .onClick(() => { 193 // 宿主线程中创建Worker对象 194 const workerInstance = new worker.ThreadWorker("entry/ets/workers/Worker.ets"); 195 // 宿主线程向worker线程传递信息 196 const buffer = new ArrayBuffer(8); 197 workerInstance.postMessage(buffer, [buffer]); 198 199 // 此时buffer的所有权转移到了worker线程，在宿主线程中不可用 200 // const view = new Int8Array(buffer).fill(3); 201 202 // 宿主线程接收worker线程信息 203 workerInstance.onmessage = (e: MessageEvents): void => { 204 // data：worker线程发送的信息 205 let data: Int8Array = e.data; 206 console.info("main thread data is " + data); 207 // 销毁Worker对象 208 workerInstance.terminate(); 209 } 210 // 在调用terminate后，执行onexit 211 workerInstance.onexit = (code) => { 212 console.info("main thread terminate"); 213 } 214 // 监听Worker错误 215 workerInstance.onAllErrors = (err: ErrorEvent) => { 216 console.error("main error message " + err.message); 217 } 218 }) 219 } 220 .width('100%') 221 .height('100%') 222 } 223 } 224} 225``` 226 227### postMessage<sup>9+</sup> 228 229postMessage(message: Object, options?: PostMessageOptions): void 230 231宿主线程可以通过转移对象所有权或拷贝数据的方式向Worker线程发送消息。在传递[Sendable对象](../../arkts-utils/arkts-sendable.md)时，使用拷贝数据的方式。 232 233**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 234 235**系统能力：** SystemCapability.Utils.Lang 236 237**参数：** 238 239| 参数名 | 类型 | 必填 | 说明 | 240| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 241| message | Object | 是 | 发送至Worker的数据，该数据对象必须是可序列化对象，序列化支持类型见[其他说明](#序列化支持类型)。 | 242| options | [PostMessageOptions](#postmessageoptions) | 否 | 当填入该参数时，传输的数据将通过所有权转移的方式发送到Worker线程。这些数据在宿主线程中将变为不可用，仅在Worker线程中可用。<br>若不填入该参数，默认设置为 undefined，数据将通过拷贝的方式传输到Worker线程。 | 243 244**错误码：** 245 246以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 247 248| 错误码ID | 错误信息 | 249| -------- | ----------------------------------------- | 250| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 251| 10200004 | The Worker instance is not running. | 252| 10200006 | An exception occurred during serialization. | 253 254**示例：** 255 256```ts 257import { worker } from '@kit.ArkTS'; 258 259const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets"); 260 261workerInstance.postMessage("hello world"); 262 263let buffer = new ArrayBuffer(8); 264 265// 填入options参数，buffer的所有权会转移到Worker线程，在宿主线程中将不可用 266workerInstance.postMessage(buffer, [buffer]); 267 268// 未填入options参数，默认值为undefined，通过拷贝数据的方式将buffer发送到Worker线程 269workerInstance.postMessage(buffer); 270``` 271 272 273### postMessageWithSharedSendable<sup>12+</sup> 274 275postMessageWithSharedSendable(message: Object, transfer?: ArrayBuffer[]): void 276 277宿主线程向Worker线程发送消息，消息中的[Sendable对象](../../arkts-utils/arkts-sendable.md)通过引用传递，非Sendable对象通过拷贝数据的方式传递。 278 279**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 280 281**系统能力：** SystemCapability.Utils.Lang 282 283**参数：** 284 285| 参数名 | 类型 | 必填 | 说明 | 286| --------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 287| message | Object | 是 | 发送至Worker的数据，该数据对象必须是可序列化对象，序列化支持类型见[序列化类型说明](#序列化支持类型)。如果需要共享数据，支持类型见[Sendable支持的数据类型](../../arkts-utils/arkts-sendable.md#sendable支持的数据类型)。 | 288| transfer | ArrayBuffer[] | 否 | 可转移的ArrayBuffer实例对象数组。该数组中对象的所有权将转移到Worker线程，在宿主线程中变为不可用，仅在Worker线程中可用，数组不可传入null。默认值为空数组。 | 289 290**错误码：** 291 292以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 293 294| 错误码ID | 错误信息 | 295| -------- | ----------------------------------------- | 296| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 297| 10200004 | The Worker instance is not running. | 298| 10200006 | An exception occurred during serialization. | 299 300**示例：** 301 302<!--code_no_check--> 303```ts 304// Index.ets 305// 新建SendableObject实例并通过宿主线程传递至Worker线程 306 307import { worker } from '@kit.ArkTS'; 308import { SendableObject } from './sendable'; 309 310const workerInstance = new worker.ThreadWorker("entry/ets/workers/Worker.ets"); 311let object: SendableObject = new SendableObject(); 312workerInstance.postMessageWithSharedSendable(object); 313 314// 使用postMessage接口传递Sendable对象，使用拷贝数据的方式传递 315workerInstance.postMessage(object); 316``` 317 318```ts 319// sendable.ets 320// 定义SendableObject 321 322@Sendable 323export class SendableObject { 324 a:number = 45; 325} 326``` 327 328<!--code_no_check--> 329```ts 330// worker文件路径为：entry/src/main/ets/workers/Worker.ets 331// Worker.ets 332// 接收宿主线程传递至Worker线程的数据并访问 333 334import { SendableObject } from '../pages/sendable'; 335import { worker, ThreadWorkerGlobalScope, MessageEvents, ErrorEvent } from '@kit.ArkTS'; 336 337const workerPort: ThreadWorkerGlobalScope = worker.workerPort; 338 339workerPort.onmessage = (e: MessageEvents) => { 340 let obj: SendableObject = e.data; 341 console.info("sendable obj is: " + obj.a); 342} 343``` 344 345 346### on<sup>9+</sup> 347 348on(type: string, listener: WorkerEventListener): void 349 350向宿主线程的Worker实例对象添加一个事件监听，该接口与[addEventListener<sup>9+</sup>](#addeventlistener9)接口功能一致。 351 352**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 353 354**系统能力：** SystemCapability.Utils.Lang 355 356**参数：** 357 358| 参数名 | 类型 | 必填 | 说明 | 359| -------- | -------------------------------------------- | ---- | ---------------------- | 360| type | string | 是 | 监听的事件类型。 | 361| listener | [WorkerEventListener](#workereventlistener9) | 是 | 回调的事件。 | 362 363**错误码：** 364 365以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 366 367| 错误码ID | 错误信息 | 368| -------- | -------------------------------------------- | 369| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 370| 10200004 | Worker instance is not running. | 371| 10200005 | The invoked API is not supported in workers. | 372 373**示例：** 374 375```ts 376// Index.ets 377import { worker } from '@kit.ArkTS'; 378 379const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets"); 380 381workerInstance.on("alert", () => { 382 console.info("alert listener callback"); 383}) 384 385// 使用on添加的事件监听可以多次执行 386workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持 387workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持 388``` 389 390 391### once<sup>9+</sup> 392 393once(type: string, listener: WorkerEventListener): void 394 395向宿主线程的Worker实例对象添加一个事件监听，该事件监听只执行一次，执行完后会自动删除。 396 397**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 398 399**系统能力：** SystemCapability.Utils.Lang 400 401**参数：** 402 403| 参数名 | 类型 | 必填 | 说明 | 404| -------- | -------------------------------------------- | ---- | ---------------------- | 405| type | string | 是 | 监听的事件类型。 | 406| listener | [WorkerEventListener](#workereventlistener9) | 是 | 回调的事件。 | 407 408**错误码：** 409 410以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 411 412| 错误码ID | 错误信息 | 413| -------- | -------------------------------------------- | 414| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 415| 10200004 | Worker instance is not running. | 416| 10200005 | The invoked API is not supported in workers. | 417 418**示例：** 419 420```ts 421// Index.ets 422import { worker } from '@kit.ArkTS'; 423 424const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets"); 425 426workerInstance.once("alert", () => { 427 console.info("alert listener callback"); 428}) 429 430workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持 431 432// 使用once添加的事件监听在执行一次后自动删除，无法多次执行 433// workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持 434``` 435 436 437### off<sup>9+</sup> 438 439off(type: string, listener?: WorkerEventListener): void 440 441移除宿主线程的Worker实例对象中类型为type的事件监听，该接口与[removeEventListener<sup>9+</sup>](#removeeventlistener9)接口功能一致。 442 443**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 444 445**系统能力：** SystemCapability.Utils.Lang 446 447**参数：** 448 449| 参数名 | 类型 | 必填 | 说明 | 450| -------- | -------------------------------------------- | ---- | ---------------------------- | 451| type | string | 是 | 需要删除的事件类型。 | 452| listener | [WorkerEventListener](#workereventlistener9) | 否 | 需要删除的特定监听器回调函数。如果未传入此参数，则会删除该类型的所有监听器。 | 453 454**错误码：** 455 456以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 457 458| 错误码ID | 错误信息 | 459| -------- | -------------------------------------------- | 460| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 461| 10200004 | Worker instance is not running. | 462| 10200005 | The invoked API is not supported in workers. | 463 464**示例：** 465 466```ts 467// Index.ets 468import { worker } from '@kit.ArkTS'; 469 470const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets"); 471 472const handler1 = () => console.info("Handler 1"); 473const handler2 = () => console.info("Handler 2"); 474 475// 注册两个监听器 476workerInstance.on("alert", handler1); 477workerInstance.on("alert", handler2); 478 479// 首次触发：两个监听器都会执行 480workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持 481 482// 删除 handler1 监听器 483workerInstance.off("alert", handler1); 484 485// 再次触发：只剩 handler2 会执行 486workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持 487 488// 删除"alert"类型所有监听器 489workerInstance.off("alert"); 490``` 491 492### registerGlobalCallObject<sup>11+</sup> 493 494registerGlobalCallObject(instanceName: string, globalCallObject: Object): void 495 496在宿主线程的ThreadWorker实例上注册一个对象，该对象的方法可在Worker线程中调用。详情请参见[callGlobalCallObjectMethod](#callglobalcallobjectmethod11)。 497 498**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 499 500**系统能力：** SystemCapability.Utils.Lang 501 502**参数：** 503 504| 参数名 | 类型 | 必填 | 说明 | 505| -------- | ------------- | ---- | ------------------------------------------------------------ | 506| instanceName | string | 是 | 注册对象时使用的键，调用时通过该键值找到被注册的对象。 | 507| globalCallObject | Object | 是 | 被注册的对象，ThreadWorker实例会持有被注册对象的强引用。 | 508 509**错误码：** 510 511以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 512 513| 错误码ID | 错误信息 | 514| -------- | ----------------------------------------- | 515| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 516| 10200004 | Worker instance is not running. | 517 518**示例：** 519```ts 520//Index.ets 521import { worker } from '@kit.ArkTS'; 522 523const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets"); 524class TestObj { 525 private message : string = "this is a message from TestObj"; 526 public getMessage() : string { 527 return this.message; 528 } 529 public getMessageWithInput(str : string) : string { 530 return this.message + " with input: " + str; 531 } 532} 533let registerObj = new TestObj(); 534// 在ThreadWorker实例上注册registerObj 535workerInstance.registerGlobalCallObject("myObj", registerObj); 536workerInstance.postMessage("start worker"); 537``` 538 539```ts 540// worker.ets 541import { worker, MessageEvents } from '@kit.ArkTS'; 542 543const workerPort = worker.workerPort; 544workerPort.onmessage = (e: MessageEvents): void => { 545 try { 546 // 调用方法无入参 547 let res : string = workerPort.callGlobalCallObjectMethod("myObj", "getMessage", 0) as string; 548 console.info("worker:", res) // worker: this is a message from TestObj 549 } catch (error) { 550 // 异常处理 551 console.error("worker: error code is " + error.code + " error message is " + error.message); 552 } 553 try { 554 // 调用方法有入参 555 let res : string = workerPort.callGlobalCallObjectMethod("myObj", "getMessageWithInput", 0, "hello there!") as string; 556 console.info("worker:", res); //worker: this is a message from TestObj with input: hello there! 557 } catch (error) { 558 // 异常处理 559 console.error("worker: error code is " + error.code + " error message is " + error.message); 560 } 561} 562``` 563 564### unregisterGlobalCallObject<sup>11+</sup> 565 566unregisterGlobalCallObject(instanceName?: string): void 567 568取消在宿主线程ThreadWorker实例上注册的对象，该方法会释放ThreadWorker实例中与该键相匹配的对象的强引用。如果无匹配对象，该方法不会报错。 569 570**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 571 572**系统能力：** SystemCapability.Utils.Lang 573 574**参数：** 575 576| 参数名 | 类型 | 必填 | 说明 | 577| -------- | ------------- | ---- | ------------------------------------------------------------ | 578| instanceName | string | 否 | 注册对象时使用的键。此参数不填时，会释放ThreadWorker实例中所有已注册的对象。 | 579 580**错误码：** 581 582以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 583 584| 错误码ID | 错误信息 | 585| -------- | ----------------------------------------- | 586| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 587| 10200004 | Worker instance is not running. | 588 589**示例：** 590```ts 591// Index.ets 592import { worker } from '@kit.ArkTS'; 593 594const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets"); 595class TestObj { 596 private message : string = "this is a message from TestObj"; 597 public getMessage() : string { 598 return this.message; 599 } 600 public getMessageWithInput(str : string) : string { 601 return this.message + " with input: " + str; 602 } 603} 604let registerObj = new TestObj(); 605workerInstance.registerGlobalCallObject("myObj", registerObj); 606// 取消对象注册 607workerInstance.unregisterGlobalCallObject("myObj"); 608// 取消ThreadWorker实例上的所有对象注册 609//workerInstance.unregisterGlobalCallObject(); 610workerInstance.postMessage("start worker"); 611``` 612 613### terminate<sup>9+</sup> 614 615terminate(): void 616 617销毁Worker线程并停止Worker线程接收消息。 618 619**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 620 621**系统能力：** SystemCapability.Utils.Lang 622 623**错误码：** 624 625以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 626 627| 错误码ID | 错误信息 | 628| -------- | ------------------------------- | 629| 10200004 | The Worker instance is not running. | 630 631**示例：** 632 633```ts 634// Index.ets 635import { worker } from '@kit.ArkTS'; 636 637const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets"); 638workerInstance.terminate(); 639``` 640 641 642### addEventListener<sup>9+</sup> 643 644addEventListener(type: string, listener: WorkerEventListener): void 645 646向宿主线程的Worker实例对象添加一个事件监听，该接口与[on<sup>9+</sup>](#on9)接口功能一致。 647 648**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 649 650**系统能力：** SystemCapability.Utils.Lang 651 652**参数：** 653 654| 参数名 | 类型 | 必填 | 说明 | 655| -------- | -------------------------------------------- | ---- | ---------------- | 656| type | string | 是 | 监听的事件类型。 | 657| listener | [WorkerEventListener](#workereventlistener9) | 是 | 回调的事件。 | 658 659**错误码：** 660 661以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 662 663| 错误码ID | 错误信息 | 664| -------- | -------------------------------------------- | 665| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 666| 10200004 | Worker instance is not running. | 667| 10200005 | The invoked API is not supported in workers. | 668 669**示例：** 670 671```ts 672// Index.ets 673import { worker } from '@kit.ArkTS'; 674 675const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets"); 676 677workerInstance.addEventListener("alert", () => { 678 console.info("alert listener callback"); 679}) 680 681// 执行 alert 事件类型的回调 682workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持 683``` 684 685 686### removeEventListener<sup>9+</sup> 687 688removeEventListener(type: string, callback?: WorkerEventListener): void 689 690移除宿主线程的Worker实例对象中类型为type的事件监听，该接口与[off<sup>9+</sup>](#off9)接口功能一致。 691 692**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 693 694**系统能力：** SystemCapability.Utils.Lang 695 696**参数：** 697 698| 参数名 | 类型 | 必填 | 说明 | 699| -------- | -------------------------------------------- | ---- | ---------------------------- | 700| type | string | 是 | 需要删除的监听事件类型。 | 701| callback | [WorkerEventListener](#workereventlistener9) | 否 | 回调函数，删除监听事件后执行。 | 702 703**错误码：** 704 705以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 706 707| 错误码ID | 错误信息 | 708| -------- | ------------------------------- | 709| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 710| 10200004 | Worker instance is not running. | 711 712**示例：** 713 714```ts 715// Index.ets 716import { worker } from '@kit.ArkTS'; 717 718const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets"); 719 720workerInstance.addEventListener("alert", () => { 721 console.info("alert listener callback"); 722}) 723 724workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持 725 726workerInstance.removeEventListener("alert"); 727``` 728 729 730### dispatchEvent<sup>9+</sup> 731 732dispatchEvent(event: Event): boolean 733 734在宿主线程将事件对象分发到Worker线程的事件系统，该系统会自动触发该类型事件对应的所有监听器回调。 735 736**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 737 738**系统能力：** SystemCapability.Utils.Lang 739 740**参数：** 741 742| 参数名 | 类型 | 必填 | 说明 | 743| ------ | --------------- | ---- | ---------------- | 744| event | [Event](#event) | 是 | 需要分发的事件。 | 745 746**返回值：** 747 748| 类型 | 说明 | 749| ------- | ------------------------------- | 750| boolean | 分发的结果。true表示分发成功，false表示分发失败。 | 751 752**错误码：** 753 754以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 755 756| 错误码ID | 错误信息 | 757| -------- | ------------------------------- | 758| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 759| 10200004 | Worker instance is not running. | 760 761**示例：** 762 763```ts 764// Index.ets 765import { worker } from '@kit.ArkTS'; 766 767const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets"); 768 769workerInstance.addEventListener("alert", () => { 770 console.info("alert listener callback"); 771}) 772 773let result: Boolean = workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持 774 775console.info("dispatchEvent result is: ", result); 776``` 777 778分发事件（dispatchEvent）可与监听接口（on、once、addEventListener）搭配使用，完整示例请参考[分发事件与监听接口搭配使用示例](#分发事件与监听接口搭配使用示例)。 779 780 781### removeAllListener<sup>9+</sup> 782 783removeAllListener(): void 784 785移除宿主线程中Worker实例对象的所有事件监听。 786 787**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 788 789**系统能力：** SystemCapability.Utils.Lang 790 791**错误码：** 792 793以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 794 795| 错误码ID | 错误信息 | 796| -------- | ------------------------------- | 797| 10200004 | Worker instance is not running. | 798 799**示例：** 800 801```ts 802// Index.ets 803import { worker } from '@kit.ArkTS'; 804 805const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets"); 806workerInstance.addEventListener("alert", () => { 807 console.info("alert listener callback"); 808}) 809workerInstance.removeAllListener(); 810``` 811 812## WorkerEventTarget<sup>9+</sup> 813 814用于管理Worker的监听事件。 815 816### addEventListener<sup>9+</sup> 817 818addEventListener(type: string, listener: WorkerEventListener): void 819 820向Worker线程的实例对象添加事件监听。 821 822**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 823 824**系统能力：** SystemCapability.Utils.Lang 825 826**参数：** 827 828| 参数名 | 类型 | 必填 | 说明 | 829| -------- | -------------------------------------------- | ---- | ---------------- | 830| type | string | 是 | 监听的事件类型。 | 831| listener | [WorkerEventListener](#workereventlistener9) | 是 | 回调的事件。 | 832 833**错误码：** 834 835以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 836 837| 错误码ID | 错误信息 | 838| -------- | -------------------------------------------- | 839| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 840| 10200004 | The Worker instance is not running. | 841| 10200005 | The called API is not supported in the worker thread. | 842 843**示例：** 844 845```ts 846// worker.ets 847import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS'; 848 849const workerPort: ThreadWorkerGlobalScope = worker.workerPort; 850 851workerPort.onmessage = (event: MessageEvents) => { 852 workerPort.addEventListener("alert", () => { 853 console.info("alert listener callback"); 854 }) 855}; 856``` 857 858 859### removeEventListener<sup>9+</sup> 860 861removeEventListener(type: string, callback?: WorkerEventListener): void 862 863移除Worker线程实例对象中类型为type的事件监听。 864 865**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 866 867**系统能力：** SystemCapability.Utils.Lang 868 869**参数：** 870 871| 参数名 | 类型 | 必填 | 说明 | 872| -------- | -------------------------------------------- | ---- | ---------------------------- | 873| type | string | 是 | 需要删除的监听事件类型。 | 874| callback | [WorkerEventListener](#workereventlistener9) | 否 | 回调函数，删除监听事件后执行。 | 875 876**错误码：** 877 878以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 879 880| 错误码ID | 错误信息 | 881| -------- | ------------------------------- | 882| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 883| 10200004 | The Worker instance is not running. | 884 885**示例：** 886 887```ts 888// worker.ets 889import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS'; 890 891const workerPort: ThreadWorkerGlobalScope = worker.workerPort; 892 893workerPort.onmessage = (event: MessageEvents) => { 894 workerPort.addEventListener("alert", () => { 895 console.info("alert listener callback"); 896 }); 897 898 workerPort.removeEventListener("alert"); 899}; 900``` 901 902 903### dispatchEvent<sup>9+</sup> 904 905dispatchEvent(event: Event): boolean 906 907在Worker线程将事件对象分发到Worker线程的事件系统，并触发该类型事件的所有监听器回调。 908 909**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 910 911**系统能力：** SystemCapability.Utils.Lang 912 913**参数：** 914 915| 参数名 | 类型 | 必填 | 说明 | 916| ------ | --------------- | ---- | ---------------- | 917| event | [Event](#event) | 是 | 需要分发的事件。 | 918 919**返回值：** 920 921| 类型 | 说明 | 922| ------- | ------------------------------- | 923| boolean | 分发的结果。true表示分发成功，false表示分发失败。 | 924 925**错误码：** 926 927以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 928 929| 错误码ID | 错误信息 | 930| -------- | ------------------------------- | 931| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 932| 10200004 | The Worker instance is not running. | 933 934**示例：** 935 936```ts 937// worker.ets 938import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS'; 939 940const workerPort: ThreadWorkerGlobalScope = worker.workerPort; 941 942workerPort.onmessage = (event: MessageEvents) => { 943 workerPort.addEventListener("alert", () => { 944 console.info("alert listener callback"); 945 }); 946 947 workerPort.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持 948}; 949``` 950 951分发事件（dispatchEvent）可与监听接口（addEventListener）搭配使用，完整示例请参考[分发事件与监听接口搭配使用示例](#分发事件与监听接口搭配使用示例)。 952 953 954### removeAllListener<sup>9+</sup> 955 956removeAllListener(): void 957 958移除Worker线程的实例对象所有的事件监听。 959 960**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 961 962**系统能力：** SystemCapability.Utils.Lang 963 964**错误码：** 965 966以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 967 968| 错误码ID | 错误信息 | 969| -------- | ------------------------------- | 970| 10200004 | The Worker instance is not running. | 971 972**示例：** 973 974```ts 975// worker.ets 976import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS'; 977 978const workerPort: ThreadWorkerGlobalScope = worker.workerPort; 979 980workerPort.onmessage = (event: MessageEvents) => { 981 workerPort.addEventListener("alert", () => { 982 console.info("alert listener callback"); 983 }); 984 985 workerPort.removeAllListener(); 986}; 987``` 988 989 990## ThreadWorkerGlobalScope<sup>9+</sup> 991 992Worker线程用于与宿主线程通信的类。ThreadWorkerGlobalScope类继承[GlobalScope](#globalscope9)。 993 994### 属性 995 996**系统能力：** SystemCapability.Utils.Lang 997 998| 名称 | 类型 | 只读 | 可选 | 说明 | 999| ------ | ---------------------- | ---- | --- | ------------------------------------------------------------ | 1000| onmessage<sup>9+</sup> | (this: ThreadWorkerGlobalScope, ev: [MessageEvents](#messageevents9)) => void | 否 | 是 | 回调函数。表示Worker线程收到来自其宿主线程通过[postMessage](#postmessage9-1)或[postMessageWithSharedSendable](#postmessagewithsharedsendable12)接口发送的消息时被调用的事件处理程序，处理程序在Worker线程中执行。其中this指调用者对象本身[ThreadWorkerGlobalScope](#threadworkerglobalscope9)，ev类型为[MessageEvents](#messageevents9)，表示收到的宿主线程发送的消息数据。默认值为undefined。<br/>**原子化服务API**：从API version 11开始，该属性支持在原子化服务中使用。| 1001| onmessageerror<sup>9+</sup> | (this: ThreadWorkerGlobalScope, ev: [MessageEvents](#messageevents9)) => void | 否 | 是 | 回调函数。表示当Worker线程的Worker对象接收到一条无法被反序列化的消息时被调用的事件处理程序，处理程序在Worker线程中执行。其中this指调用者对象本身[ThreadWorkerGlobalScope](#threadworkerglobalscope9)，ev类型为[MessageEvents](#messageevents9)，表示收到的消息数据。默认值为undefined。<br/>**原子化服务API**：从API version 11开始，该属性支持在原子化服务中使用。| 1002 1003### postMessage<sup>9+</sup> 1004 1005postMessage(messageObject: Object, transfer: ArrayBuffer[]): void; 1006 1007Worker线程通过转移对象所有权的方式向宿主线程发送消息。 1008 1009**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1010 1011**系统能力：** SystemCapability.Utils.Lang 1012 1013**参数：** 1014 1015| 参数名 | 类型 | 必填 | 说明 | 1016| -------- | ------------- | ---- | ------------------------------------------------------------ | 1017| messageObject | Object | 是 | 发送至宿主线程的数据，该数据对象必须是可序列化对象，序列化支持类型见[其他说明](#序列化支持类型)。 | 1018| transfer | ArrayBuffer[] | 是 | 表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用，数组不可传入null。 | 1019 1020**错误码：** 1021 1022以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1023 1024| 错误码ID | 错误信息 | 1025| -------- | ----------------------------------------- | 1026| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1027| 10200004 | The Worker instance is not running. | 1028| 10200006 | An exception occurred during serialization. | 1029 1030**示例：** 1031 1032```ts 1033// Index.ets 1034import { worker, MessageEvents } from '@kit.ArkTS'; 1035 1036const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets"); 1037workerInstance.postMessage("hello world"); 1038workerInstance.onmessage = (e: MessageEvents): void => { 1039 console.info("receive data from worker.ets"); 1040} 1041``` 1042 1043```ts 1044// worker.ets 1045import { worker, MessageEvents } from '@kit.ArkTS'; 1046 1047const workerPort = worker.workerPort; 1048workerPort.onmessage = (e: MessageEvents): void => { 1049 let buffer = new ArrayBuffer(8); 1050 workerPort.postMessage(buffer, [buffer]); 1051} 1052``` 1053 1054### postMessage<sup>9+</sup> 1055 1056postMessage(messageObject: Object, options?: PostMessageOptions): void 1057 1058Worker线程通过转移对象所有权或拷贝数据的方式向宿主线程发送消息。在传递[Sendable对象](../../arkts-utils/arkts-sendable.md)时，使用拷贝数据的方式进行传递。 1059 1060**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1061 1062**系统能力：** SystemCapability.Utils.Lang 1063 1064**参数：** 1065 1066| 参数名 | 类型 | 必填 | 说明 | 1067| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 1068| messageObject | Object | 是 | 发送至宿主线程的数据，该数据对象必须是可序列化对象，序列化支持类型见[其他说明](#序列化支持类型)。 | 1069| options | [PostMessageOptions](#postmessageoptions) | 否 | 当填入该参数时，其作用与传入ArrayBuffer[]相同，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将变为不可用，仅在宿主线程中可用。<br/>若不填入该参数，默认设置为 undefined，通过拷贝数据的方式传输信息到宿主线程。 | 1070 1071**错误码：** 1072 1073以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1074 1075| 错误码ID | 错误信息 | 1076| -------- | ----------------------------------------- | 1077| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1078| 10200004 | The Worker instance is not running. | 1079| 10200006 | An exception occurred during serialization. | 1080 1081**示例：** 1082 1083```ts 1084// Index.ets 1085import { worker, MessageEvents } from '@kit.ArkTS'; 1086 1087const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets"); 1088workerInstance.postMessage("hello world"); 1089workerInstance.onmessage = (e: MessageEvents): void => { 1090 console.info("receive data from worker.ets"); 1091} 1092``` 1093 1094```ts 1095// worker.ets 1096import { worker, MessageEvents } from '@kit.ArkTS'; 1097 1098const workerPort = worker.workerPort; 1099workerPort.onmessage = (e: MessageEvents): void => { 1100 workerPort.postMessage("receive data from main thread"); 1101} 1102``` 1103 1104 1105### postMessageWithSharedSendable<sup>12+</sup> 1106 1107postMessageWithSharedSendable(message: Object, transfer?: ArrayBuffer[]): void 1108 1109Worker线程向宿主线程发送消息，消息中的[Sendable对象](../../arkts-utils/arkts-sendable.md)通过引用传递，非Sendable对象通过拷贝数据的方式传递。 1110 1111**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1112 1113**系统能力：** SystemCapability.Utils.Lang 1114 1115**参数：** 1116 1117| 参数名 | 类型 | 必填 | 说明 | 1118| --------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 1119| message | Object | 是 | 发送至宿主线程的数据，该数据对象必须是可序列化或可共享，序列化支持类型见[序列化类型说明](#序列化支持类型)，共享支持类型见[Sendable支持的数据类型](../../arkts-utils/arkts-sendable.md#sendable支持的数据类型)。 | 1120| transfer | ArrayBuffer[] | 否 | 表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用，数组不可传入null。默认值为空数组。 | 1121 1122**错误码：** 1123 1124以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1125 1126| 错误码ID | 错误信息 | 1127| -------- | ----------------------------------------- | 1128| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1129| 10200004 | The Worker instance is not running. | 1130| 10200006 | An exception occurred during serialization. | 1131 1132**示例：** 1133 1134<!--code_no_check--> 1135```ts 1136// worker文件路径为：entry/src/main/ets/workers/Worker.ets 1137// Worker.ets 1138// 新建SendableObject实例并通过Worker线程传递至宿主线程 1139 1140import { SendableObject } from '../pages/sendable'; 1141import { worker, ThreadWorkerGlobalScope, MessageEvents, ErrorEvent } from '@kit.ArkTS'; 1142 1143const workerPort: ThreadWorkerGlobalScope = worker.workerPort; 1144workerPort.onmessage = (e: MessageEvents) => { 1145 let object: SendableObject = new SendableObject(); 1146 workerPort.postMessageWithSharedSendable(object); 1147} 1148``` 1149 1150```ts 1151// sendable.ets 1152// 定义SendableObject 1153 1154@Sendable 1155export class SendableObject { 1156 a:number = 45; 1157} 1158``` 1159 1160<!--code_no_check--> 1161```ts 1162// Index.ets 1163// 接收Worker线程传递至宿主线程的数据并访问其属性 1164 1165import { worker, MessageEvents } from '@kit.ArkTS'; 1166import { SendableObject } from './sendable'; 1167 1168const workerInstance = new worker.ThreadWorker("entry/ets/workers/Worker.ets"); 1169workerInstance.postMessage(1); 1170workerInstance.onmessage = (e: MessageEvents) => { 1171 let obj: SendableObject = e.data; 1172 console.info("sendable index obj is: " + obj.a); 1173} 1174``` 1175 1176 1177### callGlobalCallObjectMethod<sup>11+</sup> 1178 1179callGlobalCallObjectMethod(instanceName: string, methodName: string, timeout: number, ...args: Object[]): Object 1180 1181Worker线程调用宿主线程上注册的对象的指定方法，此调用对Worker线程同步，对宿主线程异步，返回值通过数据拷贝传递。 1182 1183**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1184 1185**系统能力：** SystemCapability.Utils.Lang 1186 1187**参数：** 1188 1189| 参数名 | 类型 | 必填 | 说明 | 1190| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 1191| instanceName | string | 是 | 注册对象时使用的键，用于在宿主线程中查找对象。 | 1192| methodName | string | 是 | 在已注册对象上调用的方法名。该方法不能使用async修饰，也不能基于底层异步机制返回结果，否则会抛出异常。 | 1193| timeout | number | 是 | 表示从Worker线程发起调用开始到在主线程中执行目标方法的最大等待时间，单位为ms，取整数，取值范围为[1-5000]ms。也可取特殊值0，此时表示本次调用等待时间为5000ms。 | 1194| args | Object[] | 否 | 注册对象上所调用方法的参数数组。 | 1195 1196**返回值：** 1197 1198| 类型 | 说明 | 1199| ------------------------------------- | ------------------------------- | 1200| Object | 返回值为调用方法在宿主线程的返回值，该返回值必须是可序列化的，具体可见序列化支持类型。| 1201 1202**错误码：** 1203 1204以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1205 1206| 错误码ID | 错误信息 | 1207| -------- | ----------------------------------------- | 1208| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1209| 10200004 | Worker instance is not running. | 1210| 10200006 | An exception occurred during serialization. | 1211| 10200019 | The globalCallObject is not registered. | 1212| 10200020 | The method to be called is not callable or is an async method or a generator. | 1213| 10200021 | The global call exceeds the timeout. | 1214 1215**示例：** 1216```ts 1217//Index.ets 1218import { worker } from '@kit.ArkTS'; 1219 1220const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets"); 1221class TestObj { 1222 private message : string = "this is a message from TestObj"; 1223 public getMessage() : string { 1224 return this.message; 1225 } 1226 public getMessageWithInput(str : string) : string { 1227 return this.message + " with input: " + str; 1228 } 1229} 1230let registerObj = new TestObj(); 1231// 在ThreadWorker实例上注册registerObj 1232workerInstance.registerGlobalCallObject("myObj", registerObj); 1233workerInstance.postMessage("start worker"); 1234// 需要在组件生命周期结束时调用： 1235// workerInstance.unregisterGlobalCallObject("myObj"); 1236``` 1237 1238```ts 1239// worker.ets 1240import { worker, MessageEvents } from '@kit.ArkTS'; 1241 1242const workerPort = worker.workerPort; 1243workerPort.onmessage = (e: MessageEvents): void => { 1244 try { 1245 // 调用方法无入参 1246 let res : string = workerPort.callGlobalCallObjectMethod("myObj", "getMessage", 0) as string; 1247 console.info("worker:", res); // worker: this is a message from TestObj 1248 } catch (error) { 1249 // 异常处理 1250 console.error("worker: error code is " + error.code + " error message is " + error.message); 1251 } 1252 try { 1253 // 调用方法有入参 1254 let res : string = workerPort.callGlobalCallObjectMethod("myObj", "getMessageWithInput", 0, "hello there!") as string; 1255 console.info("worker:", res); //worker: this is a message from TestObj with input: hello there! 1256 } catch (error) { 1257 // 异常处理 1258 console.error("worker: error code is " + error.code + " error message is " + error.message); 1259 } 1260} 1261``` 1262 1263### close<sup>9+</sup> 1264 1265close(): void 1266 1267销毁Worker线程，终止Worker接收消息。 1268 1269**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1270 1271**系统能力：** SystemCapability.Utils.Lang 1272 1273**错误码：** 1274 1275以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 1276 1277| 错误码ID | 错误信息 | 1278| -------- | ------------------------------- | 1279| 10200004 | The Worker instance is not running. | 1280 1281**示例：** 1282 1283```ts 1284// Index.ets 1285import { worker } from '@kit.ArkTS'; 1286 1287const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets"); 1288workerInstance.postMessage("hello world"); 1289``` 1290 1291```ts 1292// worker.ets 1293import { worker, MessageEvents } from '@kit.ArkTS'; 1294 1295const workerPort = worker.workerPort; 1296workerPort.onmessage = (e: MessageEvents): void => { 1297 workerPort.close(); 1298} 1299``` 1300 1301 1302## WorkerEventListener<sup>9+</sup> 1303 1304事件监听类。 1305 1306### (event: Event)<sup>9+</sup> 1307 1308(event: Event): void | Promise<void> 1309 1310**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1311 1312**系统能力：** SystemCapability.Utils.Lang 1313 1314**参数：** 1315 1316| 参数名 | 类型 | 必填 | 说明 | 1317| ------ | --------------- | ---- | -------------- | 1318| event | [Event](#event) | 是 | 回调的事件类。 | 1319 1320**返回值：** 1321 1322| 类型 | 说明 | 1323| ------------------------------------- | ------------------------------- | 1324| void \| Promise<void> | 无返回值或者以Promise形式返回。 | 1325 1326**错误码：** 1327 1328以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1329 1330| 错误码ID | 错误信息 | 1331| -------- | -------------------------------------------- | 1332| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1333| 10200004 | Worker instance is not running. | 1334| 10200005 | The invoked API is not supported in workers. | 1335 1336**示例：** 1337 1338```ts 1339// Index.ets 1340import { worker, Event } from "@kit.ArkTS" 1341 1342const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets"); 1343 1344workerInstance.addEventListener("alert", (event: Event) => { 1345 console.info("event type is: ", JSON.stringify(event.type)); 1346}); 1347 1348const eventToDispatch : Event = { type: "alert", timeStamp: 0 }; // timeStamp暂未支持 1349workerInstance.dispatchEvent({ type: "alert", timeStamp: 0 }); 1350``` 1351 1352 1353## GlobalScope<sup>9+</sup> 1354 1355Worker线程自身的运行环境，GlobalScope类继承[WorkerEventTarget](#workereventtarget9)。 1356 1357**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1358 1359**系统能力：** SystemCapability.Utils.Lang 1360 1361| 名称 | 类型 | 只读 | 可选 | 说明 | 1362| ---- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------- | 1363| name | string | 是 | 否 | Worker的名字，new Worker时指定。 | 1364| self | [GlobalScope](#globalscope9) & typeof globalThis | 是 | 否 | GlobalScope本身。 | 1365| onerror | (ev: [ErrorEvent](#errorevent)) => void | 否 | 是 | Worker在执行过程中发生异常被调用的回调函数，在Worker线程中执行，ev表示收到的异常数据。默认值为undefined。| 1366 1367 1368## MessageEvents<sup>9+</sup> 1369 1370消息类，持有Worker线程间传递的数据，MessageEvents类继承[Event](#event)。 1371 1372**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1373 1374**系统能力：** SystemCapability.Utils.Lang 1375 1376| 名称 | 类型 | 只读 | 可选 | 说明 | 1377| ---- | ---- | ---- | ---- | ------------------ | 1378| data | any | 是 | 否 | 线程间传递的数据。 | 1379 1380## MessageType<sup>7+</sup> 1381 1382type MessageType = 'message' | 'messageerror'; 1383 1384表示消息类型。预留数据类型，暂未实现。 1385 1386**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1387 1388**系统能力：** SystemCapability.Utils.Lang 1389 1390| 类型 | 说明 | 1391| ---- | ------------------ | 1392| 'message' | 表示消息类型为message，值固定为'message'字符串。 | 1393| 'messageerror' | 表示消息类型为messageerror，值固定为'messageerror'字符串。 | 1394 1395## ErrorCallback<sup>18+</sup> 1396 1397type ErrorCallback = (err: ErrorEvent) => void 1398 1399表示异常回调类型。 1400 1401**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1402 1403**系统能力：** SystemCapability.Utils.Lang 1404 1405**参数：** 1406 1407| 参数名 | 类型 | 必填 | 说明 | 1408| --------- | ------------------------------- | ---- | ------------------------------------------------------------ | 1409| err | ErrorEvent | 是 | 错误事件类，表示Worker执行过程中出现的异常信息。 | 1410 1411## Worker<sup>(deprecated)</sup> 1412 1413使用以下方法前，均需先构造Worker实例，Worker类继承[EventTarget](#eventtargetdeprecated)。 1414 1415> **说明：**<br/> 1416> 从API version 7开始支持，从API version 9开始废弃，建议使用[ThreadWorker<sup>9+</sup>](#threadworker9)替代。 1417 1418### 属性 1419 1420**系统能力：** SystemCapability.Utils.Lang 1421 1422| 名称 | 类型 | 只读 | 可选 | 说明 | 1423| ------ | ---------------------- | ---- | --- | ------------------------------------------------------------ | 1424| onexit<sup>(deprecated)</sup> | (code: number) => void | 否 | 是 | 回调函数。表示Worker销毁时被调用的事件处理程序，处理程序在宿主线程中执行。其中回调函数中code类型为number，异常退出为1，正常退出为0。默认值为undefined。<br/>**说明**：从API version 7开始支持，从API version 9开始废弃，建议使用[ThreadWorker.onexit](#属性-1)替代。| 1425| onerror<sup>(deprecated)</sup> | (err: [ErrorEvent](#errorevent)) => void | 否 | 是 | 回调函数。表示Worker在执行过程中发生异常被调用的事件处理程序，处理程序在宿主线程中执行。其中回调函数中err类型为[ErrorEvent](#errorevent)，表示收到的异常数据。默认值为undefined。<br/>**说明**：从API version 7开始支持，从API version 9开始废弃，建议使用[ThreadWorker.onerror](#属性-1)替代。| 1426| onmessage<sup>(deprecated)</sup> | (event: [MessageEvent](#messageeventt)) => void | 否 | 是 | 回调函数。表示宿主线程接收到来自其创建的Worker通过workerPort.postMessage接口发送的消息时被调用的事件处理程序，处理程序在宿主线程中执行。其中回调函数中event类型为[MessageEvent](#messageeventt)，表示收到的Worker消息数据。默认值为undefined。<br/>**说明**：从API version 7开始支持，从API version 9开始废弃，建议使用[ThreadWorker.onmessage](#属性-1)替代。| 1427| onmessageerror<sup>(deprecated)</sup> | (event: [MessageEvent](#messageeventt)) => void | 否 | 是 | 回调函数。表示当Worker对象接收到一条无法被序列化的消息时被调用的事件处理程序，处理程序在宿主线程中执行。其中回调函数中event类型为[MessageEvent](#messageeventt)，表示收到的Worker消息数据。默认值为undefined。<br/>**说明**：从API version 7开始支持，从API version 9开始废弃，建议使用[ThreadWorker.onmessageerror](#属性-1)替代。| 1428 1429### constructor<sup>(deprecated)</sup> 1430 1431constructor(scriptURL: string, options?: WorkerOptions) 1432 1433Worker构造函数。 1434 1435> **说明：**<br/> 1436> 从API version 7开始支持，从API version 9开始废弃，建议使用[ThreadWorker.constructor<sup>9+</sup>](#constructor9)替代。 1437 1438**系统能力：** SystemCapability.Utils.Lang 1439 1440**参数：** 1441 1442| 参数名 | 类型 | 必填 | 说明 | 1443| --------- | ------------------------------- | ---- | ------------------------------------------------------------ | 1444| scriptURL | string | 是 | Worker线程文件的路径，详细参考[文件路径注意事项](../../arkts-utils/worker-introduction.md#文件路径注意事项)。 | 1445| options | [WorkerOptions](#workeroptions) | 否 | Worker构造的选项。 | 1446 1447**示例：** 1448 1449此处以在Stage模型的entry模块Index.ets文件中加载Worker文件为例，使用Library加载Worker线程文件的场景参考[文件路径注意事项](../../arkts-utils/worker-introduction.md#文件路径注意事项)。 1450 1451```ts 1452// Index.ets 1453import { worker } from '@kit.ArkTS'; 1454 1455// worker文件所在路径："entry/src/main/ets/workers/worker.ets" 1456const workerInstance = new worker.Worker('entry/ets/workers/worker.ets', {name: "WorkerThread"}); 1457``` 1458 1459### postMessage<sup>(deprecated)</sup> 1460 1461postMessage(message: Object, transfer: ArrayBuffer[]): void 1462 1463宿主线程通过转移对象所有权的方式向Worker线程发送消息。 1464 1465> **说明：**<br/> 1466> 从API version 7开始支持，从API version 9开始废弃，建议使用[ThreadWorker.postMessage<sup>9+</sup>](#postmessage9)替代。 1467 1468**系统能力：** SystemCapability.Utils.Lang 1469 1470**参数：** 1471 1472| 参数名 | 类型 | 必填 | 说明 | 1473| -------- | ------------- | ---- | ------------------------------------------------------------ | 1474| message | Object | 是 | 发送至Worker的数据对象必须是可序列化对象，序列化支持类型见[其他说明](#序列化支持类型)。 | 1475| transfer | ArrayBuffer[] | 是 | 表示可转移的ArrayBuffer实例对象数组，所有权会转移到Worker线程，仅在该线程中可用。数组不可传入null。 | 1476 1477**示例：** 1478 1479```ts 1480// Index.ets 1481import { worker } from '@kit.ArkTS'; 1482 1483const workerInstance = new worker.Worker("entry/ets/workers/worker.ets"); 1484 1485let buffer = new ArrayBuffer(8); 1486workerInstance.postMessage(buffer, [buffer]); 1487``` 1488 1489### postMessage<sup>(deprecated)</sup> 1490 1491postMessage(message: Object, options?: PostMessageOptions): void 1492 1493宿主线程通过转移对象所有权或者拷贝数据的方式向Worker线程发送消息。 1494 1495> **说明：**<br/> 1496> 从API version 7开始支持，从API version 9开始废弃，建议使用[ThreadWorker.postMessage<sup>9+</sup>](#postmessage9-1)替代。 1497 1498**系统能力：** SystemCapability.Utils.Lang 1499 1500**参数：** 1501 1502| 参数名 | 类型 | 必填 | 说明 | 1503| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 1504| message | Object | 是 | 发送至Worker的数据，该数据对象必须是可序列化对象，序列化支持类型见[其他说明](#序列化支持类型)。 | 1505| options | [PostMessageOptions](#postmessageoptions) | 否 | 当填入该参数时，与传入ArrayBuffer[]的作用一致，该数组中对象的所有权会被转移到Worker线程，在宿主线程中将变为不可用，仅在Worker线程中可用。<br/>若不填入该参数，默认设置为undefined，通过拷贝数据的方式传输信息到Worker线程。 | 1506 1507**示例：** 1508 1509```ts 1510// Index.ets 1511import { worker } from '@kit.ArkTS'; 1512 1513const workerInstance = new worker.Worker("entry/ets/workers/worker.ets"); 1514 1515workerInstance.postMessage("hello world"); 1516 1517let buffer = new ArrayBuffer(8); 1518workerInstance.postMessage(buffer, [buffer]); 1519``` 1520 1521 1522### on<sup>(deprecated)</sup> 1523 1524on(type: string, listener: EventListener): void 1525 1526向Worker添加一个事件监听，该接口与[addEventListener<sup>(deprecated)</sup>](#addeventlistenerdeprecated)接口功能一致。 1527 1528> **说明：**<br/> 1529> 从API version 7开始支持，从API version 9开始废弃，建议使用[ThreadWorker.on<sup>9+</sup>](#on9)替代。 1530 1531**系统能力：** SystemCapability.Utils.Lang 1532 1533**参数：** 1534 1535| 参数名 | 类型 | 必填 | 说明 | 1536| -------- | ----------------------------------------- | ---- | ---------------- | 1537| type | string | 是 | 监听的事件类型。 | 1538| listener | [EventListener](#eventlistenerdeprecated) | 是 | 回调事件。 | 1539 1540**示例：** 1541 1542```ts 1543// Index.ets 1544import { worker } from '@kit.ArkTS'; 1545 1546const workerInstance = new worker.Worker("entry/ets/workers/worker.ets"); 1547workerInstance.on("alert", () => { 1548 console.info("alert listener callback"); 1549}) 1550``` 1551 1552 1553### once<sup>(deprecated)</sup> 1554 1555once(type: string, listener: EventListener): void 1556 1557向Worker添加一个事件监听，该事件监听只执行一次，执行完后会自动删除。 1558 1559> **说明：**<br/> 1560> 从API version 7开始支持，从API version 9开始废弃，建议使用[ThreadWorker.once<sup>9+</sup>](#once9)替代。 1561 1562**系统能力：** SystemCapability.Utils.Lang 1563 1564**参数：** 1565 1566| 参数名 | 类型 | 必填 | 说明 | 1567| -------- | ----------------------------------------- | ---- | ---------------- | 1568| type | string | 是 | 监听的事件类型。 | 1569| listener | [EventListener](#eventlistenerdeprecated) | 是 | 回调事件。 | 1570 1571**示例：** 1572 1573```ts 1574// Index.ets 1575import { worker } from '@kit.ArkTS'; 1576 1577const workerInstance = new worker.Worker("entry/ets/workers/worker.ets"); 1578workerInstance.once("alert", () => { 1579 console.info("alert listener callback"); 1580}) 1581``` 1582 1583 1584### off<sup>(deprecated)</sup> 1585 1586off(type: string, listener?: EventListener): void 1587 1588移除类型为type的事件监听，该接口与[removeEventListener<sup>(deprecated)</sup>](#removeeventlistenerdeprecated)接口功能一致。 1589 1590> **说明：**<br/> 1591> 从API version 7开始支持，从API version 9开始废弃，建议使用[ThreadWorker.off<sup>9+</sup>](#off9)替代。 1592 1593**系统能力：** SystemCapability.Utils.Lang 1594 1595**参数：** 1596 1597| 参数名 | 类型 | 必填 | 说明 | 1598| -------- | ----------------------------------------- | ---- | -------------------- | 1599| type | string | 是 | 需要删除的事件类型。 | 1600| listener | [EventListener](#eventlistenerdeprecated) | 否 | 移除监听事件后所执行的回调事件。 | 1601 1602**示例：** 1603 1604```ts 1605// Index.ets 1606import { worker } from '@kit.ArkTS'; 1607 1608const workerInstance = new worker.Worker("entry/ets/workers/worker.ets"); 1609//使用on接口、once接口或addEventListener接口创建“alert”事件，使用off接口删除事件。 1610workerInstance.off("alert"); 1611``` 1612 1613 1614### terminate<sup>(deprecated)</sup> 1615 1616terminate(): void 1617 1618销毁Worker线程，终止Worker接收消息。 1619 1620> **说明：**<br/> 1621> 从API version 7开始支持，从API version 9开始废弃，建议使用[ThreadWorker.terminate<sup>9+</sup>](#terminate9)替代。 1622 1623**系统能力：** SystemCapability.Utils.Lang 1624 1625**示例：** 1626 1627```ts 1628// Index.ets 1629import { worker } from '@kit.ArkTS'; 1630 1631const workerInstance = new worker.Worker("entry/ets/workers/worker.ets"); 1632workerInstance.terminate(); 1633``` 1634 1635 1636## EventTarget<sup>(deprecated)</sup> 1637> **说明：**<br/> 1638> 从API version 7开始支持，从API version 9开始废弃，建议使用[WorkerEventTarget<sup>9+</sup>](#workereventtarget9)替代。 1639 1640### addEventListener<sup>(deprecated)</sup> 1641 1642addEventListener(type: string, listener: EventListener): void 1643 1644向Worker添加一个事件监听，该接口与[on<sup>(deprecated)</sup>](#ondeprecated)接口功能一致。 1645 1646> **说明：**<br/> 1647> 从API version 7开始支持，从API version 9开始废弃，建议使用[addEventListener<sup>9+</sup>](#addeventlistener9)替代。 1648 1649**系统能力：** SystemCapability.Utils.Lang 1650 1651**参数：** 1652 1653| 参数名 | 类型 | 必填 | 说明 | 1654| -------- | ----------------------------------------- | ---- | ---------------- | 1655| type | string | 是 | 监听的事件类型。 | 1656| listener | [EventListener](#eventlistenerdeprecated) | 是 | 事件触发时的回调函数。 | 1657 1658**示例：** 1659 1660```ts 1661// worker.ets 1662import { DedicatedWorkerGlobalScope, ErrorEvent, MessageEvents, worker } from '@kit.ArkTS'; 1663 1664const workerPort: DedicatedWorkerGlobalScope = worker.parentPort; 1665 1666workerPort.addEventListener("alert", () => { 1667 console.info("alert listener callback"); 1668}) 1669``` 1670 1671 1672### removeEventListener<sup>(deprecated)</sup> 1673 1674removeEventListener(type: string, callback?: EventListener): void 1675 1676移除Worker的事件监听，该接口与[off<sup>(deprecated)</sup>](#offdeprecated)接口功能一致。 1677 1678> **说明：**<br/> 1679> 从API version 7开始支持，从API version 9开始废弃，建议使用[removeEventListener<sup>9+</sup>](#removeeventlistener9)替代。 1680 1681**系统能力：** SystemCapability.Utils.Lang 1682 1683**参数：** 1684 1685| 参数名 | 类型 | 必填 | 说明 | 1686| -------- | ----------------------------------------- | ---- | ------------------------ | 1687| type | string | 是 | 需要移除的事件类型。 | 1688| callback | [EventListener](#eventlistenerdeprecated) | 否 | 回调函数，删除监听事件后执行。 | 1689 1690**示例：** 1691 1692```ts 1693// worker.ets 1694import { DedicatedWorkerGlobalScope, ErrorEvent, MessageEvents, worker } from '@kit.ArkTS'; 1695 1696const workerPort: DedicatedWorkerGlobalScope = worker.parentPort; 1697 1698workerPort.addEventListener("alert", () => { 1699 console.info("alert listener callback"); 1700}) 1701 1702workerPort.removeEventListener('alert'); 1703``` 1704 1705 1706### dispatchEvent<sup>(deprecated)</sup> 1707 1708dispatchEvent(event: Event): boolean 1709 1710分发定义在Worker的事件。 1711 1712> **说明：**<br/> 1713> 从API version 7开始支持，从API version 9开始废弃，建议使用[dispatchEvent<sup>9+</sup>](#dispatchevent9)替代。 1714 1715**系统能力：** SystemCapability.Utils.Lang 1716 1717**参数：** 1718 1719| 参数名 | 类型 | 必填 | 说明 | 1720| ------ | --------------- | ---- | ---------------- | 1721| event | [Event](#event) | 是 | 需要分发的事件。 | 1722 1723**返回值：** 1724 1725| 类型 | 说明 | 1726| ------- | ------------------------------- | 1727| boolean | 分发的结果。true表示分发成功，false表示分发失败。 | 1728 1729**示例：** 1730 1731```ts 1732// worker.ets 1733import { DedicatedWorkerGlobalScope, ErrorEvent, MessageEvents, worker } from '@kit.ArkTS'; 1734 1735const workerPort: DedicatedWorkerGlobalScope = worker.parentPort; 1736 1737workerPort.addEventListener("alert_add", ()=>{ 1738 console.info("alert listener callback"); 1739}) 1740 1741workerPort.dispatchEvent({type: 'alert_add', timeStamp: 0}); // timeStamp暂未支持 1742``` 1743 1744分发事件（dispatchEvent）可与监听接口（addEventListener）搭配使用，示例如下： 1745 1746```ts 1747// Index.ets 1748import { worker } from '@kit.ArkTS'; 1749 1750const workerInstance = new worker.Worker("entry/ets/workers/worker.ets"); 1751workerInstance.postMessage("hello world"); 1752workerInstance.onmessage = (): void => { 1753 console.info("receive data from worker.ets"); 1754} 1755``` 1756 1757```ts 1758// worker.ets 1759import { DedicatedWorkerGlobalScope, ErrorEvent, MessageEvents, worker } from '@kit.ArkTS'; 1760 1761const workerPort: DedicatedWorkerGlobalScope = worker.parentPort; 1762 1763workerPort.addEventListener("alert", ()=>{ 1764 console.info("alert listener callback"); 1765}) 1766 1767workerPort.onmessage = (event: MessageEvents) => { 1768 workerPort.dispatchEvent({type:"alert", timeStamp:0}); // timeStamp暂未支持 1769} 1770``` 1771 1772### removeAllListener<sup>(deprecated)</sup> 1773 1774removeAllListener(): void 1775 1776移除Worker所有的事件监听。 1777 1778> **说明：**<br/> 1779> 从API version 7开始支持，从API version 9开始废弃，建议使用[removeAllListener<sup>9+</sup>](#removealllistener9)替代。 1780 1781**系统能力：** SystemCapability.Utils.Lang 1782 1783**示例：** 1784 1785```ts 1786// worker.ets 1787import { DedicatedWorkerGlobalScope, ErrorEvent, MessageEvents, worker } from '@kit.ArkTS'; 1788 1789const workerPort: DedicatedWorkerGlobalScope = worker.parentPort; 1790 1791workerPort.addEventListener("alert_add", ()=>{ 1792 console.info("alert listener callback"); 1793}) 1794 1795workerPort.removeAllListener(); 1796``` 1797 1798 1799## DedicatedWorkerGlobalScope<sup>(deprecated)</sup> 1800 1801Worker线程用于与宿主线程通信的类。DedicatedWorkerGlobalScope类继承[WorkerGlobalScope](#workerglobalscopedeprecated)。 1802 1803> **说明：**<br/> 1804> 从API version 7开始支持，从API version 9开始废弃，建议使用[ThreadWorkerGlobalScope<sup>9+</sup>](#threadworkerglobalscope9)替代。 1805 1806### 属性 1807 1808**系统能力：** SystemCapability.Utils.Lang 1809 1810| 名称 | 类型 | 只读 | 可选 | 说明 | 1811| ------ | ---------------------- | ---- | --- | ------------------------------------------------------------ | 1812| onmessage<sup>(deprecated)</sup> | (this: DedicatedWorkerGlobalScope, ev: [MessageEvent](#messageeventt)) => void | 否 | 是 | 回调函数，表示Worker线程收到来自其宿主线程通过postMessage接口发送的消息时被调用的事件处理程序，处理程序在Worker线程中执行。其中this指调用者对象本身[DedicatedWorkerGlobalScope](#dedicatedworkerglobalscopedeprecated)，ev类型为[MessageEvent](#messageeventt)，表示收到的Worker消息数据。默认值为undefined。<br/>**说明**：从API version 7开始支持，从API version 9开始废弃，建议使用[ThreadWorkerGlobalScope.onmessage](#属性-2)替代。 | 1813| onmessageerror<sup>(deprecated)</sup> | (this: DedicatedWorkerGlobalScope, ev: [MessageEvent](#messageeventt)) => void | 否 | 是 | 回调函数，表示当Worker对象接收到一条无法被反序列化的消息时被调用的事件处理程序，处理程序在Worker线程中执行。其中this指调用者对象本身[DedicatedWorkerGlobalScope](#dedicatedworkerglobalscopedeprecated)，ev类型为[MessageEvent](#messageeventt)，表示收到的Worker消息数据。从API version 7开始支持，默认值为undefined。<br/>**说明**：从API version 9开始废弃，建议使用[ThreadWorkerGlobalScope.onmessageerror](#属性-2)替代。 | 1814 1815### postMessage<sup>(deprecated)</sup> 1816 1817postMessage(messageObject: Object, transfer: Transferable[]): void 1818 1819Worker线程通过转移对象所有权的方式向宿主线程发送消息。 1820 1821> **说明：**<br/> 1822> 此接口暂不支持使用，从API version 9开始废弃，建议使用[ThreadWorkerGlobalScope<sup>9+</sup>.postMessage<sup>9+</sup>](#postmessage9-2)替代。 1823 1824**系统能力：** SystemCapability.Utils.Lang 1825 1826**参数：** 1827 1828| 参数名 | 类型 | 必填 | 说明 | 1829| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 1830| messageObject | Object | 是 | 发送至宿主线程的数据，该数据对象必须是可序列化对象，序列化支持类型见[其他说明](#序列化支持类型)。 | 1831| transfer| Transferable[] | 是 | 暂不支持该参数类型。 | 1832 1833### postMessage<sup>(deprecated)</sup> 1834 1835postMessage(messageObject: Object, transfer: ArrayBuffer[]): void 1836 1837Worker线程通过转移对象所有权的方式向宿主线程发送消息。 1838 1839> **说明：**<br/> 1840> DedicatedWorkerGlobalScope类自API version 9开始废弃，本接口建议使用[ThreadWorkerGlobalScope<sup>9+</sup>.postMessage<sup>9+</sup>](#postmessage9-2)替代。 1841 1842**系统能力：** SystemCapability.Utils.Lang 1843 1844**参数：** 1845 1846| 参数名 | 类型 | 必填 | 说明 | 1847| -------- | ------------- | ---- | ------------------------------------------------------------ | 1848| messageObject | Object | 是 | 发送至宿主线程的数据，该数据对象必须是可序列化对象，序列化支持类型见[其他说明](#序列化支持类型)。 | 1849| transfer | ArrayBuffer[] | 是 | 表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用，数组不可传入null。 | 1850 1851**示例：** 1852 1853```ts 1854// Index.ets 1855import { worker } from '@kit.ArkTS'; 1856 1857const workerInstance = new worker.Worker("entry/ets/workers/worker.ets"); 1858workerInstance.postMessage("hello world"); 1859workerInstance.onmessage = (e: MessageEvents): void => { 1860 // let data = e.data; 1861 console.info("receive data from worker.ets"); 1862} 1863``` 1864```ts 1865// worker.ets 1866import { DedicatedWorkerGlobalScope, worker } from '@kit.ArkTS'; 1867 1868const workerPort: DedicatedWorkerGlobalScope = worker.parentPort; 1869 1870workerPort.onmessage = (): void => { 1871 // let data = e.data; 1872 let buffer = new ArrayBuffer(5) 1873 workerPort.postMessage(buffer, [buffer]); 1874} 1875``` 1876 1877### postMessage<sup>(deprecated)</sup> 1878 1879postMessage(messageObject: Object, options?: PostMessageOptions): void 1880 1881Worker线程通过转移对象所有权或者拷贝数据的方式向宿主线程发送消息。 1882 1883> **说明：**<br/> 1884> 从API version 7开始支持，从API version 9开始废弃，建议使用[ThreadWorkerGlobalScope<sup>9+</sup>.postMessage<sup>9+</sup>](#postmessage9-3)替代。 1885 1886**系统能力：** SystemCapability.Utils.Lang 1887 1888**参数：** 1889 1890| 参数名 | 类型 | 必填 | 说明 | 1891| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 1892| messageObject | Object | 是 | 发送至宿主线程的数据，该数据对象必须是可序列化对象，序列化支持类型见[其他说明](#序列化支持类型)。 | 1893| options | [PostMessageOptions](#postmessageoptions) | 否 | 当填入该参数时，与传入ArrayBuffer[]的作用一致，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用。<br/>若不填入该参数，默认设置为 undefined，通过拷贝数据的方式传输信息到宿主线程。 | 1894 1895**示例：** 1896 1897<!--no_check--> 1898```ts 1899// Index.ets 1900import { worker } from '@kit.ArkTS'; 1901 1902const workerInstance = new worker.Worker("entry/ets/workers/worker.ets"); 1903workerInstance.postMessage("hello world"); 1904workerInstance.onmessage = (): void => { 1905 console.info("receive data from worker.ets"); 1906} 1907``` 1908```ts 1909// worker.ets 1910import { ErrorEvent, MessageEvents, worker } from '@kit.ArkTS'; 1911 1912const parentPort = worker.parentPort; 1913parentPort.onmessage = (e: MessageEvents) => { 1914 parentPort.postMessage("receive data from main thread"); 1915} 1916``` 1917 1918### close<sup>(deprecated)</sup> 1919 1920close(): void 1921 1922销毁Worker线程，终止Worker接收消息。 1923 1924> **说明：**<br/> 1925> 从API version 7开始支持，从API version 9开始废弃，建议使用[ThreadWorkerGlobalScope<sup>9+</sup>.close<sup>9+</sup>](#close9)替代。 1926 1927**系统能力：** SystemCapability.Utils.Lang 1928 1929**示例：** 1930 1931```ts 1932// Index.ets 1933import { worker } from '@kit.ArkTS'; 1934 1935const workerInstance = new worker.Worker("entry/ets/workers/worker.ets"); 1936workerInstance.postMessage("hello world"); 1937``` 1938```ts 1939// worker.ets 1940import { worker } from '@kit.ArkTS'; 1941 1942const parentPort = worker.parentPort; 1943parentPort.onmessage = (): void => { 1944 parentPort.close() 1945} 1946``` 1947 1948 1949## PostMessageOptions 1950 1951明确数据传递过程中需要转移所有权的对象，这些对象必须是ArrayBuffer，在发送方的上下文中将变为不可用，仅在接收方可用。 1952 1953**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 1954 1955**系统能力：** SystemCapability.Utils.Lang 1956 1957| 名称 | 类型 | 只读 | 可选 | 说明 | 1958| -------- | -------- | ---- | ---- | --------------------------------- | 1959| transfer | Object[] | 否 | 是 | ArrayBuffer数组，用于传递所有权。该数组中不可传入null。默认值为undefined。 | 1960 1961 1962## Event 1963 1964事件类。 1965 1966**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1967 1968**系统能力：** SystemCapability.Utils.Lang 1969 1970| 名称 | 类型 | 只读 | 可选 | 说明 | 1971| --------- | ------ | ---- | ---- | -------------------------------------------- | 1972| type | string | 是 | 否 | 指定事件的类型。 | 1973| timeStamp | number | 是 | 否 | 事件创建时的时间戳（精度为毫秒），目前不支持。 | 1974 1975 1976## EventListener<sup>(deprecated)</sup> 1977 1978事件监听类用于处理事件。 1979 1980> **说明：** 1981> 1982> 从API version 7开始支持，从API version 9开始废弃，建议使用[WorkerEventListener<sup>9+</sup>](#workereventlistener9)替代。 1983 1984### (evt: Event)<sup>(deprecated)</sup> 1985 1986(evt: Event): void | Promise<void> 1987 1988> **说明：** 1989> 1990> 从API version 7开始支持，从API version 9开始废弃，建议使用[(event:Event)<sup>9+</sup>](#event-event9)替代。 1991 1992**系统能力：** SystemCapability.Utils.Lang 1993 1994**参数：** 1995 1996| 参数名 | 类型 | 必填 | 说明 | 1997| ------ | --------------- | ---- | -------------- | 1998| evt | [Event](#event) | 是 | 回调的事件类。 | 1999 2000**返回值：** 2001 2002| 类型 | 说明 | 2003| ------------------------------------- | ------------------------------- | 2004| void \| Promise<void> | 无返回值或者以Promise形式返回。 | 2005 2006**示例：** 2007 2008```ts 2009// Index.ets 2010import { worker } from '@kit.ArkTS'; 2011 2012const workerInstance = new worker.Worker("entry/ets/workers/worker.ets"); 2013workerInstance.addEventListener("alert", ()=>{ 2014 console.info("alert listener callback"); 2015}) 2016``` 2017 2018 2019## ErrorEvent 2020 2021错误事件类用于表示Worker执行过程中出现异常的详细信息，该类继承[Event](#event)。 2022 2023**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 2024 2025**系统能力：** SystemCapability.Utils.Lang 2026 2027| 名称 | 类型 | 只读 | 可选 | 说明 | 2028| -------- | ------ | ---- | ---- | -------------------- | 2029| message | string | 是 | 否 | 异常发生的错误信息。 | 2030| filename | string | 是 | 否 | 出现异常所在的文件。 | 2031| lineno | number | 是 | 否 | 异常所在的行数。 | 2032| colno | number | 是 | 否 | 异常所在的列数。 | 2033| error | Object | 是 | 否 | 异常类型。 | 2034 2035 2036## MessageEvent\<T\> 2037 2038消息类，持有Worker线程间传递的数据，MessageEvent类继承[Event](#event)。 2039 2040**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 2041 2042**系统能力：** SystemCapability.Utils.Lang 2043 2044| 名称 | 类型 | 只读 | 可选 | 说明 | 2045| ---- | ---- | ---- | ---- | ------------------ | 2046| data | T | 是 | 否 | 线程间传递的数据。 | 2047 2048 2049## WorkerGlobalScope<sup>(deprecated)</sup> 2050 2051Worker线程自身的运行环境，WorkerGlobalScope类继承[EventTarget](#eventtargetdeprecated)。 2052 2053> **说明：**<br/> 2054> 从API version 7开始支持，从API version 9开始废弃，建议使用[GlobalScope<sup>9+</sup>](#globalscope9)替代。 2055 2056**系统能力：** SystemCapability.Utils.Lang 2057 2058| 名称 | 类型 | 只读 | 可选 | 说明 | 2059| ---- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------- | 2060| name | string | 是 | 否 | Worker的名字，new Worker时指定。 | 2061| self | [WorkerGlobalScope](#workerglobalscopedeprecated) & typeof globalThis | 是 | 否 | WorkerGlobalScope本身。 | 2062| onerror | (ev: [ErrorEvent](#errorevent)) => void | 否 | 是 | Worker在执行过程中发生异常被调用的回调函数，在Worker线程中执行，ev表示收到的异常数据，默认值为undefined。 | 2063 2064 2065## 其他说明 2066 2067### 序列化支持类型 2068 2069序列化支持类型包括：除Symbol之外的基础类型、Date、String、RegExp、Array、Map、Set、Object（仅限简单对象，比如通过"{}"或者"new Object"创建，普通对象仅支持传递属性，不支持传递其原型及方法）、ArrayBuffer、TypedArray。 2070 2071特例：传递通过自定义class创建出来的object时，不会发生序列化错误，但是自定义class的属性（如Function）无法通过序列化传递。 2072> **说明：**<br/> 2073> 以API version 9的FA工程为例。 2074 2075```ts 2076// Index.ets 2077import { worker, MessageEvents } from '@kit.ArkTS'; 2078 2079const workerInstance = new worker.ThreadWorker("workers/worker.ets"); 2080workerInstance.postMessage("message from main thread to worker"); 2081workerInstance.onmessage = (d: MessageEvents): void => { 2082 // 当Worker线程传递obj2时，data即为obj2。data没有Init、SetName的方法 2083 let data: string = d.data; 2084} 2085``` 2086```ts 2087// worker.ets 2088import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS'; 2089 2090const workerPort = worker.workerPort; 2091class MyModel { 2092 name = "undefined"; 2093 Init() { 2094 this.name = "MyModel"; 2095 } 2096} 2097workerPort.onmessage = (d: MessageEvents): void => { 2098 console.info("worker.ets onmessage"); 2099 let data: string = d.data; 2100 let func1 = () => { 2101 console.info("post message is function"); 2102 } 2103 // workerPort.postMessage(func1); 传递func1发生序列化错误 2104 let obj2 = new MyModel(); 2105 workerPort.postMessage(obj2); // 传递obj2不会发生序列化错误，obj2中的函数会丢失 2106} 2107workerPort.onmessageerror = () => { 2108 console.error("worker.ets onmessageerror"); 2109} 2110workerPort.onerror = (err: ErrorEvent) => { 2111 console.error("worker.ets onerror" + err.message); 2112} 2113``` 2114 2115### 内存模型 2116Worker基于Actor并发模型实现。在Worker的交互流程中，宿主线程可以创建多个Worker子线程，各个Worker线程间运行环境相互隔离，并通过序列化、引用传递或转移所有权的方式传递对象，等到Worker线程完成计算任务，再把结果返回给宿主线程。 2117 2118Actor并发模型的交互原理：各个Actor并发地处理宿主线程任务，每个Actor内部都有一个消息队列和单线程执行模块。消息队列负责接收宿主线程及其他Actor的请求，而单线程执行模块则负责串行地处理这些请求、向其他Actor发送请求以及创建新的Actor。由于Actor采用的是异步方式，各个Actor之间相互隔离且没有数据竞争，因此Actor可以高并发运行。 2119 2120## 完整示例 2121> **说明：**<br/> 2122> API version 8及之前的版本仅支持FA模型，如需使用，注意更换构造Worker的接口和创建Worker线程中与宿主线程通信的对象的两个方法。<br> 2123### FA模型 2124> 此处以API version 9的工程为例。 2125 2126```ts 2127// main thread(同级目录为例) 2128import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS'; 2129 2130// 宿主线程中创建Worker对象 2131const workerInstance = new worker.ThreadWorker("workers/worker.ets"); 2132 2133// 宿主线程向worker线程传递信息 2134const buffer = new ArrayBuffer(8); 2135workerInstance.postMessage(buffer, [buffer]); 2136 2137// 宿主线程接收worker线程信息 2138workerInstance.onmessage = (e: MessageEvents): void => { 2139 // data：worker线程发送的信息 2140 let data: Int8Array = e.data; 2141 console.info("main thread onmessage"); 2142 2143 // 销毁Worker对象 2144 workerInstance.terminate(); 2145} 2146 2147// 在调用terminate后，执行回调onexit 2148workerInstance.onexit = (code) => { 2149 console.info("main thread terminate"); 2150} 2151 2152workerInstance.onerror = (err: ErrorEvent) => { 2153 console.error("main error message " + err.message); 2154} 2155``` 2156```ts 2157// worker.ets 2158import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS'; 2159 2160// 创建worker线程中与宿主线程通信的对象 2161const workerPort = worker.workerPort; 2162 2163// worker线程接收宿主线程信息 2164workerPort.onmessage = (e: MessageEvents): void => { 2165 // data：宿主线程发送的信息 2166 let data: ArrayBuffer = e.data; 2167 const view = new Int8Array(data).fill(3); 2168 console.info("worker.ets onmessage"); 2169 2170 // worker线程向宿主线程发送信息 2171 workerPort.postMessage(view); 2172} 2173 2174// worker线程发生error的回调 2175workerPort.onerror = (err: ErrorEvent) => { 2176 console.error("worker.ets onerror"); 2177} 2178``` 2179在模块级entry/build-profile.json5配置文件中添加如下配置: 2180```json 2181 "buildOption": { 2182 "sourceOption": { 2183 "workers": [ 2184 "./src/main/ets/entryability/workers/worker.ets" 2185 ] 2186 } 2187 } 2188``` 2189### Stage模型 2190> 此处以API version 18的工程为例。 2191```ts 2192// Index.ets 2193import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS'; 2194 2195@Entry 2196@Component 2197struct Index { 2198 @State message: string = 'Hello World'; 2199 build() { 2200 Row() { 2201 Column() { 2202 Text(this.message) 2203 .fontSize(50) 2204 .fontWeight(FontWeight.Bold) 2205 .onClick(() => { 2206 // 宿主线程中创建Worker对象 2207 const workerInstance = new worker.ThreadWorker("entry/ets/workers/Worker.ets"); 2208 // 宿主线程向worker线程传递信息 2209 const buffer = new ArrayBuffer(8); 2210 workerInstance.postMessage(buffer); 2211 // 宿主线程接收worker线程信息 2212 workerInstance.onmessage = (e: MessageEvents): void => { 2213 // data：worker线程发送的信息 2214 let data: Int8Array = e.data; 2215 console.info("main thread data is " + data); 2216 // 销毁Worker对象 2217 workerInstance.terminate(); 2218 } 2219 // 在调用terminate后，执行onexit 2220 workerInstance.onexit = (code) => { 2221 console.info("main thread terminate"); 2222 } 2223 2224 workerInstance.onAllErrors = (err: ErrorEvent) => { 2225 console.error("main error message " + err.message); 2226 } 2227 }) 2228 } 2229 .width('100%') 2230 .height('100%') 2231 } 2232 } 2233} 2234``` 2235```ts 2236// Worker.ets 2237import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS'; 2238 2239// 创建worker线程中与宿主线程通信的对象 2240const workerPort = worker.workerPort; 2241 2242// worker线程接收宿主线程信息 2243workerPort.onmessage = (e: MessageEvents): void => { 2244 // data：宿主线程发送的信息 2245 let data: ArrayBuffer = e.data; 2246 // 往收到的buffer里写入数据 2247 const view = new Int8Array(data).fill(3); 2248 // worker线程向宿主线程发送信息 2249 workerPort.postMessage(view); 2250} 2251 2252// worker线程发生error的回调 2253workerPort.onerror = (err: ErrorEvent) => { 2254 console.error("worker.ets onerror" + err.message); 2255} 2256``` 2257在模块级entry/build-profile.json5配置文件中添加如下配置: 2258```json 2259 "buildOption": { 2260 "sourceOption": { 2261 "workers": [ 2262 "./src/main/ets/workers/Worker.ets" 2263 ] 2264 } 2265 } 2266``` 2267<!--no_check--> 2268 2269 2270### 分发事件与监听接口搭配使用示例 2271 2272```ts 2273// Index.ets 2274import { worker, MessageEvents } from '@kit.ArkTS'; 2275 2276@Entry 2277@Component 2278struct Index { 2279 @State message: string = 'Hello World'; 2280 2281 build() { 2282 RelativeContainer() { 2283 Text(this.message) 2284 .id('HelloWorld') 2285 .fontSize($r('app.float.page_text_font_size')) 2286 .fontWeight(FontWeight.Bold) 2287 .alignRules({ 2288 center: { anchor: '__container__', align: VerticalAlign.Center }, 2289 middle: { anchor: '__container__', align: HorizontalAlign.Center } 2290 }) 2291 .onClick(() => { 2292 const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets"); 2293 2294 // 用法一: 2295 workerInstance.on("alert_on", () => { 2296 console.info("alert listener callback: alert_on"); 2297 }) 2298 workerInstance.once("alert_once", () => { 2299 console.info("alert listener callback: alert_once"); 2300 }) 2301 workerInstance.addEventListener("alert_add", () => { 2302 console.info("alert listener callback: alert_add"); 2303 }) 2304 2305 // once接口创建的事件执行一次便会删除。 2306 workerInstance.dispatchEvent({type: "alert_once", timeStamp: 0}); // timeStamp暂未支持 2307 // on接口创建的事件可以一直被分发，不能主动删除。 2308 workerInstance.dispatchEvent({type: "alert_on", timeStamp: 0}); // timeStamp暂未支持 2309 workerInstance.dispatchEvent({type: "alert_on", timeStamp: 0}); // timeStamp暂未支持 2310 // addEventListener接口创建的事件可以一直被分发，不能主动删除。 2311 workerInstance.dispatchEvent({type: "alert_add", timeStamp: 0}); // timeStamp暂未支持 2312 workerInstance.dispatchEvent({type: "alert_add", timeStamp: 0}); // timeStamp暂未支持 2313 2314 // 用法二: 2315 // event类型的type支持自定义，同时存在"message"/"messageerror"/"error"特殊类型，如下所示 2316 // 当type = "message"，onmessage接口定义的方法同时会执行。 2317 // 当type = "messageerror"，onmessageerror接口定义的方法同时会执行。 2318 // 当type = "error"，onerror接口定义的方法同时会执行。 2319 // 若调用removeEventListener接口或者off接口取消事件时，能且只能取消使用addEventListener/on/once创建的事件。 2320 2321 workerInstance.addEventListener("message", () => { 2322 console.info("message listener callback"); 2323 }) 2324 workerInstance.onmessage = (e: MessageEvents): void => { 2325 console.info("onmessage : message listener callback"); 2326 } 2327 // 调用dispatchEvent分发“message”事件，addEventListener和onmessage中定义的方法都会被执行。 2328 workerInstance.dispatchEvent({type: "message", timeStamp: 0}); // timeStamp暂未支持 2329 2330 // 向worker线程发送消息 2331 workerInstance.postMessage("test"); 2332 }) 2333 } 2334 .height('100%') 2335 .width('100%') 2336 } 2337} 2338``` 2339 2340```ts 2341// worker.ets 2342import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS'; 2343 2344const workerPort: ThreadWorkerGlobalScope = worker.workerPort; 2345 2346workerPort.onmessage = (event: MessageEvents) => { 2347 console.info("worker thread recv data is: ", event.data); 2348 let data: string = event.data; 2349 const workerHandler1 = () => console.info("Handler 1 is: ", data); 2350 const workerHandler2 = () => console.info("Handler 2 is: ", data); 2351 2352 // 注册两个监听器 2353 workerPort.addEventListener("workerListener", workerHandler1); 2354 workerPort.addEventListener("workerListener", workerHandler2); 2355 2356 // 事件workerListener注册了两个监听器，两个监听器都会执行 2357 workerPort.dispatchEvent({type: "workerListener", timeStamp: 0}); // timeStamp暂未支持 2358 2359 // 删除workerHandler1监听器 2360 workerPort.removeEventListener("workerListener", workerHandler1); // timeStamp暂未支持 2361 2362 // workerHandler1监听器已删除，只有workerHandler2执行 2363 workerPort.dispatchEvent({type: "workerListener", timeStamp: 0}); // timeStamp暂未支持 2364 2365 // 删除所有事件监听 2366 workerPort.removeAllListener(); 2367}; 2368```