启动一个worker

说明： 从 API Version 7 开始支持。

导入模块

import worker from '@ohos.worker';

权限

无

属性

WorkerOptions

worker构造函数函数的选项信息，用于为worker添加其他信息。

Worker

使用以下方法前，均需先构造worker实例，Worker类继承EventTarget。

constructor

constructor(scriptURL: string, options?: WorkerOptions)

worker构造函数。

• 参数：

  参数名	类型	必填	说明
  scriptURL	string	是	worker执行脚本的url，路径规范：若DevEco新建工程在pages同级下没有workers目录，需要新建workers目录，将脚本文件放入workers目录。
  options	WorkerOptions	否	worker构造的选项。

• 返回值：

  参数名	说明
  worker	执行Worker构造函数生成的Worker对象，失败则返回undefined。

• 示例：

  import worker from '@ohos.worker';
  const worker = new worker.Worker("workers/worker.js", {name:"first worker"});

postMessage

postMessage(message: Object, options?: PostMessageOptions): void

向worker线程发送消息，数据的传输采用结构化克隆算法。

• 参数：

  参数名	类型	必填	说明
  message	Object	是	发送至worker的数据。
  options	PostMessageOptions	否	可转移对象是 ArrayBuffer 的实例对象。transferList数组中不可传入null。

• 示例：

  import worker from '@ohos.worker';
  const worker = new worker.Worker("workers/worker.js");
  worker.postMessage("hello world");
  
  const worker = new worker.Worker("workers/worker.js");
  var buffer = new ArrayBuffer(8);
  worker.postMessage(buffer, [buffer]);

on

on(type: string, listener: EventListener): void

向worker添加一个事件监听。

• 参数：

  参数名	类型	必填	说明
  type	string	是	监听事件的type。
  listener	EventListener	是	回调的事件。

• 示例：

  import worker from '@ohos.worker';
  const worker = new worker.Worker("workers/worker.js")
  worker.on("alert", (e)=>{
      console.log("alert listener callback");
  })

once

once(type: string, listener: EventListener): void

向worker添加一个事件监听，事件监听只执行一次便自动删除。

• 参数：

  参数名	类型	必填	说明
  type	string	是	监听事件的type。
  listener	EventListener	是	回调的事件。

• 示例：

  import worker from '@ohos.worker';
  const worker = new worker.Worker("workers/worker.js");
  worker.once("alert", (e)=>{
      console.log("alert listener callback");
  })

off

off(type: string, listener?: EventListener): void

删除worker的事件监听。

• 参数：

  参数名	类型	必填	说明
  type	string	是	需要删除事件的type。
  listener	EventListener	否	需要删除的回调的事件。

• 示例：

  import worker from '@ohos.worker';
  const worker = new worker.Worker("workers/worker.js");
  worker.off("alert");

terminate

terminate(): void

关闭worker线程，终止worker接收消息。

• 示例：

  import worker from '@ohos.worker';
  const worker = new worker.Worker("workers/worker.js")
  worker.terminate()

onexit

onexit?: (code: number) => void

Worker对象的onexit属性表示worker退出时被调用的事件处理程序，处理程序在宿主线程中执行。

• 参数：

  参数名	类型	必填	说明
  code	number	否	worker退出的code。

• 示例：

  import worker from '@ohos.worker';
  const worker = new worker.Worker("workers/worker.js")
  worker.onexit = function(e) {
      console.log("onexit")
  }

onerror

onerror?: (err: ErrorEvent) => void

Worker对象的onerror属性表示worker在执行过程中发生异常被调用的事件处理程序，处理程序在宿主线程中执行。

• 参数：

  参数名	类型	必填	说明
  err	ErrorEvent	否	异常数据。

• 示例：

  import worker from '@ohos.worker';
  const worker = new worker.Worker("workers/worker.js")
  worker.onerror = function(e) {
      console.log("onerror")
  }

onmessage

onmessage?: (event: MessageEvent) => void

Worker对象的onmessage属性表示宿主线程接收到来自其创建的worker通过parentPort.postMessage接口发送的消息时被调用的事件处理程序，处理程序在宿主线程中执行。

• 参数：

  参数名	类型	必填	说明
  event	MessageEvent	否	收到的worker消息数据。

• 示例：

  import worker from '@ohos.worker';
  const worker = new worker.Worker("workers/worker.js")
  worker.onmessage = function(e) {
      console.log("onerror")
  }

onmessageerror

onmessageerror?: (event: MessageEvent) => void

Worker对象的onmessageerror属性表示当 Worker 对象接收到一条无法被序列化的消息时被调用的事件处理程序，处理程序在宿主线程中执行。

• 参数：

  参数名	类型	必填	说明
  event	MessageEvent	否	异常数据。

• 示例：

  import worker from '@ohos.worker';
  const worker = new worker.Worker("workers/worker.js")
  worker.onmessageerror= function(e) {
      console.log("onmessageerror")
  }

EventTarget

addEventListener

addEventListener(type: string, listener: EventListener): void

向worker添加一个事件监听。

• 参数：

  参数名	类型	必填	说明
  type	string	是	监听事件的type。
  listener	EventListener	是	回调的事件。

• 示例：

  import worker from '@ohos.worker';
  const worker = new worker.Worker("workers/worker.js")
  worker.addEventListener("alert", (e)=>{
      console.log("alert listener callback");
  })

removeEventListener

removeEventListener(type: string, callback?: EventListener): void

删除worker的事件监听。

• 参数：

  参数名	类型	必填	说明
  type	string	是	需要删除事件的type。
  callback	EventListener	否	需要删除的回调的事件。

• 示例：

  import worker from '@ohos.worker';
  const worker = new worker.Worker("workers/worker.js")
  worker.removeEventListener("alert")

dispatchEvent

dispatchEvent(event: Event): boolean

分发定义在worker的事件。

• 参数：

  参数名	类型	必填	说明
  event	Event	是	需要分发的事件。

• 返回值：

  参数名	说明
  boolean	分发的结果，false表示分发失败。

• 示例：

  import worker from '@ohos.worker';
  const worker = new worker.Worker("workers/worker.js")
  worker.dispatchEvent({type:"alert"})

removeAllListener

removeAllListener(): void

删除worker的所有事件监听。

• 示例：

  import worker from '@ohos.worker';
  const worker = new worker.Worker("workers/worker.js")
  worker.removeAllListener({type:"alert"})

DedicatedWorkerGlobalScope

worker线程用于与宿主线程通信的类，通过postMessage接口发送消息给宿主线程、close接口关闭worker线程，DedicatedWorkerGlobalScope类继承WorkerGlobalScope。

postMessage

postMessage(message: Object, options?: PostMessageOptions): void

worker向宿主线程发送消息。

• 参数：

  参数名	类型	必填	说明
  message	Object	是	发送至worker的数据。
  options	PostMessageOptions	否	可转移对象是ArrayBuffer的实例对象。transferList数组中不可传入null。

• 示例：

  // main.js
  import worker from '@ohos.worker';
  const worker = new worker.Worker("workers/worker.js")
  worker.postMessage("hello world")
  worker.onmessage = function(e) {
      console.log("receive data from worker.js")
  }
  
  // worker.js
  import worker from "@ohos.worker";
  const parentPort = worker.parentPort;
  parentPort.onmessage = function(e){
      parentPort.postMessage("receive data from main.js")
  }

close

close(): void

关闭worker线程，终止worker接收消息。

• 示例：

  // main.js
  import worker from '@ohos.worker';
  const worker = new worker.Worker("workers/worker.js")
  
  // worker.js
  import worker from "@ohos.worker";
  const parentPort = worker.parentPort;
  parentPort.onmessage = function(e) {
      parentPort.close()
  }

onmessage

onmessage?: (event: MessageEvent) => void

DedicatedWorkerGlobalScope的onmessage属性表示worker线程收到来自其宿主线程通过worker.postMessage接口发送的消息时被调用的事件处理程序，处理程序在worker线程中执行。

• 参数：

  参数名	类型	必填	说明
  event	MessageEvent	否	收到的worker消息数据。

• 示例：

  // main.js
  import worker from '@ohos.worker';
  const worker = new worker.Worker("workers/worker.js")
  worker.postMessage("hello world")
  
  // worker.js
  import worker from "@ohos.worker";
  const parentPort = worker.parentPort;
  parentPort.onmessage = function(e) {
      console.log("receive main.js message")
  }

onmessageerror

onmessageerror?: (event: MessageEvent) => void

DedicatedWorkerGlobalScope的onmessageerror属性表示当 Worker 对象接收到一条无法被反序列化的消息时被调用的事件处理程序，处理程序在worker线程中执行。

• 参数：

  参数名	类型	必填	说明
  event	MessageEvent	否	异常数据。

• 示例：

  // main.js
  import worker from '@ohos.worker';
  const worker = new worker.Worker("workers/worker.js")
  
  // worker.js
  import worker from "@ohos.worker";
  const parentPort = worker.parentPort;
  parentPort.onmessageerror= function(e) {
      console.log("worker.js onmessageerror")
  }

PostMessageOptions

明确数据传递过程中需要转移所有权对象的类，传递所有权的对象必须是ArrayBuffer。

Event

事件类。

EventListener

事件监听类。

(evt: Event): void | Promise<void>

执行的回调函数。

• 参数：

  参数名	类型	必填	说明
  evt	Event	是	回调的事件类。

• 返回值

  参数名	说明
  void | Promise<void>	无返回值或者以Promise形式返回。

• 示例：

  import worker from '@ohos.worker';
  const worker = new worker.Worker("workers/worker.js");
  worker.addEventListener("alert", (e)=>{
      console.log("alert listener callback");
  })

ErrorEvent

错误事件类，用于表示worker执行过程中出现异常的详细信息，ErrorEvent类继承Event。

MessageEvent

消息类，持有worker线程间传递的数据。

WorkerGlobalScope

worker线程自身的运行环境，WorkerGlobalScope类继承EventTarget。

属性

onerror

onerror?: (ev: ErrorEvent) => void

WorkerGlobalScope的onerror属性表示worker在执行过程中发生异常被调用的事件处理程序，处理程序在worker线程中执行。

• 参数：

  参数名	类型	必填	说明
  ev	ErrorEvent	否	异常数据。

• 示例：

  // main.js
  import worker from '@ohos.worker';
  const worker = new worker.Worker("workers/worker.js")
  
  // worker.js
  import worker from "@ohos.worker";
  const parentPort = worker.parentPort
  parentPort.onerror = function(e){
      console.log("worker.js onerror")
  }