• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# DataAbility开发指导
2## 场景介绍
3基于Data模板的Ability（以下简称“Data”），有助于应用管理其自身和其他应用存储数据的访问，并提供与其他应用共享数据的方法。Data既可用于同设备不同应用的数据共享，也支持跨设备不同应用的数据共享。
4
5Data提供方可以自定义数据的增、删、改、查，以及文件打开等功能，并对外提供这些接口。
6
7## 接口说明
8
9**表1** Data中相关生命周期API功能介绍
10|接口名|描述|
11|:------|:------|
12|onInitialized(info: AbilityInfo): void|在Ability初始化调用，通过此回调方法执行RDB等初始化操作。|
13|update(uri: string, valueBucket: rdb.ValuesBucket, predicates: dataAbility.DataAbilityPredicates, callback: AsyncCallback\<number>): void|更新数据库中的数据。|
14|query(uri: string, columns: Array\<string>, predicates: dataAbility.DataAbilityPredicates, callback: AsyncCallback\<ResultSet>): void|查询数据库中的数据。|
15|delete(uri: string, predicates: dataAbility.DataAbilityPredicates, callback: AsyncCallback\<number>): void|删除一条或多条数据。|
16|normalizeUri(uri: string, callback: AsyncCallback\<string>): void|对URI进行规范化。一个规范化的URI可以支持跨设备使用、持久化、备份和还原等，当上下文改变时仍然可以引用到相同的数据项。|
17|batchInsert(uri: string, valueBuckets: Array\<rdb.ValuesBucket>, callback: AsyncCallback\<number>): void|向数据库中插入多条数据。|
18|denormalizeUri(uri: string, callback: AsyncCallback\<string>): void|将一个由normalizeUri生产的规范化URI转换成非规范化的URI。|
19|insert(uri: string, valueBucket: rdb.ValuesBucket, callback: AsyncCallback\<number>): void|向数据中插入一条数据。|
20|openFile(uri: string, mode: string, callback: AsyncCallback\<number>): void|打开一个文件。|
21|getFileTypes(uri: string, mimeTypeFilter: string, callback: AsyncCallback<Array\<string>>): void|获取文件的MIME类型。|
22|getType(uri: string, callback: AsyncCallback\<string>): void|获取URI指定数据相匹配的MIME类型。|
23|executeBatch(ops: Array\<DataAbilityOperation>, callback: AsyncCallback\<Array\<DataAbilityResult>>): void|批量操作数据库中的数据。|
24|call(method: string, arg: string, extras: PacMap, callback: AsyncCallback\<PacMap>): void|自定义方法。|
25
26
27## 开发步骤
28### 创建Data
29
301. 实现Data中Insert、Query、Update、Delete接口的业务内容。保证能够满足数据库存储业务的基本需求。BatchInsert与ExecuteBatch接口已经在系统中实现遍历逻辑，依赖Insert、Query、Update、Delete接口逻辑，来实现数据的批量处理。
31
32    创建Data的代码示例如下：
33
34   ```javascript
35    import featureAbility from '@ohos.ability.featureAbility'
36    import dataAbility from '@ohos.data.dataAbility'
37    import dataRdb from '@ohos.data.rdb'
38
39    const TABLE_NAME = 'book'
40    const STORE_CONFIG = { name: 'book.db' }
41    const SQL_CREATE_TABLE = 'CREATE TABLE IF NOT EXISTS book(id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, introduction TEXT NOT NULL)'
42    let rdbStore: dataRdb.RdbStore = undefined
43
44    export default {
45    onInitialized(abilityInfo) {
46        console.info('DataAbility onInitialized, abilityInfo:' + abilityInfo.bundleName)
47        let context = featureAbility.getContext()
48        dataRdb.getRdbStore(context, STORE_CONFIG, 1, (err, store) => {
49            console.info('DataAbility getRdbStore callback')
50            store.executeSql(SQL_CREATE_TABLE, [])
51            rdbStore = store
52        });
53    },
54    insert(uri, valueBucket, callback) {
55        console.info('DataAbility insert start')
56        rdbStore.insert(TABLE_NAME, valueBucket, callback)
57    },
58    batchInsert(uri, valueBuckets, callback) {
59        console.info('DataAbility batch insert start')
60        for (let i = 0;i < valueBuckets.length; i++) {
61            console.info('DataAbility batch insert i=' + i)
62            if (i < valueBuckets.length - 1) {
63                rdbStore.insert(TABLE_NAME, valueBuckets[i], (err: any, num: number) => {
64                    console.info('DataAbility batch insert ret=' + num)
65                })
66            } else {
67                rdbStore.insert(TABLE_NAME, valueBuckets[i], callback)
68            }
69        }
70    },
71    query(uri, columns, predicates, callback) {
72        console.info('DataAbility query start')
73        let rdbPredicates = dataAbility.createRdbPredicates(TABLE_NAME, predicates)
74        rdbStore.query(rdbPredicates, columns, callback)
75    },
76    update(uri, valueBucket, predicates, callback) {
77        console.info('DataAbilityupdate start')
78        let rdbPredicates = dataAbility.createRdbPredicates(TABLE_NAME, predicates)
79        rdbStore.update(valueBucket, rdbPredicates, callback)
80    },
81    delete(uri, predicates, callback) {
82        console.info('DataAbilitydelete start')
83        let rdbPredicates = dataAbility.createRdbPredicates(TABLE_NAME, predicates)
84        rdbStore.delete(rdbPredicates, callback)
85    }
86    };
87   ```
88
892. 子模块配置
90
91   | Json重要字段 | 备注说明                                                     |
92   | ------------ | ------------------------------------------------------------ |
93   | "name"       | Ability名称，对应Ability派生的Data类名。                     |
94   | "type"       | Ability类型，Data对应的Ability类型为”data“。                 |
95   | "uri"        | 通信使用的URI。                                              |
96   | "visible"    | 对其他应用是否可见，设置为true时，Data才能与其他应用进行通信传输数据。 |
97
98   **config.json配置样例**
99
100   ```json
101   "abilities":[{
102    "srcPath": "DataAbility",
103    "name": ".DataAbility",
104    "icon": "$media:icon",
105    "srcLanguage": "ets",
106    "description": "$string:description_dataability",
107    "type": "data",
108    "visible": true,
109    "uri": "dataability://ohos.samples.etsdataability.DataAbility"
110   }]
111   ```
112
113### 访问Data
114#### 开发前准备
115
116需导入基础依赖包，以及获取与Data子模块通信的URI字符串。
117
118其中，基础依赖包包括：
119- @ohos.ability.featureAbility
120- @ohos.data.dataAbility
121- @ohos.data.rdb
122
123#### DataAbility接口开发指导
124
125
1261. 创建工具接口类对象。
127
128   工具接口类对象DataAbilityHelper相关接口可参考[DataAbilityHelper模块](../reference/apis/js-apis-dataAbilityHelper.md)。
129   ```js
130   // 作为参数传递的URI,与config中定义的URI的区别是多了一个"/",是因为作为参数传递的URI中,在第二个与第三个"/"中间,存在一个DeviceID的参数
131   import featureAbility from '@ohos.ability.featureAbility'
132   import ohos_data_ability from '@ohos.data.dataAbility'
133   import ohos_data_rdb from '@ohos.data.rdb'
134
135   var urivar = "dataability:///com.ix.DataAbility"
136   var DAHelper = featureAbility.acquireDataAbilityHelper(
137    urivar
138   );
139   ```
1402. 构建数据库相关的RDB数据。
141   ```js
142   var valuesBucket = {"name": "gaolu"}
143   var da = new ohos_data_ability.DataAbilityPredicates()
144   var valArray =new Array("value1");
145   var cars = new Array({"batchInsert1" : "value1",});
146   ```
1473. 调用insert方法向指定的Data子模块插入数据。
148   ```js
149   // callback方式调用:
150   DAHelper.insert(
151    urivar,
152    valuesBucket,
153    (error, data) => {
154        console.log("DAHelper insert result: " + data)
155    }
156   );
157   ```
158
159   ```js
160   // promise方式调用:
161   var datainsert = await DAHelper.insert(
162    urivar,
163    valuesBucket
164   );
165   ```
1664. 调用delete方法删除Data子模块中指定的数据。
167   ```js
168   // callback方式调用:
169   DAHelper.delete(
170    urivar,
171    da,
172    (error, data) => {
173        console.log("DAHelper delete result: " + data)
174    }
175   );
176   ```
177
178   ```js
179   // promise方式调用:
180   var datadelete = await DAHelper.delete(
181    urivar,
182    da,
183   );
184   ```
1855. 调用update方法更新指定Data子模块中的数据。
186   ```js
187   // callback方式调用:
188   DAHelper.update(
189    urivar
190    valuesBucket,
191    da,
192    (error, data) => {
193        console.log("DAHelper update result: " + data)
194    }
195   );
196   ```
197
198   ```js
199   // promise方式调用:
200   var dataupdate = await DAHelper.update(
201    urivar,
202    valuesBucket,
203    da,
204   );
205   ```
2066. 调用query方法在指定的Data子模块中查找数据。
207   ```js
208   // callback方式调用:
209   DAHelper.query(
210    urivar,
211    valArray,
212    da,
213    (error, data) => {
214        console.log("DAHelper query result: " + data)
215    }
216   );
217   ```
218
219   ```js
220   // promise方式调用:
221   var dataquery = await DAHelper.query(
222    urivar,
223    valArray,
224    da
225   );
226   ```
2277. 调用batchInsert方法向指定的数据子模块批量插入数据。
228   ```js
229   // callback方式调用:
230   DAHelper.batchInsert(
231    urivar,
232    cars,
233    (error, data) => {
234        console.log("DAHelper batchInsert result: " + data)
235    }
236   );
237   ```
238
239   ```js
240   // promise方式调用:
241   var databatchInsert = await DAHelper.batchInsert(
242    urivar,
243    cars
244   );
245   ```
2468. 调用executeBatch方法向指定的Data子模块进行数据的批量处理。
247   ```js
248   // callback方式调用:
249   DAHelper.executeBatch(
250    urivar,
251    [
252        {
253            uri: urivar,
254            type: featureAbility.DataAbilityOperationType.TYPE_INSERT,
255            valuesBucket: {"executeBatch" : "value1",},
256            predicates: da,
257            expectedCount:0,
258            predicatesBackReferences: null,
259            interrupted:true,
260        }
261    ],
262    (error, data) => {
263        console.log("DAHelper executeBatch result: " + data)
264    }
265   );
266   ```
267
268   ```js
269   // promise方式调用:
270   var dataexecuteBatch = await DAHelper.executeBatch(
271    urivar,
272    [
273        {
274            uri: urivar,
275            type: featureAbility.DataAbilityOperationType.TYPE_INSERT,
276            valuesBucket:
277            {
278                "executeBatch" : "value1",
279            },
280            predicates: da,
281            expectedCount:0,
282            predicatesBackReferences: null,
283            interrupted:true,
284        }
285    ]
286   );
287   ```
288
289## 相关实例
290
291针对DataAbility开发，有以下相关实例可供参考：
292
293- [`DataAbility`：DataAbility的创建与访问（eTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/samples_monthly_0730/ability/DataAbility)
294