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