js-apis-application-DataShareExtensionAbility.md 15.0 KB
Newer Older
S
songruirui 已提交
1
# 数据共享扩展能力
S
songruirui 已提交
2

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

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


## 导入模块

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

D
duanweiling 已提交
20 21 22 23 24 25 26 27
## 属性

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

| 名称 | 参数类型 | 可读 | 可写 | 说明 | 
| -------- | -------- | -------- | -------- | -------- |
| context | [ExtensionContext](js-apis-extension-context.md)  | 是 | 否 |表示数据共享扩展能力上下文。 | 

S
songruirui 已提交
28 29
## onCreate

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

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

S
songruirui 已提交
34
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Provider
S
songruirui 已提交
35 36 37 38 39

**参数:**

| 参数名 | 参数类型 | 必填 | 说明 |
| ----- | ------ | ------ | ------ |
S
songruirui 已提交
40
| want | [Want](js-apis-application-Want.md#want) | 是  | Want类型信息,包括ability名称、bundle名称等。 |
S
修改  
songruirui 已提交
41
| callback | AsyncCallback<void> | 是 | 回调函数。无返回值。 |
S
songruirui 已提交
42 43 44

**示例:**

S
songruirui 已提交
45
```ts
S
songruirui 已提交
46 47
import rdb from '@ohos.data.rdb';

S
songruirui 已提交
48 49 50 51 52
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, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)";
S
修改  
songruirui 已提交
53
let rdbStore;
S
songruirui 已提交
54

W
wanning.fang 已提交
55
export default class DataShareExtAbility extends DataShareExtensionAbility {
D
duanweiling 已提交
56
    onCreate(want, callback) {
W
wanning.fang 已提交
57 58 59 60 61 62 63 64 65 66 67
        rdb.getRdbStore(this.context, {
            name: DB_NAME
        }, 1, function (err, data) {
            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 已提交
68
        });
W
wanning.fang 已提交
69 70
    }
};
S
songruirui 已提交
71 72
```

S
songruirui 已提交
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91
## getFileTypes

getFileTypes?(uri: string, mimeTypeFilter: string, callback: AsyncCallback<Array<string>>): void

获取支持文件的MIME类型时服务端回调此接口,该方法可以选择性重写。

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

**参数:**

| 名称           | 类型                                     | 必填 | 描述                               |
| -------------- | ---------------------------------------- | ---- | ---------------------------------- |
| uri            | string                                   | 是   | 指示要获取的文件的路径。           |
| mimeTypeFilter | string                                   | 是   | 指示要获取的文件的MIME类型。       |
| callback       | AsyncCallback<Array<string>> | 是   | 回调函数。返回匹配的MIME类型数组。 |

**示例:**

```ts
W
wanning.fang 已提交
92
export default class DataShareExtAbility extends DataShareExtensionAbility {
D
duanweiling 已提交
93
    getFileTypes(uri, mimeTypeFilter, callback) {
W
wanning.fang 已提交
94 95 96 97 98
        let err = {"code":0};
        let ret = new Array("type01", "type02", "type03");
        callback(err, ret);
    }
};
S
songruirui 已提交
99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119
```

## openFile

openFile?(uri: string, mode: string, callback: AsyncCallback<number>): void

在打开文件时服务端回调此接口,该方法可以选择性重写。

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

**参数:**

| 名称     | 类型                  | 必填 | 描述                                       |
| -------- | --------------------- | ---- | ------------------------------------------ |
| uri      | string                | 是   | 指示要打开的文件的路径。        |
| mode     | string                | 是   | 指示文件打开模式,包括只读模式,读写模式。 |
| callback | AsyncCallback<number> | 是   | 回调函数。返回文件描述符。        |

**示例:**

```ts
W
wanning.fang 已提交
120
export default class DataShareExtAbility extends DataShareExtensionAbility {
D
duanweiling 已提交
121
    openFile(uri, mode, callback) {
W
wanning.fang 已提交
122 123 124 125 126
        let err = {"code":0};
        let fd = 0;
        callback(err,fd);
    }
};
S
songruirui 已提交
127 128
```

S
songruirui 已提交
129 130
## insert

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

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

S
修改  
songruirui 已提交
135
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Provider
S
songruirui 已提交
136 137 138 139 140

**参数:**

| 参数名 | 参数类型 | 必填 | 说明 |
| ----- | ------ | ------ | ------ |
S
songruirui 已提交
141
| uri |string | 是  | 指示要插入的数据的路径。 |
S
修改  
songruirui 已提交
142 143
| valueBucket |[ValuesBucket](js-apis-data-ValuesBucket.md#valuesbucket) | 是 | 指示要插入的数据。 |
| callback |AsyncCallback<number> | 是 | 回调函数。返回插入数据记录的索引。 |
S
songruirui 已提交
144 145 146

**示例:**

S
songruirui 已提交
147
```ts
148 149 150 151 152 153 154 155 156
import rdb from '@ohos.data.rdb';

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, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)";
let rdbStore;

W
wanning.fang 已提交
157
export default class DataShareExtAbility extends DataShareExtensionAbility {
D
duanweiling 已提交
158
    insert(uri, valueBucket, callback) {
W
wanning.fang 已提交
159 160 161
        if (value == null) {
            console.info('invalid valueBuckets');
            return;
S
songruirui 已提交
162
        }
W
wanning.fang 已提交
163 164 165 166 167 168 169 170
        rdbStore.insert(TBL_NAME, value, function (err, ret) {
            console.info('callback ret:' + ret);
            if (callback != undefined) {
                callback(err, ret);
            }
        });
    }
};
S
songruirui 已提交
171 172
```

S
songruirui 已提交
173
## update
S
songruirui 已提交
174

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

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

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

S
songruirui 已提交
181
**参数:**
S
songruirui 已提交
182

S
songruirui 已提交
183 184 185
| 参数名 | 参数类型 | 必填 | 说明 |
| ----- | ------ | ------ | ------ |
| uri | string | 是  | 指示要更新的数据的路径。 |
S
修改  
songruirui 已提交
186
| predicates | [DataSharePredicates](js-apis-data-DataSharePredicates.md#datasharepredicates) | 是  | 指示筛选条件。 |
S
songruirui 已提交
187
| valueBucket | [ValuesBucket](js-apis-data-ValuesBucket.md#valuesbucket) | 是 | 指示要更新的数据。 |
S
修改  
songruirui 已提交
188
| callback | AsyncCallback<number> | 是 | 回调函数。返回更新的数据记录数。 |
S
songruirui 已提交
189 190 191

**示例:**

S
songruirui 已提交
192
```ts
193 194 195 196 197 198 199 200 201
import rdb from '@ohos.data.rdb';

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, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)";
let rdbStore;

W
wanning.fang 已提交
202
export default class DataShareExtAbility extends DataShareExtensionAbility {
D
duanweiling 已提交
203
    update(uri, predicates, valueBucket, callback) {
W
wanning.fang 已提交
204 205
        if (predicates == null || predicates == undefined) {
            return;
S
songruirui 已提交
206
        }
W
wanning.fang 已提交
207 208 209 210 211 212 213
        rdbStore.update(TBL_NAME, value, predicates, function (err, ret) {
            if (callback != undefined) {
                callback(err, ret);
            }
        });
    }
};
S
songruirui 已提交
214 215
```

S
songruirui 已提交
216
## delete
S
songruirui 已提交
217

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

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

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

S
songruirui 已提交
224
**参数:**
S
songruirui 已提交
225

S
修改  
songruirui 已提交
226 227 228
| 名称       | 参数类型                                                     | 必填 | 说明                               |
| ---------- | ------------------------------------------------------------ | ---- | ---------------------------------- |
| uri        | string                                                       | 是   | 指示要删除的数据的路径。           |
S
修改  
songruirui 已提交
229
| predicates | [DataSharePredicates](js-apis-data-DataSharePredicates.md#datasharepredicates) | 是   | 指示筛选条件。                     |
S
修改  
songruirui 已提交
230
| callback   | AsyncCallback<number>                                  | 是   | 回调函数。返回已删除的数据记录数。 |
S
songruirui 已提交
231 232 233

**示例:**

S
songruirui 已提交
234
```ts
235 236 237 238 239 240 241 242 243
import rdb from '@ohos.data.rdb';

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, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)";
let rdbStore;

W
wanning.fang 已提交
244
export default class DataShareExtAbility extends DataShareExtensionAbility {
D
duanweiling 已提交
245
    delete(uri, predicates, callback) {
W
wanning.fang 已提交
246 247
        if (predicates == null || predicates == undefined) {
            return;
S
songruirui 已提交
248
        }
W
wanning.fang 已提交
249 250 251 252 253 254 255
        rdbStore.delete(TBL_NAME, predicates, function (err, ret) {
            if (callback != undefined) {
                callback(err, ret);
            }
        });
    }
};
S
songruirui 已提交
256 257
```

S
songruirui 已提交
258
## query
S
songruirui 已提交
259

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

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

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

S
songruirui 已提交
266 267
**参数:**

S
songruirui 已提交
268 269 270 271 272 273
| 名称 | 参数类型 | 必填 | 说明 |
| ----- | ------ | ------ | ------ |
| uri | string | 是  | 指示要查询的数据的路径。 |
| predicates | [DataSharePredicates](js-apis-data-DataSharePredicates.md#datasharepredicates) | 是  | 指示筛选条件。 |
| columns | Array<string> | 是 | 指示要查询的列。如果此参数为空,则查询所有列。 |
| callback | AsyncCallback<Object> | 是 | 回调函数。返回查询到的结果集。 |
S
songruirui 已提交
274 275 276

**示例:**

S
songruirui 已提交
277
```ts
278 279 280 281 282 283 284 285 286
import rdb from '@ohos.data.rdb';

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, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)";
let rdbStore;

W
wanning.fang 已提交
287
export default class DataShareExtAbility extends DataShareExtensionAbility {
D
duanweiling 已提交
288
    query(uri, predicates, columns, callback) {
W
wanning.fang 已提交
289 290
        if (predicates == null || predicates == undefined) {
            return;
S
songruirui 已提交
291
        }
W
wanning.fang 已提交
292 293 294 295 296 297 298 299 300 301
        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 已提交
302 303
```

S
songruirui 已提交
304
## getType
S
songruirui 已提交
305

S
songruirui 已提交
306
getType?(uri: string, callback: AsyncCallback<string>): void
S
songruirui 已提交
307

S
修改  
songruirui 已提交
308
获取给定URI对应的MIME类型时服务端回调此接口,该方法可以选择性重写。
S
songruirui 已提交
309

S
修改  
songruirui 已提交
310
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Provider
S
songruirui 已提交
311 312 313 314 315

**参数:**

| 参数名 | 参数类型 | 必填 | 说明 |
| ----- | ------ | ------ | ------ |
S
songruirui 已提交
316
| uri | string | 是  | 指示要获取MIME类型的数据的路径。 |
S
修改  
songruirui 已提交
317
| callback | AsyncCallback<string> | 是 | 回调函数。返回与URI指定的数据匹配的MIME类型。 |
S
songruirui 已提交
318 319 320

**示例:**

S
songruirui 已提交
321
```ts
W
wanning.fang 已提交
322
export default class DataShareExtAbility extends DataShareExtensionAbility {
D
duanweiling 已提交
323
    getType(uri, callback) {
W
wanning.fang 已提交
324 325 326 327 328
        let err = {"code":0};
        let ret = "image";
        callback(err, ret);
    }
};
S
songruirui 已提交
329 330
```

D
duanweiling 已提交
331
## batchInsert
S
songruirui 已提交
332

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

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

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

S
songruirui 已提交
339
**参数:**
S
songruirui 已提交
340

S
songruirui 已提交
341 342 343 344 345
| 名称         | 参数类型                                                     | 必填 | 说明                             |
| ------------ | ------------------------------------------------------------ | ---- | -------------------------------- |
| uri          | string                                                       | 是   | 指示要批量插入的数据的路径。     |
| valueBuckets | Array<[ValuesBucket](js-apis-data-ValuesBucket.md#valuesbucket)> | 是   | 指示要批量插入的数据。           |
| callback     | AsyncCallback<number>                                  | 是   | 回调函数。返回插入的数据记录数。 |
S
songruirui 已提交
346 347 348

**示例:**

S
songruirui 已提交
349
```ts
350 351 352 353 354 355 356 357 358
import rdb from '@ohos.data.rdb';

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, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)";
let rdbStore;

W
wanning.fang 已提交
359
export default class DataShareExtAbility extends DataShareExtensionAbility {
D
duanweiling 已提交
360
    batchInsert(uri, valueBuckets, callback) {
W
wanning.fang 已提交
361 362 363 364 365 366 367 368 369 370 371
        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 已提交
372
        });
W
wanning.fang 已提交
373 374
    }
};
S
songruirui 已提交
375 376
```

S
songruirui 已提交
377
## normalizeUri
S
songruirui 已提交
378

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

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

S
修改  
songruirui 已提交
383
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Provider
S
songruirui 已提交
384 385

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

S
songruirui 已提交
387 388
| 名称     | 类型                  | 必填 | 描述                    |
| -------- | --------------------- | ---- | ----------------------- |
S
修改  
songruirui 已提交
389
| uri      | string                | 是   | 指示用户传入的[URI](js-apis-uri.md#uri)。 |
S
修改  
songruirui 已提交
390
| callback | AsyncCallback<string> | 是   | 回调函数。如果支持URI规范化,则返回规范化URI,否则返回空。 |
S
songruirui 已提交
391 392 393

**示例:**

S
songruirui 已提交
394
```ts
W
wanning.fang 已提交
395
export default class DataShareExtAbility extends DataShareExtensionAbility {
D
duanweiling 已提交
396
    normalizeUri(uri, callback) {
W
wanning.fang 已提交
397 398 399 400 401
        let err = {"code":0};
        let ret = "normalize+" + uri;
        callback(err, ret);
    }
};
S
songruirui 已提交
402 403
```

S
songruirui 已提交
404
## denormalizeUri
S
songruirui 已提交
405

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

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

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

S
songruirui 已提交
412
**参数:**
S
songruirui 已提交
413

S
songruirui 已提交
414 415
| 名称     | 类型                  | 必填 | 描述                    |
| -------- | --------------------- | ---- | ----------------------- |
S
修改  
songruirui 已提交
416
| uri      | string                | 是   | 指示服务端使用的[URI](js-apis-uri.md#uri)。 |
S
修改  
songruirui 已提交
417
| callback | AsyncCallback<string> | 是   | 回调函数。如果反规范化成功,则返回反规范化的URI;如果无需进行反规范化,则返回原始URI;若不支持则返回空。 |
S
songruirui 已提交
418 419 420

**示例:**

S
songruirui 已提交
421
```ts
W
wanning.fang 已提交
422
export default class DataShareExtAbility extends DataShareExtensionAbility {
D
duanweiling 已提交
423
    denormalizeUri(uri, callback) {
W
wanning.fang 已提交
424 425 426 427 428
        let err = {"code":0};
        let ret = "denormalize+" + uri;
        callback(err, ret);
    }
};
S
songruirui 已提交
429
```