• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.application.DataShareExtensionAbility (数据共享扩展能力)
2
3**DataShareExtensionAbility**基于ExtensionAbility框架，提供支持数据共享业务的能力。
4
5>**说明：**
6>
7> 本模块首批接口从API version 9开始支持，后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> 本模块接口为系统接口。
10>
11> 本模块接口仅可在Stage模型下使用。
12
13
14## 导入模块
15
16```ts
17import DataShareExtensionAbility from '@ohos.application.DataShareExtensionAbility';
18```
19
20## uri命名规则
21
22标准uri定义结构如下:
23
24**Scheme://authority/path**
25- Scheme: 协议名，对于data share统一为datashare
26- authority: [userinfo@]host[:port]
27    - userinfo: 登录信息，不需要填写。
28    - host: 服务器地址，如果跨设备访问则为目标设备的ID，如果为本设备则为空。
29    - port: 服务器端口，不需要填写。
30- path: data share的标识信息和资源的路径信息，需要包含data share的标识信息，资源的路径信息可以不填写。
31
32uri示例:
33
34- 不包含资源路径: `datashare:///com.samples.datasharetest.DataShare`
35
36- 包含资源路径: `datashare:///com.samples.datasharetest.DataShare/DB00/TBL00`
37
38其中，data share的标识信息为`com.samples.datasharetest.DataShare`，资源路径为`DB00/TBL00`。
39
40## 属性
41
42**系统能力**：SystemCapability.DistributedDataManager.DataShare.Provider
43
44| 名称 | 类型 | 可读 | 可写 | 说明 |
45| -------- | -------- | -------- | -------- | -------- |
46| context | [ExtensionContext](js-apis-inner-application-extensionContext.md)  | 是 | 否 |表示数据共享扩展能力上下文。 |
47
48## onCreate
49
50onCreate?(want: Want, callback: AsyncCallback<void>): void
51
52DataShare客户端连接DataShareExtensionAbility服务端时，服务端回调此接口，执行初始化业务逻辑操作。该方法可以选择性重写。
53
54**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Provider
55
56**参数：**
57
58| 参数名 | 类型 | 必填 | 说明 |
59| ----- | ------ | ------ | ------ |
60| want | [Want](js-apis-application-want.md#want) | 是  | Want类型信息，包括Ability名称、Bundle名称等。 |
61| callback | AsyncCallback<void> | 是 | 回调函数。无返回值。 |
62
63**示例：**
64
65```ts
66import rdb from '@ohos.data.relationalStore';
67
68let DB_NAME = 'DB00.db';
69let TBL_NAME = 'TBL00';
70let DDL_TBL_CREATE = 'CREATE TABLE IF NOT EXISTS '
71    + TBL_NAME
72    + ' (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)';
73let rdbStore;
74
75export default class DataShareExtAbility extends DataShareExtensionAbility {
76    onCreate(want, callback) {
77        rdb.getRdbStore(this.context, {
78            name: DB_NAME,
79            securityLevel: rdb.SecurityLevel.S1
80        }, function (err, data) {
81            console.info(`getRdbStore done, data : ${data}`);
82            rdbStore = data;
83            rdbStore.executeSql(DDL_TBL_CREATE, [], function (err) {
84                console.error(`executeSql done, error message : ${err}`);
85            });
86            if (callback) {
87                callback();
88            }
89        });
90    }
91};
92```
93
94## insert
95
96insert?(uri: string, valueBucket: ValuesBucket, callback: AsyncCallback<number>): void
97
98在数据库插入时回调此接口，该方法可以选择性重写。
99
100**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Provider
101
102**参数：**
103
104| 参数名 | 类型 | 必填 | 说明 |
105| ----- | ------ | ------ | ------ |
106| uri |string | 是  | 指示要插入的数据的路径。 |
107| valueBucket |[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 指示要插入的数据。 |
108| callback |AsyncCallback<number> | 是 | 回调函数。返回插入数据记录的索引。 |
109
110**示例：**
111
112```ts
113import rdb from '@ohos.data.relationalStore';
114
115let DB_NAME = 'DB00.db';
116let TBL_NAME = 'TBL00';
117let DDL_TBL_CREATE = 'CREATE TABLE IF NOT EXISTS '
118    + TBL_NAME
119    + ' (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)';
120let rdbStore;
121
122export default class DataShareExtAbility extends DataShareExtensionAbility {
123    insert(uri, valueBucket, callback) {
124        if (valueBucket === null) {
125            console.error('invalid valueBuckets');
126            return;
127        }
128        rdbStore.insert(TBL_NAME, valueBucket, function (err, ret) {
129            console.info(`callback ret: ${ret}`);
130            if (callback !== undefined) {
131                callback(err, ret);
132            }
133        });
134    }
135};
136```
137
138## update
139
140update?(uri: string, predicates: dataSharePredicates.DataSharePredicates, valueBucket: ValuesBucket, callback: AsyncCallback<number>): void
141
142在数据库更新时服务端回调此接口，该方法可以选择性重写。
143
144**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Provider
145
146**参数：**
147
148| 参数名 | 类型 | 必填 | 说明 |
149| ----- | ------ | ------ | ------ |
150| uri | string | 是  | 指示要更新的数据的路径。 |
151| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是  | 指示筛选条件。 |
152| valueBucket | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 指示要更新的数据。 |
153| callback | AsyncCallback<number> | 是 | 回调函数。返回更新的数据记录数。 |
154
155**示例：**
156
157```ts
158import rdb from '@ohos.data.relationalStore';
159
160let DB_NAME = 'DB00.db';
161let TBL_NAME = 'TBL00';
162let DDL_TBL_CREATE = 'CREATE TABLE IF NOT EXISTS '
163    + TBL_NAME
164    + ' (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)';
165let rdbStore;
166
167export default class DataShareExtAbility extends DataShareExtensionAbility {
168    update(uri, predicates, valueBucket, callback) {
169        if (predicates === null || predicates === undefined) {
170            return;
171        }
172        rdbStore.update(TBL_NAME, valueBucket, predicates, function (err, ret) {
173            if (callback !== undefined) {
174                callback(err, ret);
175            }
176        });
177    }
178};
179```
180
181## delete
182
183delete?(uri: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>): void
184
185在删除数据库记录时服务端回调此接口，该方法可以选择性重写。
186
187**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Provider
188
189**参数：**
190
191| 参数名       | 类型                                                     | 必填 | 说明                               |
192| ---------- | ------------------------------------------------------------ | ---- | ---------------------------------- |
193| uri        | string                                                       | 是   | 指示要删除的数据的路径。           |
194| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是   | 指示筛选条件。                     |
195| callback   | AsyncCallback<number>                                  | 是   | 回调函数。返回已删除的数据记录数。 |
196
197**示例：**
198
199```ts
200import rdb from '@ohos.data.relationalStore';
201
202let DB_NAME = 'DB00.db';
203let TBL_NAME = 'TBL00';
204let DDL_TBL_CREATE = 'CREATE TABLE IF NOT EXISTS '
205    + TBL_NAME
206    + ' (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)';
207let rdbStore;
208
209export default class DataShareExtAbility extends DataShareExtensionAbility {
210    delete(uri, predicates, callback) {
211        if (predicates === null || predicates === undefined) {
212            return;
213        }
214        rdbStore.delete(TBL_NAME, predicates, function (err, ret) {
215            if (callback !== undefined) {
216                callback(err, ret);
217            }
218        });
219    }
220};
221```
222
223## query
224
225query?(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: AsyncCallback<Object>): void
226
227在查询数据库时服务端回调此接口，该方法可以选择性重写。
228
229**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Provider
230
231**参数：**
232
233| 参数名 | 类型 | 必填 | 说明 |
234| ----- | ------ | ------ | ------ |
235| uri | string | 是  | 指示要查询的数据的路径。 |
236| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是  | 指示筛选条件。 |
237| columns | Array<string> | 是 | 指示要查询的列。如果此参数为空，则查询所有列。 |
238| callback | AsyncCallback<Object> | 是 | 回调函数。返回查询到的结果集。 |
239
240**示例：**
241
242```ts
243import rdb from '@ohos.data.relationalStore';
244
245let DB_NAME = 'DB00.db';
246let TBL_NAME = 'TBL00';
247let DDL_TBL_CREATE = 'CREATE TABLE IF NOT EXISTS '
248    + TBL_NAME
249    + ' (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)';
250let rdbStore;
251
252export default class DataShareExtAbility extends DataShareExtensionAbility {
253    query(uri, predicates, columns, callback) {
254        if (predicates === null || predicates === undefined) {
255            return;
256        }
257        rdbStore.query(TBL_NAME, predicates, columns, function (err, resultSet) {
258            if (resultSet !== undefined) {
259                console.info(`resultSet.rowCount: ${resultSet.rowCount}`);
260            }
261            if (callback !== undefined) {
262                callback(err, resultSet);
263            }
264        });
265    }
266};
267```
268
269## batchInsert
270
271batchInsert?(uri: string, valueBuckets: Array<ValuesBucket>, callback: AsyncCallback<number>): void
272
273在数据库批量插入时服务端回调此接口，该方法可以选择性重写。
274
275**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Provider
276
277**参数：**
278
279| 参数名        | 类型                                                     | 必填 | 说明                             |
280| ------------ | ------------------------------------------------------------ | ---- | -------------------------------- |
281| uri          | string                                                       | 是   | 指示要批量插入的数据的路径。     |
282| valueBuckets | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)> | 是   | 指示要批量插入的数据。           |
283| callback     | AsyncCallback<number>                                  | 是   | 回调函数。返回插入的数据记录数。 |
284
285**示例：**
286
287```ts
288import rdb from '@ohos.data.relationalStore';
289
290let DB_NAME = 'DB00.db';
291let TBL_NAME = 'TBL00';
292let DDL_TBL_CREATE = 'CREATE TABLE IF NOT EXISTS '
293    + TBL_NAME
294    + ' (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)';
295let rdbStore;
296
297export default class DataShareExtAbility extends DataShareExtensionAbility {
298    batchInsert(uri, valueBuckets, callback) {
299        if (valueBuckets === null || valueBuckets.length === undefined) {
300            console.error('invalid valueBuckets');
301            return;
302        }
303        rdbStore.batchInsert(TBL_NAME, valueBuckets, function (err, ret) {
304                if (callback !== undefined) {
305                    callback(err, ret);
306                }
307            });
308        });
309    }
310};
311```
312
313## normalizeUri
314
315normalizeUri?(uri: string, callback: AsyncCallback<string>): void
316
317用户给定的URI转换为服务端使用的URI时回调此接口，该方法可以选择性重写。
318
319**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Provider
320
321**参数：**
322
323| 参数名     | 类型                  | 必填 | 说明                    |
324| -------- | --------------------- | ---- | ----------------------- |
325| uri      | string                | 是   | 指示用户传入的[URI](js-apis-uri.md#uri)。 |
326| callback | AsyncCallback<string> | 是   | 回调函数。如果支持URI规范化，则返回规范化URI，否则返回空。 |
327
328**示例：**
329
330```ts
331export default class DataShareExtAbility extends DataShareExtensionAbility {
332    normalizeUri(uri, callback) {
333        let err = {'code':0};
334        let ret = `normalize: ${uri}`;
335        callback(err, ret);
336    }
337};
338```
339
340## denormalizeUri
341
342denormalizeUri?(uri: string, callback: AsyncCallback<string>): void
343
344服务端使用的URI转换为用户传入的初始URI时服务端回调此接口，该方法可以选择性重写。
345
346**系统能力：**  SystemCapability.DistributedDataManager.DataShare.Provider
347
348**参数：**
349
350| 参数名     | 类型                  | 必填 | 说明                    |
351| -------- | --------------------- | ---- | ----------------------- |
352| uri      | string                | 是   | 指示服务端使用的[URI](js-apis-uri.md#uri)。 |
353| callback | AsyncCallback<string> | 是   | 回调函数。如果反规范化成功，则返回反规范化的URI；如果无需进行反规范化，则返回原始URI；若不支持则返回空。 |
354
355**示例：**
356
357```ts
358export default class DataShareExtAbility extends DataShareExtensionAbility {
359    denormalizeUri(uri, callback) {
360        let err = {'code':0};
361        let ret = `denormalize ${uri}`;
362        callback(err, ret);
363    }
364};
365```
366