HarmonyOS API：JS FA调用Java PA机制

joytrian

发布于 2023-4-12 18:17

浏览

0收藏

版本：v3.1 Beta

概述

更新时间: 2023-02-17 09:19

说明

本模块首批接口从API version 4开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

方舟开发框架-基于JS扩展的类Web开发范式框架提供了JS FA（Feature Ability）调用Java PA（Particle Ability）的机制。该机制在HarmonyOS引擎内提供了一种通道来传递方法调用、数据返回、事件上报，开发者可根据需要自行实现FA和PA两端的对应接口完成对应的功能逻辑。

JS FA调用Java PA机制介绍

更新时间: 2023-02-17 09:19

方舟开发框架-基于JS扩展的类Web开发范式框架提供了一种FA（JS API）调用PA（Java API）的机制，包含远端调用Ability和本地调用Internal Ability两种方式。

FA提供了以下三个JS接口：

FeatureAbility.callAbility(OBJECT)：调用PA能力
FeatureAbility.subscribeAbilityEvent(OBJECT, Function)：订阅PA能力
FeatureAbility.unsubscribeAbilityEvent(OBJECT)：取消订阅PA能力

在PA端提供的接口为：

boolean IRemoteObject.onRemoteRequest(int code, MessageParcel data, MessageParcel reply, MessageOption option)：Ability方式，与FA通过rpc方式通信，该方式的优点在于PA可以被不同的FA调用。
boolean onRemoteRequest(int code, MessageParcel data, MessageParcel reply, MessageOption option)：Internal Ability方式，集成在FA中，适用于与FA业务逻辑关联性强，响应时延要求高的服务。该方式仅支持本FA访问调用。

JS端与Java端通过接口扩展机制进行通信，通过bundleName和abilityName来进行关联。在FeatureAbility Plugin收到JS调用请求后，系统根据开发者在JS指定的abilityType，Ability或Internal Ability，来选择对应的方式进行处理。开发者在onRemoteRequest()中实现PA提供的业务逻辑，不同的业务通过业务码来区分。

FeatureAbility模块(JS端SDK接口)

更新时间: 2023-02-17 09:19

支持设备

API	手机	平板	智慧屏	智能穿戴
FeatureAbility.callAbility(OBJECT)	支持	支持	支持	支持
FeatureAbility.subscribeAbilityEvent(OBJECT, Function)	支持	支持	支持	支持
FeatureAbility.unsubscribeAbilityEvent(OBJECT)	支持	支持	支持	支持

导入模块

无需导入。

FeatureAbility.callAbility

callAbility(Object): Promise<string>

调用PA（Particle Ability）提供的能力。

参数

参数名	类型	必填	说明
bundleName	string	是	Ability的包名称，需要与PA端匹配，区分大小写。
abilityName	string	是	Ability名称，需要与PA端匹配，区分大小写。
messageCode	number	是	Ability操作码（操作码定义PA的业务功能，需要与PA端约定，参见boolean IRemoteObject.onRemoteRequest(int code, MessageParcel data, MessageParcel reply, MessageOption option)）。
abilityType	number	是	Ability类型，对应PA端不同的实现方式： 0：Ability，拥有独立的Ability生命周期，FA使用远端进程通信拉起并请求PA服务，适用于提供基本服务供多FA调用或者在后台独立运行的场景，具体Java侧接口定义见Ability模块接口(Java语言，Ability方式)。 1：Internal Ability，与FA共进程，采用内部函数调用的方式和FA通信，适用于对PA响应时延要求较高的场景，不支持其他FA访问调用能力，具体Java侧接口定义见AceInternalAbility类(Java语言，Internal Ability方式)。
data	Object	否	发送到Ability的数据（根据不同的业务携带相应的业务数据，数据字段名称需要与PA端约定，参见boolean IRemoteObject.onRemoteRequest(int code, MessageParcel data, MessageParcel reply, MessageOption option)）
syncOption	number	否	PA侧请求消息处理同步/异步选项，非必填，默认使用同步方式。当前异步方式仅支持AbilityType为Internal Ability类型。 0：同步方式，默认方式。 1：异步方式。

返回值

类型	说明
Promise<string>	Promise中包含PA返回的结果数据，结果格式为JSON字符串。

示例详见综合示例CallAbility调用基本计算服务示例章节。

FeatureAbility.subscribeAbilityEvent

subscribeAbilityEvent(Object): Promise<string>

订阅PA（Particle Ability）的事件上报。

参数

参数名	类型	必填	说明
bundleName	string	是	Ability的包名称，需要与PA端匹配，区分大小写。
abilityName	string	是	Ability名称，需要与PA端匹配，区分大小写。
messageCode	number	是	订阅Ability事件的操作码（需要与PA约定，参见boolean IRemoteObject.onRemoteRequest(int code, MessageParcel data, MessageParcel reply, MessageOption option)）。
abilityType	number	是	Ability类型，对应PA端不同的实现方式： 0：Ability，拥有独立的Ability生命周期，FA使用远端进程通信拉起并请求PA服务，适用于提供基本服务供多FA调用或者在后台独立运行的场景，具体Java侧接口定义见Ability模块接口(Java语言，Ability方式)。 1：Internal Ability，与FA共进程，采用内部函数调用的方式和FA通信，适用于对PA响应时延要求较高的场景，不支持其他FA访问调用能力，具体Java侧接口定义见AceInternalAbility类(Java语言，Internal Ability方式)。
syncOption	number	否	请求消息同步/异步选项，非必填，默认使用同步方式。当前异步方式仅支持AbilityType为Internal Ability类型。 0：同步方式，默认方式。 1：异步方式。

返回值

类型	说明
Promise<string>	Promise中包含订阅PA返回的结果数据，结果格式为JSON字符串。

事件上报事件上报格式为JSON字符串。
示例详见综合示例SubscribeAbilityEvent/UnsubscribeAbilityEvent订阅以及取消订阅服务示例节。

FeatureAbility.unsubscribeAbilityEvent

unsubscribeAbilityEvent(Object): Promise<string>

取消订阅PA（Particle Ability）的事件上报。

参数

参数名	类型	必填	说明
bundleName	string	是	Ability的包名称，需要与PA端匹配，区分大小写。
abilityName	string	是	Ability名称，需要与PA端匹配，区分大小写。
messageCode	number	是	取消订阅Ability事件的操作码（需要与PA约定，参见boolean IRemoteObject.onRemoteRequest(int code, MessageParcel data, MessageParcel reply, MessageOption option)）。
abilityType	number	是	Ability类型，对应PA端不同的实现方式： 0：Ability，拥有独立的Ability生命周期，FA使用远端进程通信拉起并请求PA服务，适用于提供基本服务供多FA调用或者在后台独立运行的场景，具体Java侧接口定义见Ability模块接口(Java语言，Ability方式)。 1：Internal Ability，与FA共进程，采用内部函数调用的方式和FA通信，适用于对PA响应时延要求较高的场景，不支持其他FA访问调用能力，具体Java侧接口定义见AceInternalAbility类(Java语言，Internal Ability方式)。
syncOption	number	否	请求消息同步/异步选项，非必填，默认使用同步方式。当前异步方式仅支持AbilityType为Internal Ability类型。 0：同步方式，默认方式。 1：异步方式。

返回值

类型	说明
Promise<string>	Promise中包含订阅PA的返回结果，结果格式为JSON字符串。

示例详见综合示例SubscribeAbilityEvent/UnsubscribeAbilityEvent订阅以及取消订阅服务示例章节。

Ability模块接口(Java语言，Ability方式)

更新时间: 2023-02-17 09:19

导入模块

import ohos.aafwk.ability.Ability;
import ohos.rpc.RemoteObject;1.
2.

Ability.onConnect

onConnect(Intent: intent):<IRemote>

开发者的PA首次被FA连接时回调，并返回IRemoteObject对象，用于后续的业务通信。开发者需要继承Ability类并重写该方法。

参数

参数名	类型	必填	说明
intent	Intent	是	Service连接信息。

返回值

表1 IRemote
参数名
类型
必填
说明
IRemote
Object
是
Service的代理对象。

IRemoteObject.onRemoteRequest

onRemoteRequest(code: int, data: MessageParcel, reply: MessageParcel, option: MessageOption): boolean

JS端携带的操作请求业务码以及业务数据，业务执行完后，返回响应给JS端。开发者需要继承RemoteObject类并重写该方法。

参数

参数名	类型	必填	说明
code	int	是	Js端发送的业务请求编码（PA端定义需要与Js端业务请求码保持一致）。
data	MessageParcel	是	Js端发送的MessageParcel对象，当前仅支持json字符串格式。
reply	MessageParcel	是	将本地业务响应返回给Js端的MessageParcel对象，当前仅支持String格式。
option	MessageOption	是	指示操作是同步还是异步的方式。

说明
1. code以及对应的data和reply在对外开放后，需要保证前向兼容性。
2. MessageParcel.writeString(String)默认最大支持200KB数据量，若需要传输大数据，可以使用ohos.utils.Parcel.setCapacity()调整buffer容量大小。