1# 启动一个Worker 2 3>  **说明：** 4> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 5 6Worker是与主线程并行的独立线程。创建Worker的线程称之为宿主线程，Worker自身的线程称之为Worker线程。创建Worker传入的url文件在Worker线程中执行，可以处理耗时操作但不可以直接操作UI。 7 8## 导入模块 9 10``` 11import worker from '@ohos.worker'; 12``` 13 14 15## 属性 16 17**系统能力：** 以下各项对应的系统能力均为SystemCapability.Utils.Lang。 18 19| 名称 | 参数类型 | 可读 | 可写 | 说明 | 20| ---------- | --------------------------------------------------------- | ---- | ---- | ------------------------------------ | 21| parentPort | [DedicatedWorkerGlobalScope](#dedicatedworkerglobalscope) | 是 | 是 | worker线程用于与宿主线程通信的对象。 | 22 23 24## WorkerOptions 25 26Worker构造函数的选项信息，用于为Worker添加其他信息。 27 28**系统能力：** 以下各项对应的系统能力均为SystemCapability.Utils.Lang。 29 30| 名称 | 参数类型 | 可读 | 可写 | 说明 | 31| ---- | --------- | ---- | ---- | ---------------------- | 32| type | "classic" | 是 | 是 | 按照指定方式执行脚本。 | 33| name | string | 是 | 是 | Worker的名称。 | 34 35 36## Worker 37 38使用以下方法前，均需先构造Worker实例，Worker类继承[EventTarget](#eventtarget)。 39 40 41### constructor 42 43constructor(scriptURL: string, options?: WorkerOptions) 44 45Worker构造函数。 46 47**系统能力：** SystemCapability.Utils.Lang 48 49**参数：** 50 51| 参数名 | 类型 | 必填 | 说明 | 52| --------- | ------------------------------- | ---- | ------------------------------------------------------------ | 53| scriptURL | string | 是 | Worker执行脚本的url，路径规范：若DevEco新建工程在pages同级下没有workers目录，需要新建workers目录，将脚本文件放入workers目录。 | 54| options | [WorkerOptions](#workeroptions) | 否 | Worker构造的选项。 | 55 56**返回值：** 57 58| 类型 | 说明 | 59| ------ | --------------------------------------------------------- | 60| Worker | 执行Worker构造函数生成的Worker对象，失败则返回undefined。 | 61 62**示例：** 63 64``` 65const workerInstance = new worker.Worker("workers/worker.js", {name:"first worker"}); 66``` 67 68 69### postMessage 70 71postMessage(message: Object, options?: PostMessageOptions): void 72 73向Worker线程发送消息，数据的传输采用结构化克隆算法。 74 75**系统能力：** SystemCapability.Utils.Lang 76 77**参数：** 78 79| 参数名 | 类型 | 必填 | 说明 | 80| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 81| message | Object | 是 | 发送至Worker的数据。 | 82| options | [PostMessageOptions](#postmessageoptions) | 否 | 可转移对象是 ArrayBuffer 的实例对象。transferList数组中不可传入null。 | 83 84**示例：** 85 86``` 87const workerInstance = new worker.Worker("workers/worker.js"); 88workerInstance.postMessage("hello world"); 89``` 90 91``` 92const workerInstance= new worker.Worker("workers/worker.js"); 93var buffer = new ArrayBuffer(8); 94workerInstance.postMessage(buffer, [buffer]); 95``` 96 97 98### on 99 100on(type: string, listener: EventListener): void 101 102向Worker添加一个事件监听。 103 104**系统能力：** SystemCapability.Utils.Lang 105 106**参数：** 107 108| 参数名 | 类型 | 必填 | 说明 | 109| -------- | ------------------------------- | ---- | ---------------- | 110| type | string | 是 | 监听事件的type。 | 111| listener | [EventListener](#eventlistener) | 是 | 回调的事件。 | 112 113**示例：** 114 115``` 116const workerInstance = new worker.Worker("workers/worker.js") 117workerInstance.on("alert", (e)=>{ 118 console.log("alert listener callback"); 119}) 120``` 121 122 123### once 124 125once(type: string, listener: EventListener): void 126 127向Worker添加一个事件监听，事件监听只执行一次便自动删除。 128 129**系统能力：** SystemCapability.Utils.Lang 130 131**参数：** 132 133| 参数名 | 类型 | 必填 | 说明 | 134| -------- | ------------------------------- | ---- | ---------------- | 135| type | string | 是 | 监听事件的type。 | 136| listener | [EventListener](#eventlistener) | 是 | 回调的事件。 | 137 138**示例：** 139 140``` 141const workerInstance = new worker.Worker("workers/worker.js"); 142workerInstance.once("alert", (e)=>{ 143 console.log("alert listener callback"); 144}) 145``` 146 147 148### off 149 150off(type: string, listener?: EventListener): void 151 152删除Worker的事件监听。 153 154**系统能力：** SystemCapability.Utils.Lang 155 156**参数：** 157 158| 参数名 | 类型 | 必填 | 说明 | 159| -------- | ------------------------------- | ---- | ---------------------- | 160| type | string | 是 | 需要删除事件的type。 | 161| listener | [EventListener](#eventlistener) | 否 | 需要删除的回调的事件。 | 162 163**示例：** 164 165``` 166const workerInstance = new worker.Worker("workers/worker.js"); 167workerInstance.off("alert"); 168``` 169 170 171### terminate 172 173terminate(): void 174 175关闭Worker线程，终止Worker接收消息。 176 177**系统能力：** SystemCapability.Utils.Lang 178 179**示例：** 180 181``` 182const workerInstance = new worker.Worker("workers/worker.js") 183workerInstance.terminate() 184``` 185 186 187### onexit 188 189onexit?: (code: number) => void 190 191Worker对象的onexit属性表示Worker退出时被调用的事件处理程序，处理程序在宿主线程中执行。 192 193**系统能力：** SystemCapability.Utils.Lang 194 195**参数：** 196 197| 参数名 | 类型 | 必填 | 说明 | 198| ------ | ------ | ---- | ------------------ | 199| code | number | 否 | Worker退出的code。 | 200 201**示例：** 202 203``` 204const workerInstance = new worker.Worker("workers/worker.js") 205workerInstance.onexit = function(e) { 206 console.log("onexit") 207} 208``` 209 210 211### onerror 212 213onerror?: (err: ErrorEvent) => void 214 215Worker对象的onerror属性表示Worker在执行过程中发生异常被调用的事件处理程序，处理程序在宿主线程中执行。 216 217**系统能力：** SystemCapability.Utils.Lang 218 219**参数：** 220 221| 参数名 | 类型 | 必填 | 说明 | 222| ------ | ------------------------- | ---- | ---------- | 223| err | [ErrorEvent](#errorevent) | 否 | 异常数据。 | 224 225**示例：** 226 227``` 228const workerInstance = new worker.Worker("workers/worker.js") 229workerInstance.onerror = function(e) { 230 console.log("onerror") 231} 232``` 233 234 235### onmessage 236 237onmessage?: (event: MessageEvent) => void 238 239Worker对象的onmessage属性表示宿主线程接收到来自其创建的Worker通过parentPort.postMessage接口发送的消息时被调用的事件处理程序，处理程序在宿主线程中执行。 240 241**系统能力：** SystemCapability.Utils.Lang 242 243**参数：** 244 245| 参数名 | 类型 | 必填 | 说明 | 246| ------ | ----------------------------- | ---- | ---------------------- | 247| event | [MessageEvent](#messageevent) | 否 | 收到的Worker消息数据。 | 248 249**示例：** 250 251``` 252const workerInstance = new worker.Worker("workers/worker.js") 253workerInstance.onmessage = function(e) { 254 console.log("onerror") 255} 256``` 257 258 259### onmessageerror 260 261onmessageerror?: (event: MessageEvent) => void 262 263Worker对象的onmessageerror属性表示当Worker对象接收到一条无法被序列化的消息时被调用的事件处理程序，处理程序在宿主线程中执行。 264 265**系统能力：** SystemCapability.Utils.Lang 266 267**参数：** 268 269| 参数名 | 类型 | 必填 | 说明 | 270| ------ | ----------------------------- | ---- | ---------- | 271| event | [MessageEvent](#messageevent) | 否 | 异常数据。 | 272 273**示例：** 274 275``` 276const workerInstance = new worker.Worker("workers/worker.js") 277workerInstance.onmessageerror= function(e) { 278 console.log("onmessageerror") 279} 280``` 281 282 283## EventTarget 284 285 286### addEventListener 287 288addEventListener(type: string, listener: EventListener): void 289 290向Worker添加一个事件监听。 291 292**系统能力：** SystemCapability.Utils.Lang 293 294**参数：** 295 296| 参数名 | 类型 | 必填 | 说明 | 297| -------- | ------------------------------- | ---- | ---------------- | 298| type | string | 是 | 监听事件的type。 | 299| listener | [EventListener](#eventlistener) | 是 | 回调的事件。 | 300 301**示例：** 302 303``` 304const workerInstance = new worker.Worker("workers/worker.js") 305workerInstance.addEventListener("alert", (e)=>{ 306 console.log("alert listener callback"); 307}) 308``` 309 310 311### removeEventListener 312 313removeEventListener(type: string, callback?: EventListener): void 314 315删除Worker的事件监听。 316 317**系统能力：** SystemCapability.Utils.Lang 318 319**参数：** 320 321| 参数名 | 类型 | 必填 | 说明 | 322| -------- | ------------------------------- | ---- | ---------------------- | 323| type | string | 是 | 需要删除事件的type。 | 324| callback | [EventListener](#eventlistener) | 否 | 需要删除的回调的事件。 | 325 326**示例：** 327 328``` 329const workerInstance = new worker.Worker("workers/worker.js") 330workerInstance.removeEventListener("alert") 331``` 332 333 334### dispatchEvent 335 336dispatchEvent(event: Event): boolean 337 338分发定义在Worker的事件。 339 340**系统能力：** SystemCapability.Utils.Lang 341 342**参数：** 343 344| 参数名 | 类型 | 必填 | 说明 | 345| ------ | --------------- | ---- | ---------------- | 346| event | [Event](#event) | 是 | 需要分发的事件。 | 347 348**返回值：** 349 350| 类型 | 说明 | 351| ------- | ------------------------------- | 352| boolean | 分发的结果，false表示分发失败。 | 353 354**示例：** 355 356``` 357const workerInstance = new worker.Worker("workers/worker.js") 358workerInstance.dispatchEvent({type:"alert"}) 359``` 360 361 362### removeAllListener 363 364removeAllListener(): void 365 366删除Worker的所有事件监听。 367 368**系统能力：** SystemCapability.Utils.Lang 369 370**示例：** 371 372``` 373const workerInstance = new worker.Worker("workers/worker.js") 374workerInstance.removeAllListener({type:"alert"}) 375``` 376 377 378## DedicatedWorkerGlobalScope 379 380Worker线程用于与宿主线程通信的类，通过postMessage接口发送消息给宿主线程、close接口关闭Worker线程，DedicatedWorkerGlobalScope类继承[WorkerGlobalScope](#workerglobalscope)。 381 382 383### postMessage 384 385postMessage(message: Object, options?: PostMessageOptions): void 386 387Worker向宿主线程发送消息。 388 389**系统能力：** SystemCapability.Utils.Lang 390 391**参数：** 392 393| 参数名 | 类型 | 必填 | 说明 | 394| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 395| message | Object | 是 | 发送至Worker的数据。 | 396| options | [PostMessageOptions](#postmessageoptions) | 否 | 可转移对象是ArrayBuffer的实例对象。transferList数组中不可传入null。 | 397 398**示例：** 399 400``` 401// main.js 402import worker from '@ohos.worker'; 403const workerInstance = new worker.Worker("workers/worker.js") 404workerInstance.postMessage("hello world") 405workerInstance.onmessage = function(e) { 406 console.log("receive data from worker.js") 407} 408``` 409 410``` 411// worker.js 412import worker from '@ohos.worker'; 413const parentPort = worker.parentPort; 414parentPort.onmessage = function(e){ 415 parentPort.postMessage("receive data from main.js") 416} 417``` 418 419 420### close 421 422close(): void 423 424关闭Worker线程，终止Worker接收消息。 425 426**系统能力：** SystemCapability.Utils.Lang 427 428**示例：** 429 430``` 431// main.js 432import worker from '@ohos.worker'; 433const workerInstance = new worker.Worker("workers/worker.js") 434``` 435 436``` 437// worker.js 438import worker from '@ohos.worker'; 439const parentPort = worker.parentPort; 440parentPort.onmessage = function(e) { 441 parentPort.close() 442} 443``` 444 445 446### onmessage 447 448onmessage?: (event: MessageEvent) => void 449 450DedicatedWorkerGlobalScope的onmessage属性表示Worker线程收到来自其宿主线程通过worker.postMessage接口发送的消息时被调用的事件处理程序，处理程序在Worker线程中执行。 451 452**系统能力：** SystemCapability.Utils.Lang 453 454**参数：** 455 456| 参数名 | 类型 | 必填 | 说明 | 457| ------ | ----------------------------- | ---- | ---------------------- | 458| event | [MessageEvent](#messageevent) | 否 | 收到的Worker消息数据。 | 459 460**示例：** 461 462``` 463// main.js 464import worker from '@ohos.worker'; 465const workerInstance = new worker.Worker("workers/worker.js") 466workerInstance.postMessage("hello world") 467``` 468 469``` 470// worker.js 471import worker from '@ohos.worker'; 472const parentPort = worker.parentPort; 473parentPort.onmessage = function(e) { 474 console.log("receive main.js message") 475} 476``` 477 478 479### onmessageerror 480 481onmessageerror?: (event: MessageEvent) => void 482 483DedicatedWorkerGlobalScope的onmessageerror属性表示当Worker对象接收到一条无法被反序列化的消息时被调用的事件处理程序，处理程序在Worker线程中执行。 484 485**系统能力：** SystemCapability.Utils.Lang 486 487**参数：** 488 489| 参数名 | 类型 | 必填 | 说明 | 490| ------ | ----------------------------- | ---- | ---------- | 491| event | [MessageEvent](#messageevent) | 否 | 异常数据。 | 492 493**示例：** 494 495``` 496// main.js 497import worker from '@ohos.worker'; 498const workerInstance = new worker.Worker("workers/worker.js") 499``` 500 501``` 502// worker.js 503import worker from '@ohos.worker'; 504const parentPort = worker.parentPort; 505parentPort.onmessageerror= function(e) { 506 console.log("worker.js onmessageerror") 507} 508``` 509 510 511## PostMessageOptions 512 513明确数据传递过程中需要转移所有权对象的类，传递所有权的对象必须是ArrayBuffer。 514 515**系统能力：** 以下各项对应的系统能力均为SystemCapability.Utils.Lang。 516 517| 名称 | 参数类型 | 可读 | 可写 | 说明 | 518| -------- | -------- | ---- | ---- | --------------------------------- | 519| transfer | Object[] | 是 | 是 | ArrayBuffer数组，用于传递所有权。 | 520 521 522## Event 523 524事件类。 525 526**系统能力：** 以下各项对应的系统能力均为SystemCapability.Utils.Lang。 527 528| 名称 | 参数类型 | 可读 | 可写 | 说明 | 529| --------- | -------- | ---- | ---- | ---------------------------------- | 530| type | string | 是 | 否 | 指定事件的type。 | 531| timeStamp | number | 是 | 否 | 事件创建时的时间戳（精度为毫秒）。 | 532 533 534## EventListener 535 536事件监听类。 537 538 539### (evt: Event): void | Promise<void> 540 541执行的回调函数。 542 543**系统能力：** SystemCapability.Utils.Lang 544 545**参数：** 546 547| 参数名 | 类型 | 必填 | 说明 | 548| ------ | --------------- | ---- | -------------- | 549| evt | [Event](#event) | 是 | 回调的事件类。 | 550 551**返回值：** 552 553| 类型 | 说明 | 554| ------------------------------------- | ------------------------------- | 555| void \| Promise<void> | 无返回值或者以Promise形式返回。 | 556 557**示例：** 558 559``` 560const workerInstance = new worker.Worker("workers/worker.js"); 561workerInstance.addEventListener("alert", (e)=>{ 562 console.log("alert listener callback"); 563}) 564``` 565 566 567## ErrorEvent 568 569错误事件类，用于表示Worker执行过程中出现异常的详细信息，ErrorEvent类继承[Event](#event)。 570 571**系统能力：** 以下各项对应的系统能力均为SystemCapability.Utils.Lang。 572 573| 名称 | 参数类型 | 可读 | 可写 | 说明 | 574| -------- | -------- | ---- | ---- | -------------------- | 575| message | string | 是 | 否 | 异常发生的错误信息。 | 576| filename | string | 是 | 否 | 出现异常所在的文件。 | 577| lineno | number | 是 | 否 | 异常所在的行数。 | 578| colno | number | 是 | 否 | 异常所在的列数。 | 579| error | Object | 是 | 否 | 异常类型。 | 580 581 582## MessageEvent 583 584消息类，持有Worker线程间传递的数据。 585 586**系统能力：** 以下各项对应的系统能力均为SystemCapability.Utils.Lang。 587 588| 名称 | 参数类型 | 可读 | 可写 | 说明 | 589| ---- | -------- | ---- | ---- | ------------------ | 590| data | T | 是 | 否 | 线程间传递的数据。 | 591 592 593## WorkerGlobalScope 594 595Worker线程自身的运行环境，WorkerGlobalScope类继承[EventTarget](#eventtarget)。 596 597### 属性 598 599**系统能力：** 以下各项对应的系统能力均为SystemCapability.Utils.Lang。 600 601| 名称 | 参数类型 | 可读 | 可写 | 说明 | 602| ---- | ------------------------------------------------------------ | ---- | ---- | --------------------------------------- | 603| name | string | 是 | 否 | Worker的名字，有new Worker时指定。 | 604| self | [WorkerGlobalScope](#workerglobalscope) & typeof globalThis | 是 | 否 | WorkerGlobalScope本身。 | 605 606 607### onerror 608 609onerror?: (ev: ErrorEvent) => void 610 611WorkerGlobalScope的onerror属性表示Worker在执行过程中发生异常被调用的事件处理程序，处理程序在Worker线程中执行。 612 613**系统能力：** SystemCapability.Utils.Lang 614 615**参数：** 616 617| 参数名 | 类型 | 必填 | 说明 | 618| ------ | ------------------------- | ---- | ---------- | 619| ev | [ErrorEvent](#errorevent) | 否 | 异常数据。 | 620 621**示例：** 622 623``` 624// main.js 625import worker from '@ohos.worker'; 626const workerInstance = new worker.Worker("workers/worker.js") 627``` 628 629``` 630// worker.js 631import worker from '@ohos.worker'; 632const parentPort = worker.parentPort 633parentPort.onerror = function(e){ 634 console.log("worker.js onerror") 635} 636```
