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