js-apis-data-dataShare.md 33.8 KB
Newer Older
S
songruirui 已提交
1
# 数据共享
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 20 21 22
import dataShare from '@ohos.data.dataShare'
```


## dataShare.createDataShareHelper

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

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

S
songruirui 已提交
27
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
28 29 30

**参数:**

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

N
niudongyao 已提交
37 38 39 40 41 42 43 44
**错误码:**

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

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

S
songruirui 已提交
45 46
**示例:**

S
songruirui 已提交
47
```ts
48
import Ability from '@ohos.application.Ability'
S
songruirui 已提交
49

S
修改  
songruirui 已提交
50 51
let uri = ("datashare:///com.samples.datasharetest.DataShare");
let dataShareHelper;
N
niudongyao 已提交
52 53 54
try {
    dataShare.createDataShareHelper(this.context, uri, (err, data) => {
        if (err != undefined) {
N
niudongyao 已提交
55
            console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
56 57
            return;
        }
S
songruirui 已提交
58
        console.info("createDataShareHelper succeed, data : " + data);
S
修改  
songruirui 已提交
59
        dataShareHelper = data;
N
niudongyao 已提交
60 61
    });
} catch (err) {
N
niudongyao 已提交
62
    console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
63
};
S
songruirui 已提交
64 65
```

S
songruirui 已提交
66 67 68 69
## dataShare.createDataShareHelper

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

S
songruirui 已提交
70
创建DataShareHelper实例。使用Promise异步回调。
S
songruirui 已提交
71 72 73 74 75

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

**参数:**

76
| 参数名  | 类型                                          | 必填 | 说明                           |
S
songruirui 已提交
77 78 79
| ------- | ------------------------------------------------- | ---- | ------------------------------ |
| context | [Context](js-apis-application-context.md#context) | 是   | 应用的上下文环境。             |
| uri     | string                                            | 是   | 指示要连接的服务端应用的路径。 |
S
songruirui 已提交
80 81 82

**返回值:**

S
songruirui 已提交
83 84 85
| 类型                                               | 说明                                   |
| -------------------------------------------------- | -------------------------------------- |
| Promise<[DataShareHelper](#datasharehelper)> | Promise对象。返回DataShareHelper实例。 |
S
songruirui 已提交
86

N
niudongyao 已提交
87 88 89 90 91 92 93 94
**错误码:**

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

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

S
songruirui 已提交
95 96 97
**示例:**

```ts
98
import Ability from '@ohos.application.Ability'
S
songruirui 已提交
99

S
修改  
songruirui 已提交
100 101
let uri = ("datashare:///com.samples.datasharetest.DataShare");
let dataShareHelper;
N
niudongyao 已提交
102 103 104 105 106
try {
    dataShare.createDataShareHelper(this.context, uri).then((data) => {
        console.info("createDataShareHelper succeed, data : " + data);
        dataShareHelper = data;
    }). catch((err) => {
N
niudongyao 已提交
107
        console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
108 109
    });
} catch (err) {
N
niudongyao 已提交
110
    console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
111
};
S
songruirui 已提交
112 113
```

S
songruirui 已提交
114 115
## DataShareHelper

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

S
songruirui 已提交
118 119
### on('dataChange')

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

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

S
songruirui 已提交
124
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
125 126 127

**参数:**

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

**示例:**

S
songruirui 已提交
136
```ts
137
import Ability from '@ohos.application.Ability'
S
修改  
songruirui 已提交
138
function onCallback() {
S
songruirui 已提交
139 140
    console.info("**** Observer on callback ****");
}
S
songruirui 已提交
141
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
修改  
songruirui 已提交
142
dataShareHelper.on("dataChange", uri, onCallback);
S
songruirui 已提交
143 144 145 146
```

### off('dataChange')

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

S
songruirui 已提交
149
取消订阅指定URI对应的数据资源的变更通知。使用callback异步回调。
S
songruirui 已提交
150

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

S
songruirui 已提交
153 154
**参数:**

155
| 名称     | 类型                 | 必填 | 说明                    |
S
songruirui 已提交
156
| -------- | -------------------- | ---- | ------------------------ |
S
songruirui 已提交
157 158
| type     | string               | 是   | 取消订阅的事件/回调类型,支持的事件为'dataChange'。 |
| uri      | string               | 是   | 表示指定的数据路径。 |
S
songruirui 已提交
159
| callback | AsyncCallback<void> | 否   | 回调函数。当取消订阅指定URI对应的数据资源的变更通知成功,err为undefined;否则为错误对象。 |
S
songruirui 已提交
160 161 162

**示例:**

S
songruirui 已提交
163
```ts
164
import Ability from '@ohos.application.Ability'
S
修改  
songruirui 已提交
165
function offCallback() {
S
songruirui 已提交
166 167
    console.info("**** Observer off callback ****");
}
S
songruirui 已提交
168
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
修改  
songruirui 已提交
169
dataShareHelper.off("dataChange", uri, offCallback);
S
songruirui 已提交
170 171
```

S
songruirui 已提交
172
### insert
S
songruirui 已提交
173

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

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

S
songruirui 已提交
178
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
179 180 181

**参数:**

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

**示例:**

```ts
191
import Ability from '@ohos.application.Ability'
S
songruirui 已提交
192
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
193 194 195 196 197
const valueBucket = {
    "name": "rose",
    "age": 22,
    "salary": 200.5,
}
N
niudongyao 已提交
198 199 200
try {
    dataShareHelper.insert(uri, valueBucket, (err, data) => {
        if (err != undefined) {
N
niudongyao 已提交
201
            console.error(`insert error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
202 203 204 205 206
            return;
        }
        console.info("insert succeed, data : " + data);
    });
} catch (err) {
N
niudongyao 已提交
207
    console.error(`insert error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
208
};
S
songruirui 已提交
209 210
```

S
songruirui 已提交
211
### insert
S
songruirui 已提交
212

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

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

S
songruirui 已提交
217
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
218 219 220

**参数:**

221
| 名称  | 类型                                                      | 必填 | 说明                                               |
S
songruirui 已提交
222 223 224
| ----- | --------------------------------------------------------- | ---- | -------------------------------------------------- |
| uri   | string                                                    | 是   | 指示要插入的数据的路径。                           |
| value | [ValuesBucket](js-apis-data-ValuesBucket.md#valuesbucket) | 是   | 指示要插入的数据。如果此参数为空,将插入一个空行。 |
S
songruirui 已提交
225 226 227

**返回值:**

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

**示例:**

```ts
235
import Ability from '@ohos.application.Ability'
S
songruirui 已提交
236
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
237 238 239 240 241
const valueBucket = {
    "name": "rose1",
    "age": 221,
    "salary": 20.5,
}
N
niudongyao 已提交
242 243 244 245
try {
    dataShareHelper.insert(uri, valueBucket).then((data) => {
        console.log("insert succeed, data : " + data);
    }). catch((err) => {
N
niudongyao 已提交
246
        console.error(`insert error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
247 248
    });
} catch (err) {
N
niudongyao 已提交
249
    console.error(`insert error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
250
};
S
songruirui 已提交
251 252
```

S
songruirui 已提交
253
### delete
S
songruirui 已提交
254

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

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

S
songruirui 已提交
259
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
260 261 262

**参数:**

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

**示例:**

S
songruirui 已提交
271
```ts
272
import Ability from '@ohos.application.Ability'
S
songruirui 已提交
273 274
import dataSharePredicates from '@ohos.data.dataSharePredicates'

S
songruirui 已提交
275
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
276 277
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
N
niudongyao 已提交
278 279 280
try {
    dataShareHelper.delete(uri, da, (err, data) => {
        if (err != undefined) {
N
niudongyao 已提交
281
            console.error(`delete error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
282 283 284 285 286
            return;
        }
        console.info("delete succeed, data : " + data);
    });
} catch (err) {
N
niudongyao 已提交
287
    console.error(`delete error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
288
};
S
songruirui 已提交
289 290
```

S
songruirui 已提交
291
### delete
S
songruirui 已提交
292

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

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

S
songruirui 已提交
297
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
298 299 300

**参数:**

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

**返回值:**

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

**示例:**

S
songruirui 已提交
314
```ts
315
import Ability from '@ohos.application.Ability'
S
songruirui 已提交
316 317
import dataSharePredicates from '@ohos.data.dataSharePredicates'

S
songruirui 已提交
318
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
319 320
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
N
niudongyao 已提交
321 322 323 324
try {
    dataShareHelper.delete(uri, da).then((data) =>  {
        console.log("delete succeed, data : " + data);
    }). catch((err) => {
N
niudongyao 已提交
325
        console.error(`delete error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
326 327
    });
} catch (err) {
N
niudongyao 已提交
328
    console.error(`delete error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
329
};
S
songruirui 已提交
330 331
```

S
songruirui 已提交
332
### query
S
songruirui 已提交
333

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

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

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

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

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

**示例:**

S
songruirui 已提交
351
```ts
352
import Ability from '@ohos.application.Ability'
S
songruirui 已提交
353 354
import dataSharePredicates from '@ohos.data.dataSharePredicates'

S
songruirui 已提交
355
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
356 357 358
let columns = ["*"];
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
N
niudongyao 已提交
359 360 361
try {
    dataShareHelper.query(uri, da, columns, (err, data) => {
        if (err != undefined) {
N
niudongyao 已提交
362
            console.error(`query error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
363 364
            return;
        }
S
songruirui 已提交
365
        console.log("query succeed, rowCount : " + data.rowCount);
N
niudongyao 已提交
366 367
    });
} catch (err) {
N
niudongyao 已提交
368
    console.error(`query error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
369
};
S
songruirui 已提交
370 371
```

S
songruirui 已提交
372
### query
S
songruirui 已提交
373

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

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

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

S
songruirui 已提交
380 381
**参数:**

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

**返回值:**

S
songruirui 已提交
390 391 392
| 类型                                                         | 说明                              |
| ------------------------------------------------------------ | --------------------------------- |
| Promise&lt;[DataShareResultSet](js-apis-data-DataShareResultSet.md#datashareresultset)&gt; | Promise对象。返回查询到的结果集。 |
S
songruirui 已提交
393 394 395

**示例:**

S
songruirui 已提交
396
```ts
397
import Ability from '@ohos.application.Ability'
S
songruirui 已提交
398 399
import dataSharePredicates from '@ohos.data.dataSharePredicates'

S
songruirui 已提交
400
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
401 402 403
let columns = ["*"];
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
N
niudongyao 已提交
404 405 406 407
try {
    dataShareHelper.query(uri, da, columns).then((data) =>  {
        console.log("query succeed, rowCount : " + data.rowCount);
    }). catch((err) => {
N
niudongyao 已提交
408
        console.error(`query error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
409 410
    });
} catch (err) {
N
niudongyao 已提交
411
    console.error(`query error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
412
};
S
songruirui 已提交
413 414
```

S
songruirui 已提交
415
### update
S
songruirui 已提交
416

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

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

S
songruirui 已提交
421
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
422 423 424

**参数:**

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

**示例:**

S
songruirui 已提交
434
```ts
435
import Ability from '@ohos.application.Ability'
S
songruirui 已提交
436 437
import dataSharePredicates from '@ohos.data.dataSharePredicates'

S
songruirui 已提交
438
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
439 440 441 442 443 444 445 446
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
const va = {
    "name": "roe1",
    "age": 21,
    "salary": 20.5,
   
}
N
niudongyao 已提交
447 448 449
try {
    dataShareHelper.update(uri, da, va, (err, data) => {
        if (err != undefined) {
N
niudongyao 已提交
450
            console.error(`update error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
451 452
            return;
        }
S
songruirui 已提交
453
        console.log("update succeed, data : " + data);
N
niudongyao 已提交
454 455
    });
} catch (err) {
N
niudongyao 已提交
456
    console.error(`update error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
457
};
S
songruirui 已提交
458 459
```

S
songruirui 已提交
460
### update
S
songruirui 已提交
461

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

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

S
songruirui 已提交
466
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
467 468 469

**参数:**

470
| 名称       | 类型                                                         | 必填 | 说明                                                         |
S
songruirui 已提交
471 472
| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| uri        | string                                                       | 是   | 指示要更新的数据的路径。                                     |
473
| predicates | [DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是   | 指示筛选条件。<br />update接口是否支持谓词筛选条件取决于服务端所选用的数据库,如KVDB目前并不支持谓词筛选条件,仅RDB支持。 |
S
songruirui 已提交
474
| value      | [ValuesBucket](js-apis-data-ValuesBucket.md#valuesbucket)    | 是   | 指示要更新的数据。                                           |
S
songruirui 已提交
475 476 477

**返回值:**

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

**示例:**

S
songruirui 已提交
484
```ts
485
import Ability from '@ohos.application.Ability'
S
songruirui 已提交
486 487
import dataSharePredicates from '@ohos.data.dataSharePredicates'

S
songruirui 已提交
488
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
489 490 491 492 493 494 495 496
let da = new dataSharePredicates.DataSharePredicates();
da.equalTo("name", "ZhangSan");
const va = {
    "name": "roe1",
    "age": 21,
    "salary": 20.5,
   
}
N
niudongyao 已提交
497 498 499 500
try {
    dataShareHelper.update(uri, da, va).then((data) =>  {
        console.log("update succeed, data : " + data);
    }). catch((err) => {
N
niudongyao 已提交
501
        console.error(`update error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
502 503
    });
} catch (err) {
N
niudongyao 已提交
504
    console.error(`update error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
505
};
S
songruirui 已提交
506 507
```

S
songruirui 已提交
508
### batchInsert
S
songruirui 已提交
509

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

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

S
songruirui 已提交
514
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
515 516 517

**参数:**

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

**示例:**

S
songruirui 已提交
526
```ts
527
import Ability from '@ohos.application.Ability'
S
songruirui 已提交
528
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
529 530 531
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 已提交
532 533 534
try {
    dataShareHelper.batchInsert(uri, vbs, (err, data) => {
        if (err != undefined) {
N
niudongyao 已提交
535
            console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
536 537
            return;
        }
S
songruirui 已提交
538
        console.log("batchInsert succeed, data : " + data);
N
niudongyao 已提交
539 540
    });
} catch (err) {
N
niudongyao 已提交
541
    console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
542
};
S
songruirui 已提交
543 544
```

S
songruirui 已提交
545
### batchInsert
S
songruirui 已提交
546

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

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

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

**参数:**

555
| 名称   | 类型                                                         | 必填 | 说明                     |
S
songruirui 已提交
556 557 558
| ------ | ------------------------------------------------------------ | ---- | ------------------------ |
| uri    | string                                                       | 是   | 指示要插入的数据的路径。 |
| values | Array&lt;[ValuesBucket](js-apis-data-ValuesBucket.md#valuesbucket)&gt; | 是   | 指示要插入的数据。       |
S
songruirui 已提交
559 560 561

**返回值:**

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

**示例:**

S
songruirui 已提交
568
```ts
569
import Ability from '@ohos.application.Ability'
S
songruirui 已提交
570
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
571 572 573
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 已提交
574 575 576 577
try {
    dataShareHelper.batchInsert(uri, vbs).then((data) =>  {
        console.log("batchInsert succeed, data : " + data);
    }). catch((err) => {
N
niudongyao 已提交
578
        console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
579 580
    });
} catch (err) {
N
niudongyao 已提交
581
    console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `);
N
niudongyao 已提交
582
};
S
songruirui 已提交
583 584
```

S
songruirui 已提交
585
### normalizeUri
S
songruirui 已提交
586

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

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

S
songruirui 已提交
591
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
592 593 594

**参数:**

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

**示例:**

S
songruirui 已提交
602
```ts
603
import Ability from '@ohos.application.Ability'
S
songruirui 已提交
604
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
605
dataShareHelper.normalizeUri(uri, (err, data) => {
S
songruirui 已提交
606
    if (err != undefined) {
S
songruirui 已提交
607
        console.log("normalizeUri failed, error message : " + err);
S
songruirui 已提交
608
    }else{
S
songruirui 已提交
609
        console.log("normalizeUri = " + data);
S
songruirui 已提交
610
    }
S
songruirui 已提交
611 612 613
});
```

S
songruirui 已提交
614
### normalizeUri
S
songruirui 已提交
615

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

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

S
songruirui 已提交
620
**系统能力:**  SystemCapability.DistributedDataManager.DataShare.Consumer
S
songruirui 已提交
621 622 623

**参数:**

624
| 名称 | 类型   | 必填 | 说明                                      |
S
songruirui 已提交
625 626
| ---- | ------ | ---- | ----------------------------------------- |
| uri  | string | 是   | 指示要规范化的[URI](js-apis-uri.md#uri)。 |
S
songruirui 已提交
627 628 629

**返回值:**

S
songruirui 已提交
630 631 632
| 类型             | 说明                                           |
| ---------------- | ---------------------------------------------- |
| Promise&lt;string&gt; | Promise对象。如果支持URI规范化,则返回规范化URI,否则返回空。 |
S
songruirui 已提交
633 634 635

**示例:**

S
songruirui 已提交
636
```ts
637
import Ability from '@ohos.application.Ability'
S
songruirui 已提交
638
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
639 640
dataShareHelper.normalizeUri(uri).then((data) => {
    console.log("normalizeUri = " + data);
S
songruirui 已提交
641
}).catch((err) => {
S
songruirui 已提交
642
    console.log("normalizeUri failed, error message : " + err);
S
songruirui 已提交
643 644 645
});
```

S
songruirui 已提交
646
### denormalizeUri
S
songruirui 已提交
647

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

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

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

S
songruirui 已提交
654 655
**参数:**

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

**示例:**

S
songruirui 已提交
663
```ts
664
import Ability from '@ohos.application.Ability'
S
songruirui 已提交
665
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
666
dataShareHelper.denormalizeUri(uri, (err, data) => {
S
songruirui 已提交
667
    if (err != undefined) {
S
songruirui 已提交
668
        console.log("denormalizeUri failed, error message : " + err);
S
songruirui 已提交
669
    }else{
S
songruirui 已提交
670
        console.log("denormalizeUri = " + data);
S
songruirui 已提交
671
    }
S
songruirui 已提交
672 673 674
});
```

S
songruirui 已提交
675
### denormalizeUri
S
songruirui 已提交
676

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

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

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

S
songruirui 已提交
683 684
**参数:**

685
| 名称 | 类型   | 必填 | 说明                                        |
S
songruirui 已提交
686 687
| ---- | ------ | ---- | ------------------------------------------- |
| uri  | string | 是   | 指示要反规范化的[URI](js-apis-uri.md#uri)。 |
S
songruirui 已提交
688 689 690

**返回值:**

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

**示例:**

S
songruirui 已提交
697
```ts
698
import Ability from '@ohos.application.Ability'
S
songruirui 已提交
699
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
700 701
dataShareHelper.denormalizeUri(uri).then((data) => {
    console.log("denormalizeUri = " + data);
S
songruirui 已提交
702
}).catch((err) => {
S
songruirui 已提交
703
    console.log("denormalizeUri failed, error message : " + err);
S
songruirui 已提交
704 705 706
});
```

S
songruirui 已提交
707
### notifyChange
S
songruirui 已提交
708

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

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

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

S
songruirui 已提交
715 716
**参数:**

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

**示例:**

S
songruirui 已提交
724
```ts
725
import Ability from '@ohos.application.Ability'
S
songruirui 已提交
726
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
727 728
dataShareHelper.notifyChange(uri, () => {
    console.log("***** notifyChange *****");
S
songruirui 已提交
729 730 731
});
```

S
songruirui 已提交
732
### notifyChange
S
songruirui 已提交
733

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

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

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

S
songruirui 已提交
740 741
**参数:**

742
| 名称 | 类型   | 必填 | 说明                 |
S
songruirui 已提交
743 744
| ---- | ------ | ---- | -------------------- |
| uri  | string | 是   | 表示指定的数据路径。 |
S
songruirui 已提交
745 746 747

**返回值:**

S
songruirui 已提交
748 749 750
| 类型           | 说明                  |
| -------------- | --------------------- |
| Promise&lt;void&gt; | Promise对象。无返回结果的Promise对象。 |
S
songruirui 已提交
751 752 753

**示例:**

S
songruirui 已提交
754
```ts
755
import Ability from '@ohos.application.Ability'
S
songruirui 已提交
756
let uri = ("datashare:///com.samples.datasharetest.DataShare");
S
songruirui 已提交
757
dataShareHelper.notifyChange(uri);
N
niudongyao 已提交
758
```