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