js-apis-data-dataShare.md 35.7 KB
Newer Older
Z
zengyawen 已提交
1
# @ohos.data.dataShare (数据共享)
S
songruirui 已提交
2

S
songruirui 已提交
3
**DataShare**用于应用管理其自身数据,同时支持同个设备上不同应用间的数据共享。
S
songruirui 已提交
4

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


## 导入模块

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

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

S
songruirui 已提交
40 41 42

## dataShare.createDataShareHelper

S
songruirui 已提交
43
createDataShareHelper(context: Context, uri: string, callback: AsyncCallback<DataShareHelper>): void
S
songruirui 已提交
44

S
songruirui 已提交
45
创建DataShareHelper实例。使用callback异步回调。
S
songruirui 已提交
46

M
m00512953 已提交
47 48
使用规则:
 - 调用方应用位于后台时,使用该接口访问DataShareExtension需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限
49
 - 跨应用场景下,目标DataShareExtension的exported属性若配置为false,调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限
M
m00512953 已提交
50 51
 - 组件启动规则详见:[组件启动规则(Stage模型)](../../application-models/component-startup-rules.md)

S
songruirui 已提交
52
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
53 54 55

**参数:**

56
| 参数名   | 类型                                                 | 必填 | 说明                                                         |
S
songruirui 已提交
57
| -------- | -------------------------------------------------------- | ---- | ------------------------------------------------------------ |
N
fix  
niudongyao 已提交
58
| context  | [Context](js-apis-inner-application-context.md#context)        | 是   | 应用的上下文环境。                                           |
S
songruirui 已提交
59
| uri      | string                                                   | 是   | 指示要连接的服务端应用的路径。                               |
S
songruirui 已提交
60
| callback | AsyncCallback<[DataShareHelper](#datasharehelper)> | 是   | 回调函数。当创建DataShareHelper实例成功,err为undefined,data为获取到的DataShareHelper实例;否则为错误对象。 |
S
songruirui 已提交
61

N
niudongyao 已提交
62 63 64 65 66 67 68 69
**错误码:**

以下错误码的详细介绍请参见[数据共享错误码](../errorcodes/errorcode-datashare.md)

| 错误码ID | 错误信息                                             |
| -------- | ---------------------------------------------------- |
| 15700010 | The dataShareHelper is not initialized successfully. |

S
songruirui 已提交
70 71
**示例:**

S
songruirui 已提交
72
```ts
73
import UIAbility from '@ohos.app.ability.UIAbility';
S
songruirui 已提交
74

S
修改  
songruirui 已提交
75 76
let uri = ("datashare:///com.samples.datasharetest.DataShare");
let dataShareHelper;
N
niudongyao 已提交
77 78 79
try {
    dataShare.createDataShareHelper(this.context, uri, (err, data) => {
        if (err != undefined) {
N
niudongyao 已提交
80
            console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
81 82
            return;
        }
S
songruirui 已提交
83
        console.info("createDataShareHelper succeed, data : " + data);
S
修改  
songruirui 已提交
84
        dataShareHelper = data;
N
niudongyao 已提交
85 86
    });
} catch (err) {
N
niudongyao 已提交
87
    console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
88
};
S
songruirui 已提交
89 90
```

S
songruirui 已提交
91 92 93 94
## dataShare.createDataShareHelper

createDataShareHelper(context: Context, uri: string): Promise<DataShareHelper>

S
songruirui 已提交
95
创建DataShareHelper实例。使用Promise异步回调。
S
songruirui 已提交
96

M
m00512953 已提交
97 98
使用规则:
 - 调用方应用位于后台时,使用该接口访问DataShareExtension需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限
99
 - 跨应用场景下,目标DataShareExtension的exported属性若配置为false,调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限
M
m00512953 已提交
100 101
 - 组件启动规则详见:[组件启动规则(Stage模型)](../../application-models/component-startup-rules.md)

S
songruirui 已提交
102 103 104 105
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer

**参数:**

106
| 参数名  | 类型                                          | 必填 | 说明                           |
S
songruirui 已提交
107
| ------- | ------------------------------------------------- | ---- | ------------------------------ |
N
fix  
niudongyao 已提交
108
| context | [Context](js-apis-inner-application-context.md#context) | 是   | 应用的上下文环境。             |
S
songruirui 已提交
109
| uri     | string                                            | 是   | 指示要连接的服务端应用的路径。 |
S
songruirui 已提交
110 111 112

**返回值:**

S
songruirui 已提交
113 114 115
| 类型                                               | 说明                                   |
| -------------------------------------------------- | -------------------------------------- |
| Promise<[DataShareHelper](#datasharehelper)> | Promise对象。返回DataShareHelper实例。 |
S
songruirui 已提交
116

N
niudongyao 已提交
117 118 119 120 121 122 123 124
**错误码:**

以下错误码的详细介绍请参见[数据共享错误码](../errorcodes/errorcode-datashare.md)

| 错误码ID | 错误信息                                             |
| -------- | ---------------------------------------------------- |
| 15700010 | The dataShareHelper is not initialized successfully. |

S
songruirui 已提交
125 126 127
**示例:**

```ts
128
import UIAbility from '@ohos.app.ability.UIAbility';
S
songruirui 已提交
129

S
修改  
songruirui 已提交
130 131
let uri = ("datashare:///com.samples.datasharetest.DataShare");
let dataShareHelper;
N
niudongyao 已提交
132 133 134 135 136
try {
    dataShare.createDataShareHelper(this.context, uri).then((data) => {
        console.info("createDataShareHelper succeed, data : " + data);
        dataShareHelper = data;
    }). catch((err) => {
N
niudongyao 已提交
137
        console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
138 139
    });
} catch (err) {
N
niudongyao 已提交
140
    console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
141
};
S
songruirui 已提交
142 143
```

S
songruirui 已提交
144 145
## DataShareHelper

S
修改  
songruirui 已提交
146
DataShare管理工具实例,可使用此实例访问或管理服务端的数据。在调用DataShareHelper提供的方法前,需要先通过[createDataShareHelper](#datasharecreatedatasharehelper)构建一个实例。
S
songruirui 已提交
147

S
songruirui 已提交
148 149
### on('dataChange')

S
songruirui 已提交
150
on(type: 'dataChange', uri: string, callback: AsyncCallback<void>): void
S
songruirui 已提交
151

S
songruirui 已提交
152 153
订阅指定URI对应数据的数据变更事件。若用户(订阅者)已注册了观察者,当有其他用户触发了变更通知时(调用了下文中的notifyChange方法),订阅者将会接收到callback通知。使用callback异步回调。

S
songruirui 已提交
154
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
155 156 157

**参数:**

158
| 参数名     | 类型                 | 必填 | 说明                    |
S
songruirui 已提交
159
| -------- | -------------------- | ---- | ------------------------ |
S
songruirui 已提交
160 161
| type     | string               | 是   | 订阅的事件/回调类型,支持的事件为'dataChange',当数据更改时,触发该事件。 |
| uri      | string               | 是   | 表示指定的数据路径。 |
S
songruirui 已提交
162
| callback | AsyncCallback<void> | 是   | 回调函数。当有其他用户触发了变更通知时调用,err为undefined;否则不被触发或为错误对象。 |
S
songruirui 已提交
163 164 165

**示例:**

S
songruirui 已提交
166
```ts
167 168
import UIAbility from '@ohos.app.ability.UIAbility';

S
修改  
songruirui 已提交
169
function onCallback() {
S
songruirui 已提交
170 171
    console.info("**** Observer on callback ****");
}
S
songruirui 已提交
172
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
修改  
songruirui 已提交
173
dataShareHelper.on("dataChange", uri, onCallback);
S
songruirui 已提交
174 175 176 177
```

### off('dataChange')

S
songruirui 已提交
178
off(type: 'dataChange', uri: string, callback?: AsyncCallback<void>): void
S
songruirui 已提交
179

N
fix  
niudongyao 已提交
180
取消订阅指定URI下指定callback对应的数据资源的变更通知。
S
songruirui 已提交
181

S
songruirui 已提交
182
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
183

S
songruirui 已提交
184 185
**参数:**

186
| 参数名     | 类型                 | 必填 | 说明                    |
S
songruirui 已提交
187
| -------- | -------------------- | ---- | ------------------------ |
S
songruirui 已提交
188 189
| type     | string               | 是   | 取消订阅的事件/回调类型,支持的事件为'dataChange'。 |
| uri      | string               | 是   | 表示指定的数据路径。 |
N
fix  
niudongyao 已提交
190
| callback | AsyncCallback<void> | 否   | 表示指定取消订阅的callback通知,如果为空,则取消订阅该uri下所有的通知事件。 |
S
songruirui 已提交
191 192 193

**示例:**

S
songruirui 已提交
194
```ts
195 196
import UIAbility from '@ohos.app.ability.UIAbility';

N
fix  
niudongyao 已提交
197 198
function callback() {
    console.info("**** Observer callback ****");
S
songruirui 已提交
199
}
S
songruirui 已提交
200
let uri = ("datashare:///com.samples.datasharetest.DataShare");
N
fix  
niudongyao 已提交
201 202
dataShareHelper.on("dataChange", uri, callback);
dataShareHelper.off("dataChange", uri, callback);
S
songruirui 已提交
203 204
```

S
songruirui 已提交
205
### insert
S
songruirui 已提交
206

S
songruirui 已提交
207
insert(uri: string, value: ValuesBucket, callback: AsyncCallback<number>): void
S
songruirui 已提交
208

S
songruirui 已提交
209
将单条数据插入数据库。使用callback异步回调。
S
songruirui 已提交
210

S
songruirui 已提交
211
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
212 213 214

**参数:**

215
| 参数名     | 类型                                                      | 必填 | 说明                                                        |
S
songruirui 已提交
216 217
| -------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| uri      | string                                                    | 是   | 指示要插入的数据的路径。                                     |
Z
zhongjianfei 已提交
218
| value    | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是   | 指示要插入的数据。如果此参数为空,将插入一个空行。           |
S
songruirui 已提交
219
| callback | AsyncCallback&lt;number&gt;                               | 是   | 回调函数。当将单条数据插入数据库成功,err为undefined,data为获取到的插入数据记录的索引;否则为错误对象。<br />因部分数据库(如KVDB)的相应接口并不支持返回索引,故若服务端使用了不支持索引的数据库,则此callback也无法返回索引值。 |
S
songruirui 已提交
220 221 222 223

**示例:**

```ts
224 225
import UIAbility from '@ohos.app.ability.UIAbility';

S
songruirui 已提交
226
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
227 228 229 230 231
const valueBucket = {
    "name": "rose",
    "age": 22,
    "salary": 200.5,
}
N
niudongyao 已提交
232 233 234
try {
    dataShareHelper.insert(uri, valueBucket, (err, data) => {
        if (err != undefined) {
N
niudongyao 已提交
235
            console.error(`insert error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
236 237 238 239 240
            return;
        }
        console.info("insert succeed, data : " + data);
    });
} catch (err) {
N
niudongyao 已提交
241
    console.error(`insert error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
242
};
S
songruirui 已提交
243 244
```

S
songruirui 已提交
245
### insert
S
songruirui 已提交
246

S
songruirui 已提交
247
insert(uri: string, value: ValuesBucket): Promise&lt;number&gt;
S
songruirui 已提交
248

S
songruirui 已提交
249
将单条数据插入数据库。使用Promise异步回调。
S
songruirui 已提交
250

S
songruirui 已提交
251
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
252 253 254

**参数:**

255
| 参数名  | 类型                                                      | 必填 | 说明                                               |
S
songruirui 已提交
256 257
| ----- | --------------------------------------------------------- | ---- | -------------------------------------------------- |
| uri   | string                                                    | 是   | 指示要插入的数据的路径。                           |
Z
zhongjianfei 已提交
258
| value | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是   | 指示要插入的数据。如果此参数为空,将插入一个空行。 |
S
songruirui 已提交
259 260 261

**返回值:**

S
songruirui 已提交
262 263 264
| 类型             | 说明                                                         |
| ---------------- | ------------------------------------------------------------ |
| Promise&lt;number&gt; | Promise对象。返回插入数据记录的索引。<br />因部分数据库(如KVDB)的相应接口并不支持返回索引,故若服务端使用了不支持索引的数据库,则此Promise也无法返回索引值。 |
S
songruirui 已提交
265 266 267 268

**示例:**

```ts
269 270
import UIAbility from '@ohos.app.ability.UIAbility';

S
songruirui 已提交
271
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
272 273 274 275 276
const valueBucket = {
    "name": "rose1",
    "age": 221,
    "salary": 20.5,
}
N
niudongyao 已提交
277 278 279 280
try {
    dataShareHelper.insert(uri, valueBucket).then((data) => {
        console.log("insert succeed, data : " + data);
    }). catch((err) => {
N
niudongyao 已提交
281
        console.error(`insert error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
282 283
    });
} catch (err) {
N
niudongyao 已提交
284
    console.error(`insert error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
285
};
S
songruirui 已提交
286 287
```

S
songruirui 已提交
288
### delete
S
songruirui 已提交
289

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

S
songruirui 已提交
292
从数据库中删除一条或多条数据记录。使用callback异步回调。
S
songruirui 已提交
293

S
songruirui 已提交
294
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
295 296 297

**参数:**

298
| 参数名       | 类型                                                         | 必填 | 说明                                                         |
S
songruirui 已提交
299 300
| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| uri        | string                                                       | 是   | 指示要删除的数据的路径。                                     |
301
| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是   | 指示筛选条件。<br />delete接口所支持的谓词方法取决于服务端所选用的数据库,如KVDB的删除目前仅支持inKeys谓词。 |
S
songruirui 已提交
302
| callback   | AsyncCallback&lt;number&gt;                                  | 是   | 回调函数。当从数据库中删除一条或多条数据记录成功,err为undefined,data为获取到的已删除的数据记录数;否则为错误对象。<br />因部分数据库(如KVDB)的相应接口并不提供相应支持,故若服务端使用此数据库,则此callback也无法返回删除的数据记录数。 |
S
songruirui 已提交
303 304 305

**示例:**

S
songruirui 已提交
306
```ts
307 308
import UIAbility from '@ohos.app.ability.UIAbility';
import dataSharePredicates from '@ohos.data.dataSharePredicates';
S
songruirui 已提交
309

S
songruirui 已提交
310
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
311 312
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
N
niudongyao 已提交
313 314 315
try {
    dataShareHelper.delete(uri, da, (err, data) => {
        if (err != undefined) {
N
niudongyao 已提交
316
            console.error(`delete error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
317 318 319 320 321
            return;
        }
        console.info("delete succeed, data : " + data);
    });
} catch (err) {
N
niudongyao 已提交
322
    console.error(`delete error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
323
};
S
songruirui 已提交
324 325
```

S
songruirui 已提交
326
### delete
S
songruirui 已提交
327

S
songruirui 已提交
328
delete(uri: string, predicates: dataSharePredicates.DataSharePredicates): Promise&lt;number&gt;
S
songruirui 已提交
329

S
songruirui 已提交
330
从数据库中删除一条或多条数据记录。使用Promise异步回调。
S
songruirui 已提交
331

S
songruirui 已提交
332
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
333 334 335

**参数:**

336
| 参数名       | 类型                                                         | 必填 | 说明                                                         |
S
songruirui 已提交
337 338
| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| uri        | string                                                       | 是   | 指示要删除的数据的路径。                                     |
339
| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是   | 指示筛选条件。<br />delete接口所支持的谓词方法取决于服务端所选用的数据库,如KVDB的删除目前仅支持inKeys谓词。 |
S
songruirui 已提交
340 341 342

**返回值:**

S
songruirui 已提交
343 344 345
| 类型             | 说明                                                         |
| ---------------- | ------------------------------------------------------------ |
| Promise&lt;number&gt; | Promise对象。返回已删除的数据记录数。<br />因部分数据库(如KVDB)的相应接口并不提供相应支持,故若服务端使用此数据库,则此Promise也无法返回删除的数据记录数。 |
S
songruirui 已提交
346 347 348

**示例:**

S
songruirui 已提交
349
```ts
350 351
import UIAbility from '@ohos.app.ability.UIAbility';
import dataSharePredicates from '@ohos.data.dataSharePredicates';
S
songruirui 已提交
352

S
songruirui 已提交
353
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
354 355
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
N
niudongyao 已提交
356 357 358 359
try {
    dataShareHelper.delete(uri, da).then((data) =>  {
        console.log("delete succeed, data : " + data);
    }). catch((err) => {
N
niudongyao 已提交
360
        console.error(`delete error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
361 362
    });
} catch (err) {
N
niudongyao 已提交
363
    console.error(`delete error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
364
};
S
songruirui 已提交
365 366
```

S
songruirui 已提交
367
### query
S
songruirui 已提交
368

S
songruirui 已提交
369
query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array&lt;string&gt;, callback: AsyncCallback&lt;DataShareResultSet&gt;): void
S
songruirui 已提交
370

S
songruirui 已提交
371
查询数据库中的数据。使用callback异步回调。
S
songruirui 已提交
372

S
songruirui 已提交
373
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
374

S
songruirui 已提交
375 376
**参数:**

377
| 参数名       | 类型                                                         | 必填 | 说明                                                         |
S
songruirui 已提交
378 379
| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| uri        | string                                                       | 是   | 指示要查询的数据的路径。                                     |
380
| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是   | 指示筛选条件。<br />query接口所支持的谓词方法取决于服务端所选用的数据库,如KVDB目前仅支持inKeys和prefixKey。 |
S
songruirui 已提交
381 382
| columns    | Array&lt;string&gt;                                          | 是   | 指示要查询的列。如果此参数为空,则查询所有列。               |
| callback   | AsyncCallback&lt;[DataShareResultSet](js-apis-data-DataShareResultSet.md#datashareresultset)&gt; | 是   | 回调函数。当查询数据库中的数据成功,err为undefined,data为获取到的查询到的结果集;否则为错误对象。 |
S
songruirui 已提交
383 384 385

**示例:**

S
songruirui 已提交
386
```ts
387 388
import UIAbility from '@ohos.app.ability.UIAbility';
import dataSharePredicates from '@ohos.data.dataSharePredicates';
S
songruirui 已提交
389

S
songruirui 已提交
390
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
391 392 393
let columns = ["*"];
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
N
niudongyao 已提交
394 395 396
try {
    dataShareHelper.query(uri, da, columns, (err, data) => {
        if (err != undefined) {
N
niudongyao 已提交
397
            console.error(`query error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
398 399
            return;
        }
S
songruirui 已提交
400
        console.log("query succeed, rowCount : " + data.rowCount);
N
niudongyao 已提交
401 402
    });
} catch (err) {
N
niudongyao 已提交
403
    console.error(`query error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
404
};
S
songruirui 已提交
405 406
```

S
songruirui 已提交
407
### query
S
songruirui 已提交
408

S
songruirui 已提交
409
query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array&lt;string&gt;): Promise&lt;DataShareResultSet&gt;
S
songruirui 已提交
410

S
songruirui 已提交
411
查询数据库中的数据。使用Promise异步回调。
S
songruirui 已提交
412

S
songruirui 已提交
413
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
414

S
songruirui 已提交
415 416
**参数:**

417
| 参数名       | 类型                                                         | 必填 | 说明                                                         |
S
songruirui 已提交
418 419
| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| uri        | string                                                       | 是   | 指示要查询的数据的路径。                                     |
420
| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是   | 指示筛选条件。<br />query接口所支持的谓词方法取决于服务端所选用的数据库,如KVDB目前仅支持inKeys和prefixKey。 |
S
songruirui 已提交
421
| columns    | Array&lt;string&gt;                                          | 是   | 指示要查询的列。如果此参数为空,则查询所有列。               |
S
songruirui 已提交
422 423 424

**返回值:**

S
songruirui 已提交
425 426 427
| 类型                                                         | 说明                              |
| ------------------------------------------------------------ | --------------------------------- |
| Promise&lt;[DataShareResultSet](js-apis-data-DataShareResultSet.md#datashareresultset)&gt; | Promise对象。返回查询到的结果集。 |
S
songruirui 已提交
428 429 430

**示例:**

S
songruirui 已提交
431
```ts
432 433
import UIAbility from '@ohos.app.ability.UIAbility';
import dataSharePredicates from '@ohos.data.dataSharePredicates';
S
songruirui 已提交
434

S
songruirui 已提交
435
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
436 437 438
let columns = ["*"];
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
N
niudongyao 已提交
439 440 441 442
try {
    dataShareHelper.query(uri, da, columns).then((data) =>  {
        console.log("query succeed, rowCount : " + data.rowCount);
    }). catch((err) => {
N
niudongyao 已提交
443
        console.error(`query error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
444 445
    });
} catch (err) {
N
niudongyao 已提交
446
    console.error(`query error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
447
};
S
songruirui 已提交
448 449
```

S
songruirui 已提交
450
### update
S
songruirui 已提交
451

S
songruirui 已提交
452
update(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket, callback: AsyncCallback&lt;number&gt;): void
S
songruirui 已提交
453

S
songruirui 已提交
454
更新数据库中的数据记录。使用callback异步回调。
S
songruirui 已提交
455

S
songruirui 已提交
456
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
457 458 459

**参数:**

460
| 参数名       | 类型                                                         | 必填 | 说明                                                         |
S
songruirui 已提交
461 462
| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| uri        | string                                                       | 是   | 指示要更新的数据的路径。                                     |
463
| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是   | 指示筛选条件。<br />update接口是否支持谓词筛选条件取决于服务端所选用的数据库,如KVDB目前并不支持谓词筛选条件,仅RDB支持。 |
Z
zhongjianfei 已提交
464
| value      | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)    | 是   | 指示要更新的数据。                                           |
S
songruirui 已提交
465
| callback   | AsyncCallback&lt;number&gt;                                  | 是   | 回调函数。当更新数据库中的数据记录成功,err为undefined,data为获取到的更新的数据记录数;否则为错误对象。<br />因部分数据库(如KVDB)的相应接口并不提供相应支持,故若服务端使用此数据库,则此callback也无法返回更新的数据记录数。 |
S
songruirui 已提交
466 467 468

**示例:**

S
songruirui 已提交
469
```ts
470 471
import UIAbility from '@ohos.app.ability.UIAbility';
import dataSharePredicates from '@ohos.data.dataSharePredicates';
S
songruirui 已提交
472

S
songruirui 已提交
473
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
474 475 476 477 478 479 480 481
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
const va = {
    "name": "roe1",
    "age": 21,
    "salary": 20.5,
   
}
N
niudongyao 已提交
482 483 484
try {
    dataShareHelper.update(uri, da, va, (err, data) => {
        if (err != undefined) {
N
niudongyao 已提交
485
            console.error(`update error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
486 487
            return;
        }
S
songruirui 已提交
488
        console.log("update succeed, data : " + data);
N
niudongyao 已提交
489 490
    });
} catch (err) {
N
niudongyao 已提交
491
    console.error(`update error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
492
};
S
songruirui 已提交
493 494
```

S
songruirui 已提交
495
### update
S
songruirui 已提交
496

S
songruirui 已提交
497
update(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket): Promise&lt;number&gt;
S
songruirui 已提交
498

S
songruirui 已提交
499
更新数据库中的数据记录。使用Promise异步回调。
S
songruirui 已提交
500

S
songruirui 已提交
501
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
502 503 504

**参数:**

505
| 参数名       | 类型                                                         | 必填 | 说明                                                         |
S
songruirui 已提交
506 507
| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| uri        | string                                                       | 是   | 指示要更新的数据的路径。                                     |
508
| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是   | 指示筛选条件。<br />update接口是否支持谓词筛选条件取决于服务端所选用的数据库,如KVDB目前并不支持谓词筛选条件,仅RDB支持。 |
Z
zhongjianfei 已提交
509
| value      | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)    | 是   | 指示要更新的数据。                                           |
S
songruirui 已提交
510 511 512

**返回值:**

S
songruirui 已提交
513 514 515
| 类型             | 说明                                                         |
| ---------------- | ------------------------------------------------------------ |
| Promise&lt;number&gt; | Promise对象。返回更新的数据记录数。<br />因部分数据库(如KVDB)的相应接口并不提供相应支持,故若服务端使用此数据库,则此Promise也无法返回更新的数据记录数。 |
S
songruirui 已提交
516 517 518

**示例:**

S
songruirui 已提交
519
```ts
520 521
import UIAbility from '@ohos.app.ability.UIAbility';
import dataSharePredicates from '@ohos.data.dataSharePredicates';
S
songruirui 已提交
522

S
songruirui 已提交
523
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
524 525 526 527 528 529 530 531
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
const va = {
    "name": "roe1",
    "age": 21,
    "salary": 20.5,
   
}
N
niudongyao 已提交
532 533 534 535
try {
    dataShareHelper.update(uri, da, va).then((data) =>  {
        console.log("update succeed, data : " + data);
    }). catch((err) => {
N
niudongyao 已提交
536
        console.error(`update error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
537 538
    });
} catch (err) {
N
niudongyao 已提交
539
    console.error(`update error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
540
};
S
songruirui 已提交
541 542
```

S
songruirui 已提交
543
### batchInsert
S
songruirui 已提交
544

S
songruirui 已提交
545
batchInsert(uri: string, values: Array&lt;ValuesBucket&gt;, callback: AsyncCallback&lt;number&gt;): void
S
songruirui 已提交
546

S
songruirui 已提交
547
将批量数据插入数据库。使用callback异步回调。
S
songruirui 已提交
548

S
songruirui 已提交
549
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
550 551 552

**参数:**

553
| 参数名     | 类型                                                         | 必填 | 说明                                                         |
S
songruirui 已提交
554 555
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| uri      | string                                                       | 是   | 指示要插入的数据的路径。                                     |
Z
zhongjianfei 已提交
556
| values   | Array&lt;[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)&gt; | 是   | 指示要插入的数据。                                           |
S
songruirui 已提交
557
| callback | AsyncCallback&lt;number&gt;                                  | 是   | 回调函数。当将批量数据插入数据库成功,err为undefined,data为获取到的插入的数据记录数;否则为错误对象。<br />因部分数据库(如KVDB)的相应接口并不提供相应支持,故若服务端使用此数据库,则此Promise也无法返回插入的数据记录数。 |
S
songruirui 已提交
558 559 560

**示例:**

S
songruirui 已提交
561
```ts
562 563
import UIAbility from '@ohos.app.ability.UIAbility';

S
songruirui 已提交
564
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
565 566 567
let vbs = new Array({"name": "roe11", "age": 21, "salary": 20.5,},
                     {"name": "roe12", "age": 21, "salary": 20.5,},
                     {"name": "roe13", "age": 21, "salary": 20.5,})
N
niudongyao 已提交
568 569 570
try {
    dataShareHelper.batchInsert(uri, vbs, (err, data) => {
        if (err != undefined) {
N
niudongyao 已提交
571
            console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
572 573
            return;
        }
S
songruirui 已提交
574
        console.log("batchInsert succeed, data : " + data);
N
niudongyao 已提交
575 576
    });
} catch (err) {
N
niudongyao 已提交
577
    console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
578
};
S
songruirui 已提交
579 580
```

S
songruirui 已提交
581
### batchInsert
S
songruirui 已提交
582

S
songruirui 已提交
583
batchInsert(uri: string, values: Array&lt;ValuesBucket&gt;): Promise&lt;number&gt;
S
songruirui 已提交
584

S
songruirui 已提交
585
将批量数据插入数据库。使用Promise异步回调。
S
songruirui 已提交
586

S
songruirui 已提交
587
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
588 589 590

**参数:**

591
| 参数名   | 类型                                                         | 必填 | 说明                     |
S
songruirui 已提交
592 593
| ------ | ------------------------------------------------------------ | ---- | ------------------------ |
| uri    | string                                                       | 是   | 指示要插入的数据的路径。 |
Z
zhongjianfei 已提交
594
| values | Array&lt;[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)&gt; | 是   | 指示要插入的数据。       |
S
songruirui 已提交
595 596 597

**返回值:**

S
songruirui 已提交
598 599 600
| 类型             | 说明                                                         |
| ---------------- | ------------------------------------------------------------ |
| Promise&lt;number&gt; | Promise对象。返回插入的数据记录数。<br />因部分数据库(如KVDB)的相应接口并不提供相应支持,故若服务端使用此数据库,则此Promise也无法返回插入的数据记录数。 |
S
songruirui 已提交
601 602 603

**示例:**

S
songruirui 已提交
604
```ts
605 606
import UIAbility from '@ohos.app.ability.UIAbility';

S
songruirui 已提交
607
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
608 609 610
let vbs = new Array({"name": "roe11", "age": 21, "salary": 20.5,},
                     {"name": "roe12", "age": 21, "salary": 20.5,},
                     {"name": "roe13", "age": 21, "salary": 20.5,})
N
niudongyao 已提交
611 612 613 614
try {
    dataShareHelper.batchInsert(uri, vbs).then((data) =>  {
        console.log("batchInsert succeed, data : " + data);
    }). catch((err) => {
N
niudongyao 已提交
615
        console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
616 617
    });
} catch (err) {
N
niudongyao 已提交
618
    console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
619
};
S
songruirui 已提交
620 621
```

S
songruirui 已提交
622
### normalizeUri
S
songruirui 已提交
623

S
songruirui 已提交
624
normalizeUri(uri: string, callback: AsyncCallback&lt;string&gt;): void
S
songruirui 已提交
625

S
songruirui 已提交
626
将给定的DataShare URI转换为规范化URI,规范化URI可供跨设备使用,DataShare  URI仅供本地环境中使用。使用callback异步回调。
S
songruirui 已提交
627

S
songruirui 已提交
628
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
629 630 631

**参数:**

632
| 参数名     | 类型                   | 必填 | 说明                                                     |
S
songruirui 已提交
633 634 635
| -------- | ---------------------- | ---- | -------------------------------------------------------- |
| uri      | string                 | 是   | 指示要规范化的[URI](js-apis-uri.md#uri)。      |
| callback | AsyncCallback&lt;string&gt; | 是   | 回调函数。当将给定的DataShare URI转换为规范化URI成功,err为undefined,data为获取到的规范化URI(如果支持URI规范化,则返回规范化URI,否则返回空);否则为错误对象。 |
S
songruirui 已提交
636 637 638

**示例:**

S
songruirui 已提交
639
```ts
640 641
import UIAbility from '@ohos.app.ability.UIAbility';

S
songruirui 已提交
642
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
643
dataShareHelper.normalizeUri(uri, (err, data) => {
S
songruirui 已提交
644
    if (err != undefined) {
S
songruirui 已提交
645
        console.log("normalizeUri failed, error message : " + err);
S
songruirui 已提交
646
    }else{
S
songruirui 已提交
647
        console.log("normalizeUri = " + data);
S
songruirui 已提交
648
    }
S
songruirui 已提交
649 650 651
});
```

S
songruirui 已提交
652
### normalizeUri
S
songruirui 已提交
653

S
songruirui 已提交
654
normalizeUri(uri: string): Promise&lt;string&gt;
S
songruirui 已提交
655

S
songruirui 已提交
656
将给定的DataShare URI转换为规范化URI,规范化URI可供跨设备使用,DataShare  URI仅供本地环境中使用。使用Promise异步回调。
S
songruirui 已提交
657

S
songruirui 已提交
658
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
659 660 661

**参数:**

662
| 参数名 | 类型   | 必填 | 说明                                      |
S
songruirui 已提交
663 664
| ---- | ------ | ---- | ----------------------------------------- |
| uri  | string | 是   | 指示要规范化的[URI](js-apis-uri.md#uri)。 |
S
songruirui 已提交
665 666 667

**返回值:**

S
songruirui 已提交
668 669 670
| 类型             | 说明                                           |
| ---------------- | ---------------------------------------------- |
| Promise&lt;string&gt; | Promise对象。如果支持URI规范化,则返回规范化URI,否则返回空。 |
S
songruirui 已提交
671 672 673

**示例:**

S
songruirui 已提交
674
```ts
675 676
import UIAbility from '@ohos.app.ability.UIAbility';

S
songruirui 已提交
677
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
678 679
dataShareHelper.normalizeUri(uri).then((data) => {
    console.log("normalizeUri = " + data);
S
songruirui 已提交
680
}).catch((err) => {
S
songruirui 已提交
681
    console.log("normalizeUri failed, error message : " + err);
S
songruirui 已提交
682 683 684
});
```

S
songruirui 已提交
685
### denormalizeUri
S
songruirui 已提交
686

S
songruirui 已提交
687
denormalizeUri(uri: string, callback: AsyncCallback&lt;string&gt;): void
S
songruirui 已提交
688

S
songruirui 已提交
689
将指定的URI转换为非规范化URI。使用callback异步回调。
S
songruirui 已提交
690

S
songruirui 已提交
691
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
692

S
songruirui 已提交
693 694
**参数:**

695
| 参数名     | 类型                   | 必填 | 说明                                                |
S
songruirui 已提交
696 697 698
| -------- | ---------------------- | ---- | --------------------------------------------------- |
| uri      | string                 | 是   | 指示要反规范化的[URI](js-apis-uri.md#uri)。 |
| callback | AsyncCallback&lt;string&gt; | 是   | 回调函数。当将指定的URI转换为非规范化URI,err为undefined,data为获取到的反规范化URI(如果反规范化成功,则返回反规范化的URI;如果无需进行反规范化,则返回原始URI;若不支持则返回空);否则为错误对象。 |
S
songruirui 已提交
699 700 701

**示例:**

S
songruirui 已提交
702
```ts
703 704
import UIAbility from '@ohos.app.ability.UIAbility';

S
songruirui 已提交
705
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
706
dataShareHelper.denormalizeUri(uri, (err, data) => {
S
songruirui 已提交
707
    if (err != undefined) {
S
songruirui 已提交
708
        console.log("denormalizeUri failed, error message : " + err);
S
songruirui 已提交
709
    }else{
S
songruirui 已提交
710
        console.log("denormalizeUri = " + data);
S
songruirui 已提交
711
    }
S
songruirui 已提交
712 713 714
});
```

S
songruirui 已提交
715
### denormalizeUri
S
songruirui 已提交
716

S
songruirui 已提交
717
denormalizeUri(uri: string): Promise&lt;string&gt;
S
songruirui 已提交
718

S
songruirui 已提交
719
将指定的URI转换为非规范化URI。使用Promise异步回调。
S
songruirui 已提交
720

S
songruirui 已提交
721
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
722

S
songruirui 已提交
723 724
**参数:**

725
| 参数名 | 类型   | 必填 | 说明                                        |
S
songruirui 已提交
726 727
| ---- | ------ | ---- | ------------------------------------------- |
| uri  | string | 是   | 指示要反规范化的[URI](js-apis-uri.md#uri)。 |
S
songruirui 已提交
728 729 730

**返回值:**

S
songruirui 已提交
731 732 733
| 类型             | 说明                                      |
| ---------------- | ----------------------------------------- |
| Promise&lt;string&gt; | Promise对象。如果反规范化成功,则返回反规范化的URI;如果无需执行任何操作,则返回原始URI;若不支持则返回空。 |
S
songruirui 已提交
734 735 736

**示例:**

S
songruirui 已提交
737
```ts
738 739
import UIAbility from '@ohos.app.ability.UIAbility';

S
songruirui 已提交
740
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
741 742
dataShareHelper.denormalizeUri(uri).then((data) => {
    console.log("denormalizeUri = " + data);
S
songruirui 已提交
743
}).catch((err) => {
S
songruirui 已提交
744
    console.log("denormalizeUri failed, error message : " + err);
S
songruirui 已提交
745 746 747
});
```

S
songruirui 已提交
748
### notifyChange
S
songruirui 已提交
749

S
songruirui 已提交
750
notifyChange(uri: string, callback: AsyncCallback&lt;void&gt;): void
S
songruirui 已提交
751

S
songruirui 已提交
752
通知已注册的观察者指定URI对应的数据资源已发生变更。使用callback异步回调。
S
songruirui 已提交
753

S
songruirui 已提交
754
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
755

S
songruirui 已提交
756 757
**参数:**

758
| 参数名    | 类型                 | 必填 | 说明                     |
S
songruirui 已提交
759 760 761
| -------- | -------------------- | ---- | ------------------------ |
| uri      | string               | 是   | 表示指定的数据路径。 |
| callback | AsyncCallback&lt;void&gt; | 是   | 回调函数。当通知已注册的观察者指定URI对应的数据资源已发生变更成功,err为undefined;否则为错误对象。 |
S
songruirui 已提交
762 763 764

**示例:**

S
songruirui 已提交
765
```ts
766 767
import UIAbility from '@ohos.app.ability.UIAbility';

S
songruirui 已提交
768
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
769 770
dataShareHelper.notifyChange(uri, () => {
    console.log("***** notifyChange *****");
S
songruirui 已提交
771 772 773
});
```

S
songruirui 已提交
774
### notifyChange
S
songruirui 已提交
775

S
songruirui 已提交
776
notifyChange(uri: string): Promise&lt;void&gt;
S
songruirui 已提交
777

S
songruirui 已提交
778
通知已注册的观察者指定URI对应的数据资源已发生变更。使用Promise异步回调。
S
songruirui 已提交
779

S
songruirui 已提交
780
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
781

S
songruirui 已提交
782 783
**参数:**

784
| 参数名 | 类型   | 必填 | 说明                 |
S
songruirui 已提交
785 786
| ---- | ------ | ---- | -------------------- |
| uri  | string | 是   | 表示指定的数据路径。 |
S
songruirui 已提交
787 788 789

**返回值:**

S
songruirui 已提交
790 791 792
| 类型           | 说明                  |
| -------------- | --------------------- |
| Promise&lt;void&gt; | Promise对象。无返回结果的Promise对象。 |
S
songruirui 已提交
793 794 795

**示例:**

S
songruirui 已提交
796
```ts
797 798
import UIAbility from '@ohos.app.ability.UIAbility';

S
songruirui 已提交
799
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
800
dataShareHelper.notifyChange(uri);
N
niudongyao 已提交
801
```