js-apis-data-storage.md 24.2 KB
Newer Older
Z
zengyawen 已提交
1
# 轻量级存储
Z
zengyawen 已提交
2 3 4 5

轻量级存储为应用提供key-value键值型的文件数据处理能力,支持应用对数据进行轻量级存储及查询。数据存储形式为键值对,键的类型为字符串型,值的存储数据类型包括数字型、字符型、布尔型。


Z
zengyawen 已提交
6
> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明:**
Z
zengyawen 已提交
7 8 9 10
>
> - 本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
>
> - 从API Version 9开始,该接口不再维护,推荐使用新接口[`@ohos.data.preferences`](js-apis-data-preferences.md)。
Z
zengyawen 已提交
11 12 13


## 导入模块
Z
zengyawen 已提交
14

G
ge-yafang 已提交
15
```js
G
ge-yafang 已提交
16
import dataStorage from '@ohos.data.storage';
Z
zengyawen 已提交
17 18
```

G
ge-yafang 已提交
19
## 常量
Z
zengyawen 已提交
20

21
**系统能力**:以下各项对应的系统能力均为SystemCapability.DistributedDataManager.Preferences.Core
22

Z
zengyawen 已提交
23 24 25
| 名称 | 参数类型 | 可读 | 可写 | 说明 |
| -------- | -------- | -------- | -------- | -------- |
| MAX_KEY_LENGTH | string | 是 | 否 | key的最大长度限制,大小为80字节。 |
G
ge-yafang 已提交
26
| MAX_VALUE_LENGTH | string | 是 | 否 | value的最大长度限制,大小为8192字节。 |
Z
zengyawen 已提交
27 28


29
## dataStorage.getStorageSync
Z
zengyawen 已提交
30 31

getStorageSync(path: string): Storage
Z
zengyawen 已提交
32 33 34

读取指定文件,将数据加载到Storage实例,用于数据操作,此方法为同步方法。

35 36
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
37 38 39 40 41 42 43 44 45 46 47
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | path | string | 是 | 应用程序内部数据存储路径。 |

- 返回值:
  | 类型 | 说明 |
  | -------- | -------- |
  | [Storage](#storage) | 获取到要操作的Storage实例,用于进行数据存储操作。 |

- 示例:
G
ge-yafang 已提交
48
  ```js
Z
zengyawen 已提交
49 50
  import dataStorage from '@ohos.data.storage'
  import featureAbility from '@ohos.ability.featureAbility'
Z
zengyawen 已提交
51
  
52
  var context = featureAbility.getContext()
53 54 55 56 57
  context.getFilesDir((err, path) => {
      if (err) {
          console.error('getFilesDir failed. err: ' + JSON.stringify(err));
          return;
      }
P
PaDoBoo 已提交
58
      console.info('getFilesDir successful. path:' + JSON.stringify(path));
59 60 61 62
      let storage = dataStorage.getStorageSync(path + '/mystore')
      storage.putSync('startup', 'auto')
      storage.flushSync()
  });
Z
zengyawen 已提交
63 64 65
  ```


66
## dataStorage.getStorage
Z
zengyawen 已提交
67 68

getStorage(path: string, callback: AsyncCallback<Storage>): void
Z
zengyawen 已提交
69 70 71

读取指定文件,将数据加载到Storage实例,用于数据操作,使用callback形式返回结果。

72 73
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
74 75 76 77 78 79 80
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | path | string | 是 | 应用程序内部数据存储路径。 |
  | callback | AsyncCallback<[Storage](#storage)> | 是 | 回调函数。 |

- 示例:
G
ge-yafang 已提交
81
  ```js
Z
zengyawen 已提交
82 83
  import dataStorage from '@ohos.data.storage'
  import featureAbility from '@ohos.ability.featureAbility'
Z
zengyawen 已提交
84
  
85
  var context = featureAbility.getContext()
86
  context.getFilesDir((err, path) => {
87
      if (err) {
88
          console.error('getFilesDir failed. err: ' + JSON.stringify(err));
89 90
          return;
      }
P
PaDoBoo 已提交
91
      console.info('getFilesDir successful. path:' + JSON.stringify(path));
92 93 94 95 96 97 98 99 100
      dataStorage.getStorage(path + '/mystore', function (err, storage) {
          if (err) {
              console.info("Get the storage failed, path: " + path + '/mystore')
              return;
          }
          storage.putSync('startup', 'auto')
          storage.flushSync()
      })
  });
Z
zengyawen 已提交
101 102 103
  ```


104
## dataStorage.getStorage
Z
zengyawen 已提交
105 106

getStorage(path: string): Promise<Storage>
Z
zengyawen 已提交
107 108 109

读取指定文件,将数据加载到Storage实例,用于数据操作,使用Promise方式作为异步方法。

110 111
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
112 113 114 115 116 117 118 119 120 121 122
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | path | string | 是 | 应用程序内部数据存储路径。 |

- 返回值:
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise<[Storage](#storage)> | Promise实例,用于异步获取结果。 |

- 示例:
G
ge-yafang 已提交
123
  ```js
Z
zengyawen 已提交
124 125
  import dataStorage from '@ohos.data.storage'
  import featureAbility from '@ohos.ability.featureAbility'
Z
zengyawen 已提交
126
  
127
  var context = featureAbility.getContext()
128
  context.getFilesDir((err, path) => {
P
PaDoBoo 已提交
129 130 131 132 133
      if (err) {
          console.info("Get the storage failed, path: " + path + '/mystore')
          return;
      }
      console.info('getFilesDir successful. path:' + JSON.stringify(path));
134 135 136 137 138 139 140 141
      let promisegetSt = dataStorage.getStorage(path + '/mystore')
      promisegetSt.then((storage) => {
          storage.putSync('startup', 'auto')
          storage.flushSync()
      }).catch((err) => {
          console.info("Get the storage failed, path: " + path + '/mystore')
      })
  });
Z
zengyawen 已提交
142 143 144
  ```


145
## dataStorage.deleteStorageSync
Z
zengyawen 已提交
146 147

deleteStorageSync(path: string): void
Z
zengyawen 已提交
148 149 150

从内存中移除指定文件对应的Storage单实例,并删除指定文件及其备份文件、损坏文件。删除指定文件时,应用不允许再使用该实例进行数据操作,否则会出现数据一致性问题,此方法为同步方法。

151 152
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
153 154 155 156 157 158 159 160 161 162 163
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | path | string | 是 | 应用程序内部数据存储路径。 |

- 示例:
  ```
  dataStorage.deleteStorageSync(path + '/mystore')
  ```


164
## dataStorage.deleteStorage
Z
zengyawen 已提交
165

166
deleteStorage(path: string, callback: AsyncCallback<void>): void
Z
zengyawen 已提交
167 168 169

从内存中移除指定文件对应的Storage单实例,并删除指定文件及其备份文件、损坏文件。删除指定文件时,应用不允许再使用该实例进行数据操作,否则会出现数据一致性问题,使用callback方式作为异步方法。

170 171
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
172 173 174 175 176 177 178
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | path | string | 是 | 应用程序内部数据存储路径。 |
  | callback | AsyncCallback<void> | 是 | 回调函数。 |

- 示例:
G
ge-yafang 已提交
179
  ```js
Z
zengyawen 已提交
180 181 182 183 184 185 186 187 188 189
  dataStorage.deleteStorage(path + '/mystore', function (err) {
      if (err) {
          console.info("Deleted failed with err: " + err)
          return
      }
      console.info("Deleted successfully.")
  })
  ```


190
## dataStorage.deleteStorage
Z
zengyawen 已提交
191 192

deleteStorage(path: string): Promise<void>
Z
zengyawen 已提交
193 194 195

从内存中移除指定文件对应的Storage单实例,并删除指定文件及其备份文件、损坏文件。删除指定文件时,应用不允许再使用该实例进行数据操作,否则会出现数据一致性问题,使用promise方式作为异步方法。

196 197
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
198 199 200 201 202 203 204 205 206 207 208
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | path | string | 是 | 应用程序内部数据存储路径。 |

- 返回值:
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise<void> | Promise实例,用于异步获取结果。 |

- 示例:
G
ge-yafang 已提交
209
  ```js
210 211
  let promisedelSt = dataStorage.deleteStorage(path + '/mystore')
  promisedelSt.then(() => {
Z
zengyawen 已提交
212 213 214 215 216 217 218
      console.info("Deleted successfully.")
  }).catch((err) => {
      console.info("Deleted failed with err: " + err)
  })
  ```


219
## dataStorage.removeStorageFromCacheSync
Z
zengyawen 已提交
220 221

removeStorageFromCacheSync(path: string): void
Z
zengyawen 已提交
222

Z
zengyawen 已提交
223
从内存中移除指定文件对应的Storage单实例。移除Storage单实例时,应用不允许再使用该实例进行数据操作,否则会出现数据一致性问题。
Z
zengyawen 已提交
224

Z
zengyawen 已提交
225
此方法为同步方法。
Z
zengyawen 已提交
226

227 228
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
229 230 231 232 233 234
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | path | string | 是 | 应用程序内部数据存储路径。 |

- 示例:
G
ge-yafang 已提交
235
  ```js
Z
zengyawen 已提交
236 237 238 239
  dataStorage.removeStorageFromCacheSync(path + '/mystore')
  ```


240
## dataStorage.removeStorageFromCache
Z
zengyawen 已提交
241

242
removeStorageFromCache(path: string, callback: AsyncCallback<void>): void
Z
zengyawen 已提交
243

Z
zengyawen 已提交
244
从内存中移除指定文件对应的Storage单实例。移除Storage单实例时,应用不允许再使用该实例进行数据操作,否则会出现数据一致性问题。
Z
zengyawen 已提交
245

Z
zengyawen 已提交
246
此方法为异步方法。
Z
zengyawen 已提交
247

248 249
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
250 251 252 253
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | path | string | 是 | 应用程序内部数据存储路径。 |
254
  | callback | AsyncCallback<void> | 是 | 回调函数。 |
Z
zengyawen 已提交
255 256

- 示例:
G
ge-yafang 已提交
257
  ```js
Z
zengyawen 已提交
258 259 260 261 262 263 264 265 266 267
  dataStorage.removeStorageFromCache(path + '/mystore', function (err) {
      if (err) {
          console.info("Removed storage from cache failed with err: " + err)
          return
      }
      console.info("Removed storage from cache successfully.")
  })
  ```


268
## dataStorage.removeStorageFromCache
Z
zengyawen 已提交
269 270

removeStorageFromCache(path: string): Promise<void>
Z
zengyawen 已提交
271

Z
zengyawen 已提交
272
从内存中移除指定文件对应的Storage单实例。移除Storage单实例时,应用不允许再使用该实例进行数据操作,否则会出现数据一致性问题。
Z
zengyawen 已提交
273 274 275

此方法为异步方法。

276 277
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
278 279 280 281 282 283 284 285 286 287 288
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | path | string | 是 | 应用程序内部数据存储路径。 |

- 返回值:
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise<void> | Promise实例,用于异步获取结果。 |

- 示例:
G
ge-yafang 已提交
289
  ```js
290 291
  let promiserevSt = dataStorage.removeStorageFromCache(path + '/mystore')
  promiserevSt.then(() => {
Z
zengyawen 已提交
292 293 294 295 296 297 298
      console.info("Removed storage from cache successfully.")
  }).catch((err) => {
      console.info("Removed storage from cache failed with err: " + err)
  })
  ```


299
## Storage
Z
zengyawen 已提交
300

Z
zengyawen 已提交
301
提供获取和修改存储数据的接口。
Z
zengyawen 已提交
302 303


304
### getSync
Z
zengyawen 已提交
305 306

getSync(key: string, defValue: ValueType): ValueType
Z
zengyawen 已提交
307 308

获取键对应的值,如果值为null或者非默认值类型,返回默认数据。
Z
zengyawen 已提交
309

Z
zengyawen 已提交
310
此方法为同步方法。
Z
zengyawen 已提交
311

312 313
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
314 315 316
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
G
ge-yafang 已提交
317 318
  | key | string | 是 | 要获取的存储key名称,不能为空。 |
  | defValue | [ValueType](#valuetype) | 是 | 给定key的存储不存在,则要返回的默认值。支持number、string、boolean。 |
Z
zengyawen 已提交
319 320 321 322 323 324 325

- 返回值:
  | 类型 | 说明 |
  | -------- | -------- |
  | ValueType | 键对应的值,如果值为null或者非默认值类型,返回默认数据。 |

- 示例:
G
ge-yafang 已提交
326
  ```js
Z
zengyawen 已提交
327 328 329 330 331
  let value = storage.getSync('startup', 'default')
  console.info("The value of startup is " + value)
  ```


332
### get
Z
zengyawen 已提交
333 334

get(key: string, defValue: ValueType, callback: AsyncCallback<ValueType>): void
Z
zengyawen 已提交
335 336

获取键对应的值,如果值为null或者非默认值类型,返回默认数据。
Z
zengyawen 已提交
337 338 339

此方法为异步方法。

340 341
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
342 343 344
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
G
ge-yafang 已提交
345 346
  | key | string | 是 | 要获取的存储key名称,不能为空。 |
  | defValue | [ValueType](#valuetype) | 是 | 默认返回值。支持number、string、boolean。 |
Z
zengyawen 已提交
347 348 349
  | callback | AsyncCallback<ValueType> | 是 | 回调函数。 |

- 示例:
G
ge-yafang 已提交
350
  ```js
Z
zengyawen 已提交
351 352 353 354 355 356 357 358 359 360
  storage.get('startup', 'default', function(err, value) {
      if (err) {
          console.info("Get the value of startup failed with err: " + err)
          return
      }
      console.info("The value of startup is " + value)
  })
  ```


361
### get
Z
zengyawen 已提交
362 363

get(key: string, defValue: ValueType): Promise<ValueType>
Z
zengyawen 已提交
364

Z
zengyawen 已提交
365
获取键对应的值,如果值为null或者非默认值类型,返默认数据。
Z
zengyawen 已提交
366

Z
zengyawen 已提交
367
此方法为异步方法。
Z
zengyawen 已提交
368

369 370
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
371 372 373
- **参数:**
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
G
ge-yafang 已提交
374 375
  | key | string | 是 | 要获取的存储key名称,不能为空。 |
  | defValue | [ValueType](#valuetype) | 是 | 默认返回值。支持number、string、boolean。 |
Z
zengyawen 已提交
376 377 378 379 380 381 382

- 返回值:
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise<ValueType> | Promise实例,用于异步获取结果。 |

- 示例:
G
ge-yafang 已提交
383
  ```js
384 385
  let promiseget = storage.get('startup', 'default')
  promiseget.then((value) => {
Z
zengyawen 已提交
386 387 388 389 390 391 392
      console.info("The value of startup is " + value)
  }).catch((err) => {
      console.info("Get the value of startup failed with err: " + err)
  })
  ```


393
### putSync
Z
zengyawen 已提交
394 395

putSync(key: string, value: ValueType): void
Z
zengyawen 已提交
396

Z
zengyawen 已提交
397
首先获取指定文件对应的Storage实例,然后借助Storage API将数据写入Storage实例,通过flush或者flushSync将Storage实例持久化。
Z
zengyawen 已提交
398 399 400

此方法为同步方法。

401 402
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
403 404 405
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
G
ge-yafang 已提交
406 407
  | key | string | 是 | 要修改的存储的key,不能为空。 |
  | value | [ValueType](#valuetype) | 是 | 存储的新值。支持number、string、boolean。 |
Z
zengyawen 已提交
408 409

- 示例:
G
ge-yafang 已提交
410
  ```js
Z
zengyawen 已提交
411 412 413 414
  storage.putSync('startup', 'auto')
  ```


415
### put
Z
zengyawen 已提交
416 417

put(key: string, value: ValueType, callback: AsyncCallback<void>): void
Z
zengyawen 已提交
418

Z
zengyawen 已提交
419
首先获取指定文件对应的Storage实例,然后借助Storage API将数据写入Storage实例,通过flush或者flushSync将Storage实例持久化。
Z
zengyawen 已提交
420

Z
zengyawen 已提交
421
此方法为异步方法。
Z
zengyawen 已提交
422

423 424
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
425 426 427
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
G
ge-yafang 已提交
428 429
  | key | string | 是 | 要修改的存储的key,不能为空。 |
  | value | [ValueType](#valuetype) | 是 | 存储的新值。支持number、string、boolean。 |
Z
zengyawen 已提交
430 431 432
  | callback | AsyncCallback<void> | 是 | 回调函数。 |

- 示例:
G
ge-yafang 已提交
433
  ```js
Z
zengyawen 已提交
434 435 436 437 438 439 440 441 442 443
  storage.put('startup', 'auto', function (err) {
      if (err) {
          console.info("Put the value of startup failed with err: " + err)
          return
      }
      console.info("Put the value of startup successfully.")
  })
  ```


444
### put
Z
zengyawen 已提交
445 446

put(key: string, value: ValueType): Promise<void>
Z
zengyawen 已提交
447

Z
zengyawen 已提交
448
首先获取指定文件对应的Storage实例,然后借助Storage API将数据写入Storage实例,通过flush或者flushSync将Storage实例持久化。
Z
zengyawen 已提交
449 450 451

此方法为异步方法。

452 453
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
454 455 456
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
G
ge-yafang 已提交
457 458
  | key | string | 是 | 要修改的存储的key,不能为空。 |
  | value | [ValueType](#valuetype) | 是 | 存储的新值。支持number、string、boolean。 |
Z
zengyawen 已提交
459 460 461 462 463 464 465

- 返回值:
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise<void> | Promise实例,用于异步处理。 |

- 示例:
G
ge-yafang 已提交
466
  ```js
467 468
  let promiseput = storage.put('startup', 'auto')
  promiseput.then(() => {
Z
zengyawen 已提交
469 470 471 472 473 474 475
      console.info("Put the value of startup successfully.")
  }).catch((err) => {
      console.info("Put the value of startup failed with err: " + err)
  })
  ```


476
### hasSync
Z
zengyawen 已提交
477 478

hasSync(key: string): boolean
Z
zengyawen 已提交
479

Z
zengyawen 已提交
480
检查存储对象是否包含名为给定key的存储。
Z
zengyawen 已提交
481

Z
zengyawen 已提交
482
此方法为同步方法。
Z
zengyawen 已提交
483

484 485
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
486 487 488
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
G
ge-yafang 已提交
489
  | key | string | 是 | 要获取的存储key名称,不能为空。 |
Z
zengyawen 已提交
490 491 492 493 494 495 496

- 返回值:
  | 类型 | 说明 |
  | -------- | -------- |
  | boolean | true 表示存在,false表示不存在。 |

- 示例:
G
ge-yafang 已提交
497
  ```js
Z
zengyawen 已提交
498 499 500 501 502 503 504
  let isExist = storage.hasSync('startup')
  if (isExist) {
      console.info("The key of startup is contained.")
  }
  ```


505
### has
Z
zengyawen 已提交
506 507

has(key: string, callback: AsyncCallback<boolean>): boolean
Z
zengyawen 已提交
508

Z
zengyawen 已提交
509
检查存储对象是否包含名为给定key的存储。
Z
zengyawen 已提交
510 511 512

此方法为异步方法。

513 514
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
515 516 517 518 519 520 521 522 523 524 525 526
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | key | string | 是 | 要获取的存储key名称,不能为空。 |
  | callback | AsyncCallback<boolean> | 是 | 回调函数。 |

- 返回值:
  | 类型 | 说明 |
  | -------- | -------- |
  | boolean | true表示存在,false表示不存在。 |

- 示例:
G
ge-yafang 已提交
527
  ```js
Z
zengyawen 已提交
528 529 530 531 532 533 534 535 536 537 538 539
  storage.has('startup', function (err, isExist) {
      if (err) {
          console.info("Check the key of startup failed with err: " + err)
          return
      }
      if (isExist) {
          console.info("The key of startup is contained.")
      }
  })
  ```


540
### has
Z
zengyawen 已提交
541 542

has(key: string): Promise<boolean>
Z
zengyawen 已提交
543

Z
zengyawen 已提交
544
检查存储对象是否包含名为给定key的存储。
Z
zengyawen 已提交
545

Z
zengyawen 已提交
546
此方法为异步方法。
Z
zengyawen 已提交
547

548 549
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
550 551 552
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
G
ge-yafang 已提交
553
  | key | string | 是 | 要获取的存储key名称,不能为空。 |
Z
zengyawen 已提交
554 555 556 557 558 559 560

- 返回值:
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise<boolean> | Promise实例,用于异步处理。 |

- 示例:
G
ge-yafang 已提交
561
  ```js
562 563
  let promisehas = storage.has('startup')
  promisehas.then((isExist) => {
Z
zengyawen 已提交
564 565 566 567 568 569 570 571 572
      if (isExist) {
          console.info("The key of startup is contained.")
      }
  }).catch((err) => {
      console.info("Check the key of startup failed with err: " + err)
  })
  ```


573
### deleteSync
Z
zengyawen 已提交
574 575

deleteSync(key: string): void
Z
zengyawen 已提交
576

Z
zengyawen 已提交
577
从存储对象中删除名为给定key的存储。
Z
zengyawen 已提交
578 579 580

此方法为同步方法。

581 582
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
583 584 585 586 587 588
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | key | string | 是 | 要获取的存储key名称。它不能为空。 |

- 示例:
G
ge-yafang 已提交
589
  ```js
Z
zengyawen 已提交
590 591 592 593
  storage.deleteSync('startup')
  ```


G
ge-yafang 已提交
594
### deletej
Z
zengyawen 已提交
595 596

delete(key: string, callback: AsyncCallback<void>): void
Z
zengyawen 已提交
597

Z
zengyawen 已提交
598
从存储对象中删除名为给定key的存储。
Z
zengyawen 已提交
599 600 601

此方法为异步方法。

602 603
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
604 605 606 607 608 609 610
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | key | string | 是 | 要获取的存储key名称,不能为空。 |
  | callback | AsyncCallback<void> | 是 | 回调函数。 |

- 示例:
G
ge-yafang 已提交
611
  ```js
Z
zengyawen 已提交
612 613 614 615 616 617 618 619 620 621
  storage.delete('startup', function (err) {
      if (err) {
          console.info("Delete startup key failed with err: " + err)
          return
      }
      console.info("Deleted startup key successfully.")
  })
  ```


622
### delete
Z
zengyawen 已提交
623 624

delete(key: string): Promise<void>
Z
zengyawen 已提交
625 626

从存储对象删除名为给定key的存储。
Z
zengyawen 已提交
627

Z
zengyawen 已提交
628
此方法为异步方法。
Z
zengyawen 已提交
629

630 631
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
632 633 634 635 636 637 638 639 640 641 642
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | key | string | 是 | 要获取的存储key名称。 |

- 返回值:
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise<void> | Promise实例,用于异步处理。 |

- 示例:
G
ge-yafang 已提交
643
  ```js
644 645
  let promisedel = storage.delete('startup')
  promisedel.then(() => {
Z
zengyawen 已提交
646 647 648 649 650 651 652
      console.info("Deleted startup key successfully.")
  }).catch((err) => {
      console.info("Delete startup key failed with err: " + err)
  })
  ```


653
### flushSync
Z
zengyawen 已提交
654 655

flushSync(): void
Z
zengyawen 已提交
656

Z
zengyawen 已提交
657
将当前storage对象中的修改保存到当前的storage,并同步存储到文件中。
Z
zengyawen 已提交
658

Z
zengyawen 已提交
659 660
此方法为同步方法。

661 662
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
663
- 示例:
G
ge-yafang 已提交
664
  ```js
Z
zengyawen 已提交
665 666
  storage.flushSync()
  ```
Z
zengyawen 已提交
667 668


669
### flush
Z
zengyawen 已提交
670

Z
zengyawen 已提交
671
flush(callback: AsyncCallback<void>): void
Z
zengyawen 已提交
672 673

将当前storage对象中的修改保存到当前的storage,并异步存储到文件中。
Z
zengyawen 已提交
674 675 676

此方法为异步方法。

677 678
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
679 680 681 682
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | callback | AsyncCallback<void> | 是 | 回调函数。 |
Z
zengyawen 已提交
683

Z
zengyawen 已提交
684
- 示例:
G
ge-yafang 已提交
685
  ```js
Z
zengyawen 已提交
686 687 688 689 690 691 692 693
  storage.flush(function (err) {
      if (err) {
          console.info("Flush to file failed with err: " + err)
          return
      }
      console.info("Flushed to file successfully.")
  })
  ```
Z
zengyawen 已提交
694 695


696
### flush
Z
zengyawen 已提交
697

Z
zengyawen 已提交
698
flush(): Promise<void>
Z
zengyawen 已提交
699

Z
zengyawen 已提交
700
将当前storage对象中的修改保存到当前的storage,并异步存储到文件中。
Z
zengyawen 已提交
701

Z
zengyawen 已提交
702
此方法为异步方法。
Z
zengyawen 已提交
703

704 705
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
706 707 708 709
- 返回值:
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise<void> | Promise实例,用于异步处理。 |
Z
zengyawen 已提交
710

Z
zengyawen 已提交
711
- 示例:
G
ge-yafang 已提交
712
  ```js
713 714
  let promiseflush = storage.flush()
  promiseflush.then(() => {
Z
zengyawen 已提交
715 716 717 718 719
      console.info("Flushed to file successfully.")
  }).catch((err) => {
      console.info("Flush to file failed with err: " + err)
  })
  ```
Z
zengyawen 已提交
720

Z
zengyawen 已提交
721

722
### clearSync
Z
zengyawen 已提交
723 724

clearSync(): void
Z
zengyawen 已提交
725 726 727 728 729

清除此存储对象中的所有存储。

此方法为同步方法。

730 731
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
732
- 示例:
G
ge-yafang 已提交
733
  ```js
Z
zengyawen 已提交
734 735
  storage.clearSync()
  ```
Z
zengyawen 已提交
736 737


738
### clear
Z
zengyawen 已提交
739

Z
zengyawen 已提交
740
clear(callback: AsyncCallback<void>): void
Z
zengyawen 已提交
741 742 743 744 745

清除此存储对象中的所有存储。

此方法为异步方法。

746 747
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
748 749 750 751 752 753
- 参数:
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | callback | AsyncCallback<void> | 是 | 回调函数。 |

- 示例:
G
ge-yafang 已提交
754
  ```js
Z
zengyawen 已提交
755 756 757 758 759 760 761 762 763 764
  storage.clear(function (err) {
      if (err) {
          console.info("Clear to file failed with err: " + err)
          return
      }
      console.info("Cleared to file successfully.")
  })
  ```


765
### clear
Z
zengyawen 已提交
766 767

clear(): Promise<void>
Z
zengyawen 已提交
768 769 770 771 772

清除此存储对象中的所有存储。

此方法为异步方法。

773 774
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
775 776 777 778 779 780
- 返回值:
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise<void> | Promise实例,用于异步处理。 |

- 示例:
G
ge-yafang 已提交
781
  ```js
782 783
  let promiseclear = storage.clear()
  promiseclear.then(() => {
Z
zengyawen 已提交
784 785 786 787 788 789 790
      console.info("Cleared to file successfully.")
  }).catch((err) => {
      console.info("Clear to file failed with err: " + err)
  })
  ```


791
### on('change')
Z
zengyawen 已提交
792 793 794 795 796

on(type: 'change', callback: Callback<StorageObserver>): void

订阅数据变更者类需要实现StorageObserver接口,订阅的key的值发生变更后,在执行flush/flushSync方法后,callback方法会被回调。

797 798
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
799 800 801 802 803 804 805
- 参数:
  | 参数名 | 类型 | 说明 |
  | -------- | -------- | -------- |
  | type | string | 事件类型,固定值'change',表示数据变更。 |
  | callback | Callback<[StorageObserver](#storageobserver)> | 回调对象实例。 |

- 示例:
G
ge-yafang 已提交
806
  ```js
Z
zengyawen 已提交
807 808 809 810 811 812 813 814 815
  var observer = function (key) {
      console.info("The key of " + key + " changed.")
  }
  storage.on('change', observer)
  storage.putSync('startup', 'auto')
  storage.flushSync()  // observer will be called.
  ```


816
### off('change')
Z
zengyawen 已提交
817 818 819 820 821

off(type: 'change', callback: Callback<StorageObserver>): void

当不再进行订阅数据变更时,使用此接口取消订阅。

822 823
**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

Z
zengyawen 已提交
824 825 826 827 828 829 830
- 参数:
  | 参数名 | 类型 | 说明 |
  | -------- | -------- | -------- |
  | type | string | 事件类型,固定值'change',表示数据变更。 |
  | callback | Callback<[StorageObserver](#storageobserver)> | 需要取消的回调对象实例。 |

- 示例:
G
ge-yafang 已提交
831
  ```js
Z
zengyawen 已提交
832 833 834 835 836 837 838
  var observer = function (key) {
      console.info("The key of " + key + " changed.")
  }
  storage.off('change', observer)
  ```


839 840
## StorageObserver

841
**系统能力**:以下各项对应的系统能力均为SystemCapability.DistributedDataManager.Preferences.Core
Z
zengyawen 已提交
842

Z
zengyawen 已提交
843 844 845
| 名称 | 参数类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| key | string | 否 | 变更的数据内容。 |
G
ge-yafang 已提交
846 847 848 849 850 851 852 853 854 855 856 857

## ValueType

用于表示允许的数据字段类型。

**系统能力**:SystemCapability.DistributedDataManager.Preferences.Core

| 名称    | 说明                 |
| ------- | -------------------- |
| number  | 表示值类型为数字。   |
| string  | 表示值类型为字符。   |
| boolean | 表示值类型为布尔值。 |