js-apis-data-storage.md 29.5 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/>
Z
zengyawen 已提交
7
>
A
Annie_wang 已提交
8 9 10 11 12
> -  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).
> 
> -  The APIs of this module can be used only in the FA model.
A
annie_wangli 已提交
13 14 15


## Modules to Import
Z
zengyawen 已提交
16

A
Annie_wang 已提交
17
```js
A
Annie_wang 已提交
18
import data_storage from '@ohos.data.storage';
Z
zengyawen 已提交
19 20
```

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

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

25 26 27 28
| Name             | Type   | Readable | Writable | Description                                                 |
| ---------------- | ------ | -------- | -------- | ----------------------------------------------------------- |
| 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 已提交
29 30


A
Annie_wang 已提交
31
## data_storage.getStorageSync
A
annie_wangli 已提交
32 33 34

getStorageSync(path: string): Storage

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

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

A
Annie_wang 已提交
39
**Parameters**
40

A
Annie_wang 已提交
41 42 43
| Name| Type  | Mandatory| Description                      |
| ------ | ------ | ---- | -------------------------- |
| path   | string | Yes  | Path of the target file.|
A
annie_wangli 已提交
44

A
Annie_wang 已提交
45
**Return value**
46

A
Annie_wang 已提交
47 48 49
| Type               | Description                                             |
| ------------------- | ------------------------------------------------- |
| [Storage](#storage) | **Storage** instance used for data storage operations.|
A
annie_wangli 已提交
50

A
Annie_wang 已提交
51
**Example**
52 53 54 55 56 57 58

```js
import featureAbility from '@ohos.ability.featureAbility';

var path;
var context = featureAbility.getContext();
context.getFilesDir().then((filePath) => {
A
Annie_wang 已提交
59 60
  path = filePath;
  console.info("======================>getFilesDirPromise====================>");
61

A
Annie_wang 已提交
62 63 64 65
  let storage = data_storage.getStorageSync(path + '/mystore');
  storage.putSync('startup', 'auto');
  storage.flushSync();
});
66
```
A
annie_wangli 已提交
67 68


A
Annie_wang 已提交
69
## data_storage.getStorage
A
annie_wangli 已提交
70 71 72

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

A
Annie_wang 已提交
73
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 已提交
74 75 76

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

A
Annie_wang 已提交
77
**Parameters**
78

A
Annie_wang 已提交
79 80 81 82
| 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_wangli 已提交
83

A
Annie_wang 已提交
84
**Example**
85 86 87 88 89 90 91

```js
import featureAbility from '@ohos.ability.featureAbility';

var path;
var context = featureAbility.getContext();
context.getFilesDir().then((filePath) => {
A
Annie_wang 已提交
92 93
  path = filePath;
  console.info("======================>getFilesDirPromise====================>");
94

A
Annie_wang 已提交
95
  data_storage.getStorage(path + '/mystore', function (err, storage) {
96
    if (err) {
A
Annie_wang 已提交
97 98
      console.info("Failed to get the storage. path: " + path + '/mystore');
      return;
99 100 101
    }
    storage.putSync('startup', 'auto');
    storage.flushSync();
A
Annie_wang 已提交
102 103
  })
});
104
```
Z
zengyawen 已提交
105 106


A
Annie_wang 已提交
107
## data_storage.getStorage
A
annie_wangli 已提交
108 109 110

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

A
Annie_wang 已提交
111
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 已提交
112 113 114

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

A
Annie_wang 已提交
115
**Parameters**
116

A
Annie_wang 已提交
117 118 119
| Name| Type  | Mandatory| Description                      |
| ------ | ------ | ---- | -------------------------- |
| path   | string | Yes  | Path of the target file.|
A
annie_wangli 已提交
120

A
Annie_wang 已提交
121
**Return value**
122

A
Annie_wang 已提交
123 124 125
| Type                              | Description                           |
| ---------------------------------- | ------------------------------- |
| Promise&lt;[Storage](#storage)&gt; | Promise used to return the result.|
A
annie_wangli 已提交
126

A
Annie_wang 已提交
127
**Example**
128 129 130 131 132 133 134

```js
import featureAbility from '@ohos.ability.featureAbility';

var path;
var context = featureAbility.getContext();
context.getFilesDir().then((filePath) => {
A
Annie_wang 已提交
135 136
  path = filePath;
  console.info("======================>getFilesDirPromise====================>");
137

A
Annie_wang 已提交
138 139
  let getPromise = data_storage.getStorage(path + '/mystore');
  getPromise.then((storage) => {
140 141
    storage.putSync('startup', 'auto');
    storage.flushSync();
A
Annie_wang 已提交
142
  }).catch((err) => {
143
    console.info("Failed to get the storage. path: " + path + '/mystore');
A
Annie_wang 已提交
144 145
  })
});
146
```
Z
zengyawen 已提交
147 148


A
Annie_wang 已提交
149
## data_storage.deleteStorageSync
A
annie_wangli 已提交
150 151 152

deleteStorageSync(path: string): void

A
Annie_wang 已提交
153
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 已提交
154 155 156

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

A
Annie_wang 已提交
157
**Parameters**
158

A
Annie_wang 已提交
159 160 161
| Name| Type  | Mandatory| Description                      |
| ------ | ------ | ---- | -------------------------- |
| path   | string | Yes  | Path of the target file.|
A
annie_wangli 已提交
162

A
Annie_wang 已提交
163
**Example**
164 165 166 167 168 169 170 171

```js
import featureAbility from '@ohos.ability.featureAbility';

var path;
var context = featureAbility.getContext();
context.getFilesDir().then((filePath) => {
    path = filePath;
172
    console.info("======================>getFilesDirPromise====================>");
173

A
Annie_wang 已提交
174 175
    data_storage.deleteStorageSync(path + '/mystore');
});  
176
```
A
annie_wangli 已提交
177

A
Annie_wang 已提交
178
## data_storage.deleteStorage
A
annie_wangli 已提交
179 180 181

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

A
Annie_wang 已提交
182
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 已提交
183 184 185

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

A
Annie_wang 已提交
186
**Parameters**
187

A
Annie_wang 已提交
188 189 190
| Name  | Type                     | Mandatory| Description                      |
| -------- | ------------------------- | ---- | -------------------------- |
| path     | string                    | Yes  | Path of the target file.|
191
| callback | AsyncCallback&lt;void&gt; | Yes       | Callback that returns no value. |
A
annie_wangli 已提交
192

A
Annie_wang 已提交
193
**Example**
194 195 196 197 198 199 200

```js
import featureAbility from '@ohos.ability.featureAbility';

var path;
var context = featureAbility.getContext();
context.getFilesDir().then((filePath) => {
A
Annie_wang 已提交
201 202
  path = filePath;
  console.info("======================>getFilesDirPromise====================>");
203

A
Annie_wang 已提交
204
  data_storage.deleteStorage(path + '/mystore', function (err) {
205
    if (err) {
A
Annie_wang 已提交
206 207
      console.info("Failed to delete the storage with err: " + err);
      return;
208 209
    }
    console.info("Succeeded in deleting the storage.");
A
Annie_wang 已提交
210 211
  })
});
212
```
A
annie_wangli 已提交
213

Z
zengyawen 已提交
214

A
Annie_wang 已提交
215
## data_storage.deleteStorage
Z
zengyawen 已提交
216

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

A
Annie_wang 已提交
219
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 已提交
220 221 222

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

A
Annie_wang 已提交
223
**Parameters**
224

A
Annie_wang 已提交
225 226 227
| Name| Type  | Mandatory| Description                      |
| ------ | ------ | ---- | -------------------------- |
| path   | string | Yes  | Path of the target file.|
A
annie_wangli 已提交
228

A
Annie_wang 已提交
229
**Return value**
A
Annie_wang 已提交
230 231 232

| Type               | Description                           |
| ------------------- | ------------------------------- |
233
| Promise&lt;void&gt; | Promise that returns no value. |
A
annie_wangli 已提交
234

A
Annie_wang 已提交
235
**Example**
236 237 238 239 240 241 242

```js
import featureAbility from '@ohos.ability.featureAbility';

var path;
var context = featureAbility.getContext();
context.getFilesDir().then((filePath) => {
A
Annie_wang 已提交
243 244
  path = filePath;
  console.info("======================>getFilesDirPromise====================>");
245

A
Annie_wang 已提交
246 247
  let promisedelSt = data_storage.deleteStorage(path + '/mystore');
  promisedelSt.then(() => {
248
    console.info("Succeeded in deleting the storage.");
A
Annie_wang 已提交
249
  }).catch((err) => {
250
    console.info("Failed to delete the storage with err: " + err);
A
Annie_wang 已提交
251 252
  })
});
253
```
A
annie_wangli 已提交
254 255


A
Annie_wang 已提交
256
## data_storage.removeStorageFromCacheSync
A
annie_wangli 已提交
257 258 259 260

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 已提交
261

A
annie_wangli 已提交
262 263
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
264
**Parameters**
A
Annie_wang 已提交
265 266 267
| Name| Type  | Mandatory| Description                      |
| ------ | ------ | ---- | -------------------------- |
| path   | string | Yes  | Path of the target file.|
A
annie_wangli 已提交
268

A
Annie_wang 已提交
269
**Example**
270 271 272 273 274 275 276 277

```js
import featureAbility from '@ohos.ability.featureAbility';

var path;
var context = featureAbility.getContext();
context.getFilesDir().then((filePath) => {
    path = filePath;
278
    console.info("======================>getFilesDirPromise====================>");
A
Annie_wang 已提交
279 280
    
    data_storage.removeStorageFromCacheSync(path + '/mystore');
281 282
});  
```
A
annie_wangli 已提交
283 284


A
Annie_wang 已提交
285
## data_storage.removeStorageFromCache
A
annie_wangli 已提交
286 287 288

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

A
Annie_wang 已提交
289
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 已提交
290 291 292

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

A
Annie_wang 已提交
293
**Parameters**
294

A
Annie_wang 已提交
295 296 297
| Name  | Type                     | Mandatory| Description                      |
| -------- | ------------------------- | ---- | -------------------------- |
| path     | string                    | Yes  | Path of the target file.|
298
| callback | AsyncCallback&lt;void&gt; | Yes       | Callback that returns no value. |
A
annie_wangli 已提交
299

A
Annie_wang 已提交
300
**Example**
301 302 303 304 305 306 307

```js
import featureAbility from '@ohos.ability.featureAbility';

var path;
var context = featureAbility.getContext();
context.getFilesDir().then((filePath) => {
A
Annie_wang 已提交
308 309
  path = filePath;
  console.info("======================>getFilesDirPromise====================>");
310

A
Annie_wang 已提交
311
  data_storage.removeStorageFromCache(path + '/mystore', function (err) {
312
    if (err) {
A
Annie_wang 已提交
313 314
      console.info("Failed to remove storage from cache with err: " + err);
      return;
315 316
    }
    console.info("Succeeded in removing storage from cache.");
A
Annie_wang 已提交
317 318
  })
});
319
```
A
annie_wangli 已提交
320 321


A
Annie_wang 已提交
322
## data_storage.removeStorageFromCache
A
annie_wangli 已提交
323 324 325

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

A
Annie_wang 已提交
326
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 已提交
327 328 329

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

A
Annie_wang 已提交
330
**Parameters**
331

A
Annie_wang 已提交
332 333 334
| Name| Type  | Mandatory| Description                      |
| ------ | ------ | ---- | -------------------------- |
| path   | string | Yes  | Path of the target file.|
A
annie_wangli 已提交
335

A
Annie_wang 已提交
336
**Return value**
337

A
Annie_wang 已提交
338 339
| Type               | Description                           |
| ------------------- | ------------------------------- |
340
| Promise&lt;void&gt; | Promise that returns no value. |
A
annie_wangli 已提交
341

A
Annie_wang 已提交
342
**Example**
343 344 345 346 347 348 349

```js
import featureAbility from '@ohos.ability.featureAbility';

var path;
var context = featureAbility.getContext();
context.getFilesDir().then((filePath) => {
A
Annie_wang 已提交
350 351
  path = filePath;
  console.info("======================>getFilesDirPromise====================>");
352

A
Annie_wang 已提交
353 354
  let promiserevSt = data_storage.removeStorageFromCache(path + '/mystore')
  promiserevSt.then(() => {
355
    console.info("Succeeded in removing storage from cache.");
A
Annie_wang 已提交
356
  }).catch((err) => {
357
    console.info("Failed to remove storage from cache with err: " + err);
A
Annie_wang 已提交
358 359
  })
});
360
```
A
annie_wangli 已提交
361 362

## Storage
Z
zengyawen 已提交
363 364 365

Provides APIs for obtaining and modifying storage data.

A
annie_wangli 已提交
366 367 368
### getSync

getSync(key: string, defValue: ValueType): ValueType
Z
zengyawen 已提交
369 370 371

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 已提交
372 373
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
374
**Parameters**
375

A
Annie_wang 已提交
376 377 378 379
| Name  | Type                   | Mandatory| Description                                                        |
| -------- | ----------------------- | ---- | ------------------------------------------------------------ |
| key      | string                  | Yes  | Key of the data. It cannot be empty.                             |
| 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 已提交
380

A
Annie_wang 已提交
381
**Return value**
382

A
Annie_wang 已提交
383 384 385
| 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_wangli 已提交
386

A
Annie_wang 已提交
387
**Example**
388 389 390 391 392

```js
let value = storage.getSync('startup', 'default');
console.info("The value of startup is " + value);
```
A
annie_wangli 已提交
393 394 395 396 397


### get

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

A
Annie_wang 已提交
399
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 已提交
400 401 402

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

A
Annie_wang 已提交
403
**Parameters**
404

A
Annie_wang 已提交
405 406 407 408 409
| 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.|
| callback | AsyncCallback&lt;ValueType&gt; | Yes  | Callback used to return the execution result.                               |
A
annie_wangli 已提交
410

A
Annie_wang 已提交
411
**Example**
412 413 414 415 416 417

```js
storage.get('startup', 'default', function(err, value) {
    if (err) {
        console.info("Failed to get the value of startup with err: " + err);
        return;
A
annie_wangli 已提交
418
      }
419 420 421
    console.info("The value of startup is " + value);
})
```
A
annie_wangli 已提交
422 423 424 425 426


### get

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

A
Annie_wang 已提交
428
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 已提交
429 430 431

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

A
Annie_wang 已提交
432
**Parameters**
A
annie_wangli 已提交
433

A
Annie_wang 已提交
434 435 436 437
| 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_wang 已提交
438 439

**Return value**
440

A
Annie_wang 已提交
441 442 443
| Type                    | Description                           |
| ------------------------ | ------------------------------- |
| Promise&lt;ValueType&gt; | Promise used to return the result.|
A
annie_wangli 已提交
444

A
Annie_wang 已提交
445
**Example**
A
Annie_wang 已提交
446

447 448 449 450 451 452 453 454
```js
let promiseget = storage.get('startup', 'default');
promiseget.then((value) => {
    console.info("The value of startup is " + value)
}).catch((err) => {
    console.info("Failed to get the value of startup with err: " + err);
})
```
Z
zengyawen 已提交
455 456


A
annie_wangli 已提交
457 458 459 460 461
### 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 已提交
462

A
annie_wangli 已提交
463 464
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
465
**Parameters**
466

A
Annie_wang 已提交
467 468 469 470
| Name| Type                   | Mandatory| Description                                     |
| ------ | ----------------------- | ---- | ----------------------------------------- |
| 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 已提交
471

A
Annie_wang 已提交
472
**Example**
473 474

```js
A
Annie_wang 已提交
475
storage.putSync('startup', 'auto');
476
```
A
annie_wangli 已提交
477 478 479 480 481 482


### put

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

A
Annie_wang 已提交
483
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 已提交
484 485 486

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

A
Annie_wang 已提交
487
**Parameters**
488

A
Annie_wang 已提交
489 490 491 492
| Name  | Type                     | Mandatory| Description                                     |
| -------- | ------------------------- | ---- | ----------------------------------------- |
| 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.|
493
| callback | AsyncCallback&lt;void&gt; | Yes       | Callback that returns no value.                              |
A
annie_wangli 已提交
494

A
Annie_wang 已提交
495
**Example**
496 497 498 499 500 501 502 503 504 505

```js
storage.put('startup', 'auto', function (err) {
    if (err) {
        console.info("Failed to put the value of startup with err: " + err);
        return;
    }
    console.info("Succeeded in putting the value of startup.");
})
```
A
annie_wangli 已提交
506 507 508 509 510 511


### put

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

A
Annie_wang 已提交
512
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 已提交
513 514 515

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

A
Annie_wang 已提交
516
**Parameters**
517

A
Annie_wang 已提交
518 519 520 521
| Name| Type                   | Mandatory| Description                                     |
| ------ | ----------------------- | ---- | ----------------------------------------- |
| 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 已提交
522

A
Annie_wang 已提交
523
**Return value**
524

A
Annie_wang 已提交
525 526
| Type               | Description                       |
| ------------------- | --------------------------- |
527
| Promise&lt;void&gt; | Promise that returns no value. |
A
annie_wangli 已提交
528

A
Annie_wang 已提交
529
**Example**
A
Annie_wang 已提交
530

531 532 533 534 535 536 537 538
```js
let promiseput = storage.put('startup', 'auto');
promiseput.then(() => {
    console.info("Succeeded in putting the value of startup.");
}).catch((err) => {
    console.info("Failed to put the value of startup with err: " + err);
})
```
A
annie_wangli 已提交
539 540 541 542 543 544 545


### hasSync

hasSync(key: string): boolean

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

A
annie_wangli 已提交
547 548
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
549
**Parameters**
550

A
Annie_wang 已提交
551 552 553
| Name| Type  | Mandatory| Description                           |
| ------ | ------ | ---- | ------------------------------- |
| key    | string | Yes  | Key of the data. It cannot be empty.|
A
annie_wangli 已提交
554

A
Annie_wang 已提交
555
**Return value**
556

A
Annie_wang 已提交
557 558 559
| Type   | Description                                 |
| ------- | ------------------------------------- |
| boolean | Returns **true** if the storage object contains data with the specified key; returns **false** otherwise.|
A
annie_wangli 已提交
560

A
Annie_wang 已提交
561
**Example**
562 563 564 565 566 567 568

```js
let isExist = storage.hasSync('startup');
if (isExist) {
    console.info("The key of startup is contained.");
}
```
A
annie_wangli 已提交
569 570 571 572 573 574


### has

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

A
Annie_wang 已提交
575
Checks whether the storage object contains data with a given key. This API uses an asynchronous callback to return the result.
A
annie_wangli 已提交
576 577 578

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

A
Annie_wang 已提交
579
**Parameters**
580

A
Annie_wang 已提交
581 582 583 584
| 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_wangli 已提交
585

A
Annie_wang 已提交
586
**Return value**
587

A
Annie_wang 已提交
588 589 590
| Type   | Description                           |
| ------- | ------------------------------- |
| boolean | Returns **true** if the storage object contains data with the specified key; returns **false** otherwise.|
A
annie_wangli 已提交
591

A
Annie_wang 已提交
592
**Example**
593 594 595 596 597 598 599 600 601 602 603 604

```js
storage.has('startup', function (err, isExist) {
    if (err) {
        console.info("Failed to check the key of startup with err: " + err);
        return;
    }
    if (isExist) {
        console.info("The key of startup is contained.");
    }
})
```
A
annie_wangli 已提交
605 606 607 608 609 610


### has

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

A
Annie_wang 已提交
611
Checks whether the storage object contains data with a given key. This API uses a promise to return the result.
A
annie_wangli 已提交
612 613 614

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

A
Annie_wang 已提交
615
**Parameters**
616

A
Annie_wang 已提交
617 618 619
| Name| Type  | Mandatory| Description                           |
| ------ | ------ | ---- | ------------------------------- |
| key    | string | Yes  | Key of the data. It cannot be empty.|
A
annie_wangli 已提交
620

A
Annie_wang 已提交
621
**Return value**
622

A
Annie_wang 已提交
623 624 625
| Type                  | Description                       |
| ---------------------- | --------------------------- |
| Promise&lt;boolean&gt; | Promise used to return the result.|
A
annie_wangli 已提交
626

A
Annie_wang 已提交
627
**Example**
628 629 630 631 632 633 634 635 636 637 638

```js
let promisehas = storage.has('startup')
promisehas.then((isExist) => {
    if (isExist) {
        console.info("The key of startup is contained.");
    }
}).catch((err) => {
    console.info("Failed to check the key of startup with err: " + err);
})
```
A
annie_wangli 已提交
639 640 641 642 643 644 645


### deleteSync

deleteSync(key: string): void

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

A
annie_wangli 已提交
647 648
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
649
**Parameters**
650

A
Annie_wang 已提交
651 652 653
| Name| Type  | Mandatory| Description                             |
| ------ | ------ | ---- | --------------------------------- |
| key    | string | Yes  | Key of the data. It cannot be empty.|
A
annie_wangli 已提交
654

A
Annie_wang 已提交
655
**Example**
656 657

```js
A
Annie_wang 已提交
658
 storage.deleteSync('startup');
659
```
A
annie_wangli 已提交
660 661


A
Annie_wang 已提交
662
### delete
A
annie_wangli 已提交
663 664 665

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

A
Annie_wang 已提交
666
Deletes data with the specified key from this storage object. This API uses an asynchronous callback to return the result.
A
annie_wangli 已提交
667 668 669

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

A
Annie_wang 已提交
670
**Parameters**
671

A
Annie_wang 已提交
672 673 674
| Name  | Type                     | Mandatory| Description                           |
| -------- | ------------------------- | ---- | ------------------------------- |
| key      | string                    | Yes  | Key of the data. It cannot be empty.|
675
| callback | AsyncCallback&lt;void&gt; | Yes       | Callback that returns no value.      |
A
annie_wangli 已提交
676

A
Annie_wang 已提交
677
**Example**
678 679 680 681 682 683 684 685 686 687

```js
storage.delete('startup', function (err) {
    if (err) {
        console.info("Failed to delete startup key failed err: " + err);
        return;
    }
    console.info("Succeeded in deleting startup key.");
})
```
A
annie_wangli 已提交
688

Z
zengyawen 已提交
689

A
annie_wangli 已提交
690
### delete
Z
zengyawen 已提交
691

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

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

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

A
Annie_wang 已提交
698
**Parameters**
699

A
Annie_wang 已提交
700 701 702
| Name| Type  | Mandatory| Description                 |
| ------ | ------ | ---- | --------------------- |
| key    | string | Yes  | Key of the data.|
Z
zengyawen 已提交
703

A
Annie_wang 已提交
704
**Return value**
705

A
Annie_wang 已提交
706 707
| Type               | Description                       |
| ------------------- | --------------------------- |
708
| Promise&lt;void&gt; | Promise that returns no value. |
Z
zengyawen 已提交
709

A
Annie_wang 已提交
710
**Example**
711 712 713 714 715 716 717 718 719

```js
let promisedel = storage.delete('startup')
promisedel.then(() => {
    console.info("Succeeded in deleting startup key.");
}).catch((err) => {
    console.info("Failed to delete startup key failed err: " + err);
})
```
A
annie_wangli 已提交
720 721 722 723 724 725 726 727 728


### 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 已提交
729

A
Annie_wang 已提交
730
**Example**
731 732

```js
A
Annie_wang 已提交
733
storage.flushSync();
734
```
A
annie_wangli 已提交
735 736 737


### flush
Z
zengyawen 已提交
738

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

A
Annie_wang 已提交
741
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 已提交
742

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

A
Annie_wang 已提交
745
**Parameters**
746

A
Annie_wang 已提交
747 748
| Name  | Type                     | Mandatory| Description      |
| -------- | ------------------------- | ---- | ---------- |
749
| callback | AsyncCallback&lt;void&gt; | Yes       | Callback that returns no value. |
Z
zengyawen 已提交
750

A
Annie_wang 已提交
751
**Example**
752 753 754 755 756 757 758 759 760 761

```js
storage.flush(function (err) {
    if (err) {
        console.info("Failed to flush to file with err: " + err);
        return;
    }
    console.info("Succeeded in flushing to file.");
})
```
Z
zengyawen 已提交
762 763


A
annie_wangli 已提交
764
### flush
Z
zengyawen 已提交
765

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

A
Annie_wang 已提交
768
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 已提交
769

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

A
Annie_wang 已提交
772
**Return value**
773

A
Annie_wang 已提交
774 775
| Type               | Description                       |
| ------------------- | --------------------------- |
776
| Promise&lt;void&gt; | Promise that returns no value. |
A
annie_wangli 已提交
777

A
Annie_wang 已提交
778
**Example**
779 780 781 782 783 784 785 786 787

```js
let promiseflush = storage.flush();
promiseflush.then(() => {
    console.info("Succeeded in flushing to file.");
}).catch((err) => {
    console.info("Failed to flush to file with err: " + err);
})
```
A
annie_wangli 已提交
788 789 790 791 792 793 794


### clearSync

clearSync(): void

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

A
annie_wangli 已提交
796 797
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
798
**Example**
799 800

```js
A
Annie_wang 已提交
801
storage.clearSync();
802
```
A
annie_wangli 已提交
803 804 805 806 807 808


### clear

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

A
Annie_wang 已提交
809
Clears this **Storage** object. This API uses an asynchronous callback to return the result.
A
annie_wangli 已提交
810 811 812

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

A
Annie_wang 已提交
813
**Parameters**
814

A
Annie_wang 已提交
815 816
| Name  | Type                     | Mandatory| Description      |
| -------- | ------------------------- | ---- | ---------- |
817
| callback | AsyncCallback&lt;void&gt; | Yes       | Callback that returns no value. |
Z
zengyawen 已提交
818

A
Annie_wang 已提交
819
**Example**
820 821 822 823 824 825 826 827 828 829

```js
storage.clear(function (err) {
    if (err) {
        console.info("Failed to clear the storage with err: " + err);
        return;
    }
    console.info("Succeeded in clearing the storage.");
})
```
A
annie_wangli 已提交
830 831 832 833 834 835


### clear

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

A
Annie_wang 已提交
836
Clears this **Storage** object. This API uses a promise to return the result.
A
annie_wangli 已提交
837 838 839

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

A
Annie_wang 已提交
840
**Return value**
A
Annie_wang 已提交
841 842
| Type               | Description                       |
| ------------------- | --------------------------- |
843
| Promise&lt;void&gt; | Promise that returns no value. |
A
annie_wangli 已提交
844

A
Annie_wang 已提交
845
**Example**
846 847 848 849 850 851 852 853 854

```js
let promiseclear = storage.clear();
promiseclear.then(() => {
    console.info("Succeeded in clearing the storage.");
}).catch((err) => {
    console.info("Failed to clear the storage with err: " + err);
})
```
A
annie_wangli 已提交
855 856 857 858 859 860 861


### 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 已提交
862

A
annie_wangli 已提交
863 864
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
865
**Parameters**
866

A
Annie_wang 已提交
867 868 869 870
| 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_wangli 已提交
871

A
Annie_wang 已提交
872
**Example**
873 874 875 876 877 878 879 880 881

```js
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.
```
A
annie_wangli 已提交
882 883 884 885 886


### off('change')

off(type: 'change', callback: Callback&lt;StorageObserver&gt;): void
Z
zengyawen 已提交
887 888 889

Unsubscribes from data changes.

A
annie_wangli 已提交
890 891
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core

A
Annie_wang 已提交
892
**Parameters**
893

A
Annie_wang 已提交
894 895 896 897
| 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_wangli 已提交
898

A
Annie_wang 已提交
899
**Example**
900 901 902 903 904 905 906

```js
var observer = function (key) {
    console.info("The key of " + key + " changed.");
}
storage.off('change', observer);
```
A
annie_wangli 已提交
907 908 909 910 911 912


## StorageObserver

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

A
Annie_wang 已提交
913 914 915
| Name| Type| Mandatory| Description            |
| ---- | -------- | ---- | ---------------- |
| key  | string   | No  | Data changed.|
A
Annie_wang 已提交
916 917 918 919 920 921 922

## ValueType

Enumerates the value types.

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

A
Annie_wang 已提交
923 924 925 926 927
| Type   | Description                |
| ------- | -------------------- |
| number  | The value is a number.  |
| string  | The value is a string.  |
| boolean | The value is of Boolean type.|