js-apis-data-storage.md 24.3 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

G
ge-yafang 已提交
37
**参数:**
Z
zengyawen 已提交
38 39 40 41
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | path | string | 是 | 应用程序内部数据存储路径。 |

G
ge-yafang 已提交
42
**返回值:**
Z
zengyawen 已提交
43 44 45 46
  | 类型 | 说明 |
  | -------- | -------- |
  | [Storage](#storage) | 获取到要操作的Storage实例,用于进行数据存储操作。 |

G
ge-yafang 已提交
47
**示例:**
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

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

G
ge-yafang 已提交
80
**示例:**
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

G
ge-yafang 已提交
112
**参数:**
Z
zengyawen 已提交
113 114 115 116
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | path | string | 是 | 应用程序内部数据存储路径。 |

G
ge-yafang 已提交
117
**返回值:**
Z
zengyawen 已提交
118 119 120 121
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise<[Storage](#storage)> | Promise实例,用于异步获取结果。 |

G
ge-yafang 已提交
122
**示例:**
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

G
ge-yafang 已提交
153
**参数:**
Z
zengyawen 已提交
154 155 156 157
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | path | string | 是 | 应用程序内部数据存储路径。 |

G
ge-yafang 已提交
158
**示例:**
G
ge-yafang 已提交
159
  ```js
Z
zengyawen 已提交
160 161 162 163
  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

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

G
ge-yafang 已提交
178
**示例:**
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

G
ge-yafang 已提交
198
**参数:**
Z
zengyawen 已提交
199 200 201 202
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | path | string | 是 | 应用程序内部数据存储路径。 |

G
ge-yafang 已提交
203
**返回值:**
Z
zengyawen 已提交
204 205 206 207
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise<void> | Promise实例,用于异步获取结果。 |

G
ge-yafang 已提交
208
**示例:**
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

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

G
ge-yafang 已提交
234
**示例:**
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

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

G
ge-yafang 已提交
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

G
ge-yafang 已提交
278
**参数:**
Z
zengyawen 已提交
279 280 281 282
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | path | string | 是 | 应用程序内部数据存储路径。 |

G
ge-yafang 已提交
283
**返回值:**
Z
zengyawen 已提交
284 285 286 287
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise<void> | Promise实例,用于异步获取结果。 |

G
ge-yafang 已提交
288
**示例:**
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

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

G
ge-yafang 已提交
320
**返回值:**
Z
zengyawen 已提交
321 322 323 324
  | 类型 | 说明 |
  | -------- | -------- |
  | ValueType | 键对应的值,如果值为null或者非默认值类型,返回默认数据。 |

G
ge-yafang 已提交
325
**示例:**
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

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

G
ge-yafang 已提交
349
**示例:**
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

G
ge-yafang 已提交
371 372 373 374 375 376
**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
| key | string | 是 | 要获取的存储key名称,不能为空。 |
| defValue | [ValueType](#valuetype) | 是 | 默认返回值。支持number、string、boolean。 |
Z
zengyawen 已提交
377

G
ge-yafang 已提交
378
**返回值:**
Z
zengyawen 已提交
379 380 381 382
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise<ValueType> | Promise实例,用于异步获取结果。 |

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


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

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

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

此方法为同步方法。

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

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

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


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

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

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

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

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

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

G
ge-yafang 已提交
433
**示例:**
G
ge-yafang 已提交
434
  ```js
Z
zengyawen 已提交
435 436 437 438 439 440 441 442 443 444
  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.")
  })
  ```


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

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

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

此方法为异步方法。

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

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

G
ge-yafang 已提交
461
**返回值:**
Z
zengyawen 已提交
462 463 464 465
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise<void> | Promise实例,用于异步处理。 |

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


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

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

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

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

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

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

G
ge-yafang 已提交
492
**返回值:**
Z
zengyawen 已提交
493 494 495 496
  | 类型 | 说明 |
  | -------- | -------- |
  | boolean | true 表示存在,false表示不存在。 |

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


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

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

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

此方法为异步方法。

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

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

G
ge-yafang 已提交
522
**返回值:**
Z
zengyawen 已提交
523 524 525 526
  | 类型 | 说明 |
  | -------- | -------- |
  | boolean | true表示存在,false表示不存在。 |

G
ge-yafang 已提交
527
**示例:**
G
ge-yafang 已提交
528
  ```js
Z
zengyawen 已提交
529 530 531 532 533 534 535 536 537 538 539 540
  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.")
      }
  })
  ```


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

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

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

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

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

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

G
ge-yafang 已提交
556
**返回值:**
Z
zengyawen 已提交
557 558 559 560
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise<boolean> | Promise实例,用于异步处理。 |

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


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

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

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

此方法为同步方法。

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

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

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


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

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

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

此方法为异步方法。

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

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

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


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

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

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

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

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

G
ge-yafang 已提交
633
**参数:**
Z
zengyawen 已提交
634 635 636 637
  | 参数名 | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | key | string | 是 | 要获取的存储key名称。 |

G
ge-yafang 已提交
638
**返回值:**
Z
zengyawen 已提交
639 640 641 642
  | 类型 | 说明 |
  | -------- | -------- |
  | Promise<void> | Promise实例,用于异步处理。 |

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


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

flushSync(): void
Z
zengyawen 已提交
657

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

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

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

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


670
### flush
Z
zengyawen 已提交
671

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

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

此方法为异步方法。

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

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

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


697
### flush
Z
zengyawen 已提交
698

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

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

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

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

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

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

Z
zengyawen 已提交
722

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

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

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

此方法为同步方法。

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

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


739
### clear
Z
zengyawen 已提交
740

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

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

此方法为异步方法。

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

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

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


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

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

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

此方法为异步方法。

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

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

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


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

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

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

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

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

G
ge-yafang 已提交
806
**示例:**
G
ge-yafang 已提交
807
  ```js
Z
zengyawen 已提交
808 809 810 811 812 813 814 815 816
  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.
  ```


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

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

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

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

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

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


840 841
## StorageObserver

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

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

## ValueType

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

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

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