js-apis-application-dataShareExtensionAbility.md 13.1 KB
Newer Older
Z
zengyawen 已提交
1
# @ohos.application.DataShareExtensionAbility (数据共享扩展能力)
S
songruirui 已提交
2

S
songruirui 已提交
3
**DataShareExtensionAbility**基于ExtensionAbility框架,提供支持数据共享业务的能力。
S
songruirui 已提交
4 5

>**说明:** 
S
songruirui 已提交
6
>
7
> 本模块首批接口从API version 9开始支持,后续版本的新增接口,采用上角标单独标记接口的起始版本。
S
songruirui 已提交
8
>
9
> 本模块接口为系统接口。
S
songruirui 已提交
10
>
11
> 本模块接口仅可在Stage模型下使用。
S
songruirui 已提交
12 13 14 15


## 导入模块

S
songruirui 已提交
16 17
```ts
import DataShareExtensionAbility from '@ohos.application.DataShareExtensionAbility'
S
songruirui 已提交
18 19
```

N
niudongyao 已提交
20 21 22 23 24
## uri命名规则

标准uri定义结构如下:

**Scheme://authority/path** 
N
fix  
niudongyao 已提交
25
- Scheme: 协议名,对于data share统一为datashare
N
niudongyao 已提交
26
- authority: [userinfo@]host[:port]
N
niudongyao 已提交
27 28 29 30
    - userinfo: 登录信息,不需要填写。
    - host: 服务器地址,如果跨设备访问则为目标设备的ID,如果为本设备则为空。
    - port: 服务器端口,不需要填写。
- path: data share的标识信息和资源的路径信息,需要包含data share的标识信息,资源的路径信息可以不填写。
N
niudongyao 已提交
31 32 33

uri示例:

N
niudongyao 已提交
34
- 不包含资源路径: `datashare:///com.samples.datasharetest.DataShare`
N
niudongyao 已提交
35

N
niudongyao 已提交
36
- 包含资源路径: `datashare:///com.samples.datasharetest.DataShare/DB00/TBL00`
N
niudongyao 已提交
37

N
fix  
niudongyao 已提交
38
其中,data share的标识信息为`com.samples.datasharetest.DataShare`,资源路径为`DB00/TBL00`
N
niudongyao 已提交
39

D
duanweiling 已提交
40 41 42 43
## 属性

**系统能力**:SystemCapability.DistributedDataManager.DataShare.Provider

44
| 名称 | 类型 | 可读 | 可写 | 说明 | 
D
duanweiling 已提交
45
| -------- | -------- | -------- | -------- | -------- |
M
m00512953 已提交
46
| context | [ExtensionContext](js-apis-inner-application-extensionContext.md)  | 是 | 否 |表示数据共享扩展能力上下文。 | 
D
duanweiling 已提交
47

S
songruirui 已提交
48 49
## onCreate

S
songruirui 已提交
50
onCreate?(want: Want, callback: AsyncCallback<void>): void
S
songruirui 已提交
51

S
songruirui 已提交
52
DataShare客户端连接DataShareExtensionAbility服务端时,服务端回调此接口,执行初始化业务逻辑操作。该方法可以选择性重写。
S
songruirui 已提交
53

S
songruirui 已提交
54
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Provider
S
songruirui 已提交
55 56 57

**参数:**

58
| 参数名 | 类型 | 必填 | 说明 |
S
songruirui 已提交
59
| ----- | ------ | ------ | ------ |
60
| want | [Want](js-apis-application-want.md#want) | 是  | Want类型信息,包括Ability名称、Bundle名称等。 |
S
修改  
songruirui 已提交
61
| callback | AsyncCallback<void> | 是 | 回调函数。无返回值。 |
S
songruirui 已提交
62 63 64

**示例:**

S
songruirui 已提交
65
```ts
N
niudongyao 已提交
66
import rdb from '@ohos.data.relationalStore';
S
songruirui 已提交
67

S
songruirui 已提交
68 69
let DB_NAME = "DB00.db";
let TBL_NAME = "TBL00";
70
let DDL_TBL_CREATE = "CREATE TABLE IF NOT EXISTS "
71 72
    + TBL_NAME
    + " (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)";
S
修改  
songruirui 已提交
73
let rdbStore;
S
songruirui 已提交
74

W
wanning.fang 已提交
75
export default class DataShareExtAbility extends DataShareExtensionAbility {
D
duanweiling 已提交
76
    onCreate(want, callback) {
W
wanning.fang 已提交
77 78
        rdb.getRdbStore(this.context, {
            name: DB_NAME
N
niudongyao 已提交
79
        }, function (err, data) {
W
wanning.fang 已提交
80 81 82 83 84 85 86 87
            console.log('getRdbStore done, data : ' + data);
            rdbStore = data;
            rdbStore.executeSql(DDL_TBL_CREATE, [], function (err) {
                console.log('executeSql done, error message : ' + err);
            });
            if (callback) {
                callback();
            }
S
songruirui 已提交
88
        });
W
wanning.fang 已提交
89 90
    }
};
S
songruirui 已提交
91 92 93 94
```

## insert

S
songruirui 已提交
95
insert?(uri: string, valueBucket: ValuesBucket, callback: AsyncCallback<number>): void
S
songruirui 已提交
96

S
songruirui 已提交
97
在数据库插入时回调此接口,该方法可以选择性重写。
S
songruirui 已提交
98

S
修改  
songruirui 已提交
99
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Provider
S
songruirui 已提交
100 101 102

**参数:**

103
| 参数名 | 类型 | 必填 | 说明 |
S
songruirui 已提交
104
| ----- | ------ | ------ | ------ |
S
songruirui 已提交
105
| uri |string | 是  | 指示要插入的数据的路径。 |
M
m00512953 已提交
106
| valueBucket |[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 指示要插入的数据。 |
S
修改  
songruirui 已提交
107
| callback |AsyncCallback<number> | 是 | 回调函数。返回插入数据记录的索引。 |
S
songruirui 已提交
108 109 110

**示例:**

S
songruirui 已提交
111
```ts
112 113 114 115
import rdb from '@ohos.data.rdb';

let DB_NAME = "DB00.db";
let TBL_NAME = "TBL00";
116
let DDL_TBL_CREATE = "CREATE TABLE IF NOT EXISTS "
117 118
    + TBL_NAME
    + " (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)";
119 120
let rdbStore;

W
wanning.fang 已提交
121
export default class DataShareExtAbility extends DataShareExtensionAbility {
D
duanweiling 已提交
122
    insert(uri, valueBucket, callback) {
123
        if (valueBucket == null) {
W
wanning.fang 已提交
124 125
            console.info('invalid valueBuckets');
            return;
S
songruirui 已提交
126
        }
127
        rdbStore.insert(TBL_NAME, valueBucket, function (err, ret) {
W
wanning.fang 已提交
128 129 130 131 132 133 134
            console.info('callback ret:' + ret);
            if (callback != undefined) {
                callback(err, ret);
            }
        });
    }
};
S
songruirui 已提交
135 136
```

S
songruirui 已提交
137
## update
S
songruirui 已提交
138

S
songruirui 已提交
139
update?(uri: string, predicates: dataSharePredicates.DataSharePredicates, valueBucket: ValuesBucket, callback: AsyncCallback<number>): void
S
songruirui 已提交
140

S
songruirui 已提交
141
在数据库更新时服务端回调此接口,该方法可以选择性重写。
S
songruirui 已提交
142

S
修改  
songruirui 已提交
143
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Provider
S
songruirui 已提交
144

S
songruirui 已提交
145
**参数:**
S
songruirui 已提交
146

147
| 参数名 | 类型 | 必填 | 说明 |
S
songruirui 已提交
148 149
| ----- | ------ | ------ | ------ |
| uri | string | 是  | 指示要更新的数据的路径。 |
150
| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是  | 指示筛选条件。 |
M
m00512953 已提交
151
| valueBucket | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 指示要更新的数据。 |
S
修改  
songruirui 已提交
152
| callback | AsyncCallback<number> | 是 | 回调函数。返回更新的数据记录数。 |
S
songruirui 已提交
153 154 155

**示例:**

S
songruirui 已提交
156
```ts
157 158 159 160
import rdb from '@ohos.data.rdb';

let DB_NAME = "DB00.db";
let TBL_NAME = "TBL00";
161
let DDL_TBL_CREATE = "CREATE TABLE IF NOT EXISTS "
162 163
    + TBL_NAME
    + " (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)";
164 165
let rdbStore;

W
wanning.fang 已提交
166
export default class DataShareExtAbility extends DataShareExtensionAbility {
D
duanweiling 已提交
167
    update(uri, predicates, valueBucket, callback) {
W
wanning.fang 已提交
168 169
        if (predicates == null || predicates == undefined) {
            return;
S
songruirui 已提交
170
        }
171
        rdbStore.update(TBL_NAME, valueBucket, predicates, function (err, ret) {
W
wanning.fang 已提交
172 173 174 175 176 177
            if (callback != undefined) {
                callback(err, ret);
            }
        });
    }
};
S
songruirui 已提交
178 179
```

S
songruirui 已提交
180
## delete
S
songruirui 已提交
181

S
songruirui 已提交
182
delete?(uri: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>): void
S
songruirui 已提交
183

S
修改  
songruirui 已提交
184
在删除数据库记录时服务端回调此接口,该方法可以选择性重写。
S
songruirui 已提交
185

S
修改  
songruirui 已提交
186
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Provider
S
songruirui 已提交
187

S
songruirui 已提交
188
**参数:**
S
songruirui 已提交
189

190
| 参数名       | 类型                                                     | 必填 | 说明                               |
S
修改  
songruirui 已提交
191 192
| ---------- | ------------------------------------------------------------ | ---- | ---------------------------------- |
| uri        | string                                                       | 是   | 指示要删除的数据的路径。           |
193
| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是   | 指示筛选条件。                     |
S
修改  
songruirui 已提交
194
| callback   | AsyncCallback<number>                                  | 是   | 回调函数。返回已删除的数据记录数。 |
S
songruirui 已提交
195 196 197

**示例:**

S
songruirui 已提交
198
```ts
199 200 201 202
import rdb from '@ohos.data.rdb';

let DB_NAME = "DB00.db";
let TBL_NAME = "TBL00";
203
let DDL_TBL_CREATE = "CREATE TABLE IF NOT EXISTS "
204 205
    + TBL_NAME
    + " (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)";
206 207
let rdbStore;

W
wanning.fang 已提交
208
export default class DataShareExtAbility extends DataShareExtensionAbility {
D
duanweiling 已提交
209
    delete(uri, predicates, callback) {
W
wanning.fang 已提交
210 211
        if (predicates == null || predicates == undefined) {
            return;
S
songruirui 已提交
212
        }
W
wanning.fang 已提交
213 214 215 216 217 218 219
        rdbStore.delete(TBL_NAME, predicates, function (err, ret) {
            if (callback != undefined) {
                callback(err, ret);
            }
        });
    }
};
S
songruirui 已提交
220 221
```

S
songruirui 已提交
222
## query
S
songruirui 已提交
223

S
songruirui 已提交
224
query?(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: AsyncCallback<Object>): void
S
songruirui 已提交
225

S
songruirui 已提交
226
在查询数据库时服务端回调此接口,该方法可以选择性重写。
S
songruirui 已提交
227

S
修改  
songruirui 已提交
228
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Provider
S
songruirui 已提交
229

S
songruirui 已提交
230 231
**参数:**

232
| 参数名 | 类型 | 必填 | 说明 |
S
songruirui 已提交
233 234
| ----- | ------ | ------ | ------ |
| uri | string | 是  | 指示要查询的数据的路径。 |
235
| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是  | 指示筛选条件。 |
S
songruirui 已提交
236 237
| columns | Array<string> | 是 | 指示要查询的列。如果此参数为空,则查询所有列。 |
| callback | AsyncCallback<Object> | 是 | 回调函数。返回查询到的结果集。 |
S
songruirui 已提交
238 239 240

**示例:**

S
songruirui 已提交
241
```ts
242 243 244 245
import rdb from '@ohos.data.rdb';

let DB_NAME = "DB00.db";
let TBL_NAME = "TBL00";
246
let DDL_TBL_CREATE = "CREATE TABLE IF NOT EXISTS "
247 248
    + TBL_NAME
    + " (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)";
249 250
let rdbStore;

W
wanning.fang 已提交
251
export default class DataShareExtAbility extends DataShareExtensionAbility {
D
duanweiling 已提交
252
    query(uri, predicates, columns, callback) {
W
wanning.fang 已提交
253 254
        if (predicates == null || predicates == undefined) {
            return;
S
songruirui 已提交
255
        }
W
wanning.fang 已提交
256 257 258 259 260 261 262 263 264 265
        rdbStore.query(TBL_NAME, predicates, columns, function (err, resultSet) {
            if (resultSet != undefined) {
                console.info('resultSet.rowCount: ' + resultSet.rowCount);
            }
            if (callback != undefined) {
                callback(err, resultSet);
            }
        });
    }
};
S
songruirui 已提交
266 267
```

D
duanweiling 已提交
268
## batchInsert
S
songruirui 已提交
269

D
duanweiling 已提交
270
batchInsert?(uri: string, valueBuckets: Array<ValuesBucket>, callback: AsyncCallback<number>): void
S
songruirui 已提交
271

S
songruirui 已提交
272
在数据库批量插入时服务端回调此接口,该方法可以选择性重写。
S
songruirui 已提交
273

S
修改  
songruirui 已提交
274
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Provider
S
songruirui 已提交
275

S
songruirui 已提交
276
**参数:**
S
songruirui 已提交
277

278
| 参数名        | 类型                                                     | 必填 | 说明                             |
S
songruirui 已提交
279 280
| ------------ | ------------------------------------------------------------ | ---- | -------------------------------- |
| uri          | string                                                       | 是   | 指示要批量插入的数据的路径。     |
M
m00512953 已提交
281
| valueBuckets | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)> | 是   | 指示要批量插入的数据。           |
S
songruirui 已提交
282
| callback     | AsyncCallback<number>                                  | 是   | 回调函数。返回插入的数据记录数。 |
S
songruirui 已提交
283 284 285

**示例:**

S
songruirui 已提交
286
```ts
287 288 289 290
import rdb from '@ohos.data.rdb';

let DB_NAME = "DB00.db";
let TBL_NAME = "TBL00";
291
let DDL_TBL_CREATE = "CREATE TABLE IF NOT EXISTS "
292 293
    + TBL_NAME
    + " (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)";
294 295
let rdbStore;

W
wanning.fang 已提交
296
export default class DataShareExtAbility extends DataShareExtensionAbility {
D
duanweiling 已提交
297
    batchInsert(uri, valueBuckets, callback) {
W
wanning.fang 已提交
298 299 300 301 302 303 304 305 306 307 308
        if (valueBuckets == null || valueBuckets.length == undefined) {
            console.info('invalid valueBuckets');
            return;
        }
        let resultNum = valueBuckets.length
        valueBuckets.forEach(vb => {
            rdbStore.insert(TBL_NAME, vb, function (err, ret) {
                if (callback != undefined) {
                    callback(err, resultNum);
                }
            });
S
songruirui 已提交
309
        });
W
wanning.fang 已提交
310 311
    }
};
S
songruirui 已提交
312 313
```

S
songruirui 已提交
314
## normalizeUri
S
songruirui 已提交
315

S
songruirui 已提交
316
normalizeUri?(uri: string, callback: AsyncCallback<string>): void
S
songruirui 已提交
317

S
修改  
songruirui 已提交
318
用户给定的URI转换为服务端使用的URI时回调此接口,该方法可以选择性重写。
S
songruirui 已提交
319

S
修改  
songruirui 已提交
320
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Provider
S
songruirui 已提交
321 322

**参数:**
S
songruirui 已提交
323

324
| 参数名     | 类型                  | 必填 | 说明                    |
S
songruirui 已提交
325
| -------- | --------------------- | ---- | ----------------------- |
S
修改  
songruirui 已提交
326
| uri      | string                | 是   | 指示用户传入的[URI](js-apis-uri.md#uri)。 |
S
修改  
songruirui 已提交
327
| callback | AsyncCallback<string> | 是   | 回调函数。如果支持URI规范化,则返回规范化URI,否则返回空。 |
S
songruirui 已提交
328 329 330

**示例:**

S
songruirui 已提交
331
```ts
W
wanning.fang 已提交
332
export default class DataShareExtAbility extends DataShareExtensionAbility {
D
duanweiling 已提交
333
    normalizeUri(uri, callback) {
W
wanning.fang 已提交
334 335 336 337 338
        let err = {"code":0};
        let ret = "normalize+" + uri;
        callback(err, ret);
    }
};
S
songruirui 已提交
339 340
```

S
songruirui 已提交
341
## denormalizeUri
S
songruirui 已提交
342

S
songruirui 已提交
343
denormalizeUri?(uri: string, callback: AsyncCallback<string>): void
S
songruirui 已提交
344

S
修改  
songruirui 已提交
345
服务端使用的URI转换为用户传入的初始URI时服务端回调此接口,该方法可以选择性重写。
S
songruirui 已提交
346

S
修改  
songruirui 已提交
347
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Provider
S
songruirui 已提交
348

S
songruirui 已提交
349
**参数:**
S
songruirui 已提交
350

351
| 参数名     | 类型                  | 必填 | 说明                    |
S
songruirui 已提交
352
| -------- | --------------------- | ---- | ----------------------- |
S
修改  
songruirui 已提交
353
| uri      | string                | 是   | 指示服务端使用的[URI](js-apis-uri.md#uri)。 |
S
修改  
songruirui 已提交
354
| callback | AsyncCallback<string> | 是   | 回调函数。如果反规范化成功,则返回反规范化的URI;如果无需进行反规范化,则返回原始URI;若不支持则返回空。 |
S
songruirui 已提交
355 356 357

**示例:**

S
songruirui 已提交
358
```ts
W
wanning.fang 已提交
359
export default class DataShareExtAbility extends DataShareExtensionAbility {
D
duanweiling 已提交
360
    denormalizeUri(uri, callback) {
W
wanning.fang 已提交
361 362 363 364 365
        let err = {"code":0};
        let ret = "denormalize+" + uri;
        callback(err, ret);
    }
};
S
songruirui 已提交
366
```