-

开发者可以通过 DataAbilityHelper 类来访问当前应用或其他应用提供的共享数据。 DataAbilityHelper 作为客户端,与提供方的 Data 进行通信。Data 接收到请求后,执行相应的处理,并返回结果。DataAbilityHelper 提供了一系列与 Data Ability 对应的方法。

下面介绍 DataAbilityHelper 具体的使用步骤。

声明使用权限

如果待访问的 Data 声明了访问需要权限,则访问此 Data 需要在配置文件中声明需要此权限。声明请参考权限申请字段说明

"reqPermissions": [
    {
        "name": "com.example.myapplication5.DataAbility.DATA"
    }
]

创建 DataAbilityHelper

DataAbilityHelper为开发者提供了creator()方法来创建DataAbilityHelper实例。该方法为静态方法,有多个重载。最常见的方法是通过传入一个context对象来创建DataAbilityHelper对象。

获取helper对象示例:

DataAbilityHelper helper = DataAbilityHelper.creator(this);

访问Data Ability

DataAbilityHelper 为开发者提供了一系列的接口来访问不同类型的数据(文件、数据库等)。

  • 访问文件

DataAbilityHelper 为开发者提供了 FileDescriptor openFile (Uri uri, String mode)方法来操作文件。此方法需要传入两个参数,其中 uri 用来确定目标资源路径,mode 用来指定打开文件的方式,可选方式包含“r”(读), “w”(写), “rw”(读写),“wt”(覆盖写),“wa”(追加写),“rwt”(覆盖写且可读)。

该方法返回一个目标文件的 FD(文件描述符),把文件描述符封装成流,开发者就可以对文件流进行自定义处理。

访问文件示例:

  // 读取文件描述符
  FileDescriptor fd = helper.openFile(uri, "r");
  FileInputStream fis = new FileInputStream(fd);

  • 访问数据库

DataAbilityHelper 为开发者提供了增、删、改、查以及批量处理等方法来操作数据库。

方法 描述
ResultSet query(Uri uri, String[] columns, DataAbilityPredicates predicates) 查询数据库
int insert(Uri uri, ValuesBucket value) 向数据库中插入单条数据
int batchInsert(Uri uri, ValuesBucket[] values) 向数据库中插入多条数据
int delete(Uri uri, DataAbilityPredicates predicates) 删除一条或多条数据
int update(Uri uri, ValuesBucket value, DataAbilityPredicates predicates) 更新数据库
DataAbilityResult[] executeBatch(ArrayList<DataAbilityOperation> operations) 批量操作数据库

这些方法的使用说明如下:

  • query()

查询方法,其中 uri 为目标资源路径,columns 为想要查询的字段。开发者的查询条件可以通过 DataAbilityPredicates 来构建。查询用户表中 id 在 101-103 之间的用户,并把结果打印出来,代码示例如下:

    DataAbilityHelper helper = DataAbilityHelper.creator(this);

     
    // 构造查询条件
    DataAbilityPredicates predicates = new DataAbilityPredicates();
    predicates.between("userId", 101, 103);

     
    // 进行查询
    ResultSet resultSet = helper.query(uri,columns,predicates);

     
    // 处理结果
    resultSet.goToFirstRow();
    do{
        // 在此处理ResultSet中的记录;
    }while(resultSet.goToNextRow());

  • insert()

新增方法,其中 uri 为目标资源路径,ValuesBucket 为要新增的对象。插入一条用户信息的代码示例如下:

    DataAbilityHelper helper = DataAbilityHelper.creator(this);

     
    // 构造插入数据
    ValuesBucket valuesBucket = new ValuesBucket();
    valuesBucket.putString("name", "Tom");
    valuesBucket.putInteger("age", 12);
    helper.insert(uri, valuesBucket);

  • batchInsert()

批量插入方法,和 insert() 类似。批量插入用户信息的代码示例如下:

    DataAbilityHelper helper = DataAbilityHelper.creator(this);

     
    // 构造插入数据
    ValuesBucket[] values = new ValuesBucket[2];
    value[0] = new ValuesBucket();
    value[0].putString("name", "Tom");
    value[0].putInteger("age", 12);
    value[1] = new ValuesBucket();
    value[1].putString("name", "Tom1");
    value[1].putInteger("age", 16);
    helper.batchInsert(uri, values);

  • delete()

删除方法,其中删除条件可以通过 DataAbilityPredicates 来构建。删除用户表中 id 在 101-103 之间的用户,代码示例如下:

    DataAbilityHelper helper = DataAbilityHelper.creator(this);

     
    // 构造删除条件
    DataAbilityPredicates predicates = new DataAbilityPredicates();
    predicates.between("userId", 101,103);
    helper.delete(uri,predicates);

  • update()

更新方法,更新数据由 ValuesBucket 传入,更新条件由 DataAbilityPredicates 来构建。更新 id 为 102 的用户,代码示例如下:

    DataAbilityHelper helper = DataAbilityHelper.creator(this);

     
    // 构造更新条件
    DataAbilityPredicates predicates = new DataAbilityPredicates();
    predicates.equalTo("userId",102);

     
    // 构造更新数据
    ValuesBucket valuesBucket = new ValuesBucket();
    valuesBucket.putString("name", "Tom");
    valuesBucket.putInteger("age", 12);
    helper.update(uri, valuesBucket, predicates);

  • executeBatch()

此方法用来执行批量操作。DataAbilityOperation 中提供了设置操作类型、数据和操作条件的方法,开发者可自行设置自己要执行的数据库操作。插入多条数据的代码示例如下:

    DataAbilityHelper helper = DataAbilityHelper.creator(abilityObj, insertUri);

     
    // 构造批量操作
    ValuesBucket value1 = initSingleValue();
    DataAbilityOperation opt1 = DataAbilityOperation.newInsertBuilder(insertUri).withValuesBucket(value1).build();
    ValuesBucket value2 = initSingleValue2();
    DataAbilityOperation opt2 = DataAbilityOperation.newInsertBuilder(insertUri).withValuesBucket(value2).build();
    ArrayList<DataAbilityOperation> operations = new ArrayList<DataAbilityOperation>();
    operations.add(opt1);
    operations.add(opt2);
    DataAbilityResult[] result = helper.executeBatch(insertUri, operations);