Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
提交 461c13d8 编写于 作者: Y yqhan
浏览文件
操作

Modify the doc of worker module. 

Signed-off-by: Nyqhan <hanyuqing2@huawei.com>
上级 5343fc13
隐藏空白更改
内联 并排
Showing with 40 addition and 39 deletion
zh-cn/application-dev/reference/apis/js-apis-worker.md
浏览文件 @ 461c13d8
...@@ -160,9 +160,9 @@ Stage模型: ...@@ -160,9 +160,9 @@ Stage模型:
### postMessage<sup>9+</sup> ### postMessage<sup>9+</sup>
postMessage(message: Object, transfer: ArrayBuffer[]): void; postMessage(message: Object, transfer: ArrayBuffer[]): void
向Worker线程发送数据，数据类型必须是序列化所支持的类型。序列化支持类型见其他说明。 宿主线程通过转移对象所有权的方式向Worker线程发送消息。
**系统能力：** SystemCapability.Utils.Lang **系统能力：** SystemCapability.Utils.Lang
...@@ -170,8 +170,8 @@ postMessage(message: Object, transfer: ArrayBuffer[]): void; ...@@ -170,8 +170,8 @@ postMessage(message: Object, transfer: ArrayBuffer[]): void;
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------- | ---- | ------------------------------------------------------------ | | -------- | ------------- | ---- | ------------------------------------------------------------ |
| message | Object | 是 | 发送至Worker的数据。 | | message | Object | 是 | 发送至Worker的数据，该数据对象必须是可序列化，序列化支持类型见[其他说明](#序列化支持类型)。 |
| transfer | ArrayBuffer[] | 是 | 可传递&nbsp;ArrayBuffer&nbsp;的实例对象，数组中不可传入null。 | | transfer | ArrayBuffer[] | 是 | 表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到Worker线程，在宿主线程中将会变为不可用，仅在Worker线程中可用，数组不可传入null。 |
**错误码：** **错误码：**
...@@ -195,7 +195,7 @@ workerInstance.postMessage(buffer, [buffer]); ...@@ -195,7 +195,7 @@ workerInstance.postMessage(buffer, [buffer]);
postMessage(message: Object, options?: PostMessageOptions): void postMessage(message: Object, options?: PostMessageOptions): void
向Worker线程发送数据，数据类型必须是序列化所支持的类型。序列化支持类型见其他说明。 宿主线程通过转移对象所有权或者拷贝数据的方式向Worker线程发送消息。
**系统能力：** SystemCapability.Utils.Lang **系统能力：** SystemCapability.Utils.Lang
...@@ -203,8 +203,8 @@ postMessage(message: Object, options?: PostMessageOptions): void ...@@ -203,8 +203,8 @@ postMessage(message: Object, options?: PostMessageOptions): void
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | | ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ |
| message | Object | 是 | 发送至Worker的数据。 | | message | Object | 是 | 发送至Worker的数据，该数据对象必须是可序列化，序列化支持类型见[其他说明](#序列化支持类型)。 |
| options | [PostMessageOptions](#postmessageoptions) | 否 | 可传输对象是&nbsp;ArrayBuffer&nbsp;的实例对象。若不填入该参数，默认设置为 undefined。| | options | [PostMessageOptions](#postmessageoptions) | 否 | 当填入该参数时，与传入ArrayBuffer[]的作用一致，该数组中对象的所有权会被转移到Worker线程，在宿主线程中将会变为不可用，仅在Worker线程中可用。<br>若不填入该参数，默认设置为 undefined，通过拷贝数据的方式传输信息到Worker线程。 |
**错误码：** **错误码：**
...@@ -848,16 +848,16 @@ Worker线程用于与宿主线程通信的类，通过postMessage接口发送消 ...@@ -848,16 +848,16 @@ Worker线程用于与宿主线程通信的类，通过postMessage接口发送消
postMessage(messageObject: Object, transfer: ArrayBuffer[]): void; postMessage(messageObject: Object, transfer: ArrayBuffer[]): void;
Worker线程向宿主线程发送消息。 Worker线程通过转移对象所有权的方式向宿主线程发送消息。
**系统能力：** SystemCapability.Utils.Lang **系统能力：** SystemCapability.Utils.Lang
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------- | ---- | ------------------------------------------------------- | | -------- | ------------- | ---- | ------------------------------------------------------------ |
| message | Object | 是 | 发送至宿主线程的数据。 | | message | Object | 是 | 发送至宿主线程的数据，该数据对象必须是可序列化，序列化支持类型见[其他说明](#序列化支持类型)。 |
| transfer | ArrayBuffer[] | 是 | 可传输对象是ArrayBuffer的实例对象，数组中不可传入null。 | | transfer | ArrayBuffer[] | 是 | 表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用，数组不可传入null。 |
**错误码：** **错误码：**
...@@ -896,7 +896,7 @@ workerPort.onmessage = function(e){ ...@@ -896,7 +896,7 @@ workerPort.onmessage = function(e){
postMessage(messageObject: Object, options?: PostMessageOptions): void postMessage(messageObject: Object, options?: PostMessageOptions): void
Worker线程向宿主线程发送消息。 Worker线程通过转移对象所有权或者拷贝数据的方式向宿主线程发送消息。
**系统能力：** SystemCapability.Utils.Lang **系统能力：** SystemCapability.Utils.Lang
...@@ -904,8 +904,8 @@ Worker线程向宿主线程发送消息。 ...@@ -904,8 +904,8 @@ Worker线程向宿主线程发送消息。
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | | ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ |
| message | Object | 是 | 发送至宿主线程的数据。 | | message | Object | 是 | 发送至宿主线程的数据，该数据对象必须是可序列化，序列化支持类型见[其他说明](#序列化支持类型)。 |
| options | [PostMessageOptions](#postmessageoptions) | 否 | 可传输对象是ArrayBuffer的实例对象。若不填入该参数，默认设置为 undefined。| | options | [PostMessageOptions](#postmessageoptions) | 否 | 当填入该参数时，与传入ArrayBuffer[]的作用一致，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用。<br/>若不填入该参数，默认设置为 undefined，通过拷贝数据的方式传输信息到宿主线程。 |
**错误码：** **错误码：**
...@@ -978,7 +978,7 @@ workerPort.onmessage = function(e) { ...@@ -978,7 +978,7 @@ workerPort.onmessage = function(e) {
onmessage?: (this: ThreadWorkerGlobalScope, ev: MessageEvents) =&gt; void onmessage?: (this: ThreadWorkerGlobalScope, ev: MessageEvents) =&gt; void
DedicatedWorkerGlobalScope的onmessage属性表示Worker线程收到来自其宿主线程通过postMessage接口发送的消息时被调用的事件处理程序，处理程序在Worker线程中执行。 ThreadWorkerGlobalScope的onmessage属性表示Worker线程收到来自其宿主线程通过postMessage接口发送的消息时被调用的事件处理程序，处理程序在Worker线程中执行。
**系统能力：** SystemCapability.Utils.Lang **系统能力：** SystemCapability.Utils.Lang
...@@ -1021,7 +1021,7 @@ workerPort.onmessage = function(e) { ...@@ -1021,7 +1021,7 @@ workerPort.onmessage = function(e) {
onmessageerror?: (this: ThreadWorkerGlobalScope, ev: MessageEvents) =&gt; void onmessageerror?: (this: ThreadWorkerGlobalScope, ev: MessageEvents) =&gt; void
DedicatedWorkerGlobalScope的onmessageerror属性表示当Worker对象接收到一条无法被反序列化的消息时被调用的事件处理程序，处理程序在Worker线程中执行。 ThreadWorkerGlobalScope的onmessageerror属性表示当Worker对象接收到一条无法被反序列化的消息时被调用的事件处理程序，处理程序在Worker线程中执行。
**系统能力：** SystemCapability.Utils.Lang **系统能力：** SystemCapability.Utils.Lang
...@@ -1255,9 +1255,9 @@ Stage模型: ...@@ -1255,9 +1255,9 @@ Stage模型:
### postMessage<sup>(deprecated)</sup> ### postMessage<sup>(deprecated)</sup>
postMessage(message: Object, transfer: ArrayBuffer[]): void; postMessage(message: Object, transfer: ArrayBuffer[]): void
向Worker线程发送数据，数据类型必须是序列化所支持的类型。序列化支持类型见其他说明。 宿主线程通过转移对象所有权的方式向Worker线程发送消息。
> **说明：**<br/> > **说明：**<br/>
> 从API version 7 开始支持，从API version 9 开始废弃，建议使用[ThreadWorker.postMessage<sup>9+</sup>](#postmessage9)替代。 > 从API version 7 开始支持，从API version 9 开始废弃，建议使用[ThreadWorker.postMessage<sup>9+</sup>](#postmessage9)替代。
...@@ -1266,10 +1266,10 @@ postMessage(message: Object, transfer: ArrayBuffer[]): void; ...@@ -1266,10 +1266,10 @@ postMessage(message: Object, transfer: ArrayBuffer[]): void;
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------- | ---- | ----------------------------------------------- | | -------- | ------------- | ---- | ------------------------------------------------------------ |
| message | Object | 是 | 发送至Worker的数据。 | | message | Object | 是 | 发送至Worker的数据，该数据对象必须是可序列化，序列化支持类型见[其他说明](#序列化支持类型)。 |
| transfer | ArrayBuffer[] | 是 | 可转移对象是&nbsp;ArrayBuffer&nbsp;的实例对象。 | | transfer | ArrayBuffer[] | 是 | 表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到Worker线程，在宿主线程中将会变为不可用，仅在Worker线程中可用，数组不可传入null。 |
**示例：** **示例：**
...@@ -1284,7 +1284,7 @@ workerInstance.postMessage(buffer, [buffer]); ...@@ -1284,7 +1284,7 @@ workerInstance.postMessage(buffer, [buffer]);
postMessage(message: Object, options?: PostMessageOptions): void postMessage(message: Object, options?: PostMessageOptions): void
向Worker线程发送数据，数据类型必须是序列化所支持的类型。序列化支持类型见其他说明。 宿主线程通过转移对象所有权或者拷贝数据的方式向Worker线程发送消息。
> **说明：**<br/> > **说明：**<br/>
> 从API version 7 开始支持，从API version 9 开始废弃，建议使用[ThreadWorker.postMessage<sup>9+</sup>](#postmessage9-1)替代。 > 从API version 7 开始支持，从API version 9 开始废弃，建议使用[ThreadWorker.postMessage<sup>9+</sup>](#postmessage9-1)替代。
...@@ -1295,8 +1295,8 @@ postMessage(message: Object, options?: PostMessageOptions): void ...@@ -1295,8 +1295,8 @@ postMessage(message: Object, options?: PostMessageOptions): void
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | | ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ |
| message | Object | 是 | 发送至Worker的数据。 | | message | Object | 是 | 发送至Worker的数据，该数据对象必须是可序列化，序列化支持类型见[其他说明](#序列化支持类型)。 |
| options | [PostMessageOptions](#postmessageoptions) | 否 | 可传输对象是&nbsp;ArrayBuffer&nbsp;的实例对象。若不填入该参数，默认设置为 undefined。| | options | [PostMessageOptions](#postmessageoptions) | 否 | 当填入该参数时，与传入ArrayBuffer[]的作用一致，该数组中对象的所有权会被转移到Worker线程，在宿主线程中将会变为不可用，仅在Worker线程中可用。<br/>若不填入该参数，默认设置为 undefined，通过拷贝数据的方式传输信息到Worker线程。 |
**示例：** **示例：**
...@@ -1695,7 +1695,7 @@ Worker线程用于与宿主线程通信的类，通过postMessage接口发送消 ...@@ -1695,7 +1695,7 @@ Worker线程用于与宿主线程通信的类，通过postMessage接口发送消
postMessage(messageObject: Object, transfer: Transferable[]): void; postMessage(messageObject: Object, transfer: Transferable[]): void;
Worker线程向宿主线程发送消息。 Worker线程通过转移对象所有权的方式向宿主线程发送消息。
> **说明：**<br/> > **说明：**<br/>
> 此接口暂不支持使用，从API version 9 开始废弃，建议使用[ThreadWorkerGlobalScope<sup>9+</sup>.postMessage<sup>9+</sup>](#postmessage9-2)替代。 > 此接口暂不支持使用，从API version 9 开始废弃，建议使用[ThreadWorkerGlobalScope<sup>9+</sup>.postMessage<sup>9+</sup>](#postmessage9-2)替代。
...@@ -1706,14 +1706,14 @@ Worker线程向宿主线程发送消息。 ...@@ -1706,14 +1706,14 @@ Worker线程向宿主线程发送消息。
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | | ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ |
| messageObject | Object | 是 | 发送至宿主线程的数据。 | | messageObject | Object | 是 | 发送至宿主线程的数据，该数据对象必须是可序列化，序列化支持类型见[其他说明](#序列化支持类型)。 |
| transfer| Transferable[] | 是 | 暂不支持该参数类型。 | | transfer| Transferable[] | 是 | 暂不支持该参数类型。 |
### postMessage<sup>9+</sup> ### postMessage<sup>9+</sup>
postMessage(messageObject: Object, transfer: ArrayBuffer[]): void; postMessage(messageObject: Object, transfer: ArrayBuffer[]): void;
Worker线程向宿主线程发送消息。 Worker线程通过转移对象所有权的方式向宿主线程发送消息。
> **说明：**<br/> > **说明：**<br/>
> DedicatedWorkerGlobalScope类自API version 9 开始废弃，本接口建议使用[ThreadWorkerGlobalScope<sup>9+</sup>.postMessage<sup>9+</sup>](#postmessage9-2)替代。 > DedicatedWorkerGlobalScope类自API version 9 开始废弃，本接口建议使用[ThreadWorkerGlobalScope<sup>9+</sup>.postMessage<sup>9+</sup>](#postmessage9-2)替代。
...@@ -1722,10 +1722,10 @@ Worker线程向宿主线程发送消息。 ...@@ -1722,10 +1722,10 @@ Worker线程向宿主线程发送消息。
**参数：** **参数：**
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------- | ---- | ----------------------------------------------------- | | -------- | ------------- | ---- | ------------------------------------------------------------ |
| message | Object | 是 | 发送至宿主线程的数据。 | | message | Object | 是 | 发送至宿主线程的数据，该数据对象必须是可序列化，序列化支持类型见[其他说明](#序列化支持类型)。 |
| transfer | ArrayBuffer[] | 是 | 可传输对象是ArrayBuffer的实例对象，数组不可传入null。 | | transfer | ArrayBuffer[] | 是 | 表示可转移的ArrayBuffer实例对象数组，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用，数组不可传入null。 |
**示例：** **示例：**
...@@ -1754,7 +1754,7 @@ parentPort.onmessage = function(e){ ...@@ -1754,7 +1754,7 @@ parentPort.onmessage = function(e){
postMessage(messageObject: Object, options?: PostMessageOptions): void postMessage(messageObject: Object, options?: PostMessageOptions): void
Worker线程向宿主线程发送消息。 Worker线程通过转移对象所有权或者拷贝数据的方式向宿主线程发送消息。
> **说明：**<br/> > **说明：**<br/>
> 从API version 7 开始支持，从API version 9 开始废弃，建议使用[ThreadWorkerGlobalScope<sup>9+</sup>.postMessage<sup>9+</sup>](#postmessage9-3)替代。 > 从API version 7 开始支持，从API version 9 开始废弃，建议使用[ThreadWorkerGlobalScope<sup>9+</sup>.postMessage<sup>9+</sup>](#postmessage9-3)替代。
...@@ -1765,8 +1765,8 @@ Worker线程向宿主线程发送消息。 ...@@ -1765,8 +1765,8 @@ Worker线程向宿主线程发送消息。
| 参数名 | 类型 | 必填 | 说明 | | 参数名 | 类型 | 必填 | 说明 |
| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | | ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ |
| message | Object | 是 | 发送至宿主线程的数据。 | | message | Object | 是 | 发送至宿主线程的数据，该数据对象必须是可序列化，序列化支持类型见[其他说明](#序列化支持类型)。 |
| options | [PostMessageOptions](#postmessageoptions) | 否 | 可传输对象是ArrayBuffer的实例对象。若不填入该参数，默认设置为 undefined。| | options | [PostMessageOptions](#postmessageoptions) | 否 | 当填入该参数时，与传入ArrayBuffer[]的作用一致，该数组中对象的所有权会被转移到宿主线程，在Worker线程中将会变为不可用，仅在宿主线程中可用。<br/>若不填入该参数，默认设置为 undefined，通过拷贝数据的方式传输信息到宿主线程。 |
**示例：** **示例：**
...@@ -1891,7 +1891,7 @@ parentPort.onmessageerror = function(e) { ...@@ -1891,7 +1891,7 @@ parentPort.onmessageerror = function(e) {
## PostMessageOptions ## PostMessageOptions
明确数据传递过程中需要转移所有权对象的类，传递所有权的对象必须是ArrayBuffer。 明确数据传递过程中需要转移所有权对象的类，传递所有权的对象必须是ArrayBuffer，发送它的上下文中将会变为不可用，仅在接收方可用。
**系统能力：** SystemCapability.Utils.Lang **系统能力：** SystemCapability.Utils.Lang
...@@ -2094,14 +2094,15 @@ Worker基于Actor并发模型实现。在Worker的交互流程中，JS主线程 ...@@ -2094,14 +2094,15 @@ Worker基于Actor并发模型实现。在Worker的交互流程中，JS主线程
Actor并发模型的交互原理：各个Actor并发地处理主线程任务，每个Actor内部都有一个消息队列及单线程执行模块，消息队列负责接收主线程及其他Actor的请求，单线程执行模块则负责串行地处理请求、向其他Actor发送请求以及创建新的Actor。由于Actor采用的是异步方式，各个Actor之间相互隔离没有数据竞争，因此Actor可以高并发运行。 Actor并发模型的交互原理：各个Actor并发地处理主线程任务，每个Actor内部都有一个消息队列及单线程执行模块，消息队列负责接收主线程及其他Actor的请求，单线程执行模块则负责串行地处理请求、向其他Actor发送请求以及创建新的Actor。由于Actor采用的是异步方式，各个Actor之间相互隔离没有数据竞争，因此Actor可以高并发运行。
### 注意事项 ### 注意事项
- Worker存在数量限制，当前支持最多同时存在7个Worker。 - Worker存在数量限制，当前支持最多同时存在8个Worker。
- 在API version 8及之前的版本，当Worker数量超出限制时，会抛出错误Error "Too many workers, the number of workers exceeds the maximum."。 - 在API version 8及之前的版本，当Worker数量超出限制时，会抛出错误Error "Too many workers, the number of workers exceeds the maximum."。
- 从API version 9开始，当Worker数量超出限制时，会抛出错误BusinessError "Worker initialization failure, the number of workers exceeds the maximum"。 - 从API version 9开始，当Worker数量超出限制时，会抛出错误BusinessError "Worker initialization failure, the number of workers exceeds the maximum."。
- 主动销毁Worker可以调用新创建Worker对象的terminate()或parentPort.close()方法。 - 主动销毁Worker可以调用新创建Worker对象的terminate()或parentPort.close()方法。
- 自API version 9版本开始，若Worker处于已经销毁或正在销毁等非运行状态时，调用其功能接口，会抛出相应的BusinessError。 - 自API version 9版本开始，若Worker处于已经销毁或正在销毁等非运行状态时，调用其功能接口，会抛出相应的BusinessError。
- Worker的创建和销毁耗费性能，建议管理已创建的Worker并重复使用。 - Worker的创建和销毁耗费性能，建议管理已创建的Worker并重复使用。
- 创建Worker工程时，new worker.Worker构造函数和new worker.ThreadWorker构造函数不能同时使用，否则将导致工程中Worker的功能异常。自API version 9版本开始，建议使用[new worker.ThreadWorker](#constructor9)构造函数，在API version 8及之前的版本，建议使用[new worker.Worker](#constructordeprecated)构造函数。 - 创建Worker工程时，new worker.Worker构造函数和new worker.ThreadWorker构造函数不能同时使用，否则将导致工程中Worker的功能异常。自API version 9版本开始，建议使用[new worker.ThreadWorker](#constructor9)构造函数，在API version 8及之前的版本，建议使用[new worker.Worker](#constructordeprecated)构造函数。
- 创建Worker工程时，在Worker线程的文件中（比如本文中worker.ts）不能导入任何有关构建UI的方法（比如ets文件等），否则会导致Worker的功能失效。排查方式：解压生成的Hap包，在创建Worker线程的文件目录中找到"worker.js"，全局搜索"View"关键字。如果存在该关键字，说明在worker.js中打包进去了构建UI的方法，会导致Worker的功能失效，建议在创建Worker线程的文件中修改 "import “xxx” from src"中src的目录层级。 - 创建Worker工程时，在Worker线程的文件中（比如本文中worker.ts）不能导入任何有关构建UI的方法（比如ets文件等），否则会导致Worker的功能失效。排查方式：解压生成的Hap包，在创建Worker线程的文件目录中找到"worker.js"，全局搜索"View"关键字。如果存在该关键字，说明在worker.js中打包进去了构建UI的方法，会导致Worker的功能失效，建议在创建Worker线程的文件中修改 "import “xxx” from src"中src的目录层级。
- 线程间通信时传递的数据量最大限制为16M。
## 完整示例 ## 完整示例
> **说明：**<br/> > **说明：**<br/>
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或