js-apis-application-dataShareExtensionAbility.md 13.3 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
```ts
M
mingxihua 已提交
17
import DataShareExtensionAbility from '@ohos.application.DataShareExtensionAbility';
S
songruirui 已提交
18 19
```

D
duanweiling 已提交
20 21 22 23
## 属性

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

24
| 名称 | 类型 | 可读 | 可写 | 说明 | 
D
duanweiling 已提交
25
| -------- | -------- | -------- | -------- | -------- |
S
srr101 已提交
26
| context<sup>10+</sup> | [ExtensionContext](js-apis-inner-application-extensionContext.md)  | 是 | 否 |表示数据共享扩展能力上下文。继承自[ExtensionContext] |
D
duanweiling 已提交
27

S
songruirui 已提交
28 29
## onCreate

S
songruirui 已提交
30
onCreate?(want: Want, callback: AsyncCallback&lt;void&gt;): 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
| 参数名 | 类型 | 必填 | 说明 |
S
songruirui 已提交
39
| ----- | ------ | ------ | ------ |
40
| want | [Want](js-apis-application-want.md#want) | 是  | Want类型信息,包括Ability名称、Bundle名称等。 |
S
修改  
songruirui 已提交
41
| callback | AsyncCallback&lt;void&gt; | 是 | 回调函数。无返回值。 |
S
songruirui 已提交
42 43 44

**示例:**

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

M
mingxihua 已提交
48 49 50
let DB_NAME = 'DB00.db';
let TBL_NAME = 'TBL00';
let DDL_TBL_CREATE = 'CREATE TABLE IF NOT EXISTS '
51
    + TBL_NAME
M
mingxihua 已提交
52
    + ' (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)';
53
let rdbStore: relationalStore.RdbStore;
S
songruirui 已提交
54

W
wanning.fang 已提交
55
export default class DataShareExtAbility extends DataShareExtensionAbility {
56
    onCreate(want: Want, callback: Function) {
W
wanning.fang 已提交
57
        rdb.getRdbStore(this.context, {
N
niudongyao 已提交
58 59
            name: DB_NAME,
            securityLevel: rdb.SecurityLevel.S1
60
        }, (err, data) => {
S
srr101 已提交
61
            console.info(`getRdbStore done, data : ${data}`);
W
wanning.fang 已提交
62
            rdbStore = data;
63
            rdbStore.executeSql(DDL_TBL_CREATE, [], (err) => {
S
srr101 已提交
64
                console.error(`executeSql done, error message : ${err}`);
W
wanning.fang 已提交
65 66 67 68
            });
            if (callback) {
                callback();
            }
S
songruirui 已提交
69
        });
W
wanning.fang 已提交
70 71
    }
};
S
songruirui 已提交
72 73 74 75
```

## insert

S
songruirui 已提交
76
insert?(uri: string, valueBucket: ValuesBucket, callback: AsyncCallback&lt;number&gt;): void
S
songruirui 已提交
77

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

S
修改  
songruirui 已提交
80
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Provider
S
songruirui 已提交
81 82 83

**参数:**

84
| 参数名 | 类型 | 必填 | 说明 |
S
songruirui 已提交
85
| ----- | ------ | ------ | ------ |
S
songruirui 已提交
86
| uri |string | 是  | 指示要插入的数据的路径。 |
M
m00512953 已提交
87
| valueBucket |[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 指示要插入的数据。 |
S
修改  
songruirui 已提交
88
| callback |AsyncCallback&lt;number&gt; | 是 | 回调函数。返回插入数据记录的索引。 |
S
songruirui 已提交
89 90 91

**示例:**

S
songruirui 已提交
92
```ts
N
niudongyao 已提交
93
import rdb from '@ohos.data.relationalStore';
94
import { ValuesBucket } from '@ohos.data.ValuesBucket'
95

M
mingxihua 已提交
96 97 98
let DB_NAME = 'DB00.db';
let TBL_NAME = 'TBL00';
let DDL_TBL_CREATE = 'CREATE TABLE IF NOT EXISTS '
99
    + TBL_NAME
M
mingxihua 已提交
100
    + ' (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)';
101
let rdbStore: relationalStore.RdbStore;
102

W
wanning.fang 已提交
103
export default class DataShareExtAbility extends DataShareExtensionAbility {
104
    insert(uri: string, valueBucket: ValuesBucket, callback: Function) {
M
mingxihua 已提交
105
        if (valueBucket === null) {
S
srr101 已提交
106
            console.error('invalid valueBuckets');
W
wanning.fang 已提交
107
            return;
S
songruirui 已提交
108
        }
109
        rdbStore.insert(TBL_NAME, valueBucket, (err, ret) => {
S
srr101 已提交
110
            console.info(`callback ret: ${ret}`);
M
mingxihua 已提交
111
            if (callback !== undefined) {
W
wanning.fang 已提交
112 113 114 115 116
                callback(err, ret);
            }
        });
    }
};
S
songruirui 已提交
117 118
```

S
songruirui 已提交
119
## update
S
songruirui 已提交
120

S
songruirui 已提交
121
update?(uri: string, predicates: dataSharePredicates.DataSharePredicates, valueBucket: ValuesBucket, callback: AsyncCallback&lt;number&gt;): void
S
songruirui 已提交
122

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

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

S
songruirui 已提交
127
**参数:**
S
songruirui 已提交
128

129
| 参数名 | 类型 | 必填 | 说明 |
S
songruirui 已提交
130 131
| ----- | ------ | ------ | ------ |
| uri | string | 是  | 指示要更新的数据的路径。 |
132
| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是  | 指示筛选条件。 |
M
m00512953 已提交
133
| valueBucket | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 指示要更新的数据。 |
S
修改  
songruirui 已提交
134
| callback | AsyncCallback&lt;number&gt; | 是 | 回调函数。返回更新的数据记录数。 |
S
songruirui 已提交
135 136 137

**示例:**

S
songruirui 已提交
138
```ts
N
niudongyao 已提交
139
import rdb from '@ohos.data.relationalStore';
140 141
import dataSharePredicates from '@ohos.data.dataSharePredicates';
import { ValuesBucket } from '@ohos.data.ValuesBucket'
142

M
mingxihua 已提交
143 144 145
let DB_NAME = 'DB00.db';
let TBL_NAME = 'TBL00';
let DDL_TBL_CREATE = 'CREATE TABLE IF NOT EXISTS '
146
    + TBL_NAME
M
mingxihua 已提交
147
    + ' (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)';
148
let rdbStore: relationalStore.RdbStore;
149

W
wanning.fang 已提交
150
export default class DataShareExtAbility extends DataShareExtensionAbility {
151
    update(uri: string, predicates: dataSharePredicates.DataSharePredicates, valueBucket: ValuesBucket, callback: Function) {
M
mingxihua 已提交
152
        if (predicates === null || predicates === undefined) {
W
wanning.fang 已提交
153
            return;
S
songruirui 已提交
154
        }
155
        rdbStore.update(TBL_NAME, valueBucket, predicates, (err, ret) => {
M
mingxihua 已提交
156
            if (callback !== undefined) {
W
wanning.fang 已提交
157 158 159 160 161
                callback(err, ret);
            }
        });
    }
};
S
songruirui 已提交
162 163
```

S
songruirui 已提交
164
## delete
S
songruirui 已提交
165

S
songruirui 已提交
166
delete?(uri: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback&lt;number&gt;): void
S
songruirui 已提交
167

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

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

S
songruirui 已提交
172
**参数:**
S
songruirui 已提交
173

174
| 参数名       | 类型                                                     | 必填 | 说明                               |
S
修改  
songruirui 已提交
175 176
| ---------- | ------------------------------------------------------------ | ---- | ---------------------------------- |
| uri        | string                                                       | 是   | 指示要删除的数据的路径。           |
177
| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是   | 指示筛选条件。                     |
S
修改  
songruirui 已提交
178
| callback   | AsyncCallback&lt;number&gt;                                  | 是   | 回调函数。返回已删除的数据记录数。 |
S
songruirui 已提交
179 180 181

**示例:**

S
songruirui 已提交
182
```ts
N
niudongyao 已提交
183
import rdb from '@ohos.data.relationalStore';
184
import dataSharePredicates from '@ohos.data.dataSharePredicates';
185

M
mingxihua 已提交
186 187 188
let DB_NAME = 'DB00.db';
let TBL_NAME = 'TBL00';
let DDL_TBL_CREATE = 'CREATE TABLE IF NOT EXISTS '
189
    + TBL_NAME
M
mingxihua 已提交
190
    + ' (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)';
191
let rdbStore: relationalStore.RdbStore;
192

W
wanning.fang 已提交
193
export default class DataShareExtAbility extends DataShareExtensionAbility {
194
    delete(uri: string, predicates: dataSharePredicates.DataSharePredicates, callback: Function) {
M
mingxihua 已提交
195
        if (predicates === null || predicates === undefined) {
W
wanning.fang 已提交
196
            return;
S
songruirui 已提交
197
        }
198
        rdbStore.delete(TBL_NAME, predicates, (err, ret) => {
M
mingxihua 已提交
199
            if (callback !== undefined) {
W
wanning.fang 已提交
200 201 202 203 204
                callback(err, ret);
            }
        });
    }
};
S
songruirui 已提交
205 206
```

S
songruirui 已提交
207
## query
S
songruirui 已提交
208

S
songruirui 已提交
209
query?(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array&lt;string&gt;, callback: AsyncCallback&lt;Object&gt;): void
S
songruirui 已提交
210

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

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

S
songruirui 已提交
215 216
**参数:**

217
| 参数名 | 类型 | 必填 | 说明 |
S
songruirui 已提交
218 219
| ----- | ------ | ------ | ------ |
| uri | string | 是  | 指示要查询的数据的路径。 |
220
| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是  | 指示筛选条件。 |
S
songruirui 已提交
221 222
| columns | Array&lt;string&gt; | 是 | 指示要查询的列。如果此参数为空,则查询所有列。 |
| callback | AsyncCallback&lt;Object&gt; | 是 | 回调函数。返回查询到的结果集。 |
S
songruirui 已提交
223 224 225

**示例:**

S
songruirui 已提交
226
```ts
N
niudongyao 已提交
227
import rdb from '@ohos.data.relationalStore';
228
import dataSharePredicates from '@ohos.data.dataSharePredicates';
229

M
mingxihua 已提交
230 231 232
let DB_NAME = 'DB00.db';
let TBL_NAME = 'TBL00';
let DDL_TBL_CREATE = 'CREATE TABLE IF NOT EXISTS '
233
    + TBL_NAME
M
mingxihua 已提交
234
    + ' (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)';
235
let rdbStore: relationalStore.RdbStore;
236

W
wanning.fang 已提交
237
export default class DataShareExtAbility extends DataShareExtensionAbility {
238
    query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: Function) {
M
mingxihua 已提交
239
        if (predicates === null || predicates === undefined) {
W
wanning.fang 已提交
240
            return;
S
songruirui 已提交
241
        }
242
        rdbStore.query(TBL_NAME, predicates, columns, (err, resultSet) => {
M
mingxihua 已提交
243
            if (resultSet !== undefined) {
S
srr101 已提交
244
                console.info(`resultSet.rowCount: ${resultSet.rowCount}`);
W
wanning.fang 已提交
245
            }
M
mingxihua 已提交
246
            if (callback !== undefined) {
W
wanning.fang 已提交
247 248 249 250 251
                callback(err, resultSet);
            }
        });
    }
};
S
songruirui 已提交
252 253
```

D
duanweiling 已提交
254
## batchInsert
S
songruirui 已提交
255

D
duanweiling 已提交
256
batchInsert?(uri: string, valueBuckets: Array&lt;ValuesBucket&gt;, callback: AsyncCallback&lt;number&gt;): void
S
songruirui 已提交
257

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

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

S
songruirui 已提交
262
**参数:**
S
songruirui 已提交
263

264
| 参数名        | 类型                                                     | 必填 | 说明                             |
S
songruirui 已提交
265 266
| ------------ | ------------------------------------------------------------ | ---- | -------------------------------- |
| uri          | string                                                       | 是   | 指示要批量插入的数据的路径。     |
M
m00512953 已提交
267
| valueBuckets | Array&lt;[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)&gt; | 是   | 指示要批量插入的数据。           |
S
songruirui 已提交
268
| callback     | AsyncCallback&lt;number&gt;                                  | 是   | 回调函数。返回插入的数据记录数。 |
S
songruirui 已提交
269 270 271

**示例:**

S
songruirui 已提交
272
```ts
N
niudongyao 已提交
273
import rdb from '@ohos.data.relationalStore';
274
import { ValuesBucket } from '@ohos.data.ValuesBucket'
275

M
mingxihua 已提交
276 277 278
let DB_NAME = 'DB00.db';
let TBL_NAME = 'TBL00';
let DDL_TBL_CREATE = 'CREATE TABLE IF NOT EXISTS '
279
    + TBL_NAME
M
mingxihua 已提交
280
    + ' (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)';
281
let rdbStore: relationalStore.RdbStore;
282

W
wanning.fang 已提交
283
export default class DataShareExtAbility extends DataShareExtensionAbility {
284
  batchInsert(uri: string, valueBuckets: Array<ValuesBucket>, callback: Function) {
Y
yuyaozhi 已提交
285 286 287
    if (valueBuckets === null || valueBuckets.length === undefined) {
      console.error('invalid valueBuckets');
      return;
W
wanning.fang 已提交
288
    }
289
    rdbStore.batchInsert(TBL_NAME, valueBuckets, (err, ret) => {
Y
yuyaozhi 已提交
290 291 292 293 294
      if (callback !== undefined) {
        callback(err, ret);
      }
    });
  };
W
wanning.fang 已提交
295
};
S
songruirui 已提交
296 297
```

S
songruirui 已提交
298
## normalizeUri
S
songruirui 已提交
299

S
songruirui 已提交
300
normalizeUri?(uri: string, callback: AsyncCallback&lt;string&gt;): void
S
songruirui 已提交
301

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

S
修改  
songruirui 已提交
304
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Provider
S
songruirui 已提交
305 306

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

308
| 参数名     | 类型                  | 必填 | 说明                    |
S
songruirui 已提交
309
| -------- | --------------------- | ---- | ----------------------- |
S
修改  
songruirui 已提交
310
| uri      | string                | 是   | 指示用户传入的[URI](js-apis-uri.md#uri)。 |
S
修改  
songruirui 已提交
311
| callback | AsyncCallback&lt;string&gt; | 是   | 回调函数。如果支持URI规范化,则返回规范化URI,否则返回空。 |
S
songruirui 已提交
312 313 314

**示例:**

S
songruirui 已提交
315
```ts
W
wanning.fang 已提交
316
export default class DataShareExtAbility extends DataShareExtensionAbility {
317 318 319 320 321 322 323 324 325 326 327
  normalizeUri(uri: string, callback: Function) {
    let key = 'code';
    let value = 0;
    let err: BusinessError = {
      code: value,
      name: key,
      message: key
    };
    let ret: string = `normalize: ${uri}`;
    callback(err, ret);
  }
W
wanning.fang 已提交
328
};
S
songruirui 已提交
329 330
```

S
songruirui 已提交
331
## denormalizeUri
S
songruirui 已提交
332

S
songruirui 已提交
333
denormalizeUri?(uri: string, callback: AsyncCallback&lt;string&gt;): void
S
songruirui 已提交
334

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

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

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

341
| 参数名     | 类型                  | 必填 | 说明                    |
S
songruirui 已提交
342
| -------- | --------------------- | ---- | ----------------------- |
S
修改  
songruirui 已提交
343
| uri      | string                | 是   | 指示服务端使用的[URI](js-apis-uri.md#uri)。 |
S
修改  
songruirui 已提交
344
| callback | AsyncCallback&lt;string&gt; | 是   | 回调函数。如果反规范化成功,则返回反规范化的URI;如果无需进行反规范化,则返回原始URI;若不支持则返回空。 |
S
songruirui 已提交
345 346 347

**示例:**

S
songruirui 已提交
348
```ts
W
wanning.fang 已提交
349
export default class DataShareExtAbility extends DataShareExtensionAbility {
350 351 352 353 354 355 356 357 358 359 360
  denormalizeUri(uri: string, callback: Function) {
    let key = 'code';
    let value = 0;
    let err: BusinessError = {
      code: value,
      name: key,
      message: key
    };
      let ret = `denormalize ${uri}`;
      callback(err, ret);
  }
W
wanning.fang 已提交
361
};
S
songruirui 已提交
362
```