js-apis-data-preferences.md 32.2 KB
Newer Older
A
Annie_wang 已提交
1
# Preferences
A
annie_wangli 已提交
2

A
Annie_wang 已提交
3 4 5
The **Preferences** module provides APIs for processing data in the form of key-value (KV) pairs and supports persistence of the KV pairs when required.

The key is of the string type, and the value can be a number, a string, a Boolean value, or an array of numbers, strings, or Boolean values.
A
annie_wangli 已提交
6 7


A
Annie_wang 已提交
8
> **NOTE**<br/>
A
Annie_wang 已提交
9
>
A
Annie_wang 已提交
10
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
A
annie_wangli 已提交
11 12


A
Annie_wang 已提交
13
## Modules to Import
A
annie_wangli 已提交
14

A
Annie_wang 已提交
15
```js
A
Annie_wang 已提交
16
import data_preferences from '@ohos.data.preferences';
A
annie_wangli 已提交
17 18
```

A
Annie_wang 已提交
19
## Constants
A
annie_wangli 已提交
20

A
Annie_wang 已提交
21
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
A
annie_wangli 已提交
22

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


A
annie_wangli 已提交
29
## data_preferences.getPreferences
A
annie_wangli 已提交
30 31 32

getPreferences(context: Context, name: string, callback: AsyncCallback&lt;Preferences&gt;): void

A
Annie_wang 已提交
33
Obtains a **Preferences** instance. This API uses an asynchronous callback to return the result.
A
annie_wangli 已提交
34

A
Annie_wang 已提交
35
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
A
annie_wangli 已提交
36

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

| Name  | Type                                            | Mandatory| Description                                                        |
| -------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ |
A
Annie_wang 已提交
41 42
| context  | Context            | Yes  | Application context.<br>For the application context of the FA model, see [Context](js-apis-Context.md).<br>For the application context of the stage model, see [Context](js-apis-ability-context.md).                                                |
| name     | string                                           | Yes  | Name of the **Preferences** instance.|
A
Annie_wang 已提交
43
| callback | AsyncCallback&lt;[Preferences](#preferences)&gt; | Yes  | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **object** is the **Preferences** instance obtained. Otherwise, **err** is an error code.|
A
annie_wangli 已提交
44

A
Annie_wang 已提交
45
**Example**
A
Annie_wang 已提交
46

A
Annie_wang 已提交
47 48
FA model:

A
Annie_wang 已提交
49
```js
A
Annie_wang 已提交
50 51 52 53 54 55
// Obtain the context.
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();

let preferences = null;
data_preferences.getPreferences(context, 'mystore', function (err, object) {
A
Annie_wang 已提交
56
    if (err) {
A
Annie_wang 已提交
57
        console.info("Failed to get the preferences. Cause: " + err);
A
Annie_wang 已提交
58 59
        return;
    }
A
Annie_wang 已提交
60 61
    preferences = object;
    console.info("Got the preferences successfully.");
A
Annie_wang 已提交
62 63
})
```
A
annie_wangli 已提交
64

A
Annie_wang 已提交
65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
Stage model:

```ts
// Obtain the context.
import Ability from '@ohos.application.Ability';
let context = null;
class MainAbility extends Ability{
    onWindowStageCreate(windowStage){
        context = this.context;
    }
}

let preferences = null;
data_preferences.getPreferences(context, 'mystore', function (err, object) {
    if (err) {
        console.info("Failed to get the preferences. Cause: " + err);
        return;
    }
    preferences = object;
    console.info("Got the preferences successfully.");
})
```
A
annie_wangli 已提交
87

A
annie_wangli 已提交
88
## data_preferences.getPreferences
A
annie_wangli 已提交
89 90 91

getPreferences(context: Context, name: string): Promise&lt;Preferences&gt;

A
Annie_wang 已提交
92
Obtains a **Preferences** instance. This API uses a promise to return the result.
A
annie_wangli 已提交
93

A
Annie_wang 已提交
94
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
A
annie_wangli 已提交
95

A
Annie_wang 已提交
96
**Parameters**
A
Annie_wang 已提交
97 98 99 100

| Name | Type                                 | Mandatory| Description                   |
| ------- | ------------------------------------- | ---- | ----------------------- |
| context | Context | Yes  | Application context.<br>For the application context of the FA model, see [Context](js-apis-Context.md).<br>For the application context of the stage model, see [Context](js-apis-ability-context.md).           |
A
Annie_wang 已提交
101
| name    | string                                | Yes  | Name of the **Preferences** instance.|
A
annie_wangli 已提交
102

A
Annie_wang 已提交
103
**Return value**
A
Annie_wang 已提交
104

A
Annie_wang 已提交
105 106 107
| Type                                      | Description                              |
| ------------------------------------------ | ---------------------------------- |
| Promise&lt;[Preferences](#preferences)&gt; | Promise used to return the **Preferences** instance obtained.|
A
annie_wangli 已提交
108

A
Annie_wang 已提交
109
**Example**
A
Annie_wang 已提交
110

A
Annie_wang 已提交
111 112
FA model:

A
Annie_wang 已提交
113
```js
A
Annie_wang 已提交
114 115 116 117 118 119
// Obtain the context.
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();

let preferences = null;
let promise = data_preferences.getPreferences(context, 'mystore');
A
Annie_wang 已提交
120 121 122
promise.then((object) => {
    preferences = object;
    console.info("Got the preferences successfully.");
A
Annie_wang 已提交
123
}).catch((err) => {
A
Annie_wang 已提交
124
    console.info("Failed to get the preferences. Cause: " + err);
A
Annie_wang 已提交
125 126
})
```
A
annie_wangli 已提交
127

A
Annie_wang 已提交
128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148
Stage model:

```ts
// Obtain the context.
import Ability from '@ohos.application.Ability';
let context = null;
class MainAbility extends Ability{
    onWindowStageCreate(windowStage){
        context = this.context;
    }
}

let preferences = null;
let promise = data_preferences.getPreferences(context, 'mystore');
promise.then((object) => {
    preferences = object;
    console.info("Got the preferences successfully.");
}).catch((err) => {
    console.info("Failed to get the preferences. Cause: " + err);
})
```
A
annie_wangli 已提交
149

A
annie_wangli 已提交
150
## data_preferences.deletePreferences
A
annie_wangli 已提交
151 152 153

deletePreferences(context: Context, name: string, callback: AsyncCallback&lt;void&gt;): void

A
Annie_wang 已提交
154 155 156 157 158
Deletes a **Preferences** instance from the memory. This API uses an asynchronous callback to return the result.

If the **Preferences** instance has a persistent file, this API also deletes the persistent file.

The deleted **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will be caused.
A
annie_wangli 已提交
159

A
Annie_wang 已提交
160
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
A
annie_wangli 已提交
161

A
Annie_wang 已提交
162
**Parameters**
A
Annie_wang 已提交
163

A
Annie_wang 已提交
164 165
| Name  | Type                                 | Mandatory| Description                                                |
| -------- | ------------------------------------- | ---- | ---------------------------------------------------- |
A
Annie_wang 已提交
166
| context  | Context | Yes  | Application context.<br>For the application context of the FA model, see [Context](js-apis-Context.md).<br>For the application context of the stage model, see [Context](js-apis-ability-context.md).                                        |
A
Annie_wang 已提交
167 168
| name     | string                                | Yes  | Name of the **Preferences** instance to delete.                          |
| callback | AsyncCallback&lt;void&gt;             | Yes  | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error code.|
A
annie_wangli 已提交
169

A
Annie_wang 已提交
170
**Example**
A
Annie_wang 已提交
171 172 173

FA model:

A
Annie_wang 已提交
174
```js
A
Annie_wang 已提交
175 176 177 178 179
// Obtain the context.
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();

data_preferences.deletePreferences(context, 'mystore', function (err) {
A
Annie_wang 已提交
180
    if (err) {
A
Annie_wang 已提交
181
        console.info("Failed to delete the preferences. Cause: " + err);
A
Annie_wang 已提交
182
        return;
A
Annie_wang 已提交
183
    }
A
Annie_wang 已提交
184
    console.info("Deleted the preferences successfully." );
A
Annie_wang 已提交
185 186
})
```
A
annie_wangli 已提交
187

A
Annie_wang 已提交
188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207
Stage model:

```ts
// Obtain the context.
import Ability from '@ohos.application.Ability';
let context = null;
class MainAbility extends Ability{
    onWindowStageCreate(windowStage){
        context = this.context;
    }
}

data_preferences.deletePreferences(context, 'mystore', function (err) {
    if (err) {
        console.info("Failed to delete the preferences. Cause: " + err);
        return;
    }
    console.info("Deleted the preferences successfully." );
})
```
A
annie_wangli 已提交
208

A
annie_wangli 已提交
209
## data_preferences.deletePreferences
A
annie_wangli 已提交
210 211 212

deletePreferences(context: Context, name: string): Promise&lt;void&gt;

A
Annie_wang 已提交
213 214 215 216 217
Deletes a **Preferences** instance from the memory. This API uses a promise to return the result.

If the **Preferences** instance has a persistent file, this API also deletes the persistent file.

The deleted **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will be caused.
A
annie_wangli 已提交
218

A
Annie_wang 已提交
219
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
A
annie_wangli 已提交
220

A
Annie_wang 已提交
221
**Parameters**
A
Annie_wang 已提交
222 223 224 225

| Name | Type                                 | Mandatory| Description                   |
| ------- | ------------------------------------- | ---- | ----------------------- |
| context | Context | Yes  | Application context.<br>For the application context of the FA model, see [Context](js-apis-Context.md).<br>For the application context of the stage model, see [Context](js-apis-ability-context.md).           |
A
Annie_wang 已提交
226
| name    | string                                | Yes  | Name of the **Preferences** instance to delete.|
A
annie_wangli 已提交
227

A
Annie_wang 已提交
228
**Return value**
A
Annie_wang 已提交
229

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

A
Annie_wang 已提交
234
**Example**
A
Annie_wang 已提交
235 236 237

FA model:

A
Annie_wang 已提交
238
```js
A
Annie_wang 已提交
239 240 241 242 243
// Obtain the context.
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();

let promise = data_preferences.deletePreferences(context, 'mystore');
A
Annie_wang 已提交
244
promise.then(() => {
A
Annie_wang 已提交
245
    console.info("Deleted the preferences successfully.");
A
Annie_wang 已提交
246
}).catch((err) => {
A
Annie_wang 已提交
247
    console.info("Failed to delete the preferences. Cause: " + err);
A
Annie_wang 已提交
248 249
})
```
A
annie_wangli 已提交
250

A
Annie_wang 已提交
251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269
Stage model:

```ts
// Obtain the context.
import Ability from '@ohos.application.Ability';
let context = null;
class MainAbility extends Ability{
    onWindowStageCreate(windowStage){
        context = this.context;
    }
}

let promise = data_preferences.deletePreferences(context, 'mystore');
promise.then(() => {
    console.info("Deleted the preferences successfully.");
}).catch((err) => {
    console.info("Failed to delete the preferences. Cause: " + err);
})
```
A
annie_wangli 已提交
270

A
annie_wangli 已提交
271
## data_preferences.removePreferencesFromCache
A
annie_wangli 已提交
272 273 274

removePreferencesFromCache(context: Context, name: string, callback: AsyncCallback&lt;void&gt;): void

A
Annie_wang 已提交
275
Removes a **Preferences** instance from the memory. This API uses an asynchronous callback to return the result.
A
annie_wangli 已提交
276

A
Annie_wang 已提交
277
The removed **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will be caused.
A
annie_wangli 已提交
278

A
Annie_wang 已提交
279
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
A
annie_wangli 已提交
280

A
Annie_wang 已提交
281
**Parameters**
A
Annie_wang 已提交
282

A
Annie_wang 已提交
283 284
| Name  | Type                                 | Mandatory| Description                                                |
| -------- | ------------------------------------- | ---- | ---------------------------------------------------- |
A
Annie_wang 已提交
285
| context  | Context | Yes  | Application context.<br>For the application context of the FA model, see [Context](js-apis-Context.md).<br>For the application context of the stage model, see [Context](js-apis-ability-context.md).                                        |
A
Annie_wang 已提交
286 287
| name     | string                                | Yes  | Name of the **Preferences** instance to remove.                          |
| callback | AsyncCallback&lt;void&gt;             | Yes  | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error code.|
A
annie_wangli 已提交
288

A
Annie_wang 已提交
289
**Example**
A
Annie_wang 已提交
290 291 292

FA model:

A
Annie_wang 已提交
293
```js
A
Annie_wang 已提交
294 295 296 297 298
// Obtain the context.
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();

data_preferences.removePreferencesFromCache(context, 'mystore', function (err) {
A
Annie_wang 已提交
299
    if (err) {
A
Annie_wang 已提交
300 301
        console.info("Failed to remove the preferences. Cause: " + err);
        return;
A
Annie_wang 已提交
302
    }
A
Annie_wang 已提交
303
    console.info("Removed the preferences successfully.");
A
Annie_wang 已提交
304 305
})
```
A
annie_wangli 已提交
306

A
Annie_wang 已提交
307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326
Stage model:

```ts
// Obtain the context.
import Ability from '@ohos.application.Ability';
let context = null;
class MainAbility extends Ability{
    onWindowStageCreate(windowStage){
        context = this.context;
    }
}

data_preferences.removePreferencesFromCache(context, 'mystore', function (err) {
    if (err) {
        console.info("Failed to remove the preferences. Cause: " + err);
        return;
    }
    console.info("Removed the preferences successfully.");
})
```
A
annie_wangli 已提交
327

A
annie_wangli 已提交
328
## data_preferences.removePreferencesFromCache
A
annie_wangli 已提交
329 330 331

removePreferencesFromCache(context: Context, name: string): Promise&lt;void&gt;

A
Annie_wang 已提交
332
Removes a **Preferences** instance from the memory. This API uses a promise to return the result.
A
annie_wangli 已提交
333

A
Annie_wang 已提交
334
The removed **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will be caused.
A
annie_wangli 已提交
335

A
Annie_wang 已提交
336
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
A
annie_wangli 已提交
337

A
Annie_wang 已提交
338
**Parameters**
A
Annie_wang 已提交
339 340 341 342

| Name | Type                                 | Mandatory| Description                   |
| ------- | ------------------------------------- | ---- | ----------------------- |
| context | Context | Yes  | Application context.<br>For the application context of the FA model, see [Context](js-apis-Context.md).<br>For the application context of the stage model, see [Context](js-apis-ability-context.md).           |
A
Annie_wang 已提交
343
| name    | string                                | Yes  | Name of the **Preferences** instance to remove.|
A
annie_wangli 已提交
344

A
Annie_wang 已提交
345
**Return value**
A
Annie_wang 已提交
346

A
Annie_wang 已提交
347 348 349
| Type               | Description                     |
| ------------------- | ------------------------- |
| Promise&lt;void&gt; | Promise that returns no value.|
A
annie_wangli 已提交
350

A
Annie_wang 已提交
351
**Example**
A
Annie_wang 已提交
352 353 354

FA model:

A
Annie_wang 已提交
355
```js
A
Annie_wang 已提交
356 357 358 359 360
// Obtain the context.
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();

let promise = data_preferences.removePreferencesFromCache(context, 'mystore');
A
Annie_wang 已提交
361
promise.then(() => {
A
Annie_wang 已提交
362
    console.info("Removed the preferences successfully.");
A
Annie_wang 已提交
363
}).catch((err) => {
A
Annie_wang 已提交
364
    console.info("Failed to remove the preferences. Cause: " + err);
A
Annie_wang 已提交
365 366
})
```
A
annie_wangli 已提交
367

A
Annie_wang 已提交
368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386
Stage model:

```ts
// Obtain the context.
import Ability from '@ohos.application.Ability';
let context = null;
class MainAbility extends Ability{
    onWindowStageCreate(windowStage){
        context = this.context;
    }
}

let promise = data_preferences.removePreferencesFromCache(context, 'mystore');
promise.then(() => {
    console.info("Removed the preferences successfully.");
}).catch((err) => {
    console.info("Failed to remove the preferences. Cause: " + err);
})
```
A
annie_wangli 已提交
387 388 389

## Preferences

A
Annie_wang 已提交
390 391 392
Provides methods for obtaining and modifying data.

Before calling any method of **Preferences**, you must obtain a **Preferences** instance by using [data_preferences.getPreferences](#data_preferencesgetpreferences).
A
annie_wangli 已提交
393 394 395 396 397 398


### get

get(key: string, defValue: ValueType, callback: AsyncCallback&lt;ValueType&gt;): void

A
Annie_wang 已提交
399
Obtains the value of a key. This API uses an asynchronous callback to return the result. If the value is **null** or is not the type of the default value, the default value is returned.
A
annie_wangli 已提交
400

A
Annie_wang 已提交
401
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
A
annie_wangli 已提交
402

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

A
Annie_wang 已提交
405 406 407 408 409
| Name  | Type                                        | Mandatory| Description                                                        |
| -------- | -------------------------------------------- | ---- | ------------------------------------------------------------ |
| key      | string                                       | Yes  | Key of the data to obtain. It cannot be empty.                             |
| defValue | [ValueType](#valuetype)                      | Yes  | Default value to be returned. The value can be a number, a string, a Boolean value, or an array of numbers, strings, or Boolean values.|
| callback | AsyncCallback&lt;[ValueType](#valuetype)&gt; | Yes  | Callback invoked to return the result. If the operation is successful, **err** is** undefined** and **data** is the value obtained. Otherwise, **err** is an error code.|
A
annie_wangli 已提交
410

A
Annie_wang 已提交
411
**Example**
A
Annie_wang 已提交
412 413 414

```js
preferences.get('startup', 'default', function(err, data) {
A
Annie_wang 已提交
415
    if (err) {
A
Annie_wang 已提交
416 417
        console.info("Failed to get the value of 'startup'. Cause: " + err);
        return;
A
Annie_wang 已提交
418
    }
A
Annie_wang 已提交
419
    console.info("Got the value of 'startup'. Data: " + data);
A
Annie_wang 已提交
420 421
})
```
A
annie_wangli 已提交
422 423 424 425 426 427


### get

get(key: string, defValue: ValueType): Promise&lt;ValueType&gt;

A
Annie_wang 已提交
428
Obtains the value of a key. This API uses a promise to return the result. If the value is **null** or is not the type of the default value, the default value is returned.
A
annie_wangli 已提交
429

A
Annie_wang 已提交
430
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
A
annie_wangli 已提交
431

A
Annie_wang 已提交
432
 **Parameters**
A
Annie_wang 已提交
433
 
A
Annie_wang 已提交
434 435 436 437
| Name  | Type                   | Mandatory| Description                                                        |
| -------- | ----------------------- | ---- | ------------------------------------------------------------ |
| key      | string                  | Yes  | Key of the data to obtain. It cannot be empty.                             |
| defValue | [ValueType](#valuetype) | Yes  | Default value to be returned. The value can be a number, a string, a Boolean value, or an array of numbers, strings, or Boolean values.|
A
annie_wangli 已提交
438

A
Annie_wang 已提交
439
**Return value**
A
Annie_wang 已提交
440 441 442 443

| Type                               | Description                         |
| ----------------------------------- | ----------------------------- |
| Promise<[ValueType](#valuetype)&gt; | Promise used to return the value obtained.|
A
annie_wangli 已提交
444

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

A
Annie_wang 已提交
447 448 449 450
```js
let promise = preferences.get('startup', 'default');
promise.then((data) => {
    console.info("Got the value of 'startup'. Data: " + data);
A
Annie_wang 已提交
451
}).catch((err) => {
A
Annie_wang 已提交
452
    console.info("Failed to get the value of 'startup'. Cause: " + err);
A
Annie_wang 已提交
453 454
})
```
A
annie_wangli 已提交
455

A
Annie_wang 已提交
456 457 458 459
### getAll

getAll(callback: AsyncCallback&lt;Object&gt;): void;

A
Annie_wang 已提交
460
Obtains an **Object** instance that contains all KV pairs. This API uses an asynchronous callback to return the result.
A
Annie_wang 已提交
461 462 463 464

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

**Parameters**
A
Annie_wang 已提交
465

A
Annie_wang 已提交
466 467 468
| Name  | Type                       | Mandatory| Description                                                        |
| -------- | --------------------------- | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback&lt;Object&gt; | Yes  | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **value** is the **Object** instance obtained. Otherwise, **err** is an error code.|
A
Annie_wang 已提交
469 470

**Example**
A
Annie_wang 已提交
471 472

```js
A
Annie_wang 已提交
473
preferences.getAll(function (err, value) {
A
Annie_wang 已提交
474
    if (err) {
A
Annie_wang 已提交
475 476
        console.info("Failed to get all KV pairs. Cause: " + err);
        return;
A
Annie_wang 已提交
477
    }
A
Annie_wang 已提交
478 479 480
    let allKeys = Object.keys(value);
    console.info("getAll keys = " + allKeys);
    console.info("getAll object = " + JSON.stringify(value));
A
Annie_wang 已提交
481 482 483 484 485 486 487 488
});
```


### getAll

getAll(): Promise&lt;Object&gt;

A
Annie_wang 已提交
489
Obtains an **Object** instance that contains all KV pairs. This API uses a promise to return the result.
A
Annie_wang 已提交
490 491 492 493

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

**Return value**
A
Annie_wang 已提交
494

A
Annie_wang 已提交
495 496 497
| Type                 | Description                                       |
| --------------------- | ------------------------------------------- |
| Promise&lt;Object&gt; | Promise used to return the **Object** instance obtained.|
A
Annie_wang 已提交
498 499

**Example**
A
Annie_wang 已提交
500

A
Annie_wang 已提交
501 502
```js
let promise = preferences.getAll();
A
Annie_wang 已提交
503
promise.then((value) => {
A
Annie_wang 已提交
504 505 506
    let allKeys = Object.keys(value);
    console.info('getAll keys = ' + allKeys);
    console.info("getAll object = " + JSON.stringify(value));
A
Annie_wang 已提交
507
}).catch((err) => {
A
Annie_wang 已提交
508
    console.info("Failed to get all KV pairs. Cause: " + err);
A
Annie_wang 已提交
509 510
})
```
A
annie_wangli 已提交
511 512 513 514 515

### put

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

A
Annie_wang 已提交
516
Writes data to this **Preferences** instance. This API uses an asynchronous callback to return the result. You can use [flush](#flush) to make the **Preferences** instance persistent.
A
annie_wangli 已提交
517

A
Annie_wang 已提交
518
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
A
annie_wangli 已提交
519

A
Annie_wang 已提交
520
**Parameters**
A
Annie_wang 已提交
521

A
Annie_wang 已提交
522 523 524 525 526
| Name  | Type                     | Mandatory| Description                                                        |
| -------- | ------------------------- | ---- | ------------------------------------------------------------ |
| key      | string                    | Yes  | Key of the data. It cannot be empty.                               |
| value    | [ValueType](#valuetype)   | Yes  | Value to write. The value can be a number, a string, a Boolean value, or an array of numbers, strings, or Boolean values.|
| callback | AsyncCallback&lt;void&gt; | Yes  | Callback invoked to return the result. If the operation is successful, **err** is undefined. Otherwise, **err** is an error code.    |
A
annie_wangli 已提交
527

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

A
Annie_wang 已提交
530
```js
A
Annie_wang 已提交
531 532
preferences.put('startup', 'auto', function (err) {
    if (err) {
A
Annie_wang 已提交
533 534
        console.info("Failed to put the value of 'startup'. Cause: " + err);
        return;
A
Annie_wang 已提交
535
    }
A
Annie_wang 已提交
536
    console.info("Put the value of 'startup' successfully.");
A
Annie_wang 已提交
537 538
})
```
A
annie_wangli 已提交
539 540 541 542 543 544


### put

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

A
Annie_wang 已提交
545
Writes data to this **Preferences** instance. This API uses a promise to return the result. You can use [flush](#flush) to make the **Preferences** instance persistent.
A
annie_wangli 已提交
546

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

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

A
Annie_wang 已提交
551 552 553 554
| Name| Type                   | Mandatory| Description                                                        |
| ------ | ----------------------- | ---- | ------------------------------------------------------------ |
| key    | string                  | Yes  | Key of the data. It cannot be empty.                               |
| value  | [ValueType](#valuetype) | Yes  | Value to write. The value can be a number, a string, a Boolean value, or an array of numbers, strings, or Boolean values.|
A
annie_wangli 已提交
555

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

A
Annie_wang 已提交
558 559 560
| Type               | Description                     |
| ------------------- | ------------------------- |
| Promise&lt;void&gt; | Promise that returns no value.|
A
annie_wangli 已提交
561

A
Annie_wang 已提交
562
**Example**
A
Annie_wang 已提交
563

A
Annie_wang 已提交
564 565
```js
let promise = preferences.put('startup', 'auto');
A
Annie_wang 已提交
566
promise.then(() => {
A
Annie_wang 已提交
567
    console.info("Put the value of 'startup' successfully.");
A
Annie_wang 已提交
568
}).catch((err) => {
A
Annie_wang 已提交
569
    console.info("Failed to put the value of 'startup'. Cause: " + err);
A
Annie_wang 已提交
570 571
})
```
A
annie_wangli 已提交
572 573 574 575


### has

A
Annie_wang 已提交
576
has(key: string, callback: AsyncCallback&lt;boolean&gt;): void
A
annie_wangli 已提交
577

A
Annie_wang 已提交
578
Checks whether this **Preferences** instance contains a KV pair with the given key. This API uses an asynchronous callback to return the result..
A
annie_wangli 已提交
579

A
Annie_wang 已提交
580
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
A
annie_wangli 已提交
581

A
Annie_wang 已提交
582
**Parameters**
A
Annie_wang 已提交
583

A
Annie_wang 已提交
584 585 586 587
| Name  | Type                        | Mandatory| Description                                                        |
| -------- | ---------------------------- | ---- | ------------------------------------------------------------ |
| key      | string                       | Yes  | Key of the data to check. It cannot be empty.                             |
| callback | AsyncCallback&lt;boolean&gt; | Yes  | Callback invoked to return the result. If the **Preferences** instance contains the KV pair, **true** will be returned. Otherwise, **false** will be returned.|
A
annie_wangli 已提交
588

A
Annie_wang 已提交
589
**Example**
A
Annie_wang 已提交
590

A
Annie_wang 已提交
591
```js
A
Annie_wang 已提交
592 593
preferences.has('startup', function (err, isExist) {
    if (err) {
A
Annie_wang 已提交
594 595
        console.info("Failed to check the key 'startup'. Cause: " + err);
        return;
A
Annie_wang 已提交
596 597
    }
    if (isExist) {
A
Annie_wang 已提交
598
        console.info("The key 'startup' is contained.");
A
Annie_wang 已提交
599
    } else {
A
Annie_wang 已提交
600
        console.info("The key 'startup' is not contained.");
A
Annie_wang 已提交
601 602 603
    }
})
```
A
annie_wangli 已提交
604 605 606 607 608 609


### has

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

A
Annie_wang 已提交
610
Checks whether this **Preferences** instance contains a KV pair with the given key. This API uses a promise to return the result..
A
annie_wangli 已提交
611

A
Annie_wang 已提交
612
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
A
annie_wangli 已提交
613

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

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

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

A
Annie_wang 已提交
622 623 624
| Type                  | Description                                                        |
| ---------------------- | ------------------------------------------------------------ |
| Promise&lt;boolean&gt; | Promise used to return the result. If the **Preferences** instance contains the KV pair, **true** will be returned. Otherwise, **false** will be returned.|
A
annie_wangli 已提交
625

A
Annie_wang 已提交
626
**Example**
A
Annie_wang 已提交
627 628 629

```js
let promise = preferences.has('startup');
A
Annie_wang 已提交
630 631
promise.then((isExist) => {
    if (isExist) {
A
Annie_wang 已提交
632
        console.info("The key 'startup' is contained.");
A
Annie_wang 已提交
633
    } else {
A
Annie_wang 已提交
634
        console.info("The key 'startup' is not contained.");
A
Annie_wang 已提交
635 636
    }
}).catch((err) => {
A
Annie_wang 已提交
637
    console.info("Failed to check the key 'startup'. Cause: " + err);
A
Annie_wang 已提交
638 639
})
```
A
annie_wangli 已提交
640 641 642 643 644 645


### delete

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

A
Annie_wang 已提交
646
Deletes a KV pair from this **Preferences** instance. This API uses an asynchronous callback to return the result.
A
annie_wangli 已提交
647

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

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

A
Annie_wang 已提交
652 653 654 655
| Name  | Type                     | Mandatory| Description                                                |
| -------- | ------------------------- | ---- | ---------------------------------------------------- |
| key      | string                    | Yes  | Key of the KV pair to delete. It cannot be empty.                     |
| callback | AsyncCallback&lt;void&gt; | Yes  | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error code.|
A
annie_wangli 已提交
656

A
Annie_wang 已提交
657
**Example**
A
Annie_wang 已提交
658

A
Annie_wang 已提交
659
```js
A
Annie_wang 已提交
660 661
preferences.delete('startup', function (err) {
    if (err) {
A
Annie_wang 已提交
662 663
        console.info("Failed to delete the key 'startup'. Cause: " + err);
        return;
A
Annie_wang 已提交
664
    }
A
Annie_wang 已提交
665
    console.info("Deleted the key 'startup'.");
A
Annie_wang 已提交
666 667
})
```
A
annie_wangli 已提交
668 669 670 671 672 673


### delete

delete(key: string): Promise&lt;void&gt;

A
Annie_wang 已提交
674
Deletes a KV pair from this **Preferences** instance. This API uses a promise to return the result.
A
annie_wangli 已提交
675

A
Annie_wang 已提交
676
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
A
annie_wangli 已提交
677

A
Annie_wang 已提交
678
**Parameters**
A
Annie_wang 已提交
679

A
Annie_wang 已提交
680 681 682
| Name| Type  | Mandatory| Description                           |
| ------ | ------ | ---- | ------------------------------- |
| key    | string | Yes  | Key of the KV pair to delete. It cannot be empty.|
A
annie_wangli 已提交
683

A
Annie_wang 已提交
684
**Return value**
A
Annie_wang 已提交
685

A
Annie_wang 已提交
686 687 688
| Type               | Description                     |
| ------------------- | ------------------------- |
| Promise&lt;void&gt; | Promise that returns no value.|
A
annie_wangli 已提交
689

A
Annie_wang 已提交
690
**Example**
A
Annie_wang 已提交
691

A
Annie_wang 已提交
692 693
```js
let promise = preferences.delete('startup');
A
Annie_wang 已提交
694
promise.then(() => {
A
Annie_wang 已提交
695
    console.info("Deleted the key 'startup'.");
A
Annie_wang 已提交
696
}).catch((err) => {
A
Annie_wang 已提交
697
    console.info("Failed to delete the key 'startup'. Cause: " + err);
A
Annie_wang 已提交
698 699
})
```
A
annie_wangli 已提交
700 701 702 703 704 705


### flush

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

A
Annie_wang 已提交
706
Saves the data of this **Preferences** instance to a file asynchronously. This API uses an asynchronous callback to return the result.
A
annie_wangli 已提交
707

A
Annie_wang 已提交
708
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
A
annie_wangli 已提交
709

A
Annie_wang 已提交
710
**Parameters**
A
Annie_wang 已提交
711

A
Annie_wang 已提交
712 713 714
| Name  | Type                     | Mandatory| Description                                                |
| -------- | ------------------------- | ---- | ---------------------------------------------------- |
| callback | AsyncCallback&lt;void&gt; | Yes  | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error code.|
A
annie_wangli 已提交
715

A
Annie_wang 已提交
716
**Example**
A
Annie_wang 已提交
717

A
Annie_wang 已提交
718
```js
A
Annie_wang 已提交
719 720
preferences.flush(function (err) {
    if (err) {
A
Annie_wang 已提交
721 722
        console.info("Failed to flush data. Cause: " + err);
        return;
A
Annie_wang 已提交
723
    }
A
Annie_wang 已提交
724
    console.info("Flushed data successfully.");
A
Annie_wang 已提交
725 726
})
```
A
annie_wangli 已提交
727 728 729 730 731 732


### flush

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

A
Annie_wang 已提交
733
Saves the data of this **Preferences** instance to a file asynchronously. This API uses a promise to return the result.
A
annie_wangli 已提交
734

A
Annie_wang 已提交
735
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
A
annie_wangli 已提交
736

A
Annie_wang 已提交
737
**Return value**
A
Annie_wang 已提交
738

A
Annie_wang 已提交
739 740 741
| Type               | Description                     |
| ------------------- | ------------------------- |
| Promise&lt;void&gt; | Promise that returns no value.|
A
annie_wangli 已提交
742

A
Annie_wang 已提交
743
**Example**
A
Annie_wang 已提交
744

A
Annie_wang 已提交
745 746
```js
let promise = preferences.flush();
A
Annie_wang 已提交
747 748 749
promise.then(() => {
    console.info("Flushed data to file successfully.")
}).catch((err) => {
A
Annie_wang 已提交
750
    console.info("Failed to flush data. Cause: " + err);
A
Annie_wang 已提交
751 752
})
```
A
annie_wangli 已提交
753 754 755 756 757 758


### clear

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

A
Annie_wang 已提交
759
Clears this **Preferences** instance. This API uses an asynchronous callback to return the result.
A
annie_wangli 已提交
760

A
Annie_wang 已提交
761
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
A
annie_wangli 已提交
762

A
Annie_wang 已提交
763
**Parameters**
A
Annie_wang 已提交
764

A
Annie_wang 已提交
765 766 767
| Name  | Type                     | Mandatory| Description                                                |
| -------- | ------------------------- | ---- | ---------------------------------------------------- |
| callback | AsyncCallback&lt;void&gt; | Yes  | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error code.|
A
annie_wangli 已提交
768

A
Annie_wang 已提交
769
**Example**
A
Annie_wang 已提交
770

A
Annie_wang 已提交
771
```js
A
Annie_wang 已提交
772 773
preferences.clear(function (err) {
    if (err) {
A
Annie_wang 已提交
774 775
        console.info("Failed to clear data. Cause: " + err);
        return;
A
Annie_wang 已提交
776
    }
A
Annie_wang 已提交
777
    console.info("Cleared data successfully.");
A
Annie_wang 已提交
778 779
})
```
A
annie_wangli 已提交
780 781 782 783 784 785


### clear

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

A
Annie_wang 已提交
786
Clears this **Preferences** instance. This API uses a promise to return the result.
A
annie_wangli 已提交
787

A
Annie_wang 已提交
788
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
A
annie_wangli 已提交
789

A
Annie_wang 已提交
790
**Return value**
A
Annie_wang 已提交
791

A
Annie_wang 已提交
792 793 794
| Type               | Description                     |
| ------------------- | ------------------------- |
| Promise&lt;void&gt; | Promise that returns no value.|
A
annie_wangli 已提交
795

A
Annie_wang 已提交
796
**Example**
A
Annie_wang 已提交
797

A
Annie_wang 已提交
798
```js
A
Annie_wang 已提交
799 800
let promise = preferences.clear()
promise.then(() => {
A
Annie_wang 已提交
801
    console.info("Cleared data successfully.");
A
Annie_wang 已提交
802
}).catch((err) => {
A
Annie_wang 已提交
803
    console.info("Failed to clear data. Cause: " + err);
A
Annie_wang 已提交
804 805
})
```
A
annie_wangli 已提交
806 807 808 809 810 811


### on('change')

on(type: 'change', callback: Callback&lt;{ key : string }&gt;): void

A
Annie_wang 已提交
812
Subscribes to data changes. A callback will be triggered to return the new value if the value of the subscribed key is changed and [flushed](#flush).
A
annie_wangli 已提交
813

A
Annie_wang 已提交
814
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
A
annie_wangli 已提交
815

A
Annie_wang 已提交
816
**Parameters**
A
Annie_wang 已提交
817

A
Annie_wang 已提交
818 819 820 821
| Name  | Type                            | Mandatory| Description                                    |
| -------- | -------------------------------- | ---- | ---------------------------------------- |
| type     | string                           | Yes  | Event type to subscribe to. The value **change** indicates data change events.|
| callback | Callback&lt;{ key : string }&gt; | Yes  | Callback invoked to return data changes.                          |
A
annie_wangli 已提交
822

A
Annie_wang 已提交
823
**Example**
A
Annie_wang 已提交
824

A
Annie_wang 已提交
825
```js
A
Annie_wang 已提交
826
data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) {
A
Annie_wang 已提交
827
    if (err) {
A
Annie_wang 已提交
828
        console.info("Failed to get the preferences.");
A
Annie_wang 已提交
829
        return;
A
Annie_wang 已提交
830
    }
A
Annie_wang 已提交
831
    let observer = function (key) {
A
Annie_wang 已提交
832
        console.info("The key " + key + " changed.");
A
Annie_wang 已提交
833
    }
A
Annie_wang 已提交
834
    preferences.on('change', observer);
A
Annie_wang 已提交
835
    preferences.put('startup', 'manual', function (err) {
A
Annie_wang 已提交
836
        if (err) {
A
Annie_wang 已提交
837 838
            console.info("Failed to put the value of 'startup'. Cause: " + err);
            return;
A
Annie_wang 已提交
839
        }
A
Annie_wang 已提交
840
        console.info("Put the value of 'startup' successfully.");
A
Annie_wang 已提交
841 842 843

        preferences.flush(function (err) {
            if (err) {
A
Annie_wang 已提交
844 845
                console.info("Failed to flush data. Cause: " + err);
                return;
A
Annie_wang 已提交
846
            }
A
Annie_wang 已提交
847
            console.info("Flushed data successfully."); // The observer will be called.
A
Annie_wang 已提交
848
        })
A
Annie_wang 已提交
849 850 851
    })
})
```
A
annie_wangli 已提交
852 853 854 855


### off('change')

A
Annie_wang 已提交
856
off(type: 'change', callback?: Callback&lt;{ key : string }&gt;): void
A
annie_wangli 已提交
857

A
Annie_wang 已提交
858
Unsubscribes from data changes.
A
annie_wangli 已提交
859

A
Annie_wang 已提交
860
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
A
annie_wangli 已提交
861

A
Annie_wang 已提交
862
**Parameters**
A
Annie_wang 已提交
863

A
Annie_wang 已提交
864 865 866 867
| Name  | Type                            | Mandatory| Description                                      |
| -------- | -------------------------------- | ---- | ------------------------------------------ |
| type     | string                           | Yes  | Event type to unsubscribe from. The value **change** indicates data change events.  |
| callback | Callback&lt;{ key : string }&gt; | No  | Callback to unregister. If this parameter is left blank, the callbacks used to subscribing to all data changes will be unregistered.|
A
annie_wangli 已提交
868

A
Annie_wang 已提交
869
**Example**
A
Annie_wang 已提交
870

A
Annie_wang 已提交
871
```js
A
Annie_wang 已提交
872
data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) {
A
Annie_wang 已提交
873
    if (err) {
A
Annie_wang 已提交
874
        console.info("Failed to get the preferences.");
A
Annie_wang 已提交
875
        return;
A
Annie_wang 已提交
876
    }
A
Annie_wang 已提交
877
    let observer = function (key) {
A
Annie_wang 已提交
878
        console.info("The key " + key + " changed.");
A
Annie_wang 已提交
879
    }
A
Annie_wang 已提交
880
    preferences.on('change', observer);
A
Annie_wang 已提交
881
    preferences.put('startup', 'auto', function (err) {
A
Annie_wang 已提交
882
        if (err) {
A
Annie_wang 已提交
883 884
            console.info("Failed to put the value of 'startup'. Cause: " + err);
            return;
A
Annie_wang 已提交
885
        }
A
Annie_wang 已提交
886
        console.info("Put the value of 'startup' successfully.");
A
Annie_wang 已提交
887 888 889

        preferences.flush(function (err) {
            if (err) {
A
Annie_wang 已提交
890 891
                console.info("Failed to flush data. Cause: " + err);
                return;
A
Annie_wang 已提交
892
            }
A
Annie_wang 已提交
893
            console.info("Flushed data successfully."); // The observer will be called.
A
Annie_wang 已提交
894
        })
A
Annie_wang 已提交
895
        preferences.off('change', observer);
A
Annie_wang 已提交
896 897 898
    })
})
```
A
Annie_wang 已提交
899 900 901

## ValueType

A
Annie_wang 已提交
902
Enumerates the value types.
A
Annie_wang 已提交
903

A
Annie_wang 已提交
904
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
A
Annie_wang 已提交
905

A
Annie_wang 已提交
906 907 908 909 910
| Type           | Description                          |
| --------------- | ------------------------------ |
| number          | The value is a number.            |
| string          | The value is a string.          |
| boolean         | The value is of Boolean type.          |
A
Annie_wang 已提交
911 912 913
| Array\<number>  | The value is an array of numbers.  |
| Array\<boolean> | The value is a Boolean array.  |
| Array\<string>  | The value is an array of the strings.|