js-apis-data-storage.md 25.0 KB
Newer Older
A
annie_wangli 已提交
1
# Lightweight Storage
Z
zengyawen 已提交
2

A
annie_wangli 已提交
3
Lightweight storage provides applications with data processing capability and allows applications to perform lightweight data storage and query. Data is stored in key-value (KV) pairs. Keys are of the string type, and values can be of the number, string, or Boolean type.
Z
zengyawen 已提交
4 5


A
Annie_wang 已提交
6
> **NOTE**<br/>
A
annie_wangli 已提交
7 8 9 10
>
> - The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
>
> - The APIs of this module are no longer maintained since API Version 9. You are advised to use [`@ohos.data.preferences`](js-apis-data-preferences.md).
A
annie_wangli 已提交
11 12 13


## Modules to Import
Z
zengyawen 已提交
14

A
Annie_wang 已提交
15 16
```js
import dataStorage from '@ohos.data.storage';
Z
zengyawen 已提交
17 18
```

A
Annie_wang 已提交
19
## Constants
A
annie_wangli 已提交
20 21 22 23 24

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

| Name| Type| Readable| Writable| Description|
| -------- | -------- | -------- | -------- | -------- |
A
Annie_wang 已提交
25 26
| MAX_KEY_LENGTH | string | Yes| No| Maximum length of a key. It must be less than 80 bytes.|
| MAX_VALUE_LENGTH | string | Yes| No| Maximum length of a value. It must be less than 8192 bytes.|
A
annie_wangli 已提交
27 28 29 30 31 32


## dataStorage.getStorageSync

getStorageSync(path: string): Storage

A
Annie_wang 已提交
33
Reads the specified file and loads its data to the **Storage** instance for data operations.
A
annie_wangli 已提交
34 35 36

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
37
**Parameters**
A
annie_wangli 已提交
38 39 40 41
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | path | string | Yes| Path of the target file.|

A
Annie_wang 已提交
42
**Return value**
A
annie_wangli 已提交
43 44 45 46
  | Type| Description|
  | -------- | -------- |
  | [Storage](#storage) | **Storage** instance used for data storage operations.|

A
Annie_wang 已提交
47 48
**Example**
  ```js
A
annie_wangli 已提交
49 50
  import dataStorage from '@ohos.data.storage'
  import featureAbility from '@ohos.ability.featureAbility'
A
annie_wangli 已提交
51
  
A
annie_wangli 已提交
52
  var context = featureAbility.getContext()
A
annie_wangli 已提交
53 54 55 56 57 58 59 60 61 62
  context.getFilesDir((err, path) => {
      if (err) {
          console.error('getFilesDir failed. err: ' + JSON.stringify(err));
          return;
      }
      console.info('getFilesDir successful. path:' + JSON.stringify(path));
      let storage = dataStorage.getStorageSync(path + '/mystore')
      storage.putSync('startup', 'auto')
      storage.flushSync()
  });
A
annie_wangli 已提交
63 64 65 66 67 68 69
  ```


## dataStorage.getStorage

getStorage(path: string, callback: AsyncCallback&lt;Storage&gt;): void

A
Annie_wang 已提交
70
Reads the specified file and loads its data to the **Storage** instance for data operations. This API uses an asynchronous callback to return the result.
A
annie_wangli 已提交
71 72 73

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
74
**Parameters**
A
annie_wangli 已提交
75 76 77 78 79
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | path | string | Yes| Path of the target file.|
  | callback | AsyncCallback&lt;[Storage](#storage)&gt; | Yes| Callback used to return the execution result.|

A
Annie_wang 已提交
80 81
**Example**
  ```js
A
annie_wangli 已提交
82 83
  import dataStorage from '@ohos.data.storage'
  import featureAbility from '@ohos.ability.featureAbility'
A
annie_wangli 已提交
84
  
A
annie_wangli 已提交
85
  var context = featureAbility.getContext()
A
annie_wangli 已提交
86
  context.getFilesDir((err, path) => {
A
annie_wangli 已提交
87
      if (err) {
A
annie_wangli 已提交
88
          console.error('getFilesDir failed. err: ' + JSON.stringify(err));
A
annie_wangli 已提交
89 90
          return;
      }
A
annie_wangli 已提交
91 92 93 94 95 96 97 98 99 100
      console.info('getFilesDir successful. path:' + JSON.stringify(path));
      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()
      })
  });
A
annie_wangli 已提交
101
  ```
Z
zengyawen 已提交
102 103


A
annie_wangli 已提交
104 105 106 107
## dataStorage.getStorage

getStorage(path: string): Promise&lt;Storage&gt;

A
Annie_wang 已提交
108
Reads the specified file and loads its data to the **Storage** instance for data operations. This API uses a promise to return the result.
A
annie_wangli 已提交
109 110 111

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
112
**Parameters**
A
annie_wangli 已提交
113 114 115 116
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | path | string | Yes| Path of the target file.|

A
Annie_wang 已提交
117
**Return value**
A
annie_wangli 已提交
118 119 120 121
  | Type| Description|
  | -------- | -------- |
  | Promise&lt;[Storage](#storage)&gt; | Promise used to return the result.|

A
Annie_wang 已提交
122 123
**Example**
  ```js
A
annie_wangli 已提交
124 125
  import dataStorage from '@ohos.data.storage'
  import featureAbility from '@ohos.ability.featureAbility'
A
annie_wangli 已提交
126
  
A
annie_wangli 已提交
127
  var context = featureAbility.getContext()
A
annie_wangli 已提交
128 129 130 131 132 133 134 135 136 137 138 139 140 141
  context.getFilesDir((err, path) => {
      if (err) {
          console.info("Get the storage failed, path: " + path + '/mystore')
          return;
      }
      console.info('getFilesDir successful. path:' + JSON.stringify(path));
      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')
      })
  });
A
annie_wangli 已提交
142
  ```
Z
zengyawen 已提交
143 144


A
annie_wangli 已提交
145 146 147 148
## dataStorage.deleteStorageSync

deleteStorageSync(path: string): void

A
Annie_wang 已提交
149
Deletes the singleton **Storage** instance of a file from the memory, and deletes the specified file, its backup file, and damaged files. After the specified files are deleted, the **Storage** instance cannot be used for data operations. Otherwise, data inconsistency will occur.
A
annie_wangli 已提交
150 151 152

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
153
**Parameters**
A
annie_wangli 已提交
154 155 156 157
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | path | string | Yes| Path of the target file.|

A
Annie_wang 已提交
158 159
**Example**
  ```js
A
annie_wangli 已提交
160 161 162 163 164 165 166 167
  dataStorage.deleteStorageSync(path + '/mystore')
  ```


## dataStorage.deleteStorage

deleteStorage(path: string, callback: AsyncCallback&lt;void&gt;): void

A
Annie_wang 已提交
168
Deletes the singleton **Storage** instance of a file from the memory, and deletes the specified file, its backup file, and damaged files. After the specified files are deleted, the **Storage** instance cannot be used for data operations. Otherwise, data inconsistency will occur. This API uses an asynchronous callback to return the result.
A
annie_wangli 已提交
169 170 171

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
172
**Parameters**
A
annie_wangli 已提交
173 174 175 176 177
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | path | string | Yes| Path of the target file.|
  | callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the execution result.|

A
Annie_wang 已提交
178 179
**Example**
  ```js
A
annie_wangli 已提交
180 181 182 183 184 185 186 187 188
  dataStorage.deleteStorage(path + '/mystore', function (err) {
      if (err) {
          console.info("Deleted failed with err: " + err)
          return
      }
      console.info("Deleted successfully.")
  })
  ```

Z
zengyawen 已提交
189

A
annie_wangli 已提交
190
## dataStorage.deleteStorage
Z
zengyawen 已提交
191

A
annie_wangli 已提交
192 193
deleteStorage(path: string): Promise&lt;void&gt;

A
Annie_wang 已提交
194
Deletes the singleton **Storage** instance of a file from the memory, and deletes the specified file, its backup file, and damaged files. After the specified files are deleted, the **Storage** instance cannot be used for data operations. Otherwise, data inconsistency will occur. This API uses a promise to return the result.
A
annie_wangli 已提交
195 196 197

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
198
**Parameters**
A
annie_wangli 已提交
199 200 201 202
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | path | string | Yes| Path of the target file.|

A
Annie_wang 已提交
203
**Return value**
A
annie_wangli 已提交
204 205 206 207
  | Type| Description|
  | -------- | -------- |
  | Promise&lt;void&gt; | Promise used to return the result.|

A
Annie_wang 已提交
208 209
**Example**
  ```js
A
annie_wangli 已提交
210 211 212 213 214 215 216 217 218 219 220 221 222 223
  let promisedelSt = dataStorage.deleteStorage(path + '/mystore')
  promisedelSt.then(() => {
      console.info("Deleted successfully.")
  }).catch((err) => {
      console.info("Deleted failed with err: " + err)
  })
  ```


## dataStorage.removeStorageFromCacheSync

removeStorageFromCacheSync(path: string): void

Removes the singleton **Storage** instance of a file from the cache. The removed instance cannot be used for data operations. Otherwise, data inconsistency will occur.
Z
zengyawen 已提交
224

A
annie_wangli 已提交
225 226
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
227
**Parameters**
A
annie_wangli 已提交
228 229 230 231
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | path | string | Yes| Path of the target file.|

A
Annie_wang 已提交
232 233
**Example**
  ```js
A
annie_wangli 已提交
234 235 236 237 238 239 240 241
  dataStorage.removeStorageFromCacheSync(path + '/mystore')
  ```


## dataStorage.removeStorageFromCache

removeStorageFromCache(path: string, callback: AsyncCallback&lt;void&gt;): void

A
Annie_wang 已提交
242
Removes the singleton **Storage** instance of a file from the cache. The removed instance cannot be used for data operations. Otherwise, data inconsistency will occur. This API uses an asynchronous callback to return the result.
A
annie_wangli 已提交
243 244 245

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
246
**Parameters**
A
annie_wangli 已提交
247 248 249 250 251
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | path | string | Yes| Path of the target file.|
  | callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the execution result.|

A
Annie_wang 已提交
252 253
**Example**
  ```js
A
annie_wangli 已提交
254 255 256 257 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.")
  })
  ```


## dataStorage.removeStorageFromCache

removeStorageFromCache(path: string): Promise&lt;void&gt;

A
Annie_wang 已提交
268
Removes the singleton **Storage** instance of a file from the cache. The removed instance cannot be used for data operations. Otherwise, data inconsistency will occur. This API uses a promise to return the result.
A
annie_wangli 已提交
269 270 271

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
272
**Parameters**
A
annie_wangli 已提交
273 274 275 276
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | path | string | Yes| Path of the target file.|

A
Annie_wang 已提交
277
**Return value**
A
annie_wangli 已提交
278 279 280 281
  | Type| Description|
  | -------- | -------- |
  | Promise&lt;void&gt; | Promise used to return the result.|

A
Annie_wang 已提交
282 283
**Example**
  ```js
A
annie_wangli 已提交
284 285 286 287 288 289 290 291 292 293
  let promiserevSt = dataStorage.removeStorageFromCache(path + '/mystore')
  promiserevSt.then(() => {
      console.info("Removed storage from cache successfully.")
  }).catch((err) => {
      console.info("Removed storage from cache failed with err: " + err)
  })
  ```


## Storage
Z
zengyawen 已提交
294 295 296 297

Provides APIs for obtaining and modifying storage data.


A
annie_wangli 已提交
298 299 300
### getSync

getSync(key: string, defValue: ValueType): ValueType
Z
zengyawen 已提交
301 302 303

Obtains the value corresponding to a key. If the value is null or not in the default value format, the default value is returned.

A
annie_wangli 已提交
304 305
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
306
**Parameters**
A
annie_wangli 已提交
307 308 309
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | key | string | Yes| Key of the data. It cannot be empty.|
A
Annie_wang 已提交
310
  | defValue | [ValueType](#valuetype) | Yes| Default value to be returned if the value of the specified key does not exist. It can be a number, string, or Boolean value.|
A
annie_wangli 已提交
311

A
Annie_wang 已提交
312
**Return value**
A
annie_wangli 已提交
313 314 315 316
  | Type| Description|
  | -------- | -------- |
  | ValueType | Value corresponding to the specified key. If the value is null or not in the default value format, the default value is returned.|

A
Annie_wang 已提交
317 318
**Example**
  ```js
A
annie_wangli 已提交
319 320 321 322 323 324 325 326
  let value = storage.getSync('startup', 'default')
  console.info("The value of startup is " + value)
  ```


### get

get(key: string, defValue: ValueType, callback: AsyncCallback&lt;ValueType&gt;): void
Z
zengyawen 已提交
327

A
Annie_wang 已提交
328
Obtains the value corresponding to a key. If the value is null or not in the default value format, the default value is returned. This API uses an asynchronous callback to return the result.
A
annie_wangli 已提交
329 330 331

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
332
**Parameters**
A
annie_wangli 已提交
333 334 335
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | key | string | Yes| Key of the data. It cannot be empty.|
A
Annie_wang 已提交
336
  | defValue | [ValueType](#valuetype) | Yes| Default value to be returned. It can be a number, string, or Boolean value.|
A
annie_wangli 已提交
337 338
  | callback | AsyncCallback&lt;ValueType&gt; | Yes| Callback used to return the execution result.|

A
Annie_wang 已提交
339 340
**Example**
  ```js
A
annie_wangli 已提交
341 342 343 344 345 346 347 348 349 350 351 352 353
  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)
  })
  ```


### get

get(key: string, defValue: ValueType): Promise&lt;ValueType&gt;
Z
zengyawen 已提交
354

A
Annie_wang 已提交
355
Obtains the value corresponding to a key. If the value is null or not in the default value format, the default value is returned. This API uses a promise to return the result.
A
annie_wangli 已提交
356 357 358

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
359 360 361 362 363 364
**Parameters**

| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| key | string | Yes| Key of the data. It cannot be empty.|
| defValue | [ValueType](#valuetype) | Yes| Default value to be returned. It can be a number, string, or Boolean value.|
A
annie_wangli 已提交
365

A
Annie_wang 已提交
366
**Return value**
A
annie_wangli 已提交
367 368 369 370
  | Type| Description|
  | -------- | -------- |
  | Promise&lt;ValueType&gt; | Promise used to return the result.|

A
Annie_wang 已提交
371 372
**Example**
  ```js
A
annie_wangli 已提交
373 374 375 376 377 378 379
  let promiseget = storage.get('startup', 'default')
  promiseget.then((value) => {
      console.info("The value of startup is " + value)
  }).catch((err) => {
      console.info("Get the value of startup failed with err: " + err)
  })
  ```
Z
zengyawen 已提交
380 381


A
annie_wangli 已提交
382 383 384 385 386
### putSync

putSync(key: string, value: ValueType): void

Obtains the **Storage** instance corresponding to the specified file, writes data to the **Storage** instance using a **Storage** API, and saves the modification using **flush()** or **flushSync()**.
Z
zengyawen 已提交
387

A
annie_wangli 已提交
388 389
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
390
**Parameters**
A
annie_wangli 已提交
391 392
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
A
Annie_wang 已提交
393 394
  | key | string | Yes| Key of the data. It cannot be empty.|
  | value | [ValueType](#valuetype) | Yes| New value to store. It can be a number, string, or Boolean value.|
A
annie_wangli 已提交
395

A
Annie_wang 已提交
396 397
**Example**
  ```js
A
annie_wangli 已提交
398 399 400 401 402 403 404 405
  storage.putSync('startup', 'auto')
  ```


### put

put(key: string, value: ValueType, callback: AsyncCallback&lt;void&gt;): void

A
Annie_wang 已提交
406
Obtains the **Storage** instance corresponding to the specified file, writes data to the **Storage** instance using a **Storage** API, and saves the modification using **flush()** or **flushSync()**. This API uses an asynchronous callback to return the result.
A
annie_wangli 已提交
407 408 409

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
410
**Parameters**
A
annie_wangli 已提交
411 412
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
A
Annie_wang 已提交
413 414
  | key | string | Yes| Key of the data. It cannot be empty.|
  | value | [ValueType](#valuetype) | Yes| New value to store. It can be a number, string, or Boolean value.|
A
annie_wangli 已提交
415 416
  | callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the execution result.|

A
Annie_wang 已提交
417 418
**Example**
  ```js
A
annie_wangli 已提交
419 420 421 422 423 424 425 426 427 428 429 430 431 432
  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.")
  })
  ```


### put

put(key: string, value: ValueType): Promise&lt;void&gt;

A
Annie_wang 已提交
433
Obtains the **Storage** instance corresponding to the specified file, writes data to the **Storage** instance using a **Storage** API, and saves the modification using **flush()** or **flushSync()**. This API uses a promise to return the result.
A
annie_wangli 已提交
434 435 436

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
437
**Parameters**
A
annie_wangli 已提交
438 439
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
A
Annie_wang 已提交
440 441
  | key | string | Yes| Key of the data. It cannot be empty.|
  | value | [ValueType](#valuetype) | Yes| New value to store. It can be a number, string, or Boolean value.|
A
annie_wangli 已提交
442

A
Annie_wang 已提交
443
**Return value**
A
annie_wangli 已提交
444 445 446 447
  | Type| Description|
  | -------- | -------- |
  | Promise&lt;void&gt; | Promise used to return the result.|

A
Annie_wang 已提交
448 449
**Example**
  ```js
A
annie_wangli 已提交
450 451 452 453 454 455 456 457 458 459 460 461 462 463
  let promiseput = storage.put('startup', 'auto')
  promiseput.then(() => {
      console.info("Put the value of startup successfully.")
  }).catch((err) => {
      console.info("Put the value of startup failed with err: " + err)
  })
  ```


### hasSync

hasSync(key: string): boolean

Checks whether the storage object contains data with a given key.
Z
zengyawen 已提交
464

A
annie_wangli 已提交
465 466
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
467
**Parameters**
A
annie_wangli 已提交
468 469 470 471
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | key | string | Yes| Key of the data. It cannot be empty.|

A
Annie_wang 已提交
472
**Return value**
A
annie_wangli 已提交
473 474 475 476
  | Type| Description|
  | -------- | -------- |
  | boolean | Returns **true** if the storage object contains data with the specified key; returns **false** otherwise.|

A
Annie_wang 已提交
477 478
**Example**
  ```js
A
annie_wangli 已提交
479 480 481 482 483 484 485 486 487 488 489
  let isExist = storage.hasSync('startup')
  if (isExist) {
      console.info("The key of startup is contained.")
  }
  ```


### has

has(key: string, callback: AsyncCallback&lt;boolean&gt;): boolean

A
Annie_wang 已提交
490
Checks whether the storage object contains data with a given key. This API uses an asynchronous callback to return the result.
A
annie_wangli 已提交
491 492 493

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
494
**Parameters**
A
annie_wangli 已提交
495 496 497 498 499
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | key | string | Yes| Key of the data. It cannot be empty.|
  | callback | AsyncCallback&lt;boolean&gt; | Yes| Callback used to return the execution result.|

A
Annie_wang 已提交
500
**Return value**
A
annie_wangli 已提交
501 502 503 504
  | Type| Description|
  | -------- | -------- |
  | boolean | Returns **true** if the storage object contains data with the specified key; returns **false** otherwise.|

A
Annie_wang 已提交
505 506
**Example**
  ```js
A
annie_wangli 已提交
507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522
  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.")
      }
  })
  ```


### has

has(key: string): Promise&lt;boolean&gt;

A
Annie_wang 已提交
523
Checks whether the storage object contains data with a given key. This API uses a promise to return the result.
A
annie_wangli 已提交
524 525 526

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
527
**Parameters**
A
annie_wangli 已提交
528 529 530 531
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | key | string | Yes| Key of the data. It cannot be empty.|

A
Annie_wang 已提交
532
**Return value**
A
annie_wangli 已提交
533 534 535 536
  | Type| Description|
  | -------- | -------- |
  | Promise&lt;boolean&gt; | Promise used to return the result.|

A
Annie_wang 已提交
537 538
**Example**
  ```js
A
annie_wangli 已提交
539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554
  let promisehas = storage.has('startup')
  promisehas.then((isExist) => {
      if (isExist) {
          console.info("The key of startup is contained.")
      }
  }).catch((err) => {
      console.info("Check the key of startup failed with err: " + err)
  })
  ```


### deleteSync

deleteSync(key: string): void

Deletes data with the specified key from this storage object.
Z
zengyawen 已提交
555

A
annie_wangli 已提交
556 557
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
558
**Parameters**
A
annie_wangli 已提交
559 560 561 562
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | key | string | Yes| Key of the data. It cannot be empty.|

A
Annie_wang 已提交
563 564
**Example**
  ```js
A
annie_wangli 已提交
565 566 567 568
  storage.deleteSync('startup')
  ```


A
Annie_wang 已提交
569
### delete
A
annie_wangli 已提交
570 571 572

delete(key: string, callback: AsyncCallback&lt;void&gt;): void

A
Annie_wang 已提交
573
Deletes data with the specified key from this storage object. This API uses an asynchronous callback to return the result.
A
annie_wangli 已提交
574 575 576

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
577
**Parameters**
A
annie_wangli 已提交
578 579 580 581 582
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | key | string | Yes| Key of the data. It cannot be empty.|
  | callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the execution result.|

A
Annie_wang 已提交
583 584
**Example**
  ```js
A
annie_wangli 已提交
585 586 587 588 589 590 591 592 593
  storage.delete('startup', function (err) {
      if (err) {
          console.info("Delete startup key failed with err: " + err)
          return
      }
      console.info("Deleted startup key successfully.")
  })
  ```

Z
zengyawen 已提交
594

A
annie_wangli 已提交
595
### delete
Z
zengyawen 已提交
596

A
annie_wangli 已提交
597
delete(key: string): Promise&lt;void&gt;
Z
zengyawen 已提交
598

A
Annie_wang 已提交
599
Deletes data with the specified key from this storage object. This API uses a promise to return the result.
Z
zengyawen 已提交
600

A
annie_wangli 已提交
601
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
Z
zengyawen 已提交
602

A
Annie_wang 已提交
603
**Parameters**
A
annie_wangli 已提交
604 605 606
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | key | string | Yes| Key of the data.|
Z
zengyawen 已提交
607

A
Annie_wang 已提交
608
**Return value**
A
annie_wangli 已提交
609 610 611
  | Type| Description|
  | -------- | -------- |
  | Promise&lt;void&gt; | Promise used to return the result.|
Z
zengyawen 已提交
612

A
Annie_wang 已提交
613 614
**Example**
  ```js
A
annie_wangli 已提交
615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630
  let promisedel = storage.delete('startup')
  promisedel.then(() => {
      console.info("Deleted startup key successfully.")
  }).catch((err) => {
      console.info("Delete startup key failed with err: " + err)
  })
  ```


### flushSync

flushSync(): void

Saves the modification of this object to the **Storage** instance and synchronizes the modification to the file.

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
Z
zengyawen 已提交
631

A
Annie_wang 已提交
632 633
**Example**
  ```js
A
annie_wangli 已提交
634 635 636 637 638
  storage.flushSync()
  ```


### flush
Z
zengyawen 已提交
639

A
annie_wangli 已提交
640
flush(callback: AsyncCallback&lt;void&gt;): void
Z
zengyawen 已提交
641

A
Annie_wang 已提交
642
Saves the modification of this object to the **Storage** instance and synchronizes the modification to the file. This API uses an asynchronous callback to return the result.
Z
zengyawen 已提交
643

A
annie_wangli 已提交
644
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
Z
zengyawen 已提交
645

A
Annie_wang 已提交
646
**Parameters**
A
annie_wangli 已提交
647 648 649
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the execution result.|
Z
zengyawen 已提交
650

A
Annie_wang 已提交
651 652
**Example**
  ```js
A
annie_wangli 已提交
653 654 655 656 657 658 659 660
  storage.flush(function (err) {
      if (err) {
          console.info("Flush to file failed with err: " + err)
          return
      }
      console.info("Flushed to file successfully.")
  })
  ```
Z
zengyawen 已提交
661 662


A
annie_wangli 已提交
663
### flush
Z
zengyawen 已提交
664

A
annie_wangli 已提交
665
flush(): Promise&lt;void&gt;
Z
zengyawen 已提交
666

A
Annie_wang 已提交
667
Saves the modification of this object to the **Storage** instance and synchronizes the modification to the file. This API uses a promise to return the result.
Z
zengyawen 已提交
668

A
annie_wangli 已提交
669
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
Z
zengyawen 已提交
670

A
Annie_wang 已提交
671
**Return value**
A
annie_wangli 已提交
672 673 674 675
  | Type| Description|
  | -------- | -------- |
  | Promise&lt;void&gt; | Promise used to return the result.|

A
Annie_wang 已提交
676 677
**Example**
  ```js
A
annie_wangli 已提交
678 679 680 681 682 683 684 685 686 687 688 689 690 691
  let promiseflush = storage.flush()
  promiseflush.then(() => {
      console.info("Flushed to file successfully.")
  }).catch((err) => {
      console.info("Flush to file failed with err: " + err)
  })
  ```


### clearSync

clearSync(): void

Clears this **Storage** object.
Z
zengyawen 已提交
692

A
annie_wangli 已提交
693 694
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
695 696
**Example**
  ```js
A
annie_wangli 已提交
697 698 699 700 701 702 703 704
  storage.clearSync()
  ```


### clear

clear(callback: AsyncCallback&lt;void&gt;): void

A
Annie_wang 已提交
705
Clears this **Storage** object. This API uses an asynchronous callback to return the result.
A
annie_wangli 已提交
706 707 708

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
709
**Parameters**
A
annie_wangli 已提交
710 711 712
  | Name| Type| Mandatory| Description|
  | -------- | -------- | -------- | -------- |
  | callback | AsyncCallback&lt;void&gt; | Yes| Callback used to return the execution result.|
Z
zengyawen 已提交
713

A
Annie_wang 已提交
714 715
**Example**
  ```js
A
annie_wangli 已提交
716 717 718 719 720 721 722 723 724 725 726 727 728 729
  storage.clear(function (err) {
      if (err) {
          console.info("Clear to file failed with err: " + err)
          return
      }
      console.info("Cleared to file successfully.")
  })
  ```


### clear

clear(): Promise&lt;void&gt;

A
Annie_wang 已提交
730
Clears this **Storage** object. This API uses a promise to return the result.
A
annie_wangli 已提交
731 732 733

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
734
**Return value**
A
annie_wangli 已提交
735 736 737 738
  | Type| Description|
  | -------- | -------- |
  | Promise&lt;void&gt; | Promise used to return the result.|

A
Annie_wang 已提交
739 740
**Example**
  ```js
A
annie_wangli 已提交
741 742 743 744 745 746 747 748 749 750 751 752 753 754
  let promiseclear = storage.clear()
  promiseclear.then(() => {
      console.info("Cleared to file successfully.")
  }).catch((err) => {
      console.info("Clear to file failed with err: " + err)
  })
  ```


### on('change')

on(type: 'change', callback: Callback&lt;StorageObserver&gt;): void

Subscribes to data changes. The **StorageObserver** needs to be implemented. When the value of the key subscribed to is changed, a callback will be invoked after **flush()** or **flushSync()** is executed.
Z
zengyawen 已提交
755

A
annie_wangli 已提交
756 757
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
758
**Parameters**
A
annie_wangli 已提交
759 760 761 762 763
  | Name| Type| Description|
  | -------- | -------- | -------- |
  | type | string | Event type. The value **change** indicates data change events.|
  | callback | Callback&lt;[StorageObserver](#storageobserver)&gt; | Callback used to return data changes.|

A
Annie_wang 已提交
764 765
**Example**
  ```js
A
annie_wangli 已提交
766 767 768 769 770 771 772 773 774 775 776 777
  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.
  ```


### off('change')

off(type: 'change', callback: Callback&lt;StorageObserver&gt;): void
Z
zengyawen 已提交
778 779 780

Unsubscribes from data changes.

A
annie_wangli 已提交
781 782
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
783
**Parameters**
A
annie_wangli 已提交
784 785 786 787 788
  | Name| Type| Description|
  | -------- | -------- | -------- |
  | type | string | Event type. The value **change** indicates data change events.|
  | callback | Callback&lt;[StorageObserver](#storageobserver)&gt; | Callback used to return data changes.|

A
Annie_wang 已提交
789 790
**Example**
  ```js
A
annie_wangli 已提交
791 792 793 794 795 796 797 798 799 800 801 802 803 804
  var observer = function (key) {
      console.info("The key of " + key + " changed.")
  }
  storage.off('change', observer)
  ```


## StorageObserver

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| key | string | No| Data changed.|
A
Annie_wang 已提交
805 806 807 808 809 810 811 812 813 814 815 816

## ValueType

Enumerates the value types.

**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

| Name   | Description                |
| ------- | -------------------- |
| number  | The value is a number.  |
| string  | The value is a string.  |
| boolean | The value is of Boolean type.|