启动一个worker

About 39 min

启动一个worker

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

导入模块

import worker from '@ohos.worker';
1

权限

属性

名称

参数类型

可读

可写

说明

parentPort

DedicatedWorkerGlobalScope

worker线程用于与宿主线程通信的对象

WorkerOptions

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

名称

参数类型

可读

可写

说明

type

"classic"

按照指定方式执行脚本。

name

string

worker的名称。

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"}
    
    1
    2

Worker

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

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]);
    
    1
    2
    3
    4
    5
    6
    7

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);
    })
    
    1
    2
    3
    4
    5

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);
    })
    
    1
    2
    3
    4
    5

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")
    
    1
    2
    3

terminate

terminate(): void

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

  • 示例:

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

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")
    }
    
    1
    2
    3
    4
    5

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")
    }
    
    1
    2
    3
    4
    5

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")
    }
    
    1
    2
    3
    4
    5

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")
    }
    
    1
    2
    3
    4
    5

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);
    })
    
    1
    2
    3
    4
    5

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")
    
    1
    2
    3

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"})
    
    1
    2
    3

removeAllListener

removeAllListener(): void

删除worker的所有事件监听。

  • 示例:

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

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")
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14

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()
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10

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")
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11

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")
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10

PostMessageOptions

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

名称

参数类型

可读

可写

说明

transfer

Object[]

ArrayBuffer数组,用于传递所有权。

Event

事件类。

名称

参数类型

可读

可写

说明

type

string

指定事件的type。

timeStamp

number

事件创建时的时间戳(精度为毫秒)。

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);
    })
    
    1
    2
    3
    4
    5

ErrorEvent

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

名称

参数类型

可读

可写

说明

message

string

异常发生的错误信息。

filename

string

出现异常所在的文件。

lineno

number

异常所在的行数。

colno

number

异常所在的列数。

error

Object

异常类型。

MessageEvent

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

名称

参数类型

可读

可写

说明

data

T

线程间传递的数据。

WorkerGlobalScope

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

属性

名称

参数类型

可读

可写

说明

name

string

worker的名字,有new Worker时指定。

self

WorkerGlobalScope & typeof globalThis

WorkerGlobalScope本身。

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")
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10