HarmonyOS API:分布式拉起
版本: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。默认直接打开首页。  | 




















