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```js 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](#dedicatedworkerglobalscope) | 是 | 是 | 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```js 81import worker from '@ohos.worker'; 82// worker线程创建 83 84// FA模型-目录同级（entry模块下，workers目录与pages目录同级） 85const workerFAModel01 = new worker.ThreadWorker("workers/worker.js", {name:"first worker in FA model"}); 86// FA模型-目录不同级（entry模块下，workers目录与pages目录的父目录同级） 87const workerFAModel02 = new worker.ThreadWorker("../workers/worker.js"); 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/MainAbility/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 的实例对象，数组中不可传入null。 | 175 176**错误码：** 177 178以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 179 180| 错误码ID | 错误信息 | 181| -------- | ----------------------------------------- | 182| 10200004 | Worker instance is not running. | 183| 10200006 | Serializing an uncaught exception failed. | 184 185**示例：** 186 187```js 188const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 189 190var 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 的实例对象。若不填入该参数，默认设置为 undefined。| 208 209**错误码：** 210 211以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 212 213| 错误码ID | 错误信息 | 214| -------- | ----------------------------------------- | 215| 10200004 | Worker instance is not running. | 216| 10200006 | Serializing an uncaught exception failed. | 217 218**示例：** 219 220```js 221const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 222 223workerInstance.postMessage("hello world"); 224 225var 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```js 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```js 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```js 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```js 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```js 380const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 381workerInstance.onexit = function(e) { 382 console.log("onexit"); 383} 384 385//onexit被执行两种方式： 386//主线程： 387workerInstance.terminate(); 388 389//worker线程： 390//parentPort.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```js 420const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 421workerInstance.onerror = function(e) { 422 console.log("onerror"); 423} 424``` 425 426 427### onmessage<sup>9+</sup> 428 429onmessage?: (event: MessageEvents) => void 430 431Worker对象的onmessage属性表示宿主线程接收到来自其创建的Worker通过parentPort.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```js 453const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 454workerInstance.onmessage = function(e) { 455 // e : MessageEvents, 用法如下： 456 // let data = e.data; 457 console.log("onmessage"); 458} 459``` 460 461 462### onmessageerror<sup>9+</sup> 463 464onmessageerror?: (event: MessageEvents) => void 465 466Worker对象的onmessageerror属性表示当Worker对象接收到一条无法被序列化的消息时被调用的事件处理程序，处理程序在宿主线程中执行。 467 468**系统能力：** SystemCapability.Utils.Lang 469 470**参数：** 471 472| 参数名 | 类型 | 必填 | 说明 | 473| ------ | -------------------------------- | ---- | ---------- | 474| event | [MessageEvents](#messageevents9) | 是 | 异常数据。 | 475 476**错误码：** 477 478以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 479 480| 错误码ID | 错误信息 | 481| -------- | -------------------------------------------- | 482| 10200004 | Worker instance is not running. | 483| 10200005 | The invoked API is not supported in workers. | 484 485**示例：** 486 487```js 488const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 489workerInstance.onmessageerror= function(e) { 490 console.log("onmessageerror"); 491} 492``` 493 494### addEventListener<sup>9+</sup> 495 496addEventListener(type: string, listener: WorkerEventListener): void 497 498向Worker添加一个事件监听，该接口与[on<sup>9+</sup>](#on9)接口功能一致。 499 500**系统能力：** SystemCapability.Utils.Lang 501 502**参数：** 503 504| 参数名 | 类型 | 必填 | 说明 | 505| -------- | -------------------------------------------- | ---- | ---------------- | 506| type | string | 是 | 监听的事件类型。 | 507| listener | [WorkerEventListener](#workereventlistener9) | 是 | 回调的事件。 | 508 509**错误码：** 510 511以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 512 513| 错误码ID | 错误信息 | 514| -------- | -------------------------------------------- | 515| 10200004 | Worker instance is not running. | 516| 10200005 | The invoked API is not supported in workers. | 517 518**示例：** 519 520```js 521const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 522workerInstance.addEventListener("alert", (e)=>{ 523 console.log("alert listener callback"); 524}) 525``` 526 527 528### removeEventListener<sup>9+</sup> 529 530removeEventListener(type: string, callback?: WorkerEventListener): void 531 532删除Worker的事件监听，该接口与[off<sup>9+</sup>](#off9)接口功能一致。 533 534**系统能力：** SystemCapability.Utils.Lang 535 536**参数：** 537 538| 参数名 | 类型 | 必填 | 说明 | 539| -------- | -------------------------------------------- | ---- | ---------------------------- | 540| type | string | 是 | 需要删除的监听事件类型。 | 541| callback | [WorkerEventListener](#workereventlistener9) | 否 | 回调的事件。删除的回调事件。 | 542 543**错误码：** 544 545以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 546 547| 错误码ID | 错误信息 | 548| -------- | ------------------------------- | 549| 10200004 | Worker instance is not running. | 550 551**示例：** 552 553```js 554const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 555workerInstance.addEventListener("alert", (e)=>{ 556 console.log("alert listener callback"); 557}) 558workerInstance.removeEventListener("alert"); 559``` 560 561 562### dispatchEvent<sup>9+</sup> 563 564dispatchEvent(event: Event): boolean 565 566分发定义在Worker的事件。 567 568**系统能力：** SystemCapability.Utils.Lang 569 570**参数：** 571 572| 参数名 | 类型 | 必填 | 说明 | 573| ------ | --------------- | ---- | ---------------- | 574| event | [Event](#event) | 是 | 需要分发的事件。 | 575 576**返回值：** 577 578| 类型 | 说明 | 579| ------- | ------------------------------- | 580| boolean | 分发的结果，false表示分发失败。 | 581 582**错误码：** 583 584以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 585 586| 错误码ID | 错误信息 | 587| -------- | ------------------------------- | 588| 10200004 | Worker instance is not running. | 589 590**示例：** 591 592```js 593const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 594 595workerInstance.dispatchEvent({type:"eventType", timeStamp:0}); //timeStamp暂未支持。 596``` 597 598分发事件（dispatchEvent）可与监听接口（on、once、addEventListener）搭配使用，示例如下： 599 600```js 601const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 602 603//用法一: 604workerInstance.on("alert_on", (e)=>{ 605 console.log("alert listener callback"); 606}) 607workerInstance.once("alert_once", (e)=>{ 608 console.log("alert listener callback"); 609}) 610workerInstance.addEventListener("alert_add", (e)=>{ 611 console.log("alert listener callback"); 612}) 613 614//once接口创建的事件执行一次便会删除。 615workerInstance.dispatchEvent({type:"alert_once", timeStamp:0});//timeStamp暂未支持。 616//on接口创建的事件可以一直被分发，不能主动删除。 617workerInstance.dispatchEvent({type:"alert_on", timeStamp:0}); 618workerInstance.dispatchEvent({type:"alert_on", timeStamp:0}); 619//addEventListener接口创建的事件可以一直被分发，不能主动删除。 620workerInstance.dispatchEvent({type:"alert_add", timeStamp:0}); 621workerInstance.dispatchEvent({type:"alert_add", timeStamp:0}); 622 623//用法二: 624//event类型的type支持自定义，同时存在"message"/"messageerror"/"error"特殊类型，如下所示 625//当type = "message"，onmessage接口定义的方法同时会执行。 626//当type = "messageerror"，onmessageerror接口定义的方法同时会执行。 627//当type = "error"，onerror接口定义的方法同时会执行。 628//若调用removeEventListener接口或者off接口取消事件时，能且只能取消使用addEventListener/on/once创建的事件。 629 630workerInstance.addEventListener("message", (e)=>{ 631 console.log("message listener callback"); 632}) 633workerInstance.onmessage = function(e) { 634 console.log("onmessage : message listener callback"); 635} 636//调用dispatchEvent分发“message”事件，addEventListener和onmessage中定义的方法都会被执行。 637workerInstance.dispatchEvent({type:"message", timeStamp:0}); 638``` 639 640 641### removeAllListener<sup>9+</sup> 642 643removeAllListener(): void 644 645删除Worker所有的事件监听。 646 647**系统能力：** SystemCapability.Utils.Lang 648 649**错误码：** 650 651以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 652 653| 错误码ID | 错误信息 | 654| -------- | ------------------------------- | 655| 10200004 | Worker instance is not running. | 656 657**示例：** 658 659```js 660const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 661workerInstance.addEventListener("alert", (e)=>{ 662 console.log("alert listener callback"); 663}) 664workerInstance.removeAllListener(); 665``` 666 667## WorkerEventTarget<sup>9+</sup> 668 669### addEventListener<sup>9+</sup> 670 671addEventListener(type: string, listener: WorkerEventListener): void 672 673向Worker添加一个事件监听，该接口与[on<sup>9+</sup>](#on9)接口功能一致。 674 675**系统能力：** SystemCapability.Utils.Lang 676 677**参数：** 678 679| 参数名 | 类型 | 必填 | 说明 | 680| -------- | -------------------------------------------- | ---- | ---------------- | 681| type | string | 是 | 监听的事件类型。 | 682| listener | [WorkerEventListener](#workereventlistener9) | 是 | 回调的事件。 | 683 684**错误码：** 685 686以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 687 688| 错误码ID | 错误信息 | 689| -------- | -------------------------------------------- | 690| 10200004 | Worker instance is not running. | 691| 10200005 | The invoked API is not supported in workers. | 692 693**示例：** 694 695```js 696const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 697workerInstance.addEventListener("alert", (e)=>{ 698 console.log("alert listener callback"); 699}) 700``` 701 702 703### removeEventListener<sup>9+</sup> 704 705removeEventListener(type: string, callback?: WorkerEventListener): void 706 707删除Worker的事件监听，该接口与[off<sup>9+</sup>](#off9)接口功能一致。 708 709**系统能力：** SystemCapability.Utils.Lang 710 711**参数：** 712 713| 参数名 | 类型 | 必填 | 说明 | 714| -------- | -------------------------------------------- | ---- | ---------------------------- | 715| type | string | 是 | 需要删除的监听事件类型。 | 716| callback | [WorkerEventListener](#workereventlistener9) | 否 | 回调的事件。删除的回调事件。 | 717 718**错误码：** 719 720以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 721 722| 错误码ID | 错误信息 | 723| -------- | ------------------------------- | 724| 10200004 | Worker instance is not running. | 725 726**示例：** 727 728```js 729const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 730workerInstance.addEventListener("alert", (e)=>{ 731 console.log("alert listener callback"); 732}) 733workerInstance.removeEventListener("alert"); 734``` 735 736 737### dispatchEvent<sup>9+</sup> 738 739dispatchEvent(event: Event): boolean 740 741分发定义在Worker的事件。 742 743**系统能力：** SystemCapability.Utils.Lang 744 745**参数：** 746 747| 参数名 | 类型 | 必填 | 说明 | 748| ------ | --------------- | ---- | ---------------- | 749| event | [Event](#event) | 是 | 需要分发的事件。 | 750 751**返回值：** 752 753| 类型 | 说明 | 754| ------- | ------------------------------- | 755| boolean | 分发的结果，false表示分发失败。 | 756 757**错误码：** 758 759以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 760 761| 错误码ID | 错误信息 | 762| -------- | ------------------------------- | 763| 10200004 | Worker instance is not running. | 764 765**示例：** 766 767```js 768const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 769 770workerInstance.dispatchEvent({type:"eventType", timeStamp:0}); //timeStamp暂未支持。 771``` 772 773分发事件（dispatchEvent）可与监听接口（on、once、addEventListener）搭配使用，示例如下： 774 775```js 776const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 777 778//用法一: 779workerInstance.on("alert_on", (e)=>{ 780 console.log("alert listener callback"); 781}) 782workerInstance.once("alert_once", (e)=>{ 783 console.log("alert listener callback"); 784}) 785workerInstance.addEventListener("alert_add", (e)=>{ 786 console.log("alert listener callback"); 787}) 788 789//once接口创建的事件执行一次便会删除。 790workerInstance.dispatchEvent({type:"alert_once", timeStamp:0});//timeStamp暂未支持。 791//on接口创建的事件可以一直被分发，不能主动删除。 792workerInstance.dispatchEvent({type:"alert_on", timeStamp:0}); 793workerInstance.dispatchEvent({type:"alert_on", timeStamp:0}); 794//addEventListener接口创建的事件可以一直被分发，不能主动删除。 795workerInstance.dispatchEvent({type:"alert_add", timeStamp:0}); 796workerInstance.dispatchEvent({type:"alert_add", timeStamp:0}); 797 798//用法二: 799//event类型的type支持自定义，同时存在"message"/"messageerror"/"error"特殊类型，如下所示 800//当type = "message"，onmessage接口定义的方法同时会执行。 801//当type = "messageerror"，onmessageerror接口定义的方法同时会执行。 802//当type = "error"，onerror接口定义的方法同时会执行。 803//若调用removeEventListener接口或者off接口取消事件时，能且只能取消使用addEventListener/on/once创建的事件。 804 805workerInstance.addEventListener("message", (e)=>{ 806 console.log("message listener callback"); 807}) 808workerInstance.onmessage = function(e) { 809 console.log("onmessage : message listener callback"); 810} 811//调用dispatchEvent分发“message”事件，addEventListener和onmessage中定义的方法都会被执行。 812workerInstance.dispatchEvent({type:"message", timeStamp:0}); 813``` 814 815 816### removeAllListener<sup>9+</sup> 817 818removeAllListener(): void 819 820删除Worker所有的事件监听。 821 822**系统能力：** SystemCapability.Utils.Lang 823 824**错误码：** 825 826以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 827 828| 错误码ID | 错误信息 | 829| -------- | ------------------------------- | 830| 10200004 | Worker instance is not running. | 831 832**示例：** 833 834```js 835const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 836workerInstance.addEventListener("alert", (e)=>{ 837 console.log("alert listener callback"); 838}) 839workerInstance.removeAllListener(); 840``` 841 842 843## ThreadWorkerGlobalScope<sup>9+</sup> 844 845Worker线程用于与宿主线程通信的类，通过postMessage接口发送消息给宿主线程、close接口销毁Worker线程。ThreadWorkerGlobalScope类继承[GlobalScope<sup>9+</sup>](#globalscope9)。 846 847### postMessage<sup>9+</sup> 848 849postMessage(messageObject: Object, transfer: ArrayBuffer[]): void; 850 851Worker线程向宿主线程发送消息。 852 853**系统能力：** SystemCapability.Utils.Lang 854 855**参数：** 856 857| 参数名 | 类型 | 必填 | 说明 | 858| -------- | ------------- | ---- | ------------------------------------------------------- | 859| message | Object | 是 | 发送至宿主线程的数据。 | 860| transfer | ArrayBuffer[] | 是 | 可传输对象是ArrayBuffer的实例对象，数组中不可传入null。 | 861 862**错误码：** 863 864以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 865 866| 错误码ID | 错误信息 | 867| -------- | ----------------------------------------- | 868| 10200004 | Worker instance is not running. | 869| 10200006 | Serializing an uncaught exception failed. | 870 871**示例：** 872 873```js 874// main.js 875import worker from '@ohos.worker'; 876const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 877workerInstance.postMessage("hello world"); 878workerInstance.onmessage = function(e) { 879 // let data = e.data; 880 console.log("receive data from worker.js"); 881} 882``` 883 884```js 885// worker.ts 886import worker from '@ohos.worker'; 887const workerPort = worker.workerPort; 888workerPort.onmessage = function(e){ 889 // let data = e.data; 890 var buffer = new ArrayBuffer(8); 891 workerPort.postMessage(buffer, [buffer]); 892} 893``` 894 895### postMessage<sup>9+</sup> 896 897postMessage(messageObject: Object, options?: PostMessageOptions): void 898 899Worker线程向宿主线程发送消息。 900 901**系统能力：** SystemCapability.Utils.Lang 902 903**参数：** 904 905| 参数名 | 类型 | 必填 | 说明 | 906| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 907| message | Object | 是 | 发送至宿主线程的数据。 | 908| options | [PostMessageOptions](#postmessageoptions) | 否 | 可传输对象是ArrayBuffer的实例对象。若不填入该参数，默认设置为 undefined。| 909 910**错误码：** 911 912以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 913 914| 错误码ID | 错误信息 | 915| -------- | ----------------------------------------- | 916| 10200004 | Worker instance is not running. | 917| 10200006 | Serializing an uncaught exception failed. | 918 919**示例：** 920 921```js 922// main.js 923import worker from '@ohos.worker'; 924const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 925workerInstance.postMessage("hello world"); 926workerInstance.onmessage = function(e) { 927 // let data = e.data; 928 console.log("receive data from worker.js"); 929} 930``` 931 932```js 933// worker.ts 934import worker from '@ohos.worker'; 935const workerPort = worker.workerPort; 936workerPort.onmessage = function(e){ 937 // let data = e.data; 938 workerPort.postMessage("receive data from main.js"); 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```js 962// main.js 963import worker from '@ohos.worker'; 964const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 965``` 966 967```js 968// worker.ts 969import worker from '@ohos.worker'; 970const workerPort = worker.workerPort; 971workerPort.onmessage = function(e) { 972 workerPort.close() 973} 974``` 975 976 977### onmessage<sup>9+</sup> 978 979onmessage?: (this: ThreadWorkerGlobalScope, ev: MessageEvents) => void 980 981DedicatedWorkerGlobalScope的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```js 1004// main.js 1005import worker from '@ohos.worker'; 1006const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 1007workerInstance.postMessage("hello world"); 1008``` 1009 1010```js 1011// worker.ts 1012import worker from '@ohos.worker'; 1013const workerPort = worker.workerPort; 1014workerPort.onmessage = function(e) { 1015 console.log("receive main.js message"); 1016} 1017``` 1018 1019 1020### onmessageerror<sup>9+</sup> 1021 1022onmessageerror?: (this: ThreadWorkerGlobalScope, ev: MessageEvents) => void 1023 1024DedicatedWorkerGlobalScope的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```js 1047// main.js 1048import worker from '@ohos.worker'; 1049const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 1050``` 1051 1052```js 1053// worker.ts 1054import worker from '@ohos.worker'; 1055const parentPort = worker.workerPort; 1056parentPort.onmessageerror = function(e) { 1057 console.log("worker.js 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```js 1094const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts"); 1095workerInstance.addEventListener("alert", (e)=>{ 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```js 1132// main.js 1133import worker from '@ohos.worker'; 1134const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ts") 1135``` 1136 1137```js 1138// worker.ts 1139import worker from '@ohos.worker'; 1140const workerPort = worker.workerPort 1141workerPort.onerror = function(e){ 1142 console.log("worker.js 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](#eventtarget)。 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```js 1191import worker from '@ohos.worker'; 1192// worker线程创建 1193 1194// FA模型-目录同级 1195const workerFAModel01 = new worker.Worker("workers/worker.js", {name:"first worker in FA model"}); 1196// FA模型-目录不同级（以workers目录放置pages目录前一级为例） 1197const workerFAModel02 = new worker.Worker("../workers/worker.js"); 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/MainAbility/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 的实例对象。 | 1273 1274**示例：** 1275 1276```js 1277const workerInstance = new worker.Worker("workers/worker.js"); 1278 1279var 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 的实例对象。若不填入该参数，默认设置为 undefined。| 1300 1301**示例：** 1302 1303```js 1304const workerInstance = new worker.Worker("workers/worker.js"); 1305 1306workerInstance.postMessage("hello world"); 1307 1308var 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](#eventlistener) | 是 | 回调事件。 | 1330 1331**示例：** 1332 1333```js 1334const workerInstance = new worker.Worker("workers/worker.js"); 1335workerInstance.on("alert", (e)=>{ 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](#eventlistener) | 是 | 回调事件。 | 1358 1359**示例：** 1360 1361```js 1362const workerInstance = new worker.Worker("workers/worker.js"); 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](#eventlistener) | 否 | 删除的回调事件。 | 1386 1387**示例：** 1388 1389```js 1390const workerInstance = new worker.Worker("workers/worker.js"); 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```js 1410const workerInstance = new worker.Worker("workers/worker.js"); 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```js 1435const workerInstance = new worker.Worker("workers/worker.js"); 1436workerInstance.onexit = function(e) { 1437 console.log("onexit"); 1438} 1439 1440//onexit被执行两种方式： 1441//主线程： 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```js 1469const workerInstance = new worker.Worker("workers/worker.js"); 1470workerInstance.onerror = function(e) { 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](#messageeventt) | 是 | 收到的Worker消息数据。 | 1492 1493**示例：** 1494 1495```js 1496const workerInstance = new worker.Worker("workers/worker.js"); 1497workerInstance.onmessage = function(e) { 1498 // e : MessageEvent, 用法如下： 1499 // let data = e.data; 1500 console.log("onmessage"); 1501} 1502``` 1503 1504 1505### onmessageerror<sup>(deprecated)</sup> 1506 1507onmessageerror?: (event: MessageEvent) => void 1508 1509Worker对象的onmessageerror属性表示当Worker对象接收到一条无法被序列化的消息时被调用的事件处理程序，处理程序在宿主线程中执行。 1510 1511> **说明：**<br/> 1512> 从API version 7 开始支持，从API version 9 开始废弃，建议使用[ThreadWorker.onmessageerror<sup>9+</sup>](#onmessageerror9)替代。 1513 1514**系统能力：** SystemCapability.Utils.Lang 1515 1516**参数：** 1517 1518| 参数名 | 类型 | 必填 | 说明 | 1519| ------ | ------------------------------ | ---- | ---------- | 1520| event | [MessageEvent](#messageeventt) | 是 | 异常数据。 | 1521 1522**示例：** 1523 1524```js 1525const workerInstance = new worker.Worker("workers/worker.js"); 1526workerInstance.onmessageerror= function(e) { 1527 console.log("onmessageerror"); 1528} 1529``` 1530 1531 1532## EventTarget<sup>(deprecated)</sup> 1533> **说明：**<br/> 1534> 从API version 7 开始支持，从API version 9 开始废弃，建议使用[WorkerEventTarget<sup>9+</sup>](#workereventtarget9)替代。 1535 1536### addEventListener<sup>(deprecated)</sup> 1537 1538addEventListener(type: string, listener: EventListener): void 1539 1540向Worker添加一个事件监听，该接口与[on<sup>(deprecated)</sup>](#ondeprecated)接口功能一致。 1541 1542> **说明：**<br/> 1543> 从API version 7 开始支持，从API version 9 开始废弃，建议使用[addEventListener<sup>9+</sup>](#addeventlistener9)替代。 1544 1545**系统能力：** SystemCapability.Utils.Lang 1546 1547**参数：** 1548 1549| 参数名 | 类型 | 必填 | 说明 | 1550| -------- | ------------------------------- | ---- | ---------------- | 1551| type | string | 是 | 监听的事件类型。 | 1552| listener | [EventListener](#eventlistener) | 是 | 回调的事件。 | 1553 1554**示例：** 1555 1556```js 1557const workerInstance = new worker.Worker("workers/worker.js"); 1558workerInstance.addEventListener("alert", (e)=>{ 1559 console.log("alert listener callback"); 1560}) 1561``` 1562 1563 1564### removeEventListener<sup>(deprecated)</sup> 1565 1566removeEventListener(type: string, callback?: EventListener): void 1567 1568删除Worker的事件监听，该接口与[off<sup>(deprecated)</sup>](#offdeprecated)接口功能一致。 1569 1570> **说明：**<br/> 1571> 从API version 7 开始支持，从API version 9 开始废弃，建议使用[removeEventListener<sup>9+</sup>](#removeeventlistener9)替代。 1572 1573**系统能力：** SystemCapability.Utils.Lang 1574 1575**参数：** 1576 1577| 参数名 | 类型 | 必填 | 说明 | 1578| -------- | ------------------------------- | ---- | ------------------------ | 1579| type | string | 是 | 需要删除的监听事件类型。 | 1580| callback | [EventListener](#eventlistener) | 否 | 删除的回调事件。 | 1581 1582**示例：** 1583 1584```js 1585const workerInstance = new worker.Worker("workers/worker.js"); 1586workerInstance.addEventListener("alert", (e)=>{ 1587 console.log("alert listener callback"); 1588}) 1589workerInstance.removeEventListener("alert"); 1590``` 1591 1592 1593### dispatchEvent<sup>(deprecated)</sup> 1594 1595dispatchEvent(event: Event): boolean 1596 1597分发定义在Worker的事件。 1598 1599> **说明：**<br/> 1600> 从API version 7 开始支持，从API version 9 开始废弃，建议使用[dispatchEvent<sup>9+</sup>](#dispatchevent9)替代。 1601 1602**系统能力：** SystemCapability.Utils.Lang 1603 1604**参数：** 1605 1606| 参数名 | 类型 | 必填 | 说明 | 1607| ------ | --------------- | ---- | ---------------- | 1608| event | [Event](#event) | 是 | 需要分发的事件。 | 1609 1610**返回值：** 1611 1612| 类型 | 说明 | 1613| ------- | ------------------------------- | 1614| boolean | 分发的结果，false表示分发失败。 | 1615 1616**示例：** 1617 1618```js 1619const workerInstance = new worker.Worker("workers/worker.js"); 1620 1621workerInstance.dispatchEvent({type:"eventType", timeStamp:0}); //timeStamp暂未支持。 1622``` 1623 1624分发事件（dispatchEvent）可与监听接口（on、once、addEventListener）搭配使用，示例如下： 1625 1626```js 1627const workerInstance = new worker.Worker("workers/worker.js"); 1628 1629//用法一: 1630workerInstance.on("alert_on", (e)=>{ 1631 console.log("alert listener callback"); 1632}) 1633workerInstance.once("alert_once", (e)=>{ 1634 console.log("alert listener callback"); 1635}) 1636workerInstance.addEventListener("alert_add", (e)=>{ 1637 console.log("alert listener callback"); 1638}) 1639 1640//once接口创建的事件执行一次便会删除。 1641workerInstance.dispatchEvent({type:"alert_once", timeStamp:0});//timeStamp暂未支持。 1642//on接口创建的事件可以一直被分发，不能主动删除。 1643workerInstance.dispatchEvent({type:"alert_on", timeStamp:0}); 1644workerInstance.dispatchEvent({type:"alert_on", timeStamp:0}); 1645//addEventListener接口创建的事件可以一直被分发，不能主动删除。 1646workerInstance.dispatchEvent({type:"alert_add", timeStamp:0}); 1647workerInstance.dispatchEvent({type:"alert_add", timeStamp:0}); 1648 1649//用法二: 1650//event类型的type支持自定义，同时存在"message"/"messageerror"/"error"特殊类型，如下所示 1651//当type = "message"，onmessage接口定义的方法同时会执行。 1652//当type = "messageerror"，onmessageerror接口定义的方法同时会执行。 1653//当type = "error"，onerror接口定义的方法同时会执行。 1654//若调用removeEventListener接口或者off接口取消事件时，能且只能取消使用addEventListener/on/once创建的事件。 1655 1656workerInstance.addEventListener("message", (e)=>{ 1657 console.log("message listener callback"); 1658}) 1659workerInstance.onmessage = function(e) { 1660 console.log("onmessage : message listener callback"); 1661} 1662//调用dispatchEvent分发“message”事件，addEventListener和onmessage中定义的方法都会被执行。 1663workerInstance.dispatchEvent({type:"message", timeStamp:0}); 1664``` 1665### removeAllListener<sup>(deprecated)</sup> 1666 1667removeAllListener(): void 1668 1669删除Worker所有的事件监听。 1670 1671> **说明：**<br/> 1672> 从API version 7 开始支持，从API version 9 开始废弃，建议使用[removeAllListener<sup>9+</sup>](#removealllistener9)替代。 1673 1674**系统能力：** SystemCapability.Utils.Lang 1675 1676**示例：** 1677 1678```js 1679const workerInstance = new worker.Worker("workers/worker.js"); 1680workerInstance.addEventListener("alert", (e)=>{ 1681 console.log("alert listener callback"); 1682}) 1683workerInstance.removeAllListener(); 1684``` 1685 1686 1687## DedicatedWorkerGlobalScope<sup>(deprecated)</sup> 1688 1689Worker线程用于与宿主线程通信的类，通过postMessage接口发送消息给宿主线程、close接口销毁Worker线程。DedicatedWorkerGlobalScope类继承[WorkerGlobalScope](#workerglobalscope)。 1690 1691> **说明：**<br/> 1692> 从API version 7 开始支持，从API version 9 开始废弃，建议使用[ThreadWorkerGlobalScope<sup>9+</sup>](#threadworkerglobalscope9)替代。 1693 1694### postMessage<sup>(deprecated)</sup> 1695 1696postMessage(messageObject: Object, transfer: Transferable[]): void; 1697 1698Worker线程向宿主线程发送消息。 1699 1700> **说明：**<br/> 1701> 此接口暂不支持使用，从API version 9 开始废弃，建议使用[ThreadWorkerGlobalScope<sup>9+</sup>.postMessage<sup>9+</sup>](#postmessage9-2)替代。 1702 1703**系统能力：** SystemCapability.Utils.Lang 1704 1705**参数：** 1706 1707| 参数名 | 类型 | 必填 | 说明 | 1708| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 1709| messageObject | Object | 是 | 发送至宿主线程的数据。 | 1710| transfer| Transferable[] | 是 | 暂不支持该参数类型。 | 1711 1712### postMessage<sup>9+</sup> 1713 1714postMessage(messageObject: Object, transfer: ArrayBuffer[]): void; 1715 1716Worker线程向宿主线程发送消息。 1717 1718> **说明：**<br/> 1719> DedicatedWorkerGlobalScope类自API version 9 开始废弃，本接口建议使用[ThreadWorkerGlobalScope<sup>9+</sup>.postMessage<sup>9+</sup>](#postmessage9-2)替代。 1720 1721**系统能力：** SystemCapability.Utils.Lang 1722 1723**参数：** 1724 1725| 参数名 | 类型 | 必填 | 说明 | 1726| -------- | ------------- | ---- | ----------------------------------------------------- | 1727| message | Object | 是 | 发送至宿主线程的数据。 | 1728| transfer | ArrayBuffer[] | 是 | 可传输对象是ArrayBuffer的实例对象，数组不可传入null。 | 1729 1730**示例：** 1731 1732```js 1733// main.js 1734import worker from '@ohos.worker'; 1735const workerInstance = new worker.Worker("workers/worker.js"); 1736workerInstance.postMessage("hello world"); 1737workerInstance.onmessage = function(e) { 1738 // let data = e.data; 1739 console.log("receive data from worker.js"); 1740} 1741``` 1742```js 1743// worker.js 1744import worker from '@ohos.worker'; 1745const parentPort = worker.parentPort; 1746parentPort.onmessage = function(e){ 1747 // let data = e.data; 1748 let buffer = new ArrayBuffer(5) 1749 parentPort.postMessage(buffer, [buffer]); 1750} 1751``` 1752 1753### postMessage<sup>(deprecated)</sup> 1754 1755postMessage(messageObject: Object, options?: PostMessageOptions): void 1756 1757Worker线程向宿主线程发送消息。 1758 1759> **说明：**<br/> 1760> 从API version 7 开始支持，从API version 9 开始废弃，建议使用[ThreadWorkerGlobalScope<sup>9+</sup>.postMessage<sup>9+</sup>](#postmessage9-3)替代。 1761 1762**系统能力：** SystemCapability.Utils.Lang 1763 1764**参数：** 1765 1766| 参数名 | 类型 | 必填 | 说明 | 1767| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 1768| message | Object | 是 | 发送至宿主线程的数据。 | 1769| options | [PostMessageOptions](#postmessageoptions) | 否 | 可传输对象是ArrayBuffer的实例对象。若不填入该参数，默认设置为 undefined。| 1770 1771**示例：** 1772 1773```js 1774// main.js 1775import worker from '@ohos.worker'; 1776const workerInstance = new worker.Worker("workers/worker.js"); 1777workerInstance.postMessage("hello world"); 1778workerInstance.onmessage = function(e) { 1779 // let data = e.data; 1780 console.log("receive data from worker.js"); 1781} 1782``` 1783```js 1784// worker.js 1785import worker from '@ohos.worker'; 1786const parentPort = worker.parentPort; 1787parentPort.onmessage = function(e){ 1788 // let data = e.data; 1789 parentPort.postMessage("receive data from main.js"); 1790} 1791``` 1792 1793### close<sup>(deprecated)</sup> 1794 1795close(): void 1796 1797销毁Worker线程，终止Worker接收消息。 1798 1799> **说明：**<br/> 1800> 从API version 7 开始支持，从API version 9 开始废弃，建议使用[ThreadWorkerGlobalScope<sup>9+</sup>.close<sup>9+</sup>](#close9)替代。 1801 1802**系统能力：** SystemCapability.Utils.Lang 1803 1804**示例：** 1805 1806```js 1807// main.js 1808import worker from '@ohos.worker'; 1809const workerInstance = new worker.Worker("workers/worker.js"); 1810``` 1811```js 1812// worker.js 1813import worker from '@ohos.worker'; 1814const parentPort = worker.parentPort; 1815parentPort.onmessage = function(e) { 1816 parentPort.close() 1817} 1818``` 1819 1820 1821### onmessage<sup>(deprecated)</sup> 1822 1823onmessage?: (this: DedicatedWorkerGlobalScope, ev: MessageEvent) => void 1824 1825DedicatedWorkerGlobalScope的onmessage属性表示Worker线程收到来自其宿主线程通过postMessage接口发送的消息时被调用的事件处理程序，处理程序在Worker线程中执行。 1826 1827> **说明：**<br/> 1828> 从API version 7 开始支持，从API version 9 开始废弃，建议使用[ThreadWorkerGlobalScope<sup>9+</sup>.onmessage<sup>9+</sup>](#onmessage9-1)替代。 1829 1830**系统能力：** SystemCapability.Utils.Lang 1831 1832**参数：** 1833 1834| 参数名 | 类型 | 必填 | 说明 | 1835| ------ | ------------------------------------------------------------ | ---- | ------------------------ | 1836| this | [DedicatedWorkerGlobalScope](#dedicatedworkerglobalscopedeprecated) | 是 | 指向调用者对象。 | 1837| ev | [MessageEvent](#messageeventt) | 是 | 收到宿主线程发送的数据。 | 1838 1839**示例：** 1840 1841```js 1842// main.js 1843import worker from '@ohos.worker'; 1844const workerInstance = new worker.Worker("workers/worker.js"); 1845workerInstance.postMessage("hello world"); 1846``` 1847```js 1848// worker.js 1849import worker from '@ohos.worker'; 1850const parentPort = worker.parentPort; 1851parentPort.onmessage = function(e) { 1852 console.log("receive main.js message"); 1853} 1854``` 1855 1856 1857### onmessageerror<sup>(deprecated)</sup> 1858 1859onmessageerror?: (this: DedicatedWorkerGlobalScope, ev: MessageEvent) => void 1860 1861DedicatedWorkerGlobalScope的onmessageerror属性表示当Worker对象接收到一条无法被反序列化的消息时被调用的事件处理程序，处理程序在Worker线程中执行。 1862 1863> **说明：**<br/> 1864> 从API version 7 开始支持，从API version 9 开始废弃，建议使用[ThreadWorkerGlobalScope<sup>9+</sup>.onmessageerror<sup>9+</sup>](#onmessageerror9-1)替代。 1865 1866**系统能力：** SystemCapability.Utils.Lang 1867 1868**参数：** 1869 1870| 参数名 | 类型 | 必填 | 说明 | 1871| ------ | ------------------------------ | ---- | ---------- | 1872| this | [DedicatedWorkerGlobalScope](#dedicatedworkerglobalscopedeprecated) | 是 | 指向调用者对象。 | 1873| ev | [MessageEvent](#messageeventt) | 是 | 异常数据。 | 1874 1875**示例：** 1876 1877```js 1878// main.js 1879import worker from '@ohos.worker'; 1880const workerInstance = new worker.Worker("workers/worker.js"); 1881``` 1882```js 1883// worker.js 1884import worker from '@ohos.worker'; 1885const parentPort = worker.parentPort; 1886parentPort.onmessageerror = function(e) { 1887 console.log("worker.js onmessageerror") 1888} 1889``` 1890 1891 1892## PostMessageOptions 1893 1894明确数据传递过程中需要转移所有权对象的类，传递所有权的对象必须是ArrayBuffer。 1895 1896**系统能力：** SystemCapability.Utils.Lang 1897 1898| 名称 | 类型 | 可读 | 可写 | 说明 | 1899| -------- | -------- | ---- | ---- | --------------------------------- | 1900| transfer | Object[] | 是 | 是 | ArrayBuffer数组，用于传递所有权。该数组中不可传入null。 | 1901 1902 1903## Event 1904 1905事件类。 1906 1907**系统能力：** SystemCapability.Utils.Lang 1908 1909| 名称 | 类型 | 可读 | 可写 | 说明 | 1910| --------- | ------ | ---- | ---- | -------------------------------------------- | 1911| type | string | 是 | 否 | 指定事件的类型。 | 1912| timeStamp | number | 是 | 否 | 事件创建时的时间戳（精度为毫秒），暂未支持。 | 1913 1914 1915## EventListener<sup>(deprecated)</sup> 1916 1917(evt: Event): void | Promise<void> 1918 1919事件监听类。 1920 1921> **说明：**<br/> 1922> 从API version 7 开始支持，从API version 9 开始废弃，建议使用[WorkerEventListener<sup>9+</sup>](#workereventlistener9)替代。 1923 1924**系统能力：** SystemCapability.Utils.Lang 1925 1926**参数：** 1927 1928| 参数名 | 类型 | 必填 | 说明 | 1929| ------ | --------------- | ---- | -------------- | 1930| evt | [Event](#event) | 是 | 回调的事件类。 | 1931 1932**返回值：** 1933 1934| 类型 | 说明 | 1935| ------------------------------------- | ------------------------------- | 1936| void \| Promise<void> | 无返回值或者以Promise形式返回。 | 1937 1938**示例：** 1939 1940```js 1941const workerInstance = new worker.Worker("workers/worker.js"); 1942workerInstance.addEventListener("alert", (e)=>{ 1943 console.log("alert listener callback"); 1944}) 1945``` 1946 1947 1948## ErrorEvent 1949 1950错误事件类，用于表示Worker执行过程中出现异常的详细信息，ErrorEvent类继承[Event](#event)。 1951 1952**系统能力：** SystemCapability.Utils.Lang 1953 1954| 名称 | 类型 | 可读 | 可写 | 说明 | 1955| -------- | ------ | ---- | ---- | -------------------- | 1956| message | string | 是 | 否 | 异常发生的错误信息。 | 1957| filename | string | 是 | 否 | 出现异常所在的文件。 | 1958| lineno | number | 是 | 否 | 异常所在的行数。 | 1959| colno | number | 是 | 否 | 异常所在的列数。 | 1960| error | Object | 是 | 否 | 异常类型。 | 1961 1962 1963## MessageEvent\<T\> 1964 1965消息类，持有Worker线程间传递的数据。 1966 1967**系统能力：** SystemCapability.Utils.Lang 1968 1969| 名称 | 类型 | 可读 | 可写 | 说明 | 1970| ---- | ---- | ---- | ---- | ------------------ | 1971| data | T | 是 | 否 | 线程间传递的数据。 | 1972 1973 1974## WorkerGlobalScope<sup>(deprecated)</sup> 1975 1976Worker线程自身的运行环境，WorkerGlobalScope类继承[EventTarget](#eventtarget)。 1977 1978> **说明：**<br/> 1979> 从API version 7 开始支持，从API version 9 开始废弃，建议使用[GlobalScope<sup>9+</sup>](#globalscope9)替代。 1980 1981### 属性 1982 1983**系统能力：** SystemCapability.Utils.Lang 1984 1985| 名称 | 类型 | 可读 | 可写 | 说明 | 1986| ---- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------- | 1987| name | string | 是 | 否 | Worker的名字，new Worker时指定。 | 1988| self | [WorkerGlobalScope](#workerglobalscope) & typeof globalThis | 是 | 否 | WorkerGlobalScope本身。 | 1989 1990 1991### onerror<sup>(deprecated)</sup> 1992 1993onerror?: (ev: ErrorEvent) => void 1994 1995WorkerGlobalScope的onerror属性表示Worker在执行过程中发生异常被调用的事件处理程序，处理程序在Worker线程中执行。 1996 1997> **说明：**<br/> 1998> 从API version 7 开始支持，从API version 9 开始废弃，建议使用[GlobalScope<sup>9+</sup>.onerror<sup>9+</sup>](#onerror9-1)替代。 1999 2000**系统能力：** SystemCapability.Utils.Lang 2001 2002**参数：** 2003 2004| 参数名 | 类型 | 必填 | 说明 | 2005| ------ | ------------------------- | ---- | ---------- | 2006| ev | [ErrorEvent](#errorevent) | 是 | 异常数据。 | 2007 2008**示例：** 2009 2010```js 2011// main.js 2012import worker from '@ohos.worker'; 2013const workerInstance = new worker.Worker("workers/worker.js") 2014``` 2015```js 2016// worker.js 2017import worker from '@ohos.worker'; 2018const parentPort = worker.parentPort 2019parentPort.onerror = function(e){ 2020 console.log("worker.js onerror") 2021} 2022``` 2023 2024 2025## 其他说明 2026 2027### 序列化支持类型 2028| Type | 备注 | 是否支持 | 2029| ------------------ | -------------------------------------- | -------- | 2030| All Primitive Type | 不包括symbol | 是 | 2031| Date | | 是 | 2032| String | | 是 | 2033| RegExp | | 是 | 2034| Array | | 是 | 2035| Map | | 是 | 2036| Set | | 是 | 2037| Object | 只支持Plain Object，不支持带function的 | 是 | 2038| ArrayBuffer | 提供transfer能力 | 是 | 2039| TypedArray | | 是 | 2040 2041特例：传递通过自定义class创建出来的object时，不会发生序列化错误，但是自定义class的属性（如Function）无法通过序列化传递。 2042> **说明：**<br/> 2043> 以API version 9的FA工程为例。 2044 2045```js 2046// main.js 2047import worker from '@ohos.worker'; 2048const workerInstance = new worker.ThreadWorker("workers/worker.js"); 2049workerInstance.postMessage("message from main to worker"); 2050workerInstance.onmessage = function(d) { 2051 // 当worker线程传递obj2时，data即为obj2。data没有Init、SetName的方法 2052 let data = d.data; 2053} 2054``` 2055```js 2056// worker.js 2057import worker from '@ohos.worker'; 2058const workerPort = worker.workerPort; 2059class MyModel { 2060 name = "undefined" 2061 Init() { 2062 this.name = "MyModel" 2063 } 2064} 2065workerPort.onmessage = function(d) { 2066 console.log("worker.js onmessage"); 2067 let data = d.data; 2068 let func1 = function() { 2069 console.log("post message is function"); 2070 } 2071 let obj1 = { 2072 "index": 2, 2073 "name1": "zhangshan", 2074 setName() { 2075 this.index = 3; 2076 } 2077 } 2078 let obj2 = new MyModel(); 2079 // workerPort.postMessage(func1); 传递func1发生序列化错误 2080 // workerPort.postMessage(obj1); 传递obj1发生序列化错误 2081 workerPort.postMessage(obj2); // 传递obj2不会发生序列化错误 2082} 2083workerPort.onmessageerror = function(e) { 2084 console.log("worker.js onmessageerror"); 2085} 2086workerPort.onerror = function(e) { 2087 console.log("worker.js onerror"); 2088} 2089``` 2090 2091### 内存模型 2092Worker基于Actor并发模型实现。在Worker的交互流程中，JS主线程可以创建多个Worker子线程，各个Worker线程间相互隔离，并通过序列化传递对象，等到Worker线程完成计算任务，再把结果返回给主线程。 2093 2094Actor并发模型的交互原理：各个Actor并发地处理主线程任务，每个Actor内部都有一个消息队列及单线程执行模块，消息队列负责接收主线程及其他Actor的请求，单线程执行模块则负责串行地处理请求、向其他Actor发送请求以及创建新的Actor。由于Actor采用的是异步方式，各个Actor之间相互隔离没有数据竞争，因此Actor可以高并发运行。 2095 2096### 注意事项 2097- Worker存在数量限制，当前支持最多同时存在7个Worker。 2098- 在API version 8及之前的版本，当Worker数量超出限制时，会抛出错误Error "Too many workers, the number of workers exceeds the maximum."。 2099- 从API version 9开始，当Worker数量超出限制时，会抛出错误BusinessError "Worker initialization failure, the number of workers exceeds the maximum"。 2100- 主动销毁Worker可以调用新创建Worker对象的terminate()或parentPort.close()方法。 2101- 自API version 9版本开始，若Worker处于已经销毁或正在销毁等非运行状态时，调用其功能接口，会抛出相应的BusinessError。 2102- Worker的创建和销毁耗费性能，建议管理已创建的Worker并重复使用。 2103- 创建Worker工程时，new worker.Worker构造函数和new worker.ThreadWorker构造函数不能同时使用，否则将导致工程中Worker的功能异常。自API version 9版本开始，建议使用[new worker.ThreadWorker](#constructor9)构造函数，在API version 8及之前的版本，建议使用[new worker.Worker](#constructordeprecated)构造函数。 2104- 创建Worker工程时，在Worker线程的文件中（比如本文中worker.ts）不能导入任何有关构建UI的方法（比如ETS文件等），否则会导致Worker的功能失效。排查方式：解压生成的Hap包，在创建Worker线程的文件目录中找到"worker.js"，全局搜索"View"关键字。如果存在该关键字，说明在worker.js中打包进去了构建UI的方法，会导致Worker的功能失效，建议在创建Worker线程的文件中修改 "import “xxx” from src"中src的目录层级。 2105 2106## 完整示例 2107> **说明：**<br/> 2108> 以API version 9的工程为例。<br> API version 8及之前的版本仅支持FA模型，如需使用，注意更换构造Worker的接口和创建worker线程中与主线程通信的对象的两个方法。 2109### FA模型 2110 2111```js 2112// main.js(同级目录为例) 2113import worker from '@ohos.worker'; 2114// 主线程中创建Worker对象 2115const workerInstance = new worker.ThreadWorker("workers/worker.ts"); 2116// 创建js和ts文件都可以 2117// const workerInstance = new worker.ThreadWorker("workers/worker.js"); 2118 2119// API version 9之前版本，worker对象的构造方法 2120// const workerInstance = new worker.Worker("workers/worker.js"); 2121 2122// 主线程向worker线程传递信息 2123workerInstance.postMessage("123"); 2124 2125// 主线程接收worker线程信息 2126workerInstance.onmessage = function(e) { 2127 // data：worker线程发送的信息 2128 let data = e.data; 2129 console.log("main.js onmessage"); 2130 2131 // 销毁Worker对象 2132 workerInstance.terminate(); 2133} 2134 2135// 在调用terminate后，执行回调onexit 2136workerInstance.onexit = function() { 2137 console.log("main.js terminate"); 2138} 2139``` 2140```js 2141// worker.ts 2142import worker from '@ohos.worker'; 2143 2144// 创建worker线程中与主线程通信的对象 2145const workerPort = worker.workerPort 2146 2147// API version 9之前版本，创建worker线程中与主线程通信的对象 2148// const parentPort = worker.parentPort 2149 2150// worker线程接收主线程信息 2151workerPort.onmessage = function(e) { 2152 // data：主线程发送的信息 2153 let data = e.data; 2154 console.log("worker.ts onmessage"); 2155 2156 // worker线程向主线程发送信息 2157 workerPort.postMessage("123") 2158} 2159 2160// worker线程发生error的回调 2161workerPort.onerror= function(e) { 2162 console.log("worker.ts onerror"); 2163} 2164``` 2165build-profile.json5 配置 : 2166```json 2167 "buildOption": { 2168 "sourceOption": { 2169 "workers": [ 2170 "./src/main/ets/MainAbility/workers/worker.ts" 2171 ] 2172 } 2173 } 2174``` 2175### Stage模型 2176```js 2177// main.js（以不同目录为例） 2178import worker from '@ohos.worker'; 2179 2180// 主线程中创建Worker对象 2181const workerInstance = new worker.ThreadWorker("entry/ets/pages/workers/worker.ts"); 2182// 创建js和ts文件都可以 2183// const workerInstance = new worker.ThreadWorker("entry/ets/pages/workers/worker.js"); 2184 2185// 主线程向worker线程传递信息 2186workerInstance.postMessage("123"); 2187 2188// 主线程接收worker线程信息 2189workerInstance.onmessage = function(e) { 2190 // data：worker线程发送的信息 2191 let data = e.data; 2192 console.log("main.js onmessage"); 2193 2194 // 销毁Worker对象 2195 workerInstance.terminate(); 2196} 2197// 在调用terminate后，执行onexit 2198workerInstance.onexit = function() { 2199 console.log("main.js terminate"); 2200} 2201``` 2202```js 2203// worker.ts 2204import worker from '@ohos.worker'; 2205 2206// 创建worker线程中与主线程通信的对象 2207const workerPort = worker.workerPort 2208 2209// worker线程接收主线程信息 2210workerPort.onmessage = function(e) { 2211 // data：主线程发送的信息 2212 let data = e.data; 2213 console.log("worker.ts onmessage"); 2214 2215 // worker线程向主线程发送信息 2216 workerPort.postMessage("123") 2217} 2218 2219// worker线程发生error的回调 2220workerPort.onerror= function(e) { 2221 console.log("worker.ts onerror"); 2222} 2223``` 2224build-profile.json5 配置: 2225```json 2226 "buildOption": { 2227 "sourceOption": { 2228 "workers": [ 2229 "./src/main/ets/pages/workers/worker.ts" 2230 ] 2231 } 2232 } 2233``` 2234<!--no_check-->