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