文档中心

导入模块

收起
自动换行
深色代码主题
复制
import { worker } from '@kit.ArkTS';

常量

系统能力： SystemCapability.Utils.Lang

展开

名称	类型	只读	说明
workerPort⁹⁺	ThreadWorkerGlobalScope	是	Worker线程用于与宿主线程通信的对象。元服务API：从API version 11开始，该接口支持在元服务中使用。
parentPort^(deprecated)	DedicatedWorkerGlobalScope	是	Worker线程用于与宿主线程通信的对象。说明：从API version 7开始支持，从API version 9开始废弃，建议使用workerPort替代。

名称

类型

只读

说明

workerPort⁹⁺

ThreadWorkerGlobalScope

是

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

元服务API：从API version 11开始，该接口支持在元服务中使用。

parentPort^(deprecated)

DedicatedWorkerGlobalScope

是

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

说明：从API version 7开始支持，从API version 9开始废弃，建议使用workerPort替代。

WorkerOptions

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

系统能力： SystemCapability.Utils.Lang

展开

名称	类型	只读	可选	说明
type	'classic' \| 'module'	否	是	Worker执行脚本的模式类型，暂不支持module类型，默认值为"classic"。元服务API：从API version 11开始，该接口支持在元服务中使用。
name	string	否	是	Worker的名称。默认值为undefined，此时线程名称为'WorkerThread'。非默认值情况下，对应的线程名称带有'WorkerThread_'前缀。比如name为'testName'时，对应的线程名称为'WorkerThread_testName'。线程名称可通过HeapMemoryInfo的threadName获取。元服务API：从API version 11开始，该接口支持在元服务中使用。
shared	boolean	否	是	表示Worker共享功能，此接口暂不支持。元服务API：从API version 12开始，该接口支持在元服务中使用。
priority¹⁸⁺	ThreadWorkerPriority	否	是	表示Worker线程优先级。默认值为MEDIUM。元服务API：从API version 18开始，该接口支持在元服务中使用。

ThreadWorkerPriority¹⁸⁺

Phone18+PC/2in118+Tablet18+TV19+Wearable18+

Worker线程的优先级枚举，各优先级对应关系请参考QoS等级定义。

系统能力： SystemCapability.Utils.Lang

展开

名称	值	说明
HIGH	0	适用于打开文档等用户触发并且可以看到进展的任务，任务在几秒钟之内完成。对应QOS_USER_INITIATED。元服务API：从API version 18开始，该接口支持在元服务中使用。
MEDIUM	1	任务完成需要几秒钟。是ThreadWorkerPriority的默认值。对应QOS_DEFAULT。元服务API：从API version 18开始，该接口支持在元服务中使用。
LOW	2	适用于下载等不需要立即看到响应效果的任务，任务完成需要几秒到几分钟。对应QOS_UTILITY。元服务API：从API version 18开始，该接口支持在元服务中使用。
IDLE	3	适用于数据同步等用户不可见的后台任务，任务完成需要几分钟甚至几小时。对应QOS_BACKGROUND。元服务API：从API version 18开始，该接口支持在元服务中使用。
DEADLINE²⁰⁺	4	适用于页面加载等越快越好的关键任务，任务几乎是瞬间完成的。对应QOS_DEADLINE_REQUEST。元服务API：从API version 20开始，该接口支持在元服务中使用。
VIP²⁰⁺	5	适用于UI线程、动画渲染等用户交互任务，任务是即时的。对应QOS_USER_INTERACTIVE。元服务API：从API version 20开始，该接口支持在元服务中使用。

ThreadWorker⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

使用以下方法前，需先构造ThreadWorker实例。ThreadWorker类继承自WorkerEventTarget。

属性

系统能力： SystemCapability.Utils.Lang

展开

名称	类型	只读	可选	说明
onexit⁹⁺	(code: number) => void	否	是	回调函数。表示Worker线程销毁时被调用的事件处理程序，该处理程序在宿主线程中执行。回调函数的code参数类型为number，异常退出时code为1，正常退出时code为0。默认值为undefined。以下错误码的详细介绍请参见语言基础类库错误码。 - 10200004：The Worker instance is not running. - 10200005：The called API is not supported in the worker thread. 元服务API：从API version 11开始，该属性支持在元服务中使用。
onerror⁹⁺	(err: ErrorEvent) => void	否	是	回调函数，用于处理onmessage回调函数中同步代码产生的异常，处理程序在宿主线程中执行。回调函数的err类型为ErrorEvent，表示收到的异常数据。默认值为undefined。以下错误码的详细介绍请参见语言基础类库错误码。 - 10200004：The Worker instance is not running. - 10200005：The called API is not supported in the worker thread. 元服务API：从API version 11开始，该属性支持在元服务中使用。
onAllErrors¹⁸⁺	ErrorCallback	否	是	回调函数。表示Worker线程生命周期内发生异常被调用的事件处理程序，处理程序在宿主线程中执行。默认值为undefined。以下错误码的详细介绍请参见语言基础类库错误码。 - 10200004：The Worker instance is not running. - 10200005：The called API is not supported in the worker thread. 元服务API：从API version 18开始，该属性支持在元服务中使用。
onmessage⁹⁺	(event: MessageEvents) => void	否	是	回调函数。表示宿主线程接收到来自其创建的Worker通过workerPort.postMessage或workerPort.postMessageWithSharedSendable接口发送的消息时被调用的事件处理程序，处理程序在宿主线程中执行。其中回调函数中event类型为MessageEvents，表示收到的Worker线程发送的消息数据。默认值为undefined。以下错误码的详细介绍请参见语言基础类库错误码。 - 10200004：The Worker instance is not running. - 10200005：The called API is not supported in the worker thread. 元服务API：从API version 11开始，该属性支持在元服务中使用。
onmessageerror⁹⁺	(event: MessageEvents) => void	否	是	回调函数。用于处理Worker对象接收到的无法被序列化的消息。该处理程序在宿主线程中执行，event类型为MessageEvents，表示收到的Worker消息数据。默认值为undefined。以下错误码的详细介绍请参见语言基础类库错误码。 - 10200004：The Worker instance is not running. - 10200005：The called API is not supported in the worker thread. 元服务API：从API version 11开始，该属性支持在元服务中使用。

使用Worker模块时，API version 18及之后的版本建议在宿主线程中注册onAllErrors回调，以捕获Worker线程生命周期内的各种异常。API version 18之前的版本应注册onerror回调。如果未注册onAllErrors或onerror回调，当Worker线程出现异常时会发生崩溃问题。注意，onerror接口仅能捕获onmessage回调中的同步异常，捕获异常后，Worker线程将进入销毁流程，无法继续使用。

onAllErrors接口与onerror接口之间的行为差异如下：

异常捕获范围

onAllErrors接口可以捕获Worker线程的onmessage回调、timer回调以及文件执行等流程中产生的全局异常。

onerror接口仅能捕获Worker线程的onmessage回调中同步方法产生的异常，无法捕获多线程回调和模块化相关异常。
异常捕获后的线程状态

onAllErrors接口捕获异常后，Worker线程仍然存活并可以继续使用。这使开发者可以在捕获异常后执行其他操作，无需担心线程终止。

onerror接口捕获异常后，Worker线程会进入销毁流程，无法继续使用。这意味着在onerror触发后，Worker线程将被终止，后续操作将无法进行。
适用场景

onAllErrors接口适用于捕获Worker线程中所有类型异常的场景，特别是确保异常发生后Worker线程仍能继续运行的复杂场景。

onerror接口适用于只需要捕获onmessage回调中同步异常的简单场景。由于捕获异常后线程会被销毁，适用于不需要继续使用Worker线程的情况。

推荐使用onAllErrors接口，因为它提供了更全面的异常捕获能力，并且不会导致线程终止。

constructor⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

constructor(scriptURL: string, options?: WorkerOptions)

ThreadWorker构造函数。

元服务API：从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名	类型	必填	说明
scriptURL	string	是	Worker线程文件的路径。路径规则详细参考文件路径注意事项。
options	WorkerOptions	否	Worker构造的选项。此参数不填时，对应各属性取其默认值。

参数名

类型

必填

说明

scriptURL

string

是

Worker线程文件的路径。

路径规则详细参考文件路径注意事项。

options

WorkerOptions

否

Worker构造的选项。此参数不填时，对应各属性取其默认值。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200003	Worker initialization failed.
10200007	The worker file path is invalid.

示例：

以下示例展示了在Stage模型的entry模块Index.ets文件中加载Worker线程文件的方法，使用Library加载Worker线程文件的场景参考文件路径注意事项。

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

// worker文件所在路径："entry/src/main/ets/workers/worker.ets"
const workerInstance = new worker.ThreadWorker('entry/ets/workers/worker.ets', {name: "WorkerThread"});

postMessage⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

postMessage(message: Object, transfer: ArrayBuffer[]): void

宿主线程通过转移对象所有权的方式向Worker线程发送消息。

系统能力： SystemCapability.Utils.Lang

元服务API：从API version 11开始，该接口支持在元服务中使用。

参数：

展开

参数名	类型	必填	说明
message	Object	是	发送至Worker的数据，该数据对象必须是可序列化对象，序列化支持类型见序列化支持类型。
transfer	ArrayBuffer[]	是	表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到Worker线程，在宿主线程中将会变为不可用，仅在Worker线程中可用，数组不可传入null。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.
10200006	An exception occurred during serialization.

示例：

收起
自动换行
深色代码主题
复制
// Worker.ets
import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS';

// 创建worker线程中与宿主线程通信的对象
const workerPort = worker.workerPort;

// worker线程接收宿主线程信息
workerPort.onmessage = (e: MessageEvents): void => {
  // data：宿主线程发送的信息
  let data: ArrayBuffer = e.data;
  // 往收到的buffer里写入数据
  const view = new Int8Array(data).fill(3);
  // worker线程向宿主线程发送信息
  workerPort.postMessage(view);
}

// worker线程发生error的回调
workerPort.onerror = (err: ErrorEvent) => {
  console.error("worker.ets onerror" + err.message);
}

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS';

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            // 宿主线程中创建Worker对象
            const workerInstance = new worker.ThreadWorker("entry/ets/workers/Worker.ets");
            // 宿主线程向worker线程传递信息
            const buffer = new ArrayBuffer(8);
            workerInstance.postMessage(buffer, [buffer]);

            // 此时buffer的所有权转移到了worker线程，在宿主线程中不可用
            // const view = new Int8Array(buffer).fill(3);

            // 宿主线程接收worker线程信息
            workerInstance.onmessage = (e: MessageEvents): void => {
              // data：worker线程发送的信息
              let data: Int8Array = e.data;
              console.info("main thread data is  " + data);
              // 销毁Worker对象
              workerInstance.terminate();
            }
            // 在调用terminate后，执行onexit
            workerInstance.onexit = (code) => {
              console.info("main thread terminate");
            }
            // 监听Worker错误
            workerInstance.onAllErrors = (err: ErrorEvent) => {
              console.error("main error message " + err.message);
            }
          })
      }
      .width('100%')
      .height('100%')
    }
  }
}

postMessage⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

宿主线程可以通过转移对象所有权或拷贝数据的方式向Worker线程发送消息。在传递Sendable对象时，使用拷贝数据的方式。

元服务API：从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名

类型

必填

说明

message

Object

是

发送至Worker的数据，该数据对象必须是可序列化对象，序列化支持类型见序列化支持类型。

options

PostMessageOptions

否

当填入该参数时，传输的数据将通过所有权转移的方式发送到Worker线程。这些数据在宿主线程中将变为不可用，仅在Worker线程中可用。

若不填入该参数，默认设置为 undefined，数据将通过拷贝的方式传输到Worker线程。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.
10200006	An exception occurred during serialization.

示例：

收起
自动换行
深色代码主题
复制
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

workerInstance.postMessage("hello world");

let buffer = new ArrayBuffer(8);

// 填入options参数，buffer的所有权会转移到Worker线程，在宿主线程中将不可用
workerInstance.postMessage(buffer, {transfer: [buffer]});

postMessageWithSharedSendable¹²⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

postMessageWithSharedSendable(message: Object, transfer?: ArrayBuffer[]): void

宿主线程向Worker线程发送消息，消息中的Sendable对象通过引用传递，非Sendable对象通过拷贝数据的方式传递。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名	类型	必填	说明
message	Object	是	发送至Worker的数据，该数据对象必须是可序列化对象，序列化支持类型见序列化支持类型。如果需要共享数据，支持类型见Sendable支持的数据类型。
transfer	ArrayBuffer[]	否	可转移的ArrayBuffer实例对象数组。该数组中对象的所有权将转移到Worker线程，在宿主线程中变为不可用，仅在Worker线程中可用，数组不可传入null。默认值为undefined。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.
10200006	An exception occurred during serialization.

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
// 新建SendableObject实例并通过宿主线程传递至Worker线程

import { worker } from '@kit.ArkTS';
import { SendableObject } from './sendable';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/Worker.ets");
let object: SendableObject = new SendableObject();
workerInstance.postMessageWithSharedSendable(object);

// 使用postMessage接口传递Sendable对象，使用拷贝数据的方式传递
workerInstance.postMessage(object);

收起
自动换行
深色代码主题
复制
// sendable.ets
// 定义SendableObject

@Sendable
export class SendableObject {
  value:number = 45;
}

收起
自动换行
深色代码主题
复制
// worker文件路径为：entry/src/main/ets/workers/Worker.ets
// Worker.ets
// 接收宿主线程传递至Worker线程的数据并访问

import { SendableObject } from '../pages/sendable';
import { worker, ThreadWorkerGlobalScope, MessageEvents, ErrorEvent } from '@kit.ArkTS';

const workerPort: ThreadWorkerGlobalScope = worker.workerPort;

workerPort.onmessage = (e: MessageEvents) => {
  let obj: SendableObject = e.data;
  console.info("sendable obj is: " + obj.value);
}

on⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

向宿主线程的Worker实例对象添加一个事件监听，该接口与addEventListener⁹⁺接口功能一致。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

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

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.
10200005	The called API is not supported in the worker thread.

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

workerInstance.on("alert", () => {
    console.info("alert listener callback");
})

// 使用on添加的事件监听可以多次执行
workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持
workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持

once⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

向宿主线程的Worker实例对象添加一个事件监听，该事件监听只执行一次，执行完后会自动删除。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

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

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.
10200005	The called API is not supported in the worker thread.

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

workerInstance.once("alert", () => {
  console.info("alert listener callback");
})

workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持

off⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

移除宿主线程的Worker实例对象中类型为type的事件监听，该接口与removeEventListener⁹⁺接口功能一致。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名	类型	必填	说明
type	string	是	需要删除的事件类型。事件类型通过on⁹⁺设置。
listener	WorkerEventListener	否	需要删除的特定监听器回调函数。如果未传入此参数，则会删除该类型的所有监听器。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.
10200005	The called API is not supported in the worker thread.

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

const handler1 = () => console.info("Handler 1");
const handler2 = () => console.info("Handler 2");

// 注册两个监听器
workerInstance.on("alert", handler1);
workerInstance.on("alert", handler2);

// 首次触发：两个监听器都会执行
workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持

// 删除 handler1 监听器
workerInstance.off("alert", handler1);

// 再次触发：只剩 handler2 会执行
workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持

// 删除"alert"类型所有监听器
workerInstance.off("alert");

registerGlobalCallObject¹¹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

registerGlobalCallObject(instanceName: string, globalCallObject: Object): void

在宿主线程的ThreadWorker实例上注册一个对象，该对象的方法可在Worker线程中调用。详情请参见callGlobalCallObjectMethod。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名	类型	必填	说明
instanceName	string	是	注册对象时使用的键，调用时通过该键值找到被注册的对象。
globalCallObject	Object	是	被注册的对象，ThreadWorker实例会持有被注册对象的强引用。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
class TestObj {
  private message : string = "this is a message from TestObj";
  public getMessage() : string {
    return this.message;
  }
  public getMessageWithInput(str : string) : string {
    return this.message + " with input: " + str;
  }
}
let registerObj = new TestObj();
// 在ThreadWorker实例上注册registerObj
workerInstance.registerGlobalCallObject("myObj", registerObj);
workerInstance.postMessage("start worker");

收起
自动换行
深色代码主题
复制
// worker.ets
import { worker, MessageEvents } from '@kit.ArkTS';

const workerPort = worker.workerPort;
workerPort.onmessage = (e: MessageEvents): void => {
  try {
    // 调用方法无入参
    let res : string = workerPort.callGlobalCallObjectMethod("myObj", "getMessage", 0) as string;
    console.info("worker:", res) // worker: this is a message from TestObj
  } catch (error) {
    // 异常处理
    console.error("worker: error code is " + error.code + " error message is " + error.message);
  }
  try {
    // 调用方法有入参
    let res : string = workerPort.callGlobalCallObjectMethod("myObj", "getMessageWithInput", 0, "hello there!") as string;
    console.info("worker:", res); // worker: this is a message from TestObj with input: hello there!
  } catch (error) {
    // 异常处理
    console.error("worker: error code is " + error.code + " error message is " + error.message);
  }
}

unregisterGlobalCallObject¹¹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

unregisterGlobalCallObject(instanceName?: string): void

取消在宿主线程ThreadWorker实例上注册的对象，该方法会释放ThreadWorker实例中与该键相匹配的对象的强引用。如果无匹配对象，该方法不会报错。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名	类型	必填	说明
instanceName	string	否	注册对象时使用的键。此参数不填时，会释放ThreadWorker实例中所有已注册的对象。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
class TestObj {
  private message : string = "this is a message from TestObj";
  public getMessage() : string {
    return this.message;
  }
  public getMessageWithInput(str : string) : string {
    return this.message + " with input: " + str;
  }
}
let registerObj = new TestObj();
workerInstance.registerGlobalCallObject("myObj", registerObj);
// 取消对象注册
workerInstance.unregisterGlobalCallObject("myObj");
// 取消ThreadWorker实例上的所有对象注册
workerInstance.postMessage("start worker");

terminate⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

terminate(): void

由宿主线程主动销毁Worker线程并停止Worker线程接收消息。

元服务API：从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.terminate();

addEventListener⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

向宿主线程的Worker实例对象添加一个事件监听，该接口与on⁹⁺接口功能一致。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

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

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.
10200005	The called API is not supported in the worker thread.

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

workerInstance.addEventListener("alert", () => {
  console.info("alert listener callback");
})

// 执行 alert 事件类型的回调
workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持

removeEventListener⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

移除宿主线程的Worker实例对象中类型为type的事件监听，该接口与off⁹⁺接口功能一致。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名	类型	必填	说明
type	string	是	需要删除的监听事件类型。事件类型通过addEventListener⁹⁺设置。
callback	WorkerEventListener	否	需要删除的特定监听器回调函数。如果未传入此参数，则会删除该类型的所有监听器。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

workerInstance.addEventListener("alert", () => {
  console.info("alert listener callback");
})

workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持

workerInstance.removeEventListener("alert");

dispatchEvent⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

dispatchEvent(event: Event): boolean

在宿主线程将事件对象分发到Worker线程的事件系统，该系统会自动触发该类型事件对应的所有监听器回调。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

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

返回值：

展开

类型	说明
boolean	分发的结果。true表示分发成功，false表示分发失败。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

workerInstance.addEventListener("alert", () => {
  console.info("alert listener callback");
})

let result: boolean = workerInstance.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持

console.info("dispatchEvent result is: ", result);

分发事件（dispatchEvent）可与监听接口（on、once、addEventListener）搭配使用，完整示例请参考分发事件与监听接口搭配使用示例。

removeAllListener⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

removeAllListener(): void

移除宿主线程中Worker实例对象的所有事件监听。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.addEventListener("alert", () => {
    console.info("alert listener callback");
})
workerInstance.removeAllListener();

WorkerEventTarget⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

用于管理Worker的监听事件。

addEventListener⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

向Worker线程的实例对象添加事件监听。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

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

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.
10200005	The called API is not supported in the worker thread.

示例：

收起
自动换行
深色代码主题
复制
// worker.ets
import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS';

const workerPort: ThreadWorkerGlobalScope = worker.workerPort;

workerPort.onmessage = (event: MessageEvents) => {
  workerPort.addEventListener("alert", () => {
    console.info("alert listener callback");
  })
};

removeEventListener⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

移除Worker线程实例对象中类型为type的事件监听。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名	类型	必填	说明
type	string	是	需要删除的监听事件类型。事件类型通过addEventListener⁹⁺设置。
callback	WorkerEventListener	否	需要删除的特定监听器回调函数。如果未传入此参数，则会删除该类型的所有监听器。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.

示例：

收起
自动换行
深色代码主题
复制
// worker.ets
import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS';

const workerPort: ThreadWorkerGlobalScope = worker.workerPort;

workerPort.onmessage = (event: MessageEvents) => {
  workerPort.addEventListener("alert", () => {
    console.info("alert listener callback");
  });

  workerPort.removeEventListener("alert");
};

dispatchEvent⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

dispatchEvent(event: Event): boolean

在Worker线程将事件对象分发到Worker线程的事件系统，并触发该类型事件的所有监听器回调。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

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

返回值：

展开

类型	说明
boolean	分发的结果。true表示分发成功，false表示分发失败。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.

示例：

收起
自动换行
深色代码主题
复制
// worker.ets
import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS';

const workerPort: ThreadWorkerGlobalScope = worker.workerPort;

workerPort.onmessage = (event: MessageEvents) => {
  workerPort.addEventListener("alert", () => {
    console.info("alert listener callback");
  });

  workerPort.dispatchEvent({type: "alert", timeStamp: 0}); // timeStamp暂未支持
};

分发事件（dispatchEvent）可与监听接口（addEventListener）搭配使用，完整示例请参考分发事件与监听接口搭配使用示例。

removeAllListener⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

removeAllListener(): void

移除Worker线程的实例对象所有的事件监听。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.

示例：

收起
自动换行
深色代码主题
复制
// worker.ets
import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS';

const workerPort: ThreadWorkerGlobalScope = worker.workerPort;

workerPort.onmessage = (event: MessageEvents) => {
  workerPort.addEventListener("alert", () => {
    console.info("alert listener callback");
  });

  workerPort.removeAllListener();
};

ThreadWorkerGlobalScope⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

Worker线程用于与宿主线程通信的类。ThreadWorkerGlobalScope类继承GlobalScope。

属性

系统能力： SystemCapability.Utils.Lang

展开

名称	类型	只读	可选	说明
onmessage⁹⁺	(this: ThreadWorkerGlobalScope, ev: MessageEvents) => void	否	是	回调函数。表示Worker线程收到来自其宿主线程通过postMessage或postMessageWithSharedSendable接口发送的消息时被调用的事件处理程序，处理程序在Worker线程中执行。其中this指调用者对象本身ThreadWorkerGlobalScope，ev类型为MessageEvents，表示收到的宿主线程发送的消息数据。默认值为undefined。元服务API：从API version 11开始，该属性支持在元服务中使用。
onmessageerror⁹⁺	(this: ThreadWorkerGlobalScope, ev: MessageEvents) => void	否	是	回调函数。表示当Worker线程的Worker对象接收到一条无法被反序列化的消息时被调用的事件处理程序，处理程序在Worker线程中执行。其中this指调用者对象本身ThreadWorkerGlobalScope，ev类型为MessageEvents，表示收到的消息数据。默认值为undefined。元服务API：从API version 11开始，该属性支持在元服务中使用。

名称

类型

只读

可选

说明

onmessage⁹⁺

(this: ThreadWorkerGlobalScope, ev: MessageEvents) => void

否

是

回调函数。表示Worker线程收到来自其宿主线程通过postMessage或postMessageWithSharedSendable接口发送的消息时被调用的事件处理程序，处理程序在Worker线程中执行。其中this指调用者对象本身ThreadWorkerGlobalScope，ev类型为MessageEvents，表示收到的宿主线程发送的消息数据。默认值为undefined。

元服务API：从API version 11开始，该属性支持在元服务中使用。

onmessageerror⁹⁺

(this: ThreadWorkerGlobalScope, ev: MessageEvents) => void

否

是

回调函数。表示当Worker线程的Worker对象接收到一条无法被反序列化的消息时被调用的事件处理程序，处理程序在Worker线程中执行。其中this指调用者对象本身ThreadWorkerGlobalScope，ev类型为MessageEvents，表示收到的消息数据。默认值为undefined。

元服务API：从API version 11开始，该属性支持在元服务中使用。

postMessage⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

postMessage(messageObject: Object, transfer: ArrayBuffer[]): void;

Worker线程通过转移对象所有权的方式向宿主线程发送消息。

元服务API：从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名	类型	必填	说明
messageObject	Object	是	发送至宿主线程的数据，该数据对象必须是可序列化对象，序列化支持类型见序列化支持类型。
transfer	ArrayBuffer[]	是	表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用，数组不可传入null。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.
10200006	An exception occurred during serialization.

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker, MessageEvents } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.postMessage("hello world");
workerInstance.onmessage = (e: MessageEvents): void => {
  console.info("receive data from worker.ets");
}

收起
自动换行
深色代码主题
复制
// worker.ets
import { worker, MessageEvents } from '@kit.ArkTS';

const workerPort = worker.workerPort;
workerPort.onmessage = (e: MessageEvents): void => {
  let buffer = new ArrayBuffer(8);
  workerPort.postMessage(buffer, [buffer]);
}

postMessage⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

Worker线程通过转移对象所有权或拷贝数据的方式向宿主线程发送消息。在传递Sendable对象时，使用拷贝数据的方式进行传递。

元服务API：从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名

类型

必填

说明

messageObject

Object

是

发送至宿主线程的数据，该数据对象必须是可序列化对象，序列化支持类型见序列化支持类型。

options

PostMessageOptions

否

当填入该参数时，其作用与传入ArrayBuffer[]相同，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将变为不可用，仅在宿主线程中可用。

若不填入该参数，默认设置为 undefined，通过拷贝数据的方式传输信息到宿主线程。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.
10200006	An exception occurred during serialization.

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker, MessageEvents } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.postMessage("hello world");
workerInstance.onmessage = (e: MessageEvents): void => {
    console.info("receive data from worker.ets");
}

收起
自动换行
深色代码主题
复制
// worker.ets
import { worker, MessageEvents } from '@kit.ArkTS';

const workerPort = worker.workerPort;
workerPort.onmessage = (e: MessageEvents): void => {
    workerPort.postMessage("receive data from main thread");
}

postMessageWithSharedSendable¹²⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

postMessageWithSharedSendable(message: Object, transfer?: ArrayBuffer[]): void

Worker线程向宿主线程发送消息，消息中的Sendable对象通过引用传递，非Sendable对象通过拷贝数据的方式传递。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名	类型	必填	说明
message	Object	是	发送至宿主线程的数据，该数据对象必须是可序列化或可共享，序列化支持类型见序列化支持类型，共享支持类型见Sendable支持的数据类型。
transfer	ArrayBuffer[]	否	表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用，数组不可传入null。默认值为空数组。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.
10200006	An exception occurred during serialization.

示例：

收起
自动换行
深色代码主题
复制
// worker文件路径为：entry/src/main/ets/workers/Worker.ets
// Worker.ets
// 新建SendableObject实例并通过Worker线程传递至宿主线程

import { SendableObject } from '../pages/sendable';
import { worker, ThreadWorkerGlobalScope, MessageEvents, ErrorEvent } from '@kit.ArkTS';

const workerPort: ThreadWorkerGlobalScope = worker.workerPort;
workerPort.onmessage = (e: MessageEvents) => {
  let object: SendableObject = new SendableObject();
  workerPort.postMessageWithSharedSendable(object);
}

收起
自动换行
深色代码主题
复制
// sendable.ets
// 定义SendableObject

@Sendable
export class SendableObject {
  a:number = 45;
}

收起
自动换行
深色代码主题
复制
// Index.ets
// 接收Worker线程传递至宿主线程的数据并访问其属性

import { worker, MessageEvents } from '@kit.ArkTS';
import { SendableObject } from './sendable';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/Worker.ets");
workerInstance.postMessage(1);
workerInstance.onmessage = (e: MessageEvents) => {
  let obj: SendableObject = e.data;
  console.info("sendable index obj is: " + obj.a);
}

callGlobalCallObjectMethod¹¹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

callGlobalCallObjectMethod(instanceName: string, methodName: string, timeout: number, ...args: Object[]): Object

Worker线程调用宿主线程上注册的对象的指定方法，此调用对Worker线程同步，对宿主线程异步，返回值通过数据拷贝传递。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名	类型	必填	说明
instanceName	string	是	注册对象时使用的键，用于在宿主线程中查找对象。
methodName	string	是	在已注册对象上调用的方法名。该方法不能使用async修饰，也不能基于底层异步机制返回结果，否则会抛出异常。
timeout	number	是	表示从Worker线程发起调用开始到在主线程中执行目标方法的最大等待时间，单位为ms，取整数，取值范围为[1-5000]ms。超出范围的，则表示本次调用等待时间为5000ms。 API version 21 之前，在debug模式下受此参数设置的最大等待时间限制。从API version 21 开始，在debug模式下不受此参数设置的最大等待时间限制，可一直等待。
args	Object[]	否	注册对象上所调用方法的参数数组。

返回值：

展开

类型	说明
Object	返回值为调用方法在宿主线程的返回值，该返回值必须是可序列化的，具体可见序列化支持类型。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.
10200006	An exception occurred during serialization.
10200019	The globalCallObject is not registered.
10200020	The method to be called is not callable or is an async method or a generator.
10200021	The global call exceeds the timeout.

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
class TestObj {
  private message : string = "this is a message from TestObj";
  public getMessage() : string {
    return this.message;
  }
  public getMessageWithInput(str : string) : string {
    return this.message + " with input: " + str;
  }
}
let registerObj = new TestObj();
// 在ThreadWorker实例上注册registerObj
workerInstance.registerGlobalCallObject("myObj", registerObj);
workerInstance.postMessage("start worker");

收起
自动换行
深色代码主题
复制
// worker.ets
import { worker, MessageEvents } from '@kit.ArkTS';

const workerPort = worker.workerPort;
workerPort.onmessage = (e: MessageEvents): void => {
  try {
    // 调用方法无入参
    let res : string = workerPort.callGlobalCallObjectMethod("myObj", "getMessage", 0) as string;
    console.info("worker:", res); // worker: this is a message from TestObj
  } catch (error) {
    // 异常处理
    console.error("worker: error code is " + error.code + " error message is " + error.message);
  }
  try {
    // 调用方法有入参
    let res : string = workerPort.callGlobalCallObjectMethod("myObj", "getMessageWithInput", 0, "hello there!") as string;
    console.info("worker:", res); // worker: this is a message from TestObj with input: hello there!
  } catch (error) {
    // 异常处理
    console.error("worker: error code is " + error.code + " error message is " + error.message);
  }
}

close⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

close(): void

销毁Worker线程，终止Worker接收消息。

元服务API：从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");
workerInstance.postMessage("hello world");

收起
自动换行
深色代码主题
复制
// worker.ets
import { worker, MessageEvents } from '@kit.ArkTS';

const workerPort = worker.workerPort;
workerPort.onmessage = (e: MessageEvents): void => {
    workerPort.close();
}

postMessageAtFront

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

postMessageAtFront?(message: Object, priority: Priority, transfer?: ArrayBuffer[]): void

Worker线程向宿主线程发送插队消息，消息中的Sendable对象通过引用传递，非Sendable对象通过拷贝数据的方式传递。

说明

如果是Worker线程向宿主线程发送插队的消息，消息能够插队并且按优先级进行发送。
如果是Worker线程之间发送插队的消息，消息只能插队，没有优先级。
postMessage和postMessageWithSharedSendable接口向宿主线程发送消息，默认是HIGH优先级，无插队效果。

起始版本：26.0.0

模型约束：此接口仅可在Stage模型下使用。

元服务API：从API版本26.0.0开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名	类型	必填	说明
message	Object	是	发送至宿主线程的数据，该数据对象必须是可序列化或可共享，序列化支持类型见序列化支持类型，共享支持类型见Sendable支持的数据类型。
priority	Priority	是	消息发送的优先级。
transfer	ArrayBuffer[]	否	表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用，数组不可传入null。默认值为空数组。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.
10200006	An exception occurred during serialization.

示例：

收起
自动换行
深色代码主题
复制
// worker文件路径为：entry/src/main/ets/workers/Worker.ets
// Worker.ets

import { MessageEvents, ThreadWorkerGlobalScope, worker, Priority } from '@kit.ArkTS';

const workerPort: ThreadWorkerGlobalScope = worker.workerPort;
workerPort.onmessage = (e: MessageEvents) => {
  workerPort.postMessage("1");
  workerPort.postMessage("2");
  // 方式1：使用可选链操作符（推荐，最简洁）
  workerPort.postMessageAtFront?.("3-idle", Priority.IDLE);
  workerPort.postMessageAtFront?.("4-immediate", Priority.IMMEDIATE);

  // 方式2：使用非空断言，直接调用（需要确定它一定存在）
  workerPort.postMessageAtFront!("5-low", Priority.LOW);

  // 方式3：判断方法存在后再使用
  if (workerPort.postMessageAtFront) {
    workerPort.postMessageAtFront("6-high", Priority.HIGH);
  } else {
    workerPort.postMessageWithSharedSendable("6-high");
  }
}

收起
自动换行
深色代码主题
复制
// Index.ets
// 接收Worker线程传递至宿主线程的数据

import { worker, MessageEvents } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("entry/ets/workers/Worker.ets");
workerInstance.postMessage("start");
workerInstance.onmessage = (e: MessageEvents) => {
  // 模拟耗时操作
  let start = new Date().getTime();
  while (new Date().getTime() - start < 1000) {
    continue;
  }
  let res: string = e.data as string;
  // 执行效果：
  // result is: 1
  // result is: 4-immediate
  // result is: 6-high
  // result is: 2
  // result is: 5-low
  // result is: 3-idle
  console.info("result is: " + res);
}

如果传递的参数是对象字面量的话，需要显式标注对象字面量的类型。

收起
自动换行
深色代码主题
复制
import { worker, ThreadWorkerGlobalScope, MessageEvents, ErrorEvent, Priority } from '@kit.ArkTS';

class ClassA {
  public obj: string = ""
}

const workerPort: ThreadWorkerGlobalScope = worker.workerPort;
workerPort.onmessage = (e: MessageEvents) => {
  // 使用可选链操作符调用接口，传递字面量对象时会编译报错，需要显式标注对象字面量的类型。
  // workerPort.postMessageAtFront?.({obj: "obj"}, Priority.HIGH);

  let classAInstance: ClassA = { obj: "obj" };
  workerPort.postMessageAtFront?.(classAInstance, Priority.HIGH);

  // 使用非空断言，直接调用。可以直接传递对象字面量。
  workerPort.postMessageAtFront!({ obj: "obj" }, Priority.HIGH);
  // 判断方法存在后再使用。可以直接传递对象字面量。
  if (workerPort.postMessageAtFront) {
    workerPort.postMessageAtFront({ obj: "obj" }, Priority.HIGH);
  } else {
    workerPort.postMessageWithSharedSendable({ obj: "obj" });
  }
}

WorkerEventListener⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

事件监听类。

(event: Event)⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

指定要调用的回调函数。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

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

返回值：

展开

类型	说明
void \| Promise<void>	无返回值或者以Promise形式返回。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

展开

错误码ID	错误信息
10200004	The Worker instance is not running.
10200005	The called API is not supported in the worker thread.

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker, Event } from "@kit.ArkTS"

const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

workerInstance.addEventListener("alert", (event: Event) => {
  console.info("event type is: ", JSON.stringify(event.type));
});

const eventToDispatch : Event = { type: "alert", timeStamp: 0 }; // timeStamp暂未支持
workerInstance.dispatchEvent(eventToDispatch);

GlobalScope⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

Worker线程自身的运行环境，GlobalScope类继承WorkerEventTarget。

元服务API：从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

展开

名称	类型	只读	可选	说明
name	string	是	否	Worker的名字，new Worker时指定。
self	GlobalScope & typeof globalThis	是	否	GlobalScope本身。
onerror	(ev: ErrorEvent) => void	否	是	Worker在执行过程中发生异常被调用的回调函数，在Worker线程中执行，ev表示收到的异常数据。默认值为undefined。

MessageEvents⁹⁺

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

消息类，持有Worker线程间传递的数据，MessageEvents类继承Event。

元服务API：从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

展开

名称	类型	只读	可选	说明
data	any	是	否	线程间传递的数据。

MessageType

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

type MessageType = 'message' | 'messageerror'

表示消息类型。预留数据类型，暂未实现。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

展开

类型	说明
'message'	表示消息类型为message，值固定为'message'字符串。
'messageerror'	表示消息类型为messageerror，值固定为'messageerror'字符串。

ErrorCallback¹⁸⁺

Phone18+PC/2in118+Tablet18+TV19+Wearable18+

type ErrorCallback = (err: ErrorEvent) => void

表示异常回调类型。

元服务API：从API version 18开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名	类型	必填	说明
err	ErrorEvent	是	错误事件类，表示Worker执行过程中出现的异常信息。

Worker^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

说明

从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker替代。

属性

系统能力： SystemCapability.Utils.Lang

展开

名称	类型	只读	可选	说明
onexit^(deprecated)	(code: number) => void	否	是	回调函数。表示Worker销毁时被调用的事件处理程序，处理程序在宿主线程中执行。其中回调函数中code类型为number，异常退出为1，正常退出为0。默认值为undefined。说明：从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.onexit替代。
onerror^(deprecated)	(err: ErrorEvent) => void	否	是	回调函数。表示Worker在执行过程中发生异常被调用的事件处理程序，处理程序在宿主线程中执行。其中回调函数中err类型为ErrorEvent，表示收到的异常数据。默认值为undefined。说明：从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.onerror替代。
onmessage^(deprecated)	(event: MessageEvent) => void	否	是	回调函数。表示宿主线程接收到来自其创建的Worker通过workerPort.postMessage接口发送的消息时被调用的事件处理程序，处理程序在宿主线程中执行。其中回调函数中event类型为MessageEvent，表示收到的Worker消息数据。默认值为undefined。说明：从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.onmessage替代。
onmessageerror^(deprecated)	(event: MessageEvent) => void	否	是	回调函数。表示当Worker对象接收到一条无法被序列化的消息时被调用的事件处理程序，处理程序在宿主线程中执行。其中回调函数中event类型为MessageEvent，表示收到的Worker消息数据。默认值为undefined。说明：从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.onmessageerror替代。

constructor^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

constructor(scriptURL: string, options?: WorkerOptions)

Worker构造函数。

说明

从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.constructor⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名	类型	必填	说明
scriptURL	string	是	Worker线程文件的路径，详细参考文件路径注意事项。
options	WorkerOptions	否	Worker构造的选项。

示例：

此处以在Stage模型的entry模块Index.ets文件中加载Worker线程文件为例，使用Library加载Worker线程文件的场景参考文件路径注意事项。

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

// worker文件所在路径："entry/src/main/ets/workers/worker.ets"
const workerInstance = new worker.Worker('entry/ets/workers/worker.ets', {name: "WorkerThread"});

postMessage^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

postMessage(message: Object, transfer: ArrayBuffer[]): void

宿主线程通过转移对象所有权的方式向Worker线程发送消息。

说明

从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.postMessage⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名	类型	必填	说明
message	Object	是	发送至Worker的数据对象必须是可序列化对象，序列化支持类型见序列化支持类型。
transfer	ArrayBuffer[]	是	表示可转移的ArrayBuffer实例对象数组，所有权会转移到Worker线程，仅在该线程中可用。数组不可传入null。

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.Worker("entry/ets/workers/worker.ets");

let buffer = new ArrayBuffer(8);
workerInstance.postMessage(buffer, [buffer]);

postMessage^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

宿主线程通过转移对象所有权或者拷贝数据的方式向Worker线程发送消息。

说明

从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.postMessage⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名

类型

必填

说明

message

Object

是

发送至Worker的数据，该数据对象必须是可序列化对象，序列化支持类型见序列化支持类型。

options

PostMessageOptions

否

当填入该参数时，与传入ArrayBuffer[]的作用一致，该数组中对象的所有权会被转移到Worker线程，在宿主线程中将变为不可用，仅在Worker线程中可用。

若不填入该参数，默认设置为undefined，通过拷贝数据的方式传输信息到Worker线程。

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.Worker("entry/ets/workers/worker.ets");

workerInstance.postMessage("hello world");

let buffer = new ArrayBuffer(8);
workerInstance.postMessage(buffer, [buffer]);

on^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

向Worker添加一个事件监听，该接口与addEventListener^(deprecated)接口功能一致。

说明

从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.on⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

展开

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

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.Worker("entry/ets/workers/worker.ets");
workerInstance.on("alert", () => {
    console.info("alert listener callback");
})

once^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

向Worker添加一个事件监听，该事件监听只执行一次，执行完后会自动删除。

说明

从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.once⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

展开

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

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.Worker("entry/ets/workers/worker.ets");
workerInstance.once("alert", () => {
    console.info("alert listener callback");
})

off^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

移除类型为type的事件监听，该接口与removeEventListener^(deprecated)接口功能一致。

说明

从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.off⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名	类型	必填	说明
type	string	是	需要删除的事件类型。事件类型通过on^(deprecated)设置。
listener	EventListener	否	需要删除的特定监听器回调函数。如果未传入此参数，则会删除该类型的所有监听器。

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.Worker("entry/ets/workers/worker.ets");
// 使用on接口、once接口或addEventListener接口创建“alert”事件，使用off接口删除事件。
workerInstance.off("alert");

terminate^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

terminate(): void

销毁Worker线程，终止Worker接收消息。

说明

从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorker.terminate⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.Worker("entry/ets/workers/worker.ets");
workerInstance.terminate();

EventTarget^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

说明

从API version 7开始支持，从API version 9开始废弃，建议使用WorkerEventTarget⁹⁺替代。

addEventListener^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

向Worker添加一个事件监听，该接口与on^(deprecated)接口功能一致。

说明

从API version 7开始支持，从API version 9开始废弃，建议使用addEventListener⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

展开

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

示例：

收起
自动换行
深色代码主题
复制
// worker.ets
import { DedicatedWorkerGlobalScope, ErrorEvent, MessageEvents, worker } from '@kit.ArkTS';

const workerPort: DedicatedWorkerGlobalScope = worker.parentPort;

workerPort.addEventListener("alert", () => {
  console.info("alert listener callback");
})

removeEventListener^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

移除Worker的事件监听，该接口与off^(deprecated)接口功能一致。

说明

从API version 7开始支持，从API version 9开始废弃，建议使用removeEventListener⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名	类型	必填	说明
type	string	是	需要移除的事件类型。事件类型通过addEventListener^(deprecated)设置。
callback	EventListener	否	需要删除的特定监听器回调函数。如果未传入此参数，则会删除该类型的所有监听器。

示例：

收起
自动换行
深色代码主题
复制
// worker.ets
import { DedicatedWorkerGlobalScope, ErrorEvent, MessageEvents, worker } from '@kit.ArkTS';

const workerPort: DedicatedWorkerGlobalScope = worker.parentPort;

workerPort.addEventListener("alert", () => {
  console.info("alert listener callback");
})

workerPort.removeEventListener('alert');

dispatchEvent^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

dispatchEvent(event: Event): boolean

分发Worker实例上已注册的事件。

说明

从API version 7开始支持，从API version 9开始废弃，建议使用dispatchEvent⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

展开

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

返回值：

展开

类型	说明
boolean	分发的结果。true表示分发成功，false表示分发失败。

示例：

收起
自动换行
深色代码主题
复制
// worker.ets
import { DedicatedWorkerGlobalScope, ErrorEvent, MessageEvents, worker } from '@kit.ArkTS';

const workerPort: DedicatedWorkerGlobalScope = worker.parentPort;

workerPort.addEventListener("alert_add", ()=>{
  console.info("alert listener callback");
})

workerPort.dispatchEvent({type: 'alert_add', timeStamp: 0}); // timeStamp暂未支持

分发事件（dispatchEvent）可与监听接口（addEventListener）搭配使用，示例如下：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.Worker("entry/ets/workers/worker.ets");
workerInstance.postMessage("hello world");
workerInstance.onmessage = (): void => {
    console.info("receive data from worker.ets");
}

收起
自动换行
深色代码主题
复制
// worker.ets
import { DedicatedWorkerGlobalScope, ErrorEvent, MessageEvents, worker } from '@kit.ArkTS';

const workerPort: DedicatedWorkerGlobalScope = worker.parentPort;

workerPort.addEventListener("alert", ()=>{
  console.info("alert listener callback");
})

workerPort.onmessage = (event: MessageEvents) => {
  workerPort.dispatchEvent({type:"alert", timeStamp:0}); // timeStamp暂未支持
}

removeAllListener^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

removeAllListener(): void

移除Worker所有的事件监听。

说明

从API version 7开始支持，从API version 9开始废弃，建议使用removeAllListener⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

示例：

收起
自动换行
深色代码主题
复制
// worker.ets
import { DedicatedWorkerGlobalScope, ErrorEvent, MessageEvents, worker } from '@kit.ArkTS';

const workerPort: DedicatedWorkerGlobalScope = worker.parentPort;

workerPort.addEventListener("alert_add", ()=>{
  console.info("alert listener callback");
})

workerPort.removeAllListener();

DedicatedWorkerGlobalScope^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

Worker线程用于与宿主线程通信的类。DedicatedWorkerGlobalScope类继承WorkerGlobalScope。

说明

从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorkerGlobalScope⁹⁺替代。

属性

系统能力： SystemCapability.Utils.Lang

展开

名称

类型

只读

可选

说明

onmessage^(deprecated)

(this: DedicatedWorkerGlobalScope, ev: MessageEvent) => void

否

是

回调函数，表示Worker线程收到来自其宿主线程通过postMessage接口发送的消息时被调用的事件处理程序，处理程序在Worker线程中执行。其中this指调用者对象本身DedicatedWorkerGlobalScope，ev类型为MessageEvent，表示收到的Worker消息数据。默认值为undefined。

说明：从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorkerGlobalScope.onmessage替代。

onmessageerror^(deprecated)

(this: DedicatedWorkerGlobalScope, ev: MessageEvent) => void

否

是

回调函数，表示当Worker对象接收到一条无法被反序列化的消息时被调用的事件处理程序，处理程序在Worker线程中执行。其中this指调用者对象本身DedicatedWorkerGlobalScope，ev类型为MessageEvent，表示收到的Worker消息数据。默认值为undefined。

说明：从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorkerGlobalScope.onmessageerror替代。

postMessage^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

postMessage(messageObject: Object, transfer: Transferable[]): void

Worker线程通过转移对象所有权的方式向宿主线程发送消息。

说明

此接口暂不支持使用，从API version 9开始废弃，建议使用ThreadWorkerGlobalScope⁹⁺.postMessage⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名	类型	必填	说明
messageObject	Object	是	发送至宿主线程的数据，该数据对象必须是可序列化对象，序列化支持类型见序列化支持类型。
transfer	Transferable[]	是	暂不支持该参数类型。

postMessage^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

postMessage(messageObject: Object, transfer: ArrayBuffer[]): void

Worker线程通过转移对象所有权的方式向宿主线程发送消息。

说明

postMessage接口从API version 9开始支持，从API version 9开始废弃，建议使用ThreadWorkerGlobalScope⁹⁺.postMessage⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名	类型	必填	说明
messageObject	Object	是	发送至宿主线程的数据，该数据对象必须是可序列化对象，序列化支持类型见序列化支持类型。
transfer	ArrayBuffer[]	是	表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用，数组不可传入null。

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.Worker("entry/ets/workers/worker.ets");
workerInstance.postMessage("hello world");
workerInstance.onmessage = (e: MessageEvents): void => {
    // let data = e.data;
    console.info("receive data from worker.ets");
}

收起
自动换行
深色代码主题
复制
// worker.ets
import { DedicatedWorkerGlobalScope, worker } from '@kit.ArkTS';

const workerPort: DedicatedWorkerGlobalScope = worker.parentPort;

workerPort.onmessage = (): void => {
    // let data = e.data;
    let buffer = new ArrayBuffer(5)
    workerPort.postMessage(buffer, [buffer]);
}

postMessage^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

Worker线程通过转移对象所有权或者拷贝数据的方式向宿主线程发送消息。

说明

从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorkerGlobalScope⁹⁺.postMessage⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

参数：

展开

参数名

类型

必填

说明

messageObject

Object

是

发送至宿主线程的数据，该数据对象必须是可序列化对象，序列化支持类型见序列化支持类型。

options

PostMessageOptions

否

当填入该参数时，与传入ArrayBuffer[]的作用一致，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用。

若不填入该参数，默认设置为 undefined，通过拷贝数据的方式传输信息到宿主线程。

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.Worker("entry/ets/workers/worker.ets");
workerInstance.postMessage("hello world");
workerInstance.onmessage = (): void => {
    console.info("receive data from worker.ets");
}

收起
自动换行
深色代码主题
复制
// worker.ets
import { ErrorEvent, MessageEvents, worker } from '@kit.ArkTS';

const parentPort = worker.parentPort;
parentPort.onmessage = (e: MessageEvents) => {
  parentPort.postMessage("receive data from main thread");
}

close^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

close(): void

销毁Worker线程，终止Worker接收消息。

说明

从API version 7开始支持，从API version 9开始废弃，建议使用ThreadWorkerGlobalScope⁹⁺.close⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.Worker("entry/ets/workers/worker.ets");
workerInstance.postMessage("hello world");

收起
自动换行
深色代码主题
复制
// worker.ets
import { worker } from '@kit.ArkTS';

const parentPort = worker.parentPort;
parentPort.onmessage = (): void => {
    parentPort.close()
}

PostMessageOptions

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

明确数据传递过程中需要转移所有权的对象，这些对象必须是ArrayBuffer，在发送方的上下文中将变为不可用，仅在接收方可用。

元服务API：从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

展开

名称	类型	只读	可选	说明
transfer	Object[]	否	是	ArrayBuffer数组，用于传递所有权。该数组中不可传入null。默认值为undefined。

Event

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

事件类。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

展开

名称	类型	只读	可选	说明
type	string	是	否	指定事件的类型。
timeStamp	number	是	否	事件创建时的时间戳，单位为ms，目前不支持。

EventListener^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

事件监听类用于处理事件。

说明

从API version 7开始支持，从API version 9开始废弃，建议使用WorkerEventListener⁹⁺替代。

(evt: Event)^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

说明

从API version 7开始支持，从API version 9开始废弃，建议使用(event: Event)替代。

系统能力： SystemCapability.Utils.Lang

参数：

展开

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

返回值：

展开

类型	说明
void \| Promise<void>	无返回值或者以Promise形式返回。

示例：

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker } from '@kit.ArkTS';

const workerInstance = new worker.Worker("entry/ets/workers/worker.ets");
workerInstance.addEventListener("alert", ()=>{
    console.info("alert listener callback");
})

ErrorEvent

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

元服务API：从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

展开

名称	类型	只读	可选	说明
message	string	是	否	异常发生的错误信息。
filename	string	是	否	出现异常所在的文件。
lineno	number	是	否	异常所在的行数。
colno	number	是	否	异常所在的列数。
error	Object	是	否	异常对象。

MessageEvent<T>

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

消息类，持有Worker线程间传递的数据，MessageEvent类继承Event。

元服务API：从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

展开

名称	类型	只读	可选	说明
data	T	是	否	线程间传递的数据。

WorkerGlobalScope^(deprecated)

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

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

说明

从API version 7开始支持，从API version 9开始废弃，建议使用GlobalScope⁹⁺替代。

系统能力： SystemCapability.Utils.Lang

展开

名称	类型	只读	可选	说明
name	string	是	否	Worker的名字，new Worker时指定。
self	WorkerGlobalScope & typeof globalThis	是	否	WorkerGlobalScope本身。
onerror	(ev: ErrorEvent) => void	否	是	Worker在执行过程中发生异常被调用的回调函数，在Worker线程中执行，ev表示收到的异常数据，默认值为undefined。

Priority

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

表示发送消息时的优先级。

起始版本：26.0.0

模型约束：此接口仅可在Stage模型下使用。

元服务API：从API版本26.0.0开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

展开

名称	值	说明
IMMEDIATE	1	立即执行优先级。表示消息优先于HIGH优先级发送。
HIGH	2	高优先级。表示消息优先于LOW优先级发送。
LOW	3	低优先级。表示消息优先于IDLE优先级发送。
IDLE	4	后台优先级。表示在没有其他优先级消息的情况下，才发送该消息。

其他说明

序列化支持类型

序列化支持类型包括：除Symbol之外的基础类型、Date、String、RegExp、Array、Map、Set、Object（仅限简单对象，比如通过"{}"或者"new Object"创建，普通对象仅支持传递属性，不支持传递其原型及方法）、ArrayBuffer、TypedArray。

特例：传递通过自定义class创建出来的object时，不会发生序列化错误，但是自定义class的属性（如Function）无法通过序列化传递。

说明

以API version 9的FA工程为例。

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker, MessageEvents } from '@kit.ArkTS';

const workerInstance = new worker.ThreadWorker("workers/worker.ets");
workerInstance.postMessage("message from main thread to worker");
workerInstance.onmessage = (d: MessageEvents): void => {
  // 当Worker线程传递myModel时，data即为myModel。data没有init的方法
  let data: Record<string, Object> = d.data as Record<string, Object>;
  console.info('name:', data.name);// name: default name
  console.info('init:', data.init === undefined);// init: true
}

收起
自动换行
深色代码主题
复制
// worker.ets
import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS';

const workerPort = worker.workerPort;
class MyModel {
    name = "default name";
    init() {
        this.name = "MyModel";
    }
}
workerPort.onmessage = (d: MessageEvents): void => {
  console.info("worker.ets onmessage");
  let data: string = d.data;
  let func1 = () => {
    console.info("post message is function");
  }
  // workerPort.postMessage(func1); 传递func1发生序列化错误
  let myModel = new MyModel();
  workerPort.postMessage(myModel);     // 传递myModel不会发生序列化错误，myModel中的函数会丢失
}
workerPort.onmessageerror = () => {
    console.error("worker.ets onmessageerror");
}
workerPort.onerror = (err: ErrorEvent) => {
    console.error("worker.ets onerror" + err.message);
}

内存模型

Worker基于Actor并发模型实现。在Worker的交互流程中，宿主线程可以创建多个Worker子线程，各个Worker线程间运行环境相互隔离，并通过序列化、引用传递或转移所有权的方式传递对象，等到Worker线程完成计算任务，再把结果返回给宿主线程。

Actor并发模型的交互原理：各个Actor并发地处理宿主线程任务，每个Actor内部都有一个消息队列和单线程执行模块。消息队列负责接收宿主线程及其他Actor的请求，而单线程执行模块则负责串行地处理这些请求、向其他Actor发送请求以及创建新的Actor。由于Actor采用的是异步方式，各个Actor之间相互隔离且没有数据竞争，因此Actor可以高并发运行。

完整示例

说明

API version 8及之前的版本仅支持FA模型，如需使用，注意更换构造Worker的接口和创建Worker线程中与宿主线程通信的对象的两个方法。

FA模型

此处以API version 9的工程为例。

收起
自动换行
深色代码主题
复制
// main thread(同级目录为例)
import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS';

// 宿主线程中创建Worker对象
const workerInstance = new worker.ThreadWorker("workers/worker.ets");

// 宿主线程向worker线程传递信息
const buffer = new ArrayBuffer(8);
workerInstance.postMessage(buffer, [buffer]);

// 宿主线程接收worker线程信息
workerInstance.onmessage = (e: MessageEvents): void => {
    // data：worker线程发送的信息
    let data: Int8Array = e.data;
    console.info("main thread onmessage");

    // 销毁Worker对象
    workerInstance.terminate();
}

// 在调用terminate后，执行回调onexit
workerInstance.onexit = (code) => {
    console.info("main thread terminate");
}

workerInstance.onerror = (err: ErrorEvent) => {
    console.error("main error message " + err.message);
}

收起
自动换行
深色代码主题
复制
// worker.ets
import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS';

// 创建worker线程中与宿主线程通信的对象
const workerPort = worker.workerPort;

// worker线程接收宿主线程信息
workerPort.onmessage = (e: MessageEvents): void => {
    // data：宿主线程发送的信息
    let data: ArrayBuffer = e.data;
    const view = new Int8Array(data).fill(3);
    console.info("worker.ets onmessage");

    // worker线程向宿主线程发送信息
    workerPort.postMessage(view);
}

// worker线程发生error的回调
workerPort.onerror = (err: ErrorEvent) => {
    console.error("worker.ets onerror");
}

在模块级entry/build-profile.json5配置文件中添加如下配置:

收起
自动换行
深色代码主题
复制
  "buildOption": {
    "sourceOption": {
      "workers": [
        "./src/main/ets/entryability/workers/worker.ets"
      ]
    }
  }

Stage模型

此处以API version 18的工程为例。

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS';

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';
  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            // 宿主线程中创建Worker对象
            const workerInstance = new worker.ThreadWorker("entry/ets/workers/Worker.ets");
            // 宿主线程向worker线程传递信息
            const buffer = new ArrayBuffer(8);
            workerInstance.postMessage(buffer);
            // 宿主线程接收worker线程信息
            workerInstance.onmessage = (e: MessageEvents): void => {
              // data：worker线程发送的信息
              let data: Int8Array = e.data;
              console.info("main thread data is  " + data);
              // 销毁Worker对象
              workerInstance.terminate();
            }
            // 在调用terminate后，执行onexit
            workerInstance.onexit = (code) => {
              console.info("main thread terminate");
            }

            workerInstance.onAllErrors = (err: ErrorEvent) => {
              console.error("main error message " + err.message);
            }
          })
      }
      .width('100%')
      .height('100%')
    }
  }
}

收起
自动换行
深色代码主题
复制
// Worker.ets
import { worker, MessageEvents, ErrorEvent } from '@kit.ArkTS';

// 创建worker线程中与宿主线程通信的对象
const workerPort = worker.workerPort;

// worker线程接收宿主线程信息
workerPort.onmessage = (e: MessageEvents): void => {
  // data：宿主线程发送的信息
  let data: ArrayBuffer = e.data;
  // 往收到的buffer里写入数据
  const view = new Int8Array(data).fill(3);
  // worker线程向宿主线程发送信息
  workerPort.postMessage(view);
}

// worker线程发生error的回调
workerPort.onerror = (err: ErrorEvent) => {
  console.error("worker.ets onerror" + err.message);
}

在模块级entry/build-profile.json5配置文件中添加如下配置:

收起
自动换行
深色代码主题
复制
  "buildOption": {
    "sourceOption": {
      "workers": [
        "./src/main/ets/workers/Worker.ets"
      ]
    }
  }

分发事件与监听接口搭配使用示例

收起
自动换行
深色代码主题
复制
// Index.ets
import { worker, MessageEvents } from '@kit.ArkTS';

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  build() {
    RelativeContainer() {
      Text(this.message)
        .id('HelloWorld')
        .fontSize($r('app.float.page_text_font_size'))
        .fontWeight(FontWeight.Bold)
        .alignRules({
          center: { anchor: '__container__', align: VerticalAlign.Center },
          middle: { anchor: '__container__', align: HorizontalAlign.Center }
        })
        .onClick(() => {
          const workerInstance = new worker.ThreadWorker("entry/ets/workers/worker.ets");

          // 用法一:
          workerInstance.on("alert_on", () => {
            console.info("alert listener callback: alert_on");
          })
          workerInstance.once("alert_once", () => {
            console.info("alert listener callback: alert_once");
          })
          workerInstance.addEventListener("alert_add", () => {
            console.info("alert listener callback: alert_add");
          })

          // once接口创建的事件执行一次便会删除。
          workerInstance.dispatchEvent({type: "alert_once", timeStamp: 0}); // timeStamp暂未支持
          // on接口创建的事件可以一直被分发，不能主动删除。
          workerInstance.dispatchEvent({type: "alert_on", timeStamp: 0}); // timeStamp暂未支持
          workerInstance.dispatchEvent({type: "alert_on", timeStamp: 0}); // timeStamp暂未支持
          // addEventListener接口创建的事件可以一直被分发，不能主动删除。
          workerInstance.dispatchEvent({type: "alert_add", timeStamp: 0}); // timeStamp暂未支持
          workerInstance.dispatchEvent({type: "alert_add", timeStamp: 0}); // timeStamp暂未支持

          // 用法二:
          // event类型的type支持自定义，同时存在"message"/"messageerror"/"error"特殊类型，如下所示
          // 当type = "message"，onmessage接口定义的方法同时会执行。
          // 当type = "messageerror"，onmessageerror接口定义的方法同时会执行。
          // 当type = "error"，onerror接口定义的方法同时会执行。
          // 若调用removeEventListener接口或者off接口取消事件时，能且只能取消使用addEventListener/on/once创建的事件。

          workerInstance.addEventListener("message", () => {
            console.info("message listener callback");
          })
          workerInstance.onmessage = (e: MessageEvents): void => {
            console.info("onmessage : message listener callback");
          }
          // 调用dispatchEvent分发“message”事件，addEventListener和onmessage中定义的方法都会被执行。
          workerInstance.dispatchEvent({type: "message", timeStamp: 0}); // timeStamp暂未支持

          // 向worker线程发送消息
          workerInstance.postMessage("test");
        })
    }
    .height('100%')
    .width('100%')
  }
}

收起
自动换行
深色代码主题
复制
// worker.ets
import { ErrorEvent, MessageEvents, ThreadWorkerGlobalScope, worker } from '@kit.ArkTS';

const workerPort: ThreadWorkerGlobalScope = worker.workerPort;

workerPort.onmessage = (event: MessageEvents) => {
  console.info("worker thread recv data is: ", event.data);
  let data: string = event.data;
  const workerHandler1 = () => console.info("Handler 1 is: ", data);
  const workerHandler2 = () => console.info("Handler 2 is: ", data);

  // 注册两个监听器
  workerPort.addEventListener("workerListener", workerHandler1);
  workerPort.addEventListener("workerListener", workerHandler2);

  // 事件workerListener注册了两个监听器，两个监听器都会执行
  workerPort.dispatchEvent({type: "workerListener", timeStamp: 0}); // timeStamp暂未支持

  // 删除workerHandler1监听器
  workerPort.removeEventListener("workerListener", workerHandler1); // timeStamp暂未支持

  // workerHandler1监听器已删除，只有workerHandler2执行
  workerPort.dispatchEvent({type: "workerListener", timeStamp: 0}); // timeStamp暂未支持

  // 删除所有事件监听
  workerPort.removeAllListener();
};

@ohos.worker (启动一个Worker)

导入模块

常量

WorkerOptions

ThreadWorkerPriority18+

ThreadWorker9+

属性

constructor9+

postMessage9+

postMessage9+

postMessageWithSharedSendable12+

on9+

once9+

off9+

registerGlobalCallObject11+

unregisterGlobalCallObject11+

terminate9+

addEventListener9+

removeEventListener9+

dispatchEvent9+

removeAllListener9+

WorkerEventTarget9+

addEventListener9+

removeEventListener9+

dispatchEvent9+

removeAllListener9+

ThreadWorkerGlobalScope9+

属性

postMessage9+

postMessage9+

postMessageWithSharedSendable12+

callGlobalCallObjectMethod11+

close9+

postMessageAtFront

WorkerEventListener9+

(event: Event)9+

GlobalScope9+

MessageEvents9+

MessageType

ErrorCallback18+

Worker(deprecated)

属性

constructor(deprecated)

postMessage(deprecated)

postMessage(deprecated)

on(deprecated)

once(deprecated)

off(deprecated)

terminate(deprecated)

EventTarget(deprecated)

addEventListener(deprecated)

removeEventListener(deprecated)

dispatchEvent(deprecated)

removeAllListener(deprecated)

DedicatedWorkerGlobalScope(deprecated)

属性

postMessage(deprecated)

postMessage(deprecated)

postMessage(deprecated)

close(deprecated)

PostMessageOptions

Event

EventListener(deprecated)

(evt: Event)(deprecated)

ErrorEvent

MessageEvent<T>

WorkerGlobalScope(deprecated)

Priority

其他说明

序列化支持类型

内存模型

完整示例

FA模型

Stage模型

分发事件与监听接口搭配使用示例

ThreadWorkerPriority¹⁸⁺

ThreadWorker⁹⁺

constructor⁹⁺

postMessage⁹⁺

postMessage⁹⁺

postMessageWithSharedSendable¹²⁺

on⁹⁺

once⁹⁺

off⁹⁺

registerGlobalCallObject¹¹⁺

unregisterGlobalCallObject¹¹⁺

terminate⁹⁺

addEventListener⁹⁺

removeEventListener⁹⁺

dispatchEvent⁹⁺

removeAllListener⁹⁺

WorkerEventTarget⁹⁺

addEventListener⁹⁺

removeEventListener⁹⁺

dispatchEvent⁹⁺

removeAllListener⁹⁺

ThreadWorkerGlobalScope⁹⁺

postMessage⁹⁺

postMessage⁹⁺

postMessageWithSharedSendable¹²⁺

callGlobalCallObjectMethod¹¹⁺

close⁹⁺

WorkerEventListener⁹⁺

(event: Event)⁹⁺

GlobalScope⁹⁺

MessageEvents⁹⁺

ErrorCallback¹⁸⁺

Worker^(deprecated)

constructor^(deprecated)

postMessage^(deprecated)

postMessage^(deprecated)

on^(deprecated)

once^(deprecated)

off^(deprecated)

terminate^(deprecated)

EventTarget^(deprecated)

addEventListener^(deprecated)

removeEventListener^(deprecated)

dispatchEvent^(deprecated)

removeAllListener^(deprecated)

DedicatedWorkerGlobalScope^(deprecated)

postMessage^(deprecated)

postMessage^(deprecated)

postMessage^(deprecated)

close^(deprecated)

EventListener^(deprecated)

(evt: Event)^(deprecated)

WorkerGlobalScope^(deprecated)