!6164 【DataShare】datashare开发者指南与概述增加

Merge pull request !6164 from songruirui/master

zh-cn/application-dev/database/database-datashare-guidelines.md

+# DataShare开发指导
+DataShare即数据共享模块，提供了向其他应用共享以及管理其数据的方法。目前仅支持同个设备上应用之间的数据共享。
+
+## 接口说明
+
+**表1** 数据提供方API说明
+
+|接口名|描述|
+|:------|:------|
+|onCreate?(want: Want, callback: AsyncCallback<void>): void|DataShareExtensionAbility生命周期回调，在数据提供方应用创建时回调，执行初始化业务逻辑操作，如创建数据库。|
+|insert?(uri: string, valueBucket: ValuesBucket, callback: AsyncCallback<number>): void|业务函数，在访问方向数据库中插入数据时回调。|
+|update?(uri: string, predicates: DataSharePredicates, valueBucket: ValuesBucket, callback: AsyncCallback<number>): void|业务函数，在访问方更新数据时回调。|
+|query?(uri: string, predicates: DataSharePredicates, columns: Array<string>, callback: AsyncCallback<Object>): void|业务函数，在访问方查询数据时回调。|
+|delete?(uri: string, predicates: DataSharePredicates, callback: AsyncCallback<number>): void|业务函数，在访问方删除数据时回调。|
+
+完整的数据提供方接口请见[DataShareExtensionAbility](../reference/apis/js-apis-application-DataShareExtensionAbility.md)。
+
+**表2** 数据访问方API说明
+
+| 接口名                                                       | 描述                               |
+| :----------------------------------------------------------- | :--------------------------------- |
+| createDataShareHelper(context: Context, uri: string, callback: AsyncCallback<DataShareHelper>): void | 创建DataShare工具类。              |
+| insert(uri: string, value: ValuesBucket, callback: AsyncCallback<number>): void | 将单条数据记录插入数据库。         |
+| update(uri: string, predicates: DataSharePredicates, value: ValuesBucket, callback: AsyncCallback<number>): void | 更新数据库中的数据记录。           |
+| query(uri: string, predicates: DataSharePredicates, columns: Array<string>, callback: AsyncCallback<DataShareResultSet>): void | 查询数据库中的数据。               |
+| delete(uri: string, predicates: DataSharePredicates, callback: AsyncCallback<number>): void | 从数据库中删除一条或多条数据记录。 |
+
+完整的数据访问方接口请见[DataShareHelper](../reference/apis/js-apis-data-dataShare.md)。
+
+## 开发场景
+
+数据共享可分为数据的提供方和访问方两部分。
+
+- 提供方可以选择性实现数据的增、删、改、查，以及文件打开等功能，并对外共享这些数据。
+- 访问方利用工具类，便可以访问提供方提供的这些数据。
+
+以下是数据提供方和数据访问方应用的各自开发示例。
+
+### 数据提供方应用的开发（仅限系统应用）
+
+1. 导入基础依赖包。
+
+   ```ts
+   import Extension from '@ohos.application.DataShareExtensionAbility'
+   import rdb from '@ohos.data.rdb';
+   import fileIo from '@ohos.fileio'
+   import dataSharePredicates from '@ohos.data.dataSharePredicates'
+   ```
+
+2. 数据提供方（也称服务端）继承于DataShareExtensionAbility，开发者可根据应用需求选择性重写其业务实现。例如数据提供方只提供查询服务，则可只重写查询接口。
+
+3. 数据提供方的业务实现由开发者自定义。例如可以通过数据库、读写文件或访问网络等各方式实现数据提供方的数据存储。
+
+   ```ts
+   let DB_NAME = "DB00.db";
+   let TBL_NAME = "TBL00";
+   let DDL_TBL_CREATE = "CREATE TABLE IF NOT EXISTS "
+   + TBL_NAME
+   + " (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, isStudent BOOLEAN, Binary BINARY)";
+   
+   let rdbStore;
+   let result;
+   
+   export default class DataShareExtAbility extends Extension {
+       private rdbStore_;
+       
+   	// 重写onCreate接口
+       onCreate(want, callback) {
+           result = this.context.cacheDir + '/datashare.txt'
+           // 业务实现使用RDB
+           rdb.getRdbStore(this.context, {
+               name: DB_NAME
+           }, 1, function (err, data) {
+               rdbStore = data;
+               rdbStore.executeSql(DDL_TBL_CREATE, [], function (err) {
+                   console.log('DataShareExtAbility onCreate, executeSql done err:' + JSON.stringify(err));
+               });
+               callback();
+           });
+       }
+   
+   	// 重写query接口
+       query(uri, predicates, columns,  callback) {
+           if (predicates == null || predicates == undefined) {
+               console.info('invalid predicates');
+           }
+           try {
+               rdbStore.query(TBL_NAME, predicates, columns, function (err, resultSet) {
+                   if (resultSet != undefined) {
+                       console.info('resultSet.rowCount: ' + resultSet.rowCount);
+                   }
+                   if (callback != undefined) {
+                       callback(err, resultSet);
+                   }
+               });
+           } catch (err) {
+               console.error('error' + err);
+           }
+       }
+       // 可根据应用需求，选择性重写各个接口
+       // ...
+   };
+   ```
+
+4. 在module.json5中定义DataShareExtensionAbility。
+
+   | Json重要字段 | 备注说明                                                     |
+   | ------------ | ------------------------------------------------------------ |
+   | "name"       | Ability名称，对应Ability派生的ExtensionAbility类名。         |
+   | "type"       | Ability类型，DataShare对应的Ability类型为”dataShare“，表示基于datashare模板开发的。 |
+   | "uri"        | 通信使用的URI，是客户端链接服务端的唯一标识。                |
+   | "visible"    | 对其他应用是否可见，设置为true时，才能与其他应用进行通信传输数据。 |
+
+   **module.json5配置样例**
+
+   ```json
+   "extensionAbilities": [
+     {
+       "srcEntrance": "./ets/DataShareExtAbility/DataShareExtAbility.ts",
+       "name": "DataShareExtAbility",
+       "icon": "$media:icon",
+       "description": "$string:description_datashareextability",
+       "type": "dataShare",
+       "uri": "datashare://com.samples.datasharetest.DataShare",
+       "visible": true
+     }
+   ]
+   ```
+
+### 数据访问方应用的开发
+
+1. 导入基础依赖包。
+
+   ```ts
+   import Ability from '@ohos.application.Ability'
+   import dataShare from '@ohos.data.dataShare'
+   import dataSharePredicates from '@ohos.data.dataSharePredicates'
+   ```
+   
+2. 定义与数据提供方通信的URI字符串。
+
+   ```ts
+   // 作为参数传递的URI，与module.json5中定义的URI的区别是多了一个"/"，是因为作为参数传递的URI中，在第二个与第三个"/"中间，存在一个DeviceID的参数
+   let dseUri = ("datashare:///com.samples.datasharetest.DataShare");
+   ```
+   
+2. 创建工具接口类对象。
+
+   ```ts
+   let dsHelper;
+   let abilityContext;
+   export default class MainAbility extends Ability {
+   	onWindowStageCreate(windowStage) {
+   		abilityContext = this.context;
+   		dataShare.createDataShareHelper(abilityContext, dseUri, (err,data)=>{
+   			dsHelper = data;
+   		});
+   	}
+   }
+   ```
+   
+3. 获取到接口类对象后，便可利用其提供的接口访问提供方提供的服务，如进行数据的增删改查等。
+
+   ```ts
+   // 构建一条数据
+   var valuesBucket = {"name": "ZhangSan", "age": 21, "isStudent": false, "Binary": new Uint8Array([1,2,3])};
+   var updateBucket = {"name": "LiSi", "age": 18, "isStudent": true, "Binary": new Uint8Array([1,2,3])};
+   let da =  new dataSharePredicates.DataSharePredicates();
+   var valArray =new Array("*");
+   let people = new Array(
+   	{"name": "LiSi", "age": 41, "Binary": ar},
+   	{"name": "WangWu", "age": 21, "Binary": arr},
+   	{"name": "ZhaoLiu", "age": 61, "Binary": arr});
+   // 插入一条数据
+   dsHelper.insert(dseUri, valuesBucket, (err,data) => {
+       console.log("dsHelper insert result: " + data);
+   });
+   // 删除指定的数据
+   dsHelper.delete(dseUri, da, (err,data) => {
+       console.log("dsHelper delete result: " + data);
+   });
+   // 更新数据
+   dsHelper.update(dseUri, da, updateBucket, (err,data) => {
+       console.log("dsHelper update result: " + data);
+   });
+   // 查询数据
+   dsHelper.query(dseUri, da, valArray, (err,data) => {
+       console.log("dsHelper query result: " + data);
+   });
+   ```
+   

zh-cn/application-dev/database/database-datashare-overview.md

+# 数据共享开发概述
+
+## 数据共享简介
+
+DataShare即数据共享模块，用于应用管理其自身数据，也提供了向其他应用共享以及管理其数据的方法。目前仅支持同个设备上应用之间的数据共享。
+
+在许多应用场景中都需要用到数据共享，比如将电话簿、短信、媒体库中的数据共享给其他应用等。当然，不是所有的数据都允许其他应用访问，比如帐号、密码等；有些数据也只允许其他应用查询而不允许其删改，比如短信等。所以对于各种数据共享场景，DataSahre这样一个安全、便捷的可以跨设备、跨应用的数据共享机制是十分必需的。
+
+对于数据提供者来说，无需进行繁琐的封装，可直接使用DataShare框架实现向其他应用共享数据；对于数据访问方来说，因DataShare的访问方式不会因数据提供的方式而不同，所以只需要学习和使用一套接口即可，大大减少了学习时间和开发难度。
+
+## 基本概念
+
+
+在进行应用的开发前，开发者应了解以下基本概念：
+
+
+- 数据提供方
+
+  提供数据及实现相关业务的应用程序，也称为生产者或服务端。
+
+- 数据访问方
+
+  访问数据提供方所提供的数据或业务的应用程序，也称为消费者或客户端。
+
+- 数据集
+
+  用户要插入的数据集合，可以是一条或多条数据。数据集以键值对的形式存在，键为字符串类型，值支持数字、字符串、布尔值、无符号整型数组等多种数据类型。
+
+- 结果集
+  
+  用户查询之后的结果集合，其提供了灵活的数据访问方式，以便用户获取各项数据。
+  
+- 谓词
+  
+  用户访问数据库中的数据所使用的筛选条件，经常被应用在更新数据、删除数据和查询数据中等场景。
+
+## 运作机制
+
+**图 1**  DataShare运作机制<a name="fig3330103712254"></a>
+
+
+![](figures/zh-cn_DataShare.png)
+
+- DataShareExtAbility模块为数据提供方，实现跨应用数据共享的相关业务。
+- DataShareHelper模块为数据访问方，提供各种访问数据的接口，包括增删改查等。
+- 数据访问方与提供方通过IPC进行通信，数据提供方可以通过数据库实现，也可以通过其他数据存储方式实现。
+
+- ResultSet模块通过共享内存实现，用于存储查询数据得到的结果集，并提供了遍历结果集的方法。
+
+## 约束与限制
+
+- DataShare受到数据提供方所使用数据库的一些限制。例如支持的数据模型、Key的长度、Value的长度、每个应用程序支持同时打开数据库的最大数量等，都会受到使用的数据库的限制。
+
+- 因DataShare内部实现依赖于IPC通信，所以数据集、谓词、结果集等的载荷受到IPC通信的约束与限制。