# js_worker_module

**Repository Path**: hyq5234/js_worker_module

## Basic Information

- **Project Name**: js_worker_module
- **Description**: js_worker_module，提供JS多线程能力 | Provide JS multi-threading capability
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 30
- **Created**: 2022-03-09
- **Last Updated**: 2022-08-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# js_worker_module

### 简介

worker能够让js拥有多线程的能力，通过postMessage完成worker线程与宿主线程通信。

### 接口说明
接口实现详见：js_worker_module/jsapi/worker

#### Worker对象描述

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

##### 接口

1. 

- 接口名

|constructor(scriptURL:string, options? WorkerOptions) | 构造函数 |
|---|---|

- 使用示例

```
import worker from "@ohos.worker"
```
通过判断是否与pages目录同级和创建项目的模型类别，共有以下四种新建Worker的方式：

(1) FA模型: 目录同级
```
const workerInstance = new worker.Worker("workers/worker.js", {name:"first worker"});
```
(2) FA模型: 目录不同级（以workers目录放置pages目录前一级为例）
```
const workerInstance = new worker.Worker("../workers/worker.js", {name:"first worker"});
```
(3)  Stage模型: 目录同级
```
const workerInstance = new worker.Worker('entry/ets/workers/worker.ts');
```
(4) Stage模型: 目录不同级（以workers目录放置pages目录后一级为例）
```
const workerInstance = new worker.Worker('entry/ets/pages/workers/worker.ts');
```
对于Stage模型中scriptURL——"entry/ets/workers/worker.ts"的解释：
- entry: 为module.json5中module中name属性的值；
- ets: 表明当前工程使用的语言；
- worker.ts: 创建worker.ts文件或者worker.js文件都可以。

另外，需在工程目录下build-profile.json5文件的buildOption属性中添加配置信息，主要分为下面两种情况：

(1) 目录同级(**不添加也可以**)

FA模型:
```
  "buildOption": {
    "sourceOption": {
      "workers": [
        "./src/main/ets/MainAbility/workers/worker.js"
      ]
    }
  }
```
Stage模型:
```
  "buildOption": {
    "sourceOption": {
      "workers": [
        "./src/main/ets/workers/worker.ts"
      ]
    }
  }
```
(2) 目录不同级(**必须添加**)

FA模型:
```
  "buildOption": {
    "sourceOption": {
      "workers": [
        "./src/main/ets/workers/worker.js"
      ]
    }
  }
```
Stage模型:
```
  "buildOption": {
    "sourceOption": {
      "workers": [
        "./src/main/ets/pages/workers/worker.ts"
      ]
    }
  }
```

2. 

- 接口名

| postMessage(message:Object, options?:PostMessageOptions)  | 向worker线程发送消息  |
|---|---|
| postMessage(message:Object, transfer:ArrayBuffer[])  | 向worker线程发送消息  |

- 使用示例

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

3. 

- 接口名

| on(type:string, listener:EventListener)  | 向worker添加一个事件监听  |
|---|---|

- 使用示例

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

4. 

- 接口名

| once(type:string, listener:EventListener)  | 向worker添加一个事件监听, 事件监听只执行一次便自动删除  |
|---|---|

- 使用示例

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

5. 

- 接口名

| off(type:string, listener?:EventListener)  | 删除worker的事件监听  |
|---|---|

- 使用示例

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

6. 

- 接口名

| terminate()  | 关闭worker线程，终止worker发送消息  |
|---|---|

- 使用示例

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

7. 

- 接口名

| removeEventListener(type:string, listener?:EventListener)  | 删除worker的事件监听  |
|---|---|

- 使用示例

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

8. 

- 接口名

| dispatchEvent(event: Event)  | 分发定义在worker的事件  |
|---|---|

- 使用示例

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

9. 

- 接口名

| removeAllListener()  | 删除worker的所有事件监听  |
|---|---|

- 使用示例

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

##### 属性

1. 

- 属性名

| onexit?:(code:number)=>void  | worker退出时被调用的事件处理程序，处理程序在宿主线程中执行  |
|---|---|

- 使用示例

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

2. 

- 属性名

| onerror?:(ev:ErrorEvent)=>void  | worker在执行过程中发生异常被调用的事件处理程序，处理程序在宿主线程中执行  |
|---|---|

- 使用示例

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

3. 

- 属性名

| onmessage?:(ev:MessageEvent)=>void  | 宿主线程收到来自其创建的worker通过parentPort.postMessage接口发送的消息时被调用的事件处理程序， 处理程序在宿主线程中执行 |
|---|---|

- 使用示例

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

4. 

- 属性名

| onmessageerror?:(event:MessageEvent)=>void  | worker对象接收到一条无法序列化的消息时被调用的事件处理程序， 处理程序在宿主线程中执行 |
|---|---|

- 使用示例

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

#### parentPort对象描述

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

##### 接口

1. 

- 接口名

| postMessage(message:Object, options?:PostMessageOptions)  | 向宿主线程发送消息 |
|---|---|
| postMessage(message:Object, transfer:ArrayBuffer[])  | 向宿主线程发送消息  |

- 使用示例

```
// 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) {
    parentPort.postMessage("hello world from worker.js");
}
```

2. 

- 接口名

| close()  | 关闭worker线程，终止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) {
    parentPort.close();
}
```

##### 属性

1. 

- 属性名

| onmessage?:(event:MessageEvent)=>void  | 宿主线程收到来自其创建的worker通过worker.postMessage接口发送的消息时被调用的事件处理程序，处理程序在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");
}
```

2. 

- 属性名

| onerror?:(ev: ErrorEvent)=>void  | worker在执行过程中发生异常被调用的事件处理程序，处理程序在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.onerror = function(e) {
    console.log("onerror...");
}

```

3. 

- 属性名

| onmessageerror?:(event: MessageEvent)=>void  | worker对象接收到一条无法被反序列化的消息时被调用的事件处理程序， 处理程序在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.onmessageerror = function(e) {
    console.log("onmessageerror...");
}
```

### 涉及仓

- ace_ace_engine(foundation/arkui/ace_engine-readme_zh.md)
- ace_napi(foundation/arkui/napi-readme_zh.md)

## 相关仓
[js_worker_module 子系统](base/compileruntime/js_worker_module-readme_zh.md)


### 许可证

Worker在[Apache许可证](https://gitee.com/openharmony/js_worker_module/blob/master/LICENSE)下可用，有关完整的许可证文本，请参见[许可证](https://gitee.com/openharmony/js_worker_module/blob/master/LICENSE)。