1# @ohos.data.preferences (User Preferences) 2 3The **user preferences** module provides APIs for processing data in the form of key-value (KV) pairs and supports persistence of the KV pairs when required. 4 5The 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. 6 7 8> **NOTE** 9> 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. 11 12 13## Modules to Import 14 15```js 16import data_preferences from '@ohos.data.preferences'; 17``` 18 19## Constants 20 21**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 22 23| Name | Type| Readable| Writable| Description | 24| ---------------- | -------- | ---- | ---- | --------------------------------------- | 25| MAX_KEY_LENGTH | number | Yes | No | Maximum length of a key, which is 80 bytes. | 26| MAX_VALUE_LENGTH | number | Yes | No | Maximum length of a value, which is 8192 bytes.| 27 28 29## data_preferences.getPreferences 30 31getPreferences(context: Context, name: string, callback: AsyncCallback<Preferences>): void 32 33Obtains a **Preferences** instance. This API uses an asynchronous callback to return the result. 34 35**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 36 37**Parameters** 38 39| Name | Type | Mandatory| Description | 40| -------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | 41| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md). | 42| name | string | Yes | Name of the **Preferences** instance. | 43| callback | AsyncCallback<[Preferences](#preferences)> | 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.| 44 45**Example** 46 47FA model: 48 49```js 50// Obtain the context. 51import featureAbility from '@ohos.ability.featureAbility'; 52let context = featureAbility.getContext(); 53let preferences = null; 54 55try { 56 data_preferences.getPreferences(context, 'mystore', function (err, val) { 57 if (err) { 58 console.info("Failed to obtain the preferences. code =" + err.code + ", message =" + err.message); 59 return; 60 } 61 preferences = val; 62 console.info("Obtained the preferences successfully."); 63 }) 64} catch (err) { 65 console.info("Failed to obtain the preferences. code =" + err.code + ", message =" + err.message); 66} 67``` 68 69Stage model: 70 71```ts 72import UIAbility from '@ohos.app.ability.UIAbility'; 73 74let preferences = null; 75 76class EntryAbility extends UIAbility { 77 onWindowStageCreate(windowStage) { 78 try { 79 data_preferences.getPreferences(this.context, 'mystore', function (err, val) { 80 if (err) { 81 console.info("Failed to obtain the preferences. code =" + err.code + ", message =" + err.message); 82 return; 83 } 84 preferences = val; 85 console.info("Obtained the preferences successfully."); 86 }) 87 } catch (err) { 88 console.info("Failed to obtain the preferences. code =" + err.code + ", message =" + err.message); 89 } 90 } 91} 92``` 93 94## data_preferences.getPreferences 95 96getPreferences(context: Context, name: string): Promise<Preferences> 97 98Obtains a **Preferences** instance. This API uses a promise to return the result. 99 100**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 101 102**Parameters** 103 104| Name | Type | Mandatory| Description | 105| ------- | ------------------------------------- | ---- | ----------------------- | 106| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md). | 107| name | string | Yes | Name of the **Preferences** instance.| 108 109**Return value** 110 111| Type | Description | 112| ------------------------------------------ | ---------------------------------- | 113| Promise<[Preferences](#preferences)> | Promise used to return the **Preferences** instance obtained.| 114 115**Example** 116 117FA model: 118 119```js 120// Obtain the context. 121import featureAbility from '@ohos.ability.featureAbility'; 122let context = featureAbility.getContext(); 123 124let preferences = null; 125try { 126 let promise = data_preferences.getPreferences(context, 'mystore'); 127 promise.then((object) => { 128 preferences = object; 129 console.info("Obtained the preferences successfully."); 130 }).catch((err) => { 131 console.info("Failed to obtain the preferences. code =" + err.code + ", message =" + err.message); 132 }) 133} catch(err) { 134 console.info("Failed to obtain the preferences. code =" + err.code + ", message =" + err.message); 135} 136``` 137 138Stage model: 139 140```ts 141import UIAbility from '@ohos.app.ability.UIAbility'; 142 143let preferences = null; 144 145class EntryAbility extends UIAbility { 146 onWindowStageCreate(windowStage) { 147 try { 148 let promise = data_preferences.getPreferences(this.context, 'mystore'); 149 promise.then((object) => { 150 preferences = object; 151 console.info("Obtained the preferences successfully."); 152 }).catch((err) => { 153 console.info("Failed to obtain the preferences. code =" + err.code + ", message =" + err.message); 154 }) 155 } catch(err) { 156 console.info("Failed to obtain the preferences. code =" + err.code + ", message =" + err.message); 157 } 158 } 159} 160``` 161 162## data_preferences.deletePreferences 163 164deletePreferences(context: Context, name: string, callback: AsyncCallback<void>): void 165 166Deletes a **Preferences** instance from the memory. This API uses an asynchronous callback to return the result. 167 168If the **Preferences** instance has a persistent file, this API also deletes the persistent file. 169 170The deleted **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will be caused. 171 172**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 173 174**Parameters** 175 176| Name | Type | Mandatory| Description | 177| -------- | ------------------------------------- | ---- | ---------------------------------------------------- | 178| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md). | 179| name | string | Yes | Name of the **Preferences** instance to delete. | 180| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error code.| 181 182**Error codes** 183 184For details about the error codes, see [User Preference Error Codes](../errorcodes/errorcode-preferences.md). 185 186| ID| Error Message | 187| -------- | ------------------------------| 188| 15500010 | Failed to delete the preferences. | 189 190**Example** 191 192FA model: 193 194```js 195// Obtain the context. 196import featureAbility from '@ohos.ability.featureAbility'; 197let context = featureAbility.getContext(); 198 199try { 200 data_preferences.deletePreferences(context, 'mystore', function (err, val) { 201 if (err) { 202 console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message); 203 return; 204 } 205 console.info("Deleted the preferences successfully." ); 206 }) 207} catch (err) { 208 console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message); 209} 210``` 211 212Stage model: 213 214```ts 215import UIAbility from '@ohos.app.ability.UIAbility'; 216 217class EntryAbility extends UIAbility { 218 onWindowStageCreate(windowStage) { 219 try { 220 data_preferences.deletePreferences(this.context, 'mystore', function (err, val) { 221 if (err) { 222 console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message); 223 return; 224 } 225 console.info("Deleted the preferences successfully." ); 226 }) 227 } catch (err) { 228 console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message); 229 } 230 } 231} 232``` 233 234## data_preferences.deletePreferences 235 236deletePreferences(context: Context, name: string): Promise<void> 237 238Deletes a **Preferences** instance from the memory. This API uses a promise to return the result. 239 240If the **Preferences** instance has a persistent file, this API also deletes the persistent file. 241 242The deleted **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will be caused. 243 244**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 245 246**Parameters** 247 248| Name | Type | Mandatory| Description | 249| ------- | ------------------------------------- | ---- | ----------------------- | 250| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md). | 251| name | string | Yes | Name of the **Preferences** instance to delete.| 252 253**Return value** 254 255| Type | Description | 256| ------------------- | ------------------------- | 257| Promise<void> | Promise that returns no value.| 258 259**Error codes** 260 261For details about the error codes, see [User Preference Error Codes](../errorcodes/errorcode-preferences.md). 262 263| ID| Error Message | 264| -------- | ------------------------------| 265| 15500010 | Failed to delete the preferences. | 266 267**Example** 268 269FA model: 270 271```js 272// Obtain the context. 273import featureAbility from '@ohos.ability.featureAbility'; 274let context = featureAbility.getContext(); 275 276try { 277 let promise = data_preferences.deletePreferences(context, 'mystore'); 278 promise.then(() => { 279 console.info("Deleted the preferences successfully."); 280 }).catch((err) => { 281 console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message); 282 }) 283} catch(err) { 284 console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message); 285} 286``` 287 288Stage model: 289 290```ts 291import UIAbility from '@ohos.app.ability.UIAbility'; 292 293class EntryAbility extends UIAbility { 294 onWindowStageCreate(windowStage) { 295 try{ 296 let promise = data_preferences.deletePreferences(this.context, 'mystore'); 297 promise.then(() => { 298 console.info("Deleted the preferences successfully."); 299 }).catch((err) => { 300 console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message); 301 }) 302 } catch(err) { 303 console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message); 304 } 305 } 306} 307``` 308 309## data_preferences.removePreferencesFromCache 310 311removePreferencesFromCache(context: Context, name: string, callback: AsyncCallback<void>): void 312 313Removes a **Preferences** instance from the memory. This API uses an asynchronous callback to return the result. 314 315The removed **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will be caused. 316 317**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 318 319**Parameters** 320 321| Name | Type | Mandatory| Description | 322| -------- | ------------------------------------- | ---- | ---------------------------------------------------- | 323| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md). | 324| name | string | Yes | Name of the **Preferences** instance to remove. | 325| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error code.| 326 327**Example** 328 329FA model: 330 331```js 332// Obtain the context. 333import featureAbility from '@ohos.ability.featureAbility'; 334let context = featureAbility.getContext(); 335 336try { 337 data_preferences.removePreferencesFromCache(context, 'mystore', function (err, val) { 338 if (err) { 339 console.info("Failed to remove the preferences. code =" + err.code + ", message =" + err.message); 340 return; 341 } 342 console.info("Removed the preferences successfully."); 343 }) 344} catch (err) { 345 console.info("Failed to remove the preferences. code =" + err.code + ", message =" + err.message); 346} 347``` 348 349Stage model: 350 351```ts 352import UIAbility from '@ohos.app.ability.UIAbility'; 353 354class EntryAbility extends UIAbility { 355 onWindowStageCreate(windowStage) { 356 try { 357 data_preferences.removePreferencesFromCache(this.context, 'mystore', function (err, val) { 358 if (err) { 359 console.info("Failed to remove the preferences. code =" + err.code + ", message =" + err.message); 360 return; 361 } 362 console.info("Removed the preferences successfully."); 363 }) 364 } catch (err) { 365 console.info("Failed to remove the preferences. code =" + err.code + ", message =" + err.message); 366 } 367 } 368} 369 370``` 371 372## data_preferences.removePreferencesFromCache 373 374removePreferencesFromCache(context: Context, name: string): Promise<void> 375 376Removes a **Preferences** instance from the memory. This API uses a promise to return the result. 377 378The removed **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will be caused. 379 380**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 381 382**Parameters** 383 384| Name | Type | Mandatory| Description | 385| ------- | ------------------------------------- | ---- | ----------------------- | 386| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md). | 387| name | string | Yes | Name of the **Preferences** instance to remove.| 388 389**Return value** 390 391| Type | Description | 392| ------------------- | ------------------------- | 393| Promise<void> | Promise that returns no value.| 394 395**Example** 396 397FA model: 398 399```js 400// Obtain the context. 401import featureAbility from '@ohos.ability.featureAbility'; 402let context = featureAbility.getContext(); 403 404try { 405 let promise = data_preferences.removePreferencesFromCache(context, 'mystore'); 406 promise.then(() => { 407 console.info("Removed the preferences successfully."); 408 }).catch((err) => { 409 console.info("Failed to remove the preferences. code =" + err.code + ", message =" + err.message); 410 }) 411} catch(err) { 412 console.info("Failed to remove the preferences. code =" + err.code + ", message =" + err.message); 413} 414``` 415 416Stage model: 417 418```ts 419import UIAbility from '@ohos.app.ability.UIAbility'; 420 421class EntryAbility extends UIAbility { 422 onWindowStageCreate(windowStage) { 423 try { 424 let promise = data_preferences.removePreferencesFromCache(this.context, 'mystore'); 425 promise.then(() => { 426 console.info("Removed the preferences successfully."); 427 }).catch((err) => { 428 console.info("Failed to remove the preferences. code =" + err.code + ", message =" + err.message); 429 }) 430 } catch(err) { 431 console.info("Failed to remove the preferences. code =" + err.code + ", message =" + err.message); 432 } 433 } 434} 435``` 436 437## Preferences 438 439Provides methods for obtaining and modifying data. 440 441Before calling any method of **Preferences**, you must obtain a **Preferences** instance by using [data_preferences.getPreferences](#data_preferencesgetpreferences). 442 443 444### get 445 446get(key: string, defValue: ValueType, callback: AsyncCallback<ValueType>): void 447 448Obtains the value of a key. This API uses an asynchronous callback to return the result. If the value is **null** or is not of the default value type, **defValue** is returned. 449 450**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 451 452**Parameters** 453 454| Name | Type | Mandatory| Description | 455| -------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | 456| key | string | Yes | Key of the data to obtain. It cannot be empty. | 457| 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.| 458| callback | AsyncCallback<[ValueType](#valuetype)> | 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.| 459 460**Example** 461 462```js 463try { 464 preferences.get('startup', 'default', function (err, val) { 465 if (err) { 466 console.info("Failed to obtain the value of 'startup'. code =" + err.code + ", message =" + err.message); 467 return; 468 } 469 console.info("Obtained the value of 'startup' successfully. val: " + val); 470 }) 471} catch (err) { 472 console.info("Failed to obtain the value of 'startup'. code =" + err.code + ", message =" + err.message); 473} 474``` 475 476 477### get 478 479get(key: string, defValue: ValueType): Promise<ValueType> 480 481Obtains the value of a key. This API uses a promise to return the result. If the value is **null** or is not of the default value type, **defValue** is returned. 482 483**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 484 485 **Parameters** 486 487| Name | Type | Mandatory| Description | 488| -------- | ----------------------- | ---- | ------------------------------------------------------------ | 489| key | string | Yes | Key of the data to obtain. It cannot be empty. | 490| 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.| 491 492**Return value** 493 494| Type | Description | 495| ----------------------------------- | ----------------------------- | 496| Promise<[ValueType](#valuetype)> | Promise used to return the value obtained.| 497 498**Example** 499 500```js 501try { 502 let promise = preferences.get('startup', 'default'); 503 promise.then((data) => { 504 console.info("Got the value of 'startup'. Data: " + data); 505 }).catch((err) => { 506 console.info("Failed to obtain the value of 'startup'. code =" + err.code + ", message =" + err.message); 507 }) 508} catch(err) { 509 console.info("Failed to obtain the value of 'startup'. code =" + err.code + ", message =" + err.message); 510} 511``` 512 513### getAll 514 515getAll(callback: AsyncCallback<Object>): void; 516 517Obtains an **Object** instance that contains all KV pairs. This API uses an asynchronous callback to return the result. 518 519**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 520 521**Parameters** 522 523| Name | Type | Mandatory| Description | 524| -------- | --------------------------- | ---- | ------------------------------------------------------------ | 525| callback | AsyncCallback<Object> | 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.| 526 527**Example** 528 529```js 530try { 531 preferences.getAll(function (err, value) { 532 if (err) { 533 console.info("Failed to get all KV pairs. code =" + err.code + ", message =" + err.message); 534 return; 535 } 536 let allKeys = Object.keys(value); 537 console.info("getAll keys = " + allKeys); 538 console.info("getAll object = " + JSON.stringify(value)); 539 }) 540} catch (err) { 541 console.info("Failed to get all KV pairs. code =" + err.code + ", message =" + err.message); 542} 543``` 544 545 546### getAll 547 548getAll(): Promise<Object> 549 550Obtains an **Object** instance that contains all KV pairs. This API uses a promise to return the result. 551 552**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 553 554**Return value** 555 556| Type | Description | 557| --------------------- | ------------------------------------------- | 558| Promise<Object> | Promise used to return the **Object** instance obtained.| 559 560**Example** 561 562```js 563try { 564 let promise = preferences.getAll(); 565 promise.then((value) => { 566 let allKeys = Object.keys(value); 567 console.info('getAll keys = ' + allKeys); 568 console.info("getAll object = " + JSON.stringify(value)); 569 }).catch((err) => { 570 console.info("Failed to get all KV pairs. code =" + err.code + ", message =" + err.message); 571 }) 572} catch (err) { 573 console.info("Failed to get all KV pairs. code =" + err.code + ", message =" + err.message); 574} 575``` 576 577### put 578 579put(key: string, value: ValueType, callback: AsyncCallback<void>): void 580 581Writes 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. 582 583**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 584 585**Parameters** 586 587| Name | Type | Mandatory| Description | 588| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 589| key | string | Yes | Key of the data. It cannot be empty. | 590| 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.| 591| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is undefined. Otherwise, **err** is an error code. | 592 593**Example** 594 595```js 596try { 597 preferences.put('startup', 'auto', function (err) { 598 if (err) { 599 console.info("Failed to put the value of 'startup'. code =" + err.code + ", message =" + err.message); 600 return; 601 } 602 console.info("Put the value of 'startup' successfully."); 603 }) 604} catch (err) { 605 console.info("Failed to put the value of 'startup'. code =" + err.code + ", message =" + err.message); 606} 607``` 608 609 610### put 611 612put(key: string, value: ValueType): Promise<void> 613 614Writes 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. 615 616**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 617 618**Parameters** 619 620| Name| Type | Mandatory| Description | 621| ------ | ----------------------- | ---- | ------------------------------------------------------------ | 622| key | string | Yes | Key of the data. It cannot be empty. | 623| 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.| 624 625**Return value** 626 627| Type | Description | 628| ------------------- | ------------------------- | 629| Promise<void> | Promise that returns no value.| 630 631**Example** 632 633```js 634try { 635 let promise = preferences.put('startup', 'auto'); 636 promise.then(() => { 637 console.info("Put the value of 'startup' successfully."); 638 }).catch((err) => { 639 console.info("Failed to put the value of 'startup'. code =" + err.code +", message =" + err.message); 640 }) 641} catch(err) { 642 console.info("Failed to put the value of 'startup'. code =" + err.code +", message =" + err.message); 643} 644``` 645 646 647### has 648 649has(key: string, callback: AsyncCallback<boolean>): void 650 651Checks whether this **Preferences** instance contains a KV pair with the given key. This API uses an asynchronous callback to return the result. 652 653**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 654 655**Parameters** 656 657| Name | Type | Mandatory| Description | 658| -------- | ---------------------------- | ---- | ------------------------------------------------------------ | 659| key | string | Yes | Key of the data to check. It cannot be empty. | 660| callback | AsyncCallback<boolean> | Yes | Callback invoked to return the result. If the **Preferences** instance contains the KV pair, **true** will be returned. Otherwise, **false** will be returned.| 661 662**Example** 663 664```js 665try { 666 preferences.has('startup', function (err, val) { 667 if (err) { 668 console.info("Failed to check the key 'startup'. code =" + err.code + ", message =" + err.message); 669 return; 670 } 671 if (val) { 672 console.info("The key 'startup' is contained."); 673 } else { 674 console.info("The key 'startup' is not contained."); 675 } 676 }) 677} catch (err) { 678 console.info("Failed to check the key 'startup'. code =" + err.code + ", message =" + err.message); 679} 680``` 681 682 683### has 684 685has(key: string): Promise<boolean> 686 687Checks whether this **Preferences** instance contains a KV pair with the given key. This API uses a promise to return the result. 688 689**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 690 691**Parameters** 692 693| Name| Type | Mandatory| Description | 694| ------ | ------ | ---- | ------------------------------- | 695| key | string | Yes | Key of the data to check. It cannot be empty.| 696 697**Return value** 698 699| Type | Description | 700| ---------------------- | ------------------------------------------------------------ | 701| Promise<boolean> | Promise used to return the result. If the **Preferences** instance contains the KV pair, **true** will be returned. Otherwise, **false** will be returned.| 702 703**Example** 704 705```js 706try { 707 let promise = preferences.has('startup'); 708 promise.then((val) => { 709 if (val) { 710 console.info("The key 'startup' is contained."); 711 } else { 712 console.info("The key 'startup' is not contained."); 713 } 714 }).catch((err) => { 715 console.info("Failed to check the key 'startup'. code =" + err.code + ", message =" + err.message); 716 }) 717} catch(err) { 718 console.info("Failed to check the key 'startup'. code =" + err.code + ", message =" + err.message); 719} 720``` 721 722 723### delete 724 725delete(key: string, callback: AsyncCallback<void>): void 726 727Deletes a KV pair from this **Preferences** instance based on the specified key. This API uses an asynchronous callback to return the result. 728 729**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 730 731**Parameters** 732 733| Name | Type | Mandatory| Description | 734| -------- | ------------------------- | ---- | ---------------------------------------------------- | 735| key | string | Yes | Key of the KV pair to delete. It cannot be empty. | 736| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error code.| 737 738**Example** 739 740```js 741try { 742 preferences.delete('startup', function (err) { 743 if (err) { 744 console.info("Failed to delete the key 'startup'. code =" + err.code + ", message =" + err.message); 745 return; 746 } 747 console.info("Deleted the key 'startup'."); 748 }) 749} catch (err) { 750 console.info("Failed to delete the key 'startup'. code =" + err.code + ", message =" + err.message); 751} 752``` 753 754 755### delete 756 757delete(key: string): Promise<void> 758 759Deletes a KV pair from this **Preferences** instance. This API uses a promise to return the result. 760 761**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 762 763**Parameters** 764 765| Name| Type | Mandatory| Description | 766| ------ | ------ | ---- | ------------------------------- | 767| key | string | Yes | Key of the KV pair to delete. It cannot be empty.| 768 769**Return value** 770 771| Type | Description | 772| ------------------- | ------------------------- | 773| Promise<void> | Promise that returns no value.| 774 775**Example** 776 777```js 778try { 779 let promise = preferences.delete('startup'); 780 promise.then(() => { 781 console.info("Deleted the key 'startup'."); 782 }).catch((err) => { 783 console.info("Failed to delete the key 'startup'. code =" + err.code +", message =" + err.message); 784 }) 785} catch(err) { 786 console.info("Failed to delete the key 'startup'. code =" + err.code +", message =" + err.message); 787} 788``` 789 790 791### flush 792 793flush(callback: AsyncCallback<void>): void 794 795Saves the data of this **Preferences** instance to a file asynchronously. This API uses an asynchronous callback to return the result. 796 797**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 798 799**Parameters** 800 801| Name | Type | Mandatory| Description | 802| -------- | ------------------------- | ---- | ---------------------------------------------------- | 803| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error code.| 804 805**Example** 806 807```js 808try { 809 preferences.flush(function (err) { 810 if (err) { 811 console.info("Failed to flush data. code =" + err.code + ", message =" + err.message); 812 return; 813 } 814 console.info("Flushed data successfully."); 815 }) 816} catch (err) { 817 console.info("Failed to flush data. code =" + err.code + ", message =" + err.message); 818} 819``` 820 821 822### flush 823 824flush(): Promise<void> 825 826Saves the data of this **Preferences** instance to a file asynchronously. This API uses a promise to return the result. 827 828**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 829 830**Return value** 831 832| Type | Description | 833| ------------------- | ------------------------- | 834| Promise<void> | Promise that returns no value.| 835 836**Example** 837 838```js 839try { 840 let promise = preferences.flush(); 841 promise.then(() => { 842 console.info("Flushed data successfully."); 843 }).catch((err) => { 844 console.info("Failed to flush data. code =" + err.code + ", message =" + err.message); 845 }) 846} catch (err) { 847 console.info("Failed to flush data. code =" + err.code + ", message =" + err.message); 848} 849``` 850 851 852### clear 853 854clear(callback: AsyncCallback<void>): void 855 856Clears this **Preferences** instance. This API uses an asynchronous callback to return the result. 857 858**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 859 860**Parameters** 861 862| Name | Type | Mandatory| Description | 863| -------- | ------------------------- | ---- | ---------------------------------------------------- | 864| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error code.| 865 866**Example** 867 868```js 869try { 870 preferences.clear(function (err) { 871 if (err) { 872 console.info("Failed to clear data. code =" + err.code + ", message =" + err.message); 873 return; 874 } 875 console.info("Cleared data successfully."); 876 }) 877} catch (err) { 878 console.info("Failed to clear data. code =" + err.code + ", message =" + err.message); 879} 880``` 881 882 883### clear 884 885clear(): Promise<void> 886 887Clears this **Preferences** instance. This API uses a promise to return the result. 888 889**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 890 891**Return value** 892 893| Type | Description | 894| ------------------- | ------------------------- | 895| Promise<void> | Promise that returns no value.| 896 897**Example** 898 899```js 900try { 901 let promise = preferences.clear(); 902 promise.then(() => { 903 console.info("Cleared data successfully."); 904 }).catch((err) => { 905 console.info("Failed to clear data. code =" + err.code + ", message =" + err.message); 906 }) 907} catch(err) { 908 console.info("Failed to clear data. code =" + err.code + ", message =" + err.message); 909} 910``` 911 912 913### on('change') 914 915on(type: 'change', callback: Callback<{ key : string }>): void 916 917Subscribes 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). 918 919**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 920 921**Parameters** 922 923| Name | Type | Mandatory| Description | 924| -------- | -------------------------------- | ---- | ---------------------------------------- | 925| type | string | Yes | Event type to subscribe to. The value **change** indicates data change events.| 926| callback | Callback<{ key : string }> | Yes | Callback invoked to return data changes. | 927 928**Example** 929 930```js 931try { 932 data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) { 933 if (err) { 934 console.info("Failed to obtain the preferences."); 935 return; 936 } 937 let observer = function (key) { 938 console.info("The key " + key + " changed."); 939 } 940 preferences.on('change', observer); 941 preferences.put('startup', 'manual', function (err) { 942 if (err) { 943 console.info("Failed to put the value of 'startup'. Cause: " + err); 944 return; 945 } 946 console.info("Put the value of 'startup' successfully."); 947 948 preferences.flush(function (err) { 949 if (err) { 950 console.info("Failed to flush data. Cause: " + err); 951 return; 952 } 953 console.info("Flushed data successfully."); 954 }) 955 }) 956 }) 957} catch (err) { 958 console.info("Failed to flush data. code =" + err.code + ", message =" + err.message); 959} 960``` 961 962 963### off('change') 964 965off(type: 'change', callback?: Callback<{ key : string }>): void 966 967Unsubscribes from data changes. 968 969**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 970 971**Parameters** 972 973| Name | Type | Mandatory| Description | 974| -------- | -------------------------------- | ---- | ------------------------------------------ | 975| type | string | Yes | Event type to unsubscribe from. The value **change** indicates data change events. | 976| callback | Callback<{ key : string }> | No | Callback to unregister. If this parameter is left blank, the callbacks for all data changes will be unregistered.| 977 978**Example** 979 980```js 981try { 982 data_preferences.getPreferences(this.context, 'mystore', function (err, preferences) { 983 if (err) { 984 console.info("Failed to obtain the preferences."); 985 return; 986 } 987 let observer = function (key) { 988 console.info("The key " + key + " changed."); 989 } 990 preferences.on('change', observer); 991 preferences.put('startup', 'auto', function (err) { 992 if (err) { 993 console.info("Failed to put the value of 'startup'. Cause: " + err); 994 return; 995 } 996 console.info("Put the value of 'startup' successfully."); 997 998 preferences.flush(function (err) { 999 if (err) { 1000 console.info("Failed to flush data. Cause: " + err); 1001 return; 1002 } 1003 console.info("Flushed data successfully."); 1004 }) 1005 preferences.off('change', observer); 1006 }) 1007 }) 1008} catch (err) { 1009 console.info("Failed to flush data. code =" + err.code + ", message =" + err.message); 1010} 1011``` 1012 1013## ValueType 1014 1015Enumerates the value types. 1016 1017**System capability**: SystemCapability.DistributedDataManager.Preferences.Core 1018 1019| Type | Description | 1020| --------------- | ------------------------------ | 1021| number | The value is a number. | 1022| string | The value is a string. | 1023| boolean | The value is of Boolean type. | 1024| Array\<number> | The value is an array of numbers. | 1025| Array\<boolean> | The value is a Boolean array. | 1026| Array\<string> | The value is an array of the strings.| 1027