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