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

​RequestParams​

启动参数。

返回值:

表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

​RequestParams​

启动参数。

返回值:

表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值:

  • 0:成功接收运行结果
  • -1:取消接收运行结果
  • 其他:为开发者根据业务自定义的值

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​​查询得到。













说明



如果RequestParams中主动设置了networkId,需要添加flag属性,值为FLAG_ABILITYSLICE_MULTI_DEVICE ,表示要进行跨设备调用。






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。默认直接打开首页。


文章转载自:​​https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/js-apis-distributed-start-0000001050024935-V3?catalogVersion=V3#section179371736113615​

已于2023-4-12 18:16:34修改
收藏
回复
举报
回复
    相关推荐