回复
HarmonyOS API：分布式拉起
joytrian
发布于 2023-4-12 18:16
浏览
0收藏
版本：v3.1 Beta
分布式拉起
更新时间: 2023-02-17 09:19
说明
- 从API Version 7 开始，该接口不再维护，推荐使用新接口'@ohos.ability.featureAbility'。
- 本模块首批接口从API version 4开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
- 本模块接口仅支持在基于JS扩展的类Web开发范式下使用。
分布式拉起允许拉起一个本地或远程的FA，拉起时可以传递参数。如果使用startAbilityForResult还可以获得FA的运行结果。
注意：如果设备上已经运行该FA，且launchType为singleton，则生命周期onNewRequest()将被回调。
支持设备
API | 手机 | 平板 | 智慧屏 | 智能穿戴 |
FeatureAbility.startAbility | 支持 | 支持 | 支持 | 支持 |
FeatureAbility.startAbilityForResult | 支持 | 支持 | 支持 | 支持 |
FeatureAbility.finishWithResult | 支持 | 支持 | 支持 | 支持 |
onNewRequest | 支持 | 支持 | 支持 | 支持 |
FeatureAbility.getDeviceList6+ | 支持 | 支持 | 支持 | 支持 |
导入模块
无需导入
权限列表
ohos.permission.DISTRIBUTED_DATASYNC
ohos.permission.GET_DISTRIBUTED_DEVICE_INFO
此外，还需要在FA的onStart()中，调用requestPermissionsFromUser()方法向用户申请权限，代码示例如下：
public class MainAbility extends Ability implements IAbilityContinuation {
@Override
public void onStart(Intent intent) {
super.onStart(intent);
// 开发者显示声明需要使用的权限
requestPermissionsFromUser(new String[]{"ohos.permission.DISTRIBUTED_DATASYNC"}, 0);
}
}
FeatureAbility.startAbility
startAbility(request: RequestParams): Promise<Result>
拉起一个FA，无回调结果。允许以显式的方式，拉起远程或本地的FA。
参数：
参数名 | 类型 | 必填 | 说明 |
request | 是 | 启动参数。 |
返回值：
表1 Result
参数名 | 类型 | 非空 | 说明 |
code | number | 是 | 0：成功。 非0：失败，失败原因见data。 |
data | Object | 是 | 成功：返回null。 失败：携带错误信息，类型为String。 |
示例
// caller
export default {
start: async function() {
let actionData = {
uri: 'www.example.com'
};
let target = {
bundleName: "com.example.harmonydevsample",
abilityName: "com.example.harmonydevsample.EntryJSApiAbility",
data: actionData
};
let result = await FeatureAbility.startAbility(target);
if (result.code == 0) {
console.log('success');
} else {
console.log('cannot start browsing service, reason: ' + result.data);
}
}
}
// callee
export default {
data: {
contact: "contact information",
location: "location information"
}
}
说明
分布式场景下，data数据段下的字段名，如果与后台传入的字段同名，js中的会被覆盖。分布式拉起时传入的数据，会直接挂到应用页面的data数据段下，可直接通过this.XXX访问。
FeatureAbility.startAbilityForResult
startAbilityForResult(request: RequestParams): Promise<Result>
拉起另一个FA的能力（本地），并在回调中等待被拉起FA的结果返回。
如：一个没有定位功能的FA可以调用另一个有能力的FA，调用地图并且获得用户在地图上选择的位置。它跟FeatureAbility.startAbility的区别在于结果是在被拉起的FA消亡后再返回结果。
说明
FeatureAbility.startAbilityForResult()需要与FeatureAbility.finishWithResult()关联使用。
参数：
参数名 | 类型 | 必填 | 说明 |
request | 是 | 启动参数。 |
返回值：
表2 Result
参数名 | 类型 | 非空 | 说明 |
code | number | 是 | 0：成功 。 非0: 失败，失败原因见data。 |
data | Object | 是 | 成功：拉起FA返回的数据。 失败：携带错误信息，类型为String。 |
示例：
下面的示例展示了一个ability如何拉起另一个ability,并在另一个ability退出时拿到其中的数据。
// caller
export default {
data: {
startAbilityForResultExplicitResult: 'NA'
},
startAbilityForResultExplicit: async function() {
var result = await FeatureAbility.startAbilityForResult({
bundleName: "com.example.harmonydevsample",
abilityName: "com.example.harmonydevsample.EntryJSApiAbility"
});
this.startAbilityForResultExplicitResult = JSON.stringify(result);
}
}
// callee
export default {
onShow() {
let request = {};
request.result = {
contact: "contact information",
location: "location information"
};
FeatureAbility.finishWithResult(100, request);
}
}
FeatureAbility.finishWithResult
finishWithResult(code: number, result: Object): Promise<Result>
FA调用该接口以主动结束，同时将运行结果作为参数设置。
参数：
参数名 | 类型 | 必填 | 说明 |
code | number | 是 | FeatureAbility.startAbilityForResult接收的运行结果中，包含code值：
|
result | Object | 否 | 用户自定义返回结果。 |
返回值：
表3 Result
参数名 | 类型 | 非空 | 说明 |
code | number | 是 | 非0: 失败，具体原因见data。 |
data | Object | 是 | 失败：携带错误信息，类型为String。 |
说明
成功场景下应用会结束，无返回值。
示例：
该FA被调起并在结束后返回开发者设置的信息。
export default {
onShow() {
let request = {};
request.result = {
contact: "contact information",
location: "location information"
};
FeatureAbility.finishWithResult(100, request);
}
}
FeatureAbility.getDeviceList6+
getDeviceList(flag: number): Promise<Result>
FA调用该接口以获取设备信息列表。
参数：
参数名 | 类型 | 必填 | 说明 |
flag | number | 否 | 默认0：获取网络中所有设备信息列表。 flag取值： 0：获取网络中所有设备信息列表。 1：获取网络中在线设备信息列表。 2：获取网络中离线设备信息列表。 |
返回值：
表4 Result
参数名 | 类型 | 非空 | 说明 |
code | number | 是 | 0：成功。 非0： 失败。 |
data | Object | 是 | 失败：携带的错误信息，类型为string。 成功：返回网络设备信息列表，类型为Array<DeviceInfo>。 |
表5 DeviceInfo
参数名 | 类型 | 非空 | 说明 |
networkId | string | 是 | 网络ID |
deviceName | string | 是 | 设备名称 |
deviceState | string | 是 | 设备状态： ONLINE：在线 OFFLINE：离线 UNKNOWN：未知 |
deviceType | string | 是 | 设备类型： LAPTOP：Indicates a laptop. SMART_PHONE：Indicates a smartphone. SMART_PAD：Indicates a tablet. SMART_WATCH：Indicates a smart watch. SMART_CAR：Indicates a smart car. SMART_TV：Indicates a smart TV. UNKNOWN_TYPE：unknown type. |
示例：
export default {
start: async function() {
let flag = 1;
let ret = await FeatureAbility.getDeviceList(flag);
if (ret.code == 0) {
for (let i = 0; i < ret.data.length; i++) {
console.info('getDeviceList networkId = ' + ret.data[i].networkId);
}
}
}
}
onNewRequest
该回调用于处理FA已经启动时收到新的请求，如其他FA在本FA已经启动情况下再次通过startAbility向本FA发送请求。
在正常启动流程下，该回调不会被调用。
表6 RequestParams
参数名 | 类型 | 必填 | 说明 |
bundleName | string | 根据Ability的全称启动应用时必填 | 要启动的包名。需和abilityName配合使用，区分大小写。 |
abilityName | string | 根据Ability的全称启动应用时必填 | 要启动的ability名，区分大小写。 |
entities | Array<string> | 根据Operation的其他属性启动应用时选填 | 希望被调起的FA所归属的实体列表，如果不填，默认查找所有实体列表。需配合action使用。 |
action | string | 根据Operation的其他属性启动应用时必填 | 在不指定包名及ability名的情况下，可以通过传入action值从而根据Operation的其他属性启动应用。 |
networkId7+ | string | 根据Ability的全称启动应用时选填 | 通过网络ID主动设置想要连接的设备，networkId的值可以由getDeviceList查询得到。
|
deviceType | number | 否 | 默认0: 从本地以及远端设备中选择要启动的FA。 1: 从本地设备启动FA。 有多个FA满足条件的情况下，将弹框由用户选择设备。 备注：startAbilityForResult仅支持从本地启动，该参数不生效。 |
data | Object | 否 | 指定要传递给对方的参数，需要可被序列化。 所有在data中设置的字段，在对端FA中均可以直接在 this下拿到。 举例：假设 data.uri = "foo.com" 则对端FA中可以通过 this.uri 取得该值。 |
flag | number | 否 | 拉起FA时的配置开关，如是否免安装等。 |
url | string | 否 | 拉起FA时，指定打开的页面的url。默认直接打开首页。 |
已于2023-4-12 18:16:34修改
赞
收藏
回复
相关推荐
