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