1# State Management with Application-level Variables 2 3 4The state management module provides data storage, persistent data management, UIAbility data storage, and environment state required by applications. 5 6 7>**NOTE** 8> 9>The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 10 11 12The meanings of T and S in this topic are as follows: 13 14 15| Type | Description | 16| ---- | -------------------------------------- | 17| T | Class, number, boolean, string, and arras of these types.| 18| S | number, boolean, string. | 19 20 21## AppStorage 22 23 24For details about how to use AppStorage on the UI, see [AppStorage: Application-wide UI State Storage](../../quick-start/arkts-appstorage.md). 25 26 27### link<sup>10+</sup> 28 29static link\<T>(propName: string): SubscribedAbstractProperty\<T> 30 31Establishes two-way data binding with the given attribute (specified by **propName**) in AppStorage. If the given attribute exists in AppStorage, the two-way bound data of the attribute in AppStorage is returned. 32 33Any update of the data is synchronized back to AppStorage, which then synchronizes the update to all data and custom components bound to the attribute. 34 35If the given attribute does not exist in AppStorage, **undefined** is returned. 36 37 38**Parameters** 39 40| Name | Type | Mandatory | Description | 41| -------- | ------ | ---- | ---------------- | 42| propName | string | Yes | Attribute name in AppStorage.| 43 44**Return value** 45 46| Type | Description | 47| ----------------------------------- | ---------------------------------------- | 48| SubscribedAbstractProperty<T> | Returns two-way bound data if specified attribute exists in AppStorage; returns **undefined** otherwise.| 49 50 51```ts 52AppStorage.setOrCreate('PropA', 47); 53let linkToPropA1:SubscribedAbstractProperty<number> = AppStorage.link('PropA'); 54let linkToPropA2:SubscribedAbstractProperty<number> = AppStorage.link('PropA'); // linkToPropA2.get() == 47 55linkToPropA1.set(48); // Two-way synchronization: linkToPropA1.get() == linkToPropA2.get() == 48 56``` 57 58 59### setAndLink<sup>10+</sup> 60 61static setAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T> 62 63Works in a way similar to the **Link** API. If the given attribute exists in AppStorage, the two-way bound data of the attribute in AppStorage is returned. If the given attribute does not exist, it is created and initialized with <b class="+ topic/ph hi-d/b " id="b537113298389">defaultValue</b> in AppStorage, and two-way bound data is returned. 64 65**Parameters** 66 67| Name | Type | Mandatory | Description | 68| ------------ | ------ | ---- | ---------------------------------------- | 69| propName | string | Yes | Attribute name in AppStorage. | 70| defaultValue | T | Yes | Default value used to initialize the attribute with the specified attribute name in AppStorage.| 71 72**Return value** 73 74| Type | Description | 75| ----------------------------------- | ---------------------------------------- | 76| SubscribedAbstractProperty<T> | Instance of **SubscribedAbstractProperty<T>** and two-way bound data of the given attribute in AppStorage| 77 78 79```ts 80AppStorage.setOrCreate('PropA', 47); 81let link1: SubscribedAbstractProperty<number> = AppStorage.setAndLink('PropB', 49); // Create PropB 49 82let link2: SubscribedAbstractProperty<number> = AppStorage.setAndLink('PropA', 50); // PropA exists, remains 47 83``` 84 85 86### prop<sup>10+</sup> 87 88static prop<T>(propName: string): SubscribedAbstractProperty<T> 89 90Establishes one-way data binding with the given attribute (specified by **propName**) in AppStorage. If the given attribute exists in AppStorage, the one-way bound data of the attribute in AppStorage is returned. If the given attribute does not exist in AppStorage, **undefined** is returned. Updates of the one-way bound data are not synchronized back to AppStorage. 91 92>**NOTE** 93> 94> Prop supports only simple types. 95 96**Parameters** 97 98| Name | Type | Mandatory | Description | 99| -------- | ------ | ---- | ---------------- | 100| propName | string | Yes | Attribute name in AppStorage.| 101 102**Return value** 103 104| Type | Description | 105| ----------------------------------- | ---------------------------------------- | 106| SubscribedAbstractProperty<T> | Returns one-way bound data if specified attribute exists in AppStorage; returns **undefined** otherwise.| 107 108 109```ts 110AppStorage.setOrCreate('PropA', 47); 111let prop1: SubscribedAbstractProperty<number> = AppStorage.prop('PropA'); 112let prop2: SubscribedAbstractProperty<number> = AppStorage.prop('PropA'); 113prop1.set(1); // one-way sync: prop1.get()=1; but prop2.get() == 47 114``` 115 116 117### setAndProp<sup>10+</sup> 118 119static setAndProp<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T> 120 121Works in a way similar to the **Prop** API. If the given attribute exists in AppStorage, the one-way bound data of the attribute in AppStorage is returned. If the given attribute does not exist, it is created and initialized with **defaultValue** in AppStorage, and one-way bound data is returned. 122 123 124**Parameters** 125 126| Name | Type | Mandatory | Description | 127| ------------ | ------ | ---- | ---------------------------------------- | 128| propName | string | Yes | Attribute name in AppStorage. | 129| defaultValue | T | Yes | Default value used to initialize the attribute with the specified attribute name in AppStorage.| 130 131**Return value** 132 133| Type | Description | 134| ----------------------------------- | --------------------------------------- | 135| SubscribedAbstractProperty<T> | Instance of **SubscribedAbstractProperty<T>**.| 136 137 138```ts 139AppStorage.setOrCreate('PropA', 47); 140let prop: SubscribedAbstractProperty<number> = AppStorage.setAndProp('PropB', 49); // PropA -> 47, PropB -> 49 141``` 142 143 144### has<sup>10+</sup> 145 146static has(propName: string): boolean 147 148Checks whether the attribute with the specified attribute name exists in AppStorage. 149 150**Parameters** 151 152| Name | Type | Mandatory | Description | 153| -------- | ------ | ---- | ---------------- | 154| propName | string | Yes | Attribute name in AppStorage.| 155 156**Return value** 157 158| Type | Description | 159| ------- | ---------------------------------------- | 160| boolean | Returns **true** if the attribute with the specified attribute name exists in AppStorage; returns **false** otherwise.| 161 162 163```ts 164AppStorage.has('simpleProp'); 165``` 166 167 168### get<sup>10+</sup> 169 170static get<T>(propName: string): T | undefined 171 172Obtains the attribute with the specified attribute name in AppStorage. If the attribute does not exist, **undefined** is returned. 173 174**Parameters** 175 176| Name | Type | Mandatory | Description | 177| -------- | ------ | ---- | ---------------- | 178| propName | string | Yes | Attribute name in AppStorage.| 179 180**Return value** 181 182| Type | Description | 183| ------------------------ | ---------------------------------------- | 184| T \| undefined | Returns the attribute with the specified attribute name in AppStorage; returns **undefined** if the attribute does not exist.| 185 186 187```ts 188AppStorage.setOrCreate('PropA', 47); 189let value: number = AppStorage.get('PropA') as number; // 47 190``` 191 192 193### set<sup>10+</sup> 194 195static set<T>(propName: string, newValue: T): boolean 196 197Sets the value for the attribute with the specified attribute name in AppStorage. If the value of **newValue** is the same as the value of the attribute with the specified attribute name, that is, no value needs to be assigned, the state variable will not instruct the UI to update the value of attribute. 198 199**Parameters** 200 201| Name | Type | Mandatory | Description | 202| -------- | ------ | ---- | ---------------------- | 203| propName | string | Yes | Attribute name in AppStorage. | 204| newValue | T | Yes | Attribute value, which cannot be **undefined** or **null**.| 205 206**Return value** 207 208| Type | Description | 209| ------- | ---------------------------------------- | 210| boolean | Returns **true** if the operation is successful; return **false** if the attribute with the specified attribute name does not exist in AppStorage, or the value to set is **undefined** or **null**. | 211 212 213```ts 214AppStorage.setOrCreate('PropA', 48); 215let res: boolean = AppStorage.set('PropA', 47) // true 216let res1: boolean = AppStorage.set('PropB', 47) // false 217``` 218 219 220### setOrCreate<sup>10+</sup> 221 222static setOrCreate<T>(propName: string, newValue: T): void 223 224Sets a new value for the attribute with the specified attribute name in AppStorage or, if the attribute does not exist, creates one with the specified attribute name and the set value. 225 226If the new value is the same as the existing value of the attribute with the specified attribute name, the state variable will not instruct the UI to update the value of the attribute. 227 228**Parameters** 229 230| Name | Type | Mandatory | Description | 231| -------- | ------ | ---- | ---------------------- | 232| propName | string | Yes | Attribute name in AppStorage. | 233| newValue | T | Yes | Attribute value, which cannot be **undefined** or **null**.| 234 235 236```ts 237AppStorage.setOrCreate('simpleProp', 121); 238``` 239 240 241### delete<sup>10+</sup> 242 243static delete(propName: string): boolean 244 245Deletes the attribute with the specified attribute name from AppStorage under the prerequisite that the attribute does not have a subscriber. If there is a subscriber, **false** is returned. If the deletion is successful, **true** is returned. 246 247The subscribers of the attribute are attributes with the same name bound to APIs such as **Link** and **Prop**, **\@StorageLink('propName')**, and **\@StorageProp('propName')**. This means that if **\@StorageLink('propName')** and **\@StorageProp('propName')** are used in a custom component or if there is still a **SubscribedAbstractProperty** instance in sync with the attribute, the attribute cannot be deleted from AppStorage. 248 249**Parameters** 250 251| Name | Type | Mandatory | Description | 252| -------- | ------ | ---- | ---------------- | 253| propName | string | Yes | Attribute name in AppStorage.| 254 255**Return value** 256 257| Type | Description | 258| ------- | ---------------------------------------- | 259| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 260 261 262```ts 263AppStorage.setOrCreate('PropA', 47); 264AppStorage.link<number>('PropA'); 265let res: boolean = AppStorage.delete('PropA'); // false, PropA still has a subscriber 266 267AppStorage.setOrCreate('PropB', 48); 268let res1: boolean = AppStorage.delete('PropB'); // true, PropB is deleted from AppStorage successfully 269``` 270 271 272### keys<sup>10+</sup> 273 274static keys(): IterableIterator<string> 275 276Obtains all attribute names in AppStorage. 277 278**Return value** 279 280| Type | Description | 281| ------------------------------ | ------------------ | 282| IterableIterator<string> | All attribute names in AppStorage.| 283 284 285```ts 286AppStorage.setOrCreate('PropB', 48); 287let keys: IterableIterator<string> = AppStorage.keys(); 288``` 289 290 291### clear<sup>10+</sup> 292 293static clear(): boolean 294 295Deletes all attributes from AppStorage under the prerequisite that none of the attributes has a subscriber. If any of the attributes has a subscriber, **false** is returned. If the deletion is successful, **true** is returned. 296 297For details about the subscriber, see [Delete](#delete10). 298 299**Return value** 300 301| Type | Description | 302| ------- | ---------------------------------------- | 303| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 304 305 306```ts 307AppStorage.setOrCreate('PropA', 47); 308let res: boolean = AppStorage.clear(); // true, there are no subscribers 309``` 310 311 312### size<sup>10+</sup> 313 314static size(): number 315 316Obtains the number of attributes in AppStorage. 317 318**Return value** 319 320| Type | Description | 321| ------ | ------------------- | 322| number | Number of attributes in AppStorage.| 323 324 325```ts 326AppStorage.setOrCreate('PropB', 48); 327let res: number = AppStorage.size(); // 1 328``` 329 330 331### Link<sup>(deprecated)</sup> 332 333static Link(propName: string): any 334 335Establishes two-way data binding with the given attribute (specified by **propName**) in AppStorage. If the given attribute exists in AppStorage, the two-way bound data of the attribute in AppStorage is returned. 336 337Any update of the data is synchronized back to AppStorage, which then synchronizes the update to all data and custom components bound to the attribute. 338 339If the given attribute does not exist in AppStorage, **undefined** is returned. 340 341This API is deprecated since API version 10. You are advised to use [link10+](#link10) instead. 342 343 344**Parameters** 345 346| Name | Type | Mandatory | Description | 347| -------- | ------ | ---- | ---------------- | 348| propName | string | Yes | Attribute name in AppStorage.| 349 350**Return value** 351 352| Type | Description | 353| ---- | ---------------------------------------- | 354| any | Returns two-way bound data if specified attribute exists in AppStorage; returns **undefined** otherwise.| 355 356 357```ts 358AppStorage.SetOrCreate('PropA', 47); 359let linkToPropA1:SubscribedAbstractProperty<number> = AppStorage.Link('PropA'); 360let linkToPropA2:SubscribedAbstractProperty<number> = AppStorage.Link('PropA'); // linkToPropA2.get() == 47 361linkToPropA1.set(48); // Two-way synchronization: linkToPropA1.get() == linkToPropA2.get() == 48 362``` 363 364 365### SetAndLink<sup>(deprecated)</sup> 366 367static SetAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T> 368 369Works in a way similar to the **Link** API. If the given attribute exists in AppStorage, the two-way bound data of the attribute in AppStorage is returned. If the given attribute does not exist, it is created and initialized with <b class="+ topic/ph hi-d/b " id="b537113298389">defaultValue</b> in AppStorage, and two-way bound data is returned. 370 371This API is deprecated since API version 10. You are advised to use [setAndLink10+](#setandlink10) instead. 372 373**Parameters** 374 375| Name | Type | Mandatory | Description | 376| ------------ | ------ | ---- | ---------------------------------------- | 377| propName | string | Yes | Attribute name in AppStorage. | 378| defaultValue | T | Yes | Default value used to initialize the attribute with the specified attribute name in AppStorage.| 379 380**Return value** 381 382| Type | Description | 383| ----------------------------------- | ---------------------------------------- | 384| SubscribedAbstractProperty<T> | Instance of **SubscribedAbstractProperty<T>** and two-way bound data of the given attribute in AppStorage| 385 386 387```ts 388AppStorage.SetOrCreate('PropA', 47); 389let link1: SubscribedAbstractProperty<number> = AppStorage.SetAndLink('PropB', 49); // Create PropB 49 390let link2: SubscribedAbstractProperty<number> = AppStorage.SetAndLink('PropA', 50); // PropA exists, remains 47 391``` 392 393### Prop<sup>(deprecated)</sup> 394 395static Prop(propName: string): any 396 397Establishes one-way data binding with the given attribute (specified by **propName**) in AppStorage. If the given attribute exists in AppStorage, the one-way bound data of the attribute in AppStorage is returned. If the given attribute does not exist in AppStorage, **undefined** is returned. Updates of the one-way bound data are not synchronized back to AppStorage. 398 399>**NOTE** 400> Prop supports only simple types. 401> This API is deprecated since API version 10. You are advised to use [prop10+](#prop10) instead. 402 403**Parameters** 404 405| Name | Type | Mandatory | Description | 406| -------- | ------ | ---- | ---------------- | 407| propName | string | Yes | Attribute name in AppStorage.| 408 409**Return value** 410 411| Type | Description | 412| ---- | ---------------------------------------- | 413| any | Returns one-way bound data if specified attribute exists in AppStorage; returns **undefined** otherwise.| 414 415 416```ts 417AppStorage.SetOrCreate('PropA', 47); 418let prop1:SubscribedAbstractProperty<number> = AppStorage.Prop('PropA'); 419let prop2:SubscribedAbstractProperty<number> = AppStorage.Prop('PropA'); 420prop1.set(1); // one-way sync: prop1.get()=1; but prop2.get() == 47 421``` 422 423 424### SetAndProp<sup>(deprecated)</sup> 425 426static SetAndProp<S>(propName: string, defaultValue: S): SubscribedAbstractProperty<S> 427 428Works in a way similar to the **Prop** API. If the given attribute exists in AppStorage, the one-way bound data of the attribute in AppStorage is returned. If the given attribute does not exist, it is created and initialized with **defaultValue** in AppStorage, and one-way bound data is returned. 429 430This API is deprecated since API version 10. You are advised to use [setAndProp10+](#setandprop10) instead. 431 432**Parameters** 433 434| Name | Type | Mandatory | Description | 435| ------------ | ------ | ---- | ---------------------------------------- | 436| propName | string | Yes | Attribute name in AppStorage. | 437| defaultValue | S | Yes | Default value used to initialize the attribute with the specified attribute name in AppStorage.| 438 439**Return value** 440 441| Type | Description | 442| ----------------------------------- | --------------------------------------- | 443| SubscribedAbstractProperty<S> | Instance of **SubscribedAbstractProperty<S>**.| 444 445 446```ts 447AppStorage.SetOrCreate('PropA', 47); 448let prop: SubscribedAbstractProperty<number> = AppStorage.SetAndProp('PropB', 49); // PropA -> 47, PropB -> 49 449``` 450 451 452### Has<sup>(deprecated)</sup> 453 454static Has(propName: string): boolean 455 456Checks whether the attribute with the specified attribute name exists in AppStorage. 457 458This API is deprecated since API version 10. You are advised to use [has10+](#has10) instead. 459 460**Parameters** 461 462| Name | Type | Mandatory | Description | 463| -------- | ------ | ---- | ---------------- | 464| propName | string | Yes | Attribute name in AppStorage.| 465 466**Return value** 467 468| Type | Description | 469| ------- | ---------------------------------------- | 470| boolean | Returns **true** if the attribute with the specified attribute name exists in AppStorage; returns **false** otherwise.| 471 472 473```ts 474AppStorage.Has('simpleProp'); 475``` 476 477 478### Get<sup>(deprecated)</sup> 479 480static Get<T>(propName: string): T | undefined 481 482Obtains the attribute with the specified attribute name in AppStorage. If the attribute does not exist, **undefined** is returned. 483 484This API is deprecated since API version 10. You are advised to use [get10+](#get10) instead. 485 486**Parameters** 487 488| Name | Type | Mandatory | Description | 489| -------- | ------ | ---- | ---------------- | 490| propName | string | Yes | Attribute name in AppStorage.| 491 492**Return value** 493 494| Type | Description | 495| ------------------------ | ---------------------------------------- | 496| T \| undefined | Returns the attribute with the specified attribute name in AppStorage; returns **undefined** if the attribute does not exist.| 497 498 499```ts 500AppStorage.SetOrCreate('PropA', 47); 501let value: number = AppStorage.Get('PropA') as number; // 47 502``` 503 504 505### Set<sup>(deprecated)</sup> 506 507static Set<T>(propName: string, newValue: T): boolean 508 509Sets the value for the attribute with the specified attribute name in AppStorage. 510 511This API is deprecated since API version 10. You are advised to use [set10+](#set10) instead. 512 513**Parameters** 514 515| Name | Type | Mandatory | Description | 516| -------- | ------ | ---- | ---------------------- | 517| propName | string | Yes | Attribute name in AppStorage. | 518| newValue | T | Yes | Attribute value, which cannot be **undefined** or **null**.| 519 520**Return value** 521 522| Type | Description | 523| ------- | ---------------------------------------- | 524| boolean | Returns **true** if the operation is successful; return **false** if the attribute with the specified attribute name does not exist in AppStorage, or the value to set is **undefined** or **null**. | 525 526 527```ts 528AppStorage.SetOrCreate('PropA', 48); 529let res: boolean = AppStorage.Set('PropA', 47) // true 530let res1: boolean = AppStorage.Set('PropB', 47) // false 531``` 532 533 534### SetOrCreate<sup>(deprecated)</sup> 535 536static SetOrCreate<T>(propName: string, newValue: T): void 537 538Sets a new value for the attribute with the specified attribute name in AppStorage or, if the attribute does not exist, creates one with the specified attribute name and default value. 539 540This API is deprecated since API version 10. You are advised to use [setOrCreate10+](#setorcreate10) instead. 541 542**Parameters** 543 544| Name | Type | Mandatory | Description | 545| -------- | ------ | ---- | ---------------------- | 546| propName | string | Yes | Attribute name in AppStorage. | 547| newValue | T | Yes | Attribute value, which cannot be **undefined** or **null**.| 548 549 550```ts 551AppStorage.SetOrCreate('simpleProp', 121); 552``` 553 554 555### Delete<sup>(deprecated)</sup> 556 557static Delete(propName: string): boolean 558 559Deletes the attribute with the specified attribute name from AppStorage under the prerequisite that the attribute does not have a subscriber. If there is a subscriber, **false** is returned. If the deletion is successful, **true** is returned. 560 561The subscribers of the attribute are attributes with the same name bound to APIs such as **Link** and **Prop**, **\@StorageLink('propName')**, and **\@StorageProp('propName')**. This means that if **\@StorageLink('propName')** and **\@StorageProp('propName')** are used in a custom component or if there is still a **SubscribedAbstractProperty** instance in sync with the attribute, the attribute cannot be deleted from AppStorage. 562 563This API is deprecated since API version 10. You are advised to use [delete10+](#delete10) instead. 564 565**Parameters** 566 567| Name | Type | Mandatory | Description | 568| -------- | ------ | ---- | ---------------- | 569| propName | string | Yes | Attribute name in AppStorage.| 570 571**Return value** 572 573| Type | Description | 574| ------- | ---------------------------------------- | 575| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 576 577 578```ts 579AppStorage.SetOrCreate('PropA', 47); 580AppStorage.Link('PropA'); 581let res: boolean = AppStorage.Delete('PropA'); // false, PropA still has a subscriber 582 583AppStorage.SetOrCreate('PropB', 48); 584let res1: boolean = AppStorage.Delete('PropB'); // true, PropB is deleted from AppStorage successfully 585``` 586 587 588### Keys<sup>(deprecated)</sup> 589 590static Keys(): IterableIterator<string> 591 592Obtains all attribute names in AppStorage. 593 594This API is deprecated since API version 10. You are advised to use [keys10+](#keys10) instead. 595 596**Return value** 597 598| Type | Description | 599| ------------------------------ | ------------------ | 600| IterableIterator<string> | All attribute names in AppStorage.| 601 602 603```ts 604AppStorage.SetOrCreate('PropB', 48); 605let keys: IterableIterator<string> = AppStorage.Keys(); 606``` 607 608 609### staticClear<sup>(deprecated)</sup> 610 611static staticClear(): boolean 612 613Deletes all attributes. 614 615This API is deprecated since API version 9. You are advised to use [Clear9+](#clear9) instead. 616 617**Return value** 618 619| Type | Description | 620| ------- | --------------------------------- | 621| boolean | Returns **true** if all attributes are deleted; returns **false** if any of the attributes is being referenced by a state variable.| 622 623 624```ts 625let simple = AppStorage.staticClear(); 626``` 627 628 629### Clear<sup>(deprecated)</sup> 630 631static Clear(): boolean 632 633Deletes all attributes from AppStorage under the prerequisite that none of the attributes has a subscriber. If any of the attributes has a subscriber, **false** is returned. If the deletion is successful, **true** is returned. 634 635For details about the subscriber, see [Delete](#deletedeprecated). 636 637This API is deprecated since API version 10. You are advised to use [clear10+](#clear10) instead. 638 639**Return value** 640 641| Type | Description | 642| ------- | ---------------------------------------- | 643| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 644 645 646```typescript 647AppStorage.SetOrCreate('PropA', 47); 648let res: boolean = AppStorage.Clear(); // true, there are no subscribers 649``` 650 651 652### IsMutable<sup>(deprecated)</sup> 653 654static IsMutable(propName: string): boolean 655 656Checks whether the given attribute in AppStorage name is mutable. 657 658This API is deprecated since API version 10. 659 660**Parameters** 661 662| Name | Type | Mandatory | Description | 663| -------- | ------ | ---- | ---------------- | 664| propName | string | Yes | Attribute name in AppStorage.| 665 666**Return value** 667 668| Type | Description | 669| ------- | -------------------------------- | 670| boolean | Whether the given attribute in AppStorage name is mutable.| 671 672 673```ts 674AppStorage.SetOrCreate('PropA', 47); 675let res: boolean = AppStorage.IsMutable('simpleProp'); 676``` 677 678 679### Size<sup>(deprecated)</sup> 680 681static Size(): number 682 683Obtains the number of attributes in AppStorage. 684 685This API is deprecated since API version 10. You are advised to use [size10+](#size10) instead. 686 687**Return value** 688 689| Type | Description | 690| ------ | ------------------- | 691| number | Number of attributes in AppStorage.| 692 693 694```ts 695AppStorage.SetOrCreate('PropB', 48); 696let res: number = AppStorage.Size(); // 1 697``` 698 699 700## LocalStorage<sup>9+</sup> 701 702 703For details about how to use LocalStorage on the UI, see [LocalStorage: UI State Storage](../../quick-start/arkts-localstorage.md). 704 705 706### constructor<sup>9+</sup> 707 708constructor(initializingProperties?: Object) 709 710Creates a **LocalStorage** instance and initializes it using the attributes and values returned by **Object.keys(initializingProperties)**. 711 712Since API version 9, this API is supported in ArkTS widgets. 713 714**Parameters** 715 716| Name | Type | Mandatory | Description | 717| ---------------------- | ------ | ---- | ---------------------------------------- | 718| initializingProperties | Object | No | Attributes and values used to initialize the **LocalStorage** instance. The value cannot be **undefined**.| 719 720 721```ts 722let para:Record<string,number> = { 'PropA': 47 }; 723let storage: LocalStorage = new LocalStorage(para); 724``` 725 726 727### getShared<sup>10+</sup> 728 729static getShared(): LocalStorage 730 731Obtains the **LocalStorage** instance shared by the current stage. 732 733Since API version 9, this API is supported in ArkTS widgets. 734 735**Model restriction**: This API can be used only in the stage model. 736 737**Return value** 738 739| Type | Description | 740| ------------------------------ | ----------------- | 741| [LocalStorage](#localstorage9) | **LocalStorage** instance.| 742 743 744For details about how to use **getShared**, see [Sharing a LocalStorage Instance from UIAbility to One or More Pages](../../quick-start/arkts-localstorage.md#example-of-sharing-a-localstorage-instance-from-uiability-to-one-or-more-pages). 745 746 747### has<sup>9+</sup> 748 749has(propName: string): boolean 750 751Checks whether the attribute with the specified attribute name exists in LocalStorage. 752 753Since API version 9, this API is supported in ArkTS widgets. 754 755**Parameters** 756 757| Name | Type | Mandatory | Description | 758| -------- | ------ | ---- | ------------------ | 759| propName | string | Yes | Attribute name in LocalStorage.| 760 761**Return value** 762 763| Type | Description | 764| ------- | ---------------------------------------- | 765| boolean | Returns **true** if the attribute with the specified attribute name exists in AppStorage; returns **false** otherwise.| 766 767 768```ts 769let para:Record<string,number> = { 'PropA': 47 }; 770let storage: LocalStorage = new LocalStorage(para); 771storage.has('PropA'); // true 772``` 773 774 775### get<sup>9+</sup> 776 777get<T>(propName: string): T | undefined 778 779Obtains the attribute with the specified attribute name in LocalStorage. 780 781Since API version 9, this API is supported in ArkTS widgets. 782 783**Parameters** 784 785| Name | Type | Mandatory | Description | 786| -------- | ------ | ---- | ------------------ | 787| propName | string | Yes | Attribute name in LocalStorage.| 788 789**Return value** 790 791| Type | Description | 792| ------------------------ | ---------------------------------------- | 793| T \| undefined | Returns the attribute with the specified attribute name in LocalStorage; returns **undefined** if the attribute does not exist.| 794 795 796```ts 797let para:Record<string,number> = { 'PropA': 47 }; 798let storage: LocalStorage = new LocalStorage(para); 799let value: number = storage.get('PropA') as number; // 47 800``` 801 802 803### set<sup>9+</sup> 804 805set<T>(propName: string, newValue: T): boolean 806 807Sets a value for the attribute with the specified attribute name in LocalStorage. If the value of **newValue** is the same as the value of the attribute with the specified attribute name, that is, no value needs to be assigned, the state variable will not instruct the UI to update the value of attribute. 808 809Since API version 9, this API is supported in ArkTS widgets. 810 811**Parameters** 812 813| Name | Type | Mandatory | Description | 814| -------- | ------ | ---- | ----------------------- | 815| propName | string | Yes | Attribute name in LocalStorage. | 816| newValue | T | Yes | Attribute value, which cannot be **undefined** or **null**.| 817 818**Return value** 819 820| Type | Description | 821| ------- | ---------------------------------------- | 822| boolean | Returns **true** if the operation is successful; return **false** if the attribute with the specified attribute name does not exist in LocalStorage, or the value to set is **undefined** or **null**. | 823 824 825```ts 826let para:Record<string,number> = { 'PropA': 47 }; 827let storage: LocalStorage = new LocalStorage(para); 828let res: boolean = storage.set('PropA', 47); // true 829let res1: boolean = storage.set('PropB', 47); // false 830``` 831 832 833### setOrCreate<sup>9+</sup> 834 835setOrCreate<T>(propName: string, newValue: T): boolean 836 837Sets a new value for the attribute with the specified attribute name in LocalStorage or, if the attribute does not exist, creates one with the specified attribute name and the set value. 838If the new value is the same as the existing value of the attribute with the specified attribute name, the state variable will not instruct the UI to update the value of the attribute. 839 840Since API version 9, this API is supported in ArkTS widgets. 841 842**Parameters** 843 844| Name | Type | Mandatory | Description | 845| -------- | ------ | ---- | ----------------------- | 846| propName | string | Yes | Attribute name in LocalStorage. | 847| newValue | T | Yes | Attribute value, which cannot be **undefined** or **null**.| 848 849**Return value** 850 851| Type | Description | 852| ------- | ---------------------------------------- | 853| boolean | Returns **false** if **newValue** is set to **undefined** or **null**.<br>Updates the target attribute with the new value and returns **true** if the attribute exists in LocalStorage.<br>Creates an attribute with the specified attribute name and default value if the attribute does not exist in LocalStorage.| 854 855 856```ts 857let para:Record<string,number> = { 'PropA': 47 }; 858let storage: LocalStorage = new LocalStorage(para); 859let res: boolean =storage.setOrCreate('PropA', 121); // true 860let res1: boolean =storage.setOrCreate('PropB', 111); // true 861let res2: boolean =storage.setOrCreate('PropB', null); // false 862``` 863 864 865### link<sup>9+</sup> 866 867link<T>(propName: string): SubscribedAbstractProperty<T> 868 869Establishes two-way data binding with the given attribute in this **LocalStorage** instance. If the given attribute exists, the two-way bound data of the attribute in LocalStorage is returned. 870 871Any update of the data is synchronized back to LocalStorage, which then synchronizes the update to all data and custom components bound to the attribute. 872 873If the given attribute does not exist in LocalStorage, **undefined** is returned. 874 875Since API version 9, this API is supported in ArkTS widgets. 876 877**Parameters** 878 879| Name | Type | Mandatory | Description | 880| -------- | ------ | ---- | ------------------ | 881| propName | string | Yes | Attribute name in LocalStorage.| 882 883**Return value** 884 885| Type | Description | 886| ----------------------------------- | ---------------------------------------- | 887| SubscribedAbstractProperty<T> | Returns the **SubscribedAbstractProperty<T>** instance if the given attribute exists in AppStorage; returns **undefined** otherwise.| 888 889 890```ts 891let para:Record<string,number> = { 'PropA': 47 }; 892let storage: LocalStorage = new LocalStorage(para); 893let linkToPropA1: SubscribedAbstractProperty<number> = storage.link('PropA'); 894let linkToPropA2: SubscribedAbstractProperty<number> = storage.link('PropA'); // linkToPropA2.get() == 47 895linkToPropA1.set(48); // Two-way synchronization: linkToPropA1.get() == linkToPropA2.get() == 48 896``` 897 898 899### setAndLink<sup>9+</sup> 900 901setAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T> 902 903Works in a way similar to the **Link** API. If the given attribute exists in LocalStorage, the two-way bound data of the attribute in LocalStorage is returned. If the given attribute does not exist, it is created and initialized with **defaultValue** in LocalStorage, and two-way bound data is returned. 904 905Since API version 9, this API is supported in ArkTS widgets. 906 907**Parameters** 908 909| Name | Type | Mandatory | Description | 910| ------------ | ------ | ---- | ---------------------------------------- | 911| propName | string | Yes | Attribute name in LocalStorage. | 912| defaultValue | T | Yes | Default value used to initialize the attribute with the specified attribute name in LocalStorage.| 913 914**Return value** 915 916| Type | Description | 917| ----------------------------------- | ---------------------------------------- | 918| SubscribedAbstractProperty<T> | Returns the **SubscribedAbstractProperty<T>** instance if the given attribute exists in AppStorage; returns **undefined** otherwise.| 919 920 921```ts 922let para:Record<string,number> = { 'PropA': 47 }; 923let storage: LocalStorage = new LocalStorage(para); 924let link1: SubscribedAbstractProperty<number> = storage.setAndLink('PropB', 49); // Create PropB 49 925let link2: SubscribedAbstractProperty<number> = storage.setAndLink('PropA', 50); // PropA exists, remains 47 926``` 927 928 929### prop<sup>9+</sup> 930 931prop<S>(propName: string): SubscribedAbstractProperty<S> 932 933Establishes one-way data binding with the given attribute in this **LocalStorage** instance. If the given attribute exists, the one-way bound data of the attribute in LocalStorage is returned. If the given attribute does not exist in LocalStorage, **undefined** is returned. Updates of the one-way bound data are not synchronized back to LocalStorage. 934 935Since API version 9, this API is supported in ArkTS widgets. 936 937**Parameters** 938 939| Name | Type | Mandatory | Description | 940| -------- | ------ | ---- | ------------------ | 941| propName | string | Yes | Attribute name in LocalStorage.| 942 943**Return value** 944 945| Type | Description | 946| ----------------------------------- | ---------------------------------------- | 947| SubscribedAbstractProperty<S> | Returns the **SubscribedAbstractProperty<S>** instance if the given attribute exists in LocalStorage; returns **undefined** otherwise.| 948 949 950```ts 951let para:Record<string,number> = { 'PropA': 47 }; 952let storage: LocalStorage = new LocalStorage(para); 953let prop1: SubscribedAbstractProperty<number> = storage.prop('PropA'); 954let prop2: SubscribedAbstractProperty<number> = storage.prop('PropA'); 955prop1.set(1); // one-way sync: prop1.get()=1; but prop2.get() == 47 956``` 957 958 959### setAndProp<sup>9+</sup> 960 961setAndProp<S>(propName: string, defaultValue: S): SubscribedAbstractProperty<S> 962 963Establishes one-way data binding with the given attribute in this **LocalStorage** instance. If the given attribute exists, the one-way bound data of the attribute in LocalStorage is returned. If the given attribute does not exist, it is created and initialized with **defaultValue** in LocalStorage, and one-way bound data is returned. 964 965Since API version 9, this API is supported in ArkTS widgets. 966 967**Parameters** 968 969| Name | Type | Mandatory | Description | 970| ------------ | ------ | ---- | ---------------------------------------- | 971| propName | string | Yes | Attribute name in LocalStorage. | 972| defaultValue | S | Yes | Default value used to initialize the attribute with the specified attribute name in LocalStorage.| 973 974**Return value** 975 976| Type | Description | 977| ----------------------------------- | ---------------------------------------- | 978| SubscribedAbstractProperty<S> | Instance of **SubscribedAbstractProperty<T>** and one-way bound data of the given attribute in LocalStorage.| 979 980 981```ts 982let para:Record<string,number> = { 'PropA': 47 }; 983let storage: LocalStorage = new LocalStorage(para); 984let prop: SubscribedAbstractProperty<number> = storage.setAndProp('PropB', 49); // PropA -> 47, PropB -> 49 985``` 986 987 988### delete<sup>9+</sup> 989 990delete(propName: string): boolean 991 992Deletes the attribute with the specified attribute name from LocalStorage under the prerequisite that the attribute does not have a subscriber. If the deletion is successful, **true** is returned. 993 994The subscribers of the attribute are attributes with the same name bound to the **Link** and **Prop** APIs, **\@LocalStorageLink('propName')**, and **\@LocalStorageProp('propName')**. This means that if **\@LocalStorageLink('propName')** and **\@LocalStorageProp('propName')** are used in a custom component or if there is still a **SubscribedAbstractProperty** instance (return type of the **link** and **prop** APIs) in sync with the attribute, the attribute cannot be deleted from LocalStorage. 995 996Since API version 9, this API is supported in ArkTS widgets. 997 998**Parameters** 999 1000| Name | Type | Mandatory | Description | 1001| -------- | ------ | ---- | ------------------ | 1002| propName | string | Yes | Attribute name in LocalStorage.| 1003 1004**Return value** 1005 1006| Type | Description | 1007| ------- | ---------------------------------------- | 1008| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 1009 1010 1011```ts 1012let para:Record<string,number> = { 'PropA': 47 }; 1013let storage: LocalStorage = new LocalStorage(para); 1014storage.link<number>('PropA'); 1015let res: boolean = storage.delete('PropA'); // false, PropA still has a subscriber 1016let res1: boolean = storage.delete('PropB'); // false, PropB is not in storage 1017storage.setOrCreate('PropB', 48); 1018let res2: boolean = storage.delete('PropB'); // true, PropB is deleted from storage successfully 1019``` 1020 1021 1022### keys<sup>9+</sup> 1023 1024keys(): IterableIterator<string> 1025 1026Obtains all attribute names in LocalStorage. 1027 1028Since API version 9, this API is supported in ArkTS widgets. 1029 1030**Return value** 1031 1032| Type | Description | 1033| ------------------------------ | -------------------- | 1034| IterableIterator<string> | All attribute names in LocalStorage.| 1035 1036 1037```ts 1038let para:Record<string,number> = { 'PropA': 47 }; 1039let storage: LocalStorage = new LocalStorage(para); 1040let keys: IterableIterator<string> = storage.keys(); 1041``` 1042 1043 1044### size<sup>9+</sup> 1045 1046size(): number 1047 1048Obtains the number of attributes in LocalStorage. 1049 1050Since API version 9, this API is supported in ArkTS widgets. 1051 1052**Return value** 1053 1054| Type | Description | 1055| ------ | --------- | 1056| number | Number of attributes in LocalStorage.| 1057 1058 1059```ts 1060let para:Record<string,number> = { 'PropA': 47 }; 1061let storage: LocalStorage = new LocalStorage(para); 1062let res: number = storage.size(); // 1 1063``` 1064 1065 1066### clear<sup>9+</sup> 1067 1068clear(): boolean 1069 1070 1071Deletes all attributes from LocalStorage under the prerequisite that none of the attributes has a subscriber. If any of the attributes has a subscriber, **false** is returned. If the deletion is successful, **true** is returned. 1072 1073Since API version 9, this API is supported in ArkTS widgets. 1074 1075**Return value** 1076 1077 1078| Type | Description | 1079| ------- | ---------------------------------------- | 1080| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 1081 1082 1083 1084```ts 1085let para:Record<string,number> = { 'PropA': 47 }; 1086let storage: LocalStorage = new LocalStorage(para); 1087let res: boolean = storage.clear(); // true, there are no subscribers 1088``` 1089 1090 1091### GetShared<sup>(deprecated)</sup> 1092 1093static GetShared(): LocalStorage 1094 1095Obtains the **LocalStorage** instance shared by the current stage. 1096 1097Since API version 9, this API is supported in ArkTS widgets. 1098 1099This API is deprecated since API version 10. You are advised to use [getShared10+](#getshared10) instead. 1100 1101**Model restriction**: This API can be used only in the stage model. 1102 1103**Return value** 1104 1105| Type | Description | 1106| ------------------------------ | ----------------- | 1107| [LocalStorage](#localstorage9) | **LocalStorage** instance.| 1108 1109 1110```ts 1111let storage: LocalStorage = LocalStorage.GetShared(); 1112``` 1113 1114 1115## SubscribedAbstractProperty 1116 1117 1118### get<sup>9+</sup> 1119 1120abstract get(): T 1121 1122Obtains attribute data synchronized from AppStorage or LocalStorage. 1123 1124Since API version 9, this API is supported in ArkTS widgets. 1125 1126**Return value** 1127 1128| Type | Description | 1129| ---- | ------------------------------- | 1130| T | Attribute data synchronized from AppStorage or LocalStorage.| 1131 1132 1133```ts 1134AppStorage.SetOrCreate('PropA', 47); 1135let prop1:SubscribedAbstractProperty<number> = AppStorage.Prop('PropA'); 1136prop1.get(); // prop1.get()=47 1137``` 1138 1139 1140### set<sup>9+</sup> 1141 1142abstract set(newValue: T): void 1143 1144Sets the attribute data synchronized from AppStorage or LocalStorage. 1145 1146Since API version 9, this API is supported in ArkTS widgets. 1147 1148 1149**Parameters** 1150 1151 1152| Name | Type | Mandatory | Description | 1153| -------- | ---- | ---- | ------- | 1154| newValue | T | Yes | Data to set.| 1155 1156 1157 1158```ts 1159AppStorage.SetOrCreate('PropA', 47); 1160let prop1:SubscribedAbstractProperty<number> = AppStorage.Prop('PropA'); 1161prop1.set(1); // prop1.get()=1 1162``` 1163 1164### aboutToBeDeleted<sup>10+</sup> 1165 1166abstract aboutToBeDeleted(): void 1167 1168Cancels one-way or two-way synchronization between the **SubscribedAbstractProperty** instance and AppStorage or LocalStorage. 1169 1170 1171```ts 1172AppStorage.SetOrCreate('PropA', 47); 1173let link = AppStorage.SetAndLink('PropB', 49); // PropA -> 47, PropB -> 49 1174link.aboutToBeDeleted(); 1175link.set(50); // PropB -> 49, link.get() --> undefined 1176``` 1177 1178 1179## PersistentStorage 1180 1181 1182For details about how to use PersistentStorage on the UI, see [PersistentStorage: Application State Persistence](../../quick-start/arkts-persiststorage.md). 1183 1184 1185### PersistPropsOptions 1186 1187| Name | Type | Mandatory| Description | 1188| ------------ | ----------------------- | ---- | ------------------------------------------------------------ | 1189| key | string | Yes | Attribute name. | 1190| defaultValue | number\|string\|boolean | Yes | Default value used to initialize the created attribute. The value cannot be **undefined** or **null**.| 1191 1192 1193### persistProp<sup>10+</sup> 1194 1195static persistProp<T>(key: string, defaultValue: T): void 1196 1197Persists the attribute with the specified key in AppStorage to a file. This API is usually called before access to AppStorage. 1198 1199The sequence of determining the type and value of an attribute is as follows: 1200 12011. If the PersistentStorage file contains the attribute with the specified key, an attribute with the key as the name is created in AppStorage and initialized with the attribute of the key found in PersistentStorage. 1202 12032. If the attribute with the specified key is not found in the PersistentStorage file, AppStorage is searched for the attribute corresponding to the key. If the matching attribute is found, it is persisted. 1204 12053. If no matching attribute is found in AppStorage, it is created in AppStorage, initialized with the value of **defaultValue**, and persisted. 1206 1207According to the preceding initialization process, if AppStorage contains the matching attribute, the value of this attribute is used to overwrite the value in the PersistentStorage file. Because AppStorage stores data in the memory, the attribute value becomes impersistent. 1208 1209**Parameters** 1210 1211| Name | Type | Mandatory | Description | 1212| ------------ | ------ | ---- | ---------------------------------------- | 1213| key | string | Yes | Attribute name. | 1214| defaultValue | T | Yes | Default value used to initialize the created attribute. The value cannot be **undefined** or **null**.| 1215 1216 1217**Example:** 1218 1219 1220For details about how to use persistProp, see [Accessing PersistentStorage Initialized Attribute from AppStorage](../../quick-start/arkts-persiststorage.md#accessing-persistentstorage-initialized-attribute-from-appstorage). 1221 1222 1223### deleteProp<sup>10+</sup> 1224 1225static deleteProp(key: string): void 1226 1227Performs the reverse operation of **PersistProp**. Specifically, this API deletes the attribute corresponding to the key from PersistentStorage. Subsequent AppStorage operations do not affect data in PersistentStorage. 1228 1229**Parameters** 1230 1231| Name | Type | Mandatory | Description | 1232| ---- | ------ | ---- | ----------------------- | 1233| key | string | Yes | Attribute name in PersistentStorage.| 1234 1235 1236```ts 1237PersistentStorage.deleteProp('highScore'); 1238``` 1239 1240 1241### persistProps<sup>10+</sup> 1242 1243static persistProps(props: PersistPropsOptions[]): void 1244 1245Works in a way similar to the **PersistProp** API, with the difference that it allows for persistence in batches and is therefore ideal for initialization during application startup. 1246 1247**Parameters** 1248 1249| Name | Type | Mandatory | Description | 1250| ---------- | ---------------------------------------- | ---- | ---------------------------------------- | 1251| props | [PersistPropsOptions](#persistpropsoptions)[] | Yes| Array of persistent attributes.| 1252 1253 1254```ts 1255PersistentStorage.persistProps([{ key: 'highScore', defaultValue: '0' }, { key: 'wightScore', defaultValue: '1' }]); 1256``` 1257 1258 1259### keys<sup>10+</sup> 1260 1261static keys(): Array<string> 1262 1263Obtains an array of keys for all persistent attributes. 1264 1265**Return value** 1266 1267| Type | Description | 1268| ------------------- | ----------------- | 1269| Array<string> | Array of keys of all persistent attributes.| 1270 1271 1272```ts 1273let keys: Array<string> = PersistentStorage.keys(); 1274``` 1275 1276 1277### PersistProp<sup>(deprecated)</sup> 1278 1279static PersistProp<T>(key: string, defaultValue: T): void 1280 1281Persists the attribute with the specified key in AppStorage to a file. This API is usually called before access to AppStorage. 1282 1283The sequence of determining the type and value of an attribute is as follows: 1284 12851. If the PersistentStorage file contains the attribute with the specified key, an attribute with the key as the name is created in AppStorage and initialized with the attribute of the key found in PersistentStorage. 1286 12872. If the attribute with the specified key is not found in the PersistentStorage file, AppStorage is searched for the attribute corresponding to the key. If the matching attribute is found, it is persisted. 1288 12893. If no matching attribute is found in AppStorage, it is created in AppStorage, initialized with the value of **defaultValue**, and persisted. 1290 1291According to the preceding initialization process, if AppStorage contains the matching attribute, the value of this attribute is used to overwrite the value in the PersistentStorage file. Because AppStorage stores data in the memory, the attribute value becomes impersistent. 1292 1293This API is deprecated since API version 10. You are advised to use [persistProp10+](#persistprop10) instead. 1294 1295**Parameters** 1296 1297| Name | Type | Mandatory | Description | 1298| ------------ | ------ | ---- | ---------------------------------------- | 1299| key | string | Yes | Attribute name. | 1300| defaultValue | T | Yes | Default value used to initialize the created attribute. The value cannot be **undefined** or **null**.| 1301 1302 1303**Example:** 1304 1305 1306```ts 1307PersistentStorage.PersistProp('highScore', '0'); 1308``` 1309 1310 1311### DeleteProp<sup>(deprecated)</sup> 1312 1313static DeleteProp(key: string): void 1314 1315Performs the reverse operation of **PersistProp**. Specifically, this API deletes the attribute corresponding to the key from PersistentStorage. Subsequent AppStorage operations do not affect data in PersistentStorage. 1316 1317This API is deprecated since API version 10. You are advised to use [deleteProp10+](#deleteprop10) instead. 1318 1319**Parameters** 1320 1321| Name | Type | Mandatory | Description | 1322| ---- | ------ | ---- | ----------------------- | 1323| key | string | Yes | Attribute name in PersistentStorage.| 1324 1325 1326```ts 1327PersistentStorage.DeleteProp('highScore'); 1328``` 1329 1330 1331### PersistProps<sup>(deprecated)</sup> 1332 1333static PersistProps(properties: {key: string, defaultValue: any;}[]): void 1334 1335Works in a way similar to the **PersistProp** API, with the difference that it allows for persistence in batches and is therefore ideal for initialization during application startup. 1336 1337This API is deprecated since API version 10. You are advised to use [persistProps10+](#persistprops10) instead. 1338 1339**Parameters** 1340 1341| Name | Type | Mandatory| Description | 1342| ---------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | 1343| properties | {key: string, defaultValue: any}[] | Yes | Array of attributes to persist.<br>**key**: attribute name.<br>**defaultValue**: default value. The rules are the same as those of **PersistProp**.| 1344 1345 1346```ts 1347PersistentStorage.PersistProps([{ key: 'highScore', defaultValue: '0' }, { key: 'wightScore', defaultValue: '1' }]); 1348``` 1349 1350 1351### Keys<sup>(deprecated)</sup> 1352 1353static Keys(): Array<string> 1354 1355Obtains an array of keys for all persistent attributes. 1356 1357This API is deprecated since API version 10. You are advised to use [keys10+](#keys10-1) instead. 1358 1359**Return value** 1360 1361| Type | Description | 1362| ------------------- | ----------------- | 1363| Array<string> | Array of keys of all persistent attributes.| 1364 1365 1366```ts 1367let keys: Array<string> = PersistentStorage.Keys(); 1368``` 1369 1370 1371## Environment 1372 1373 1374For details about how to use Environment, see [Environment: Device Environment Query](../../quick-start/arkts-environment.md). 1375 1376 1377### EnvPropsOptions 1378 1379| Name | Type | Mandatory| Description | 1380| ------------ | ----------------------- | ---- | ------------------------------------------------------------ | 1381| key | string | Yes | Environment variable name. For details about the value range, see [Built-in Environment Variables](#built-in-environment-variables).| 1382| defaultValue | number\|string\|boolean | Yes | Default value used if the value of the environment variable key is not found in AppStorage.| 1383 1384 1385### envProp<sup>10+</sup> 1386 1387static envProp<S>(key: string, value: S): boolean 1388 1389Saves the built-in environment variable key in environment to AppStorage. If the value of the environment variable key is not found in AppStorage, the default value is used. If the value is successfully saved, **true** is returned. If the value of the environment variable key is found in AppStorage, **false** is returned. 1390 1391You are advised to call this API when the application is started. 1392 1393It is incorrect to use AppStorage to read environment variables without invoking **EnvProp**. 1394 1395**Parameters** 1396 1397| Name | Type | Mandatory | Description | 1398| ----- | ------ | ---- | --------------------------------------- | 1399| key | string | Yes | Environment variable name. For details about the value range, see [Built-in Environment Variables](#built-in-environment-variables). | 1400| value | S | Yes | Default value used if the value of the environment variable key is not found in AppStorage.| 1401 1402**Return value** 1403 1404| Type | Description | 1405| ------- | ---------------------------------------- | 1406| boolean | Returns **false** if the attribute corresponding to the key exists in AppStorage; returns **false** otherwise.| 1407 1408**Example:** 1409 1410 1411For details about how to use **envProp**, see [Accessing Environment Parameters from UI](../../quick-start/arkts-environment.md#accessing-environment-parameters-from-ui). 1412 1413 1414### envProps<sup>10+</sup> 1415 1416static envProps(props: EnvPropsOptions[]): void 1417 1418Works in a way similar to the **EnvProp** API, with the difference that it allows for initialization of multiple attributes in batches. You are advised to call this API during application startup to save system environment variables to AppStorage in batches. 1419 1420**Parameters** 1421 1422| Name| Type | Mandatory| Description | 1423| ------ | --------------------------------------------- | ---- | ------------------------------------ | 1424| props | [EnvPropsOptions](#envpropsoptions)[] | Yes | Array of key-value pairs consisting of system environment variables and default values.| 1425 1426 1427```ts 1428Environment.envProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, { 1429 key: 'languageCode', 1430 defaultValue: 'en' 1431}, { key: 'prop', defaultValue: 'hhhh' }]); 1432``` 1433 1434 1435### keys<sup>10+</sup> 1436 1437static keys(): Array<string> 1438 1439Array of keys of environment variables. 1440 1441**Return value** 1442 1443| Type | Description | 1444| ------------------- | ----------- | 1445| Array<string> | Returns an array of associated system attributes.| 1446 1447 1448```ts 1449Environment.envProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, { 1450 key: 'languageCode', 1451 defaultValue: 'en' 1452}, { key: 'prop', defaultValue: 'hhhh' }]); 1453 1454let keys: Array<string> = Environment.keys(); // accessibilityEnabled, languageCode, prop 1455``` 1456 1457 1458### EnvProp<sup>(deprecated)</sup> 1459 1460static EnvProp<S>(key: string, value: S): boolean 1461 1462Saves the built-in environment variable key in environment to AppStorage. If the value of the environment variable key is not found in AppStorage, the default value is used. If the value is successfully saved, **true** is returned. If the value of the environment variable key is found in AppStorage, **false** is returned. 1463 1464You are advised to call this API when the application is started. 1465 1466It is incorrect to use AppStorage to read environment variables without invoking **EnvProp**. 1467 1468This API is deprecated since API version 10. You are advised to use [envProp10+](#envprop10) instead. 1469 1470**Parameters** 1471 1472| Name | Type | Mandatory | Description | 1473| ----- | ------ | ---- | --------------------------------------- | 1474| key | string | Yes | Environment variable name. For details about the value range, see [Built-in Environment Variables](#built-in-environment-variables). | 1475| value | S | Yes | Default value used if the value of the environment variable key is not found in AppStorage.| 1476 1477**Return value** 1478 1479| Type | Description | 1480| ------- | ---------------------------------------- | 1481| boolean | Returns **false** if the attribute corresponding to the key exists in AppStorage; returns **false** otherwise.| 1482 1483**Example:** 1484 1485 1486```ts 1487Environment.EnvProp('accessibilityEnabled', 'default'); 1488``` 1489 1490 1491### EnvProps<sup>(deprecated)</sup> 1492 1493static EnvProps(props: {key: string; defaultValue: any;}[]): void 1494 1495Works in a way similar to the **EnvProp** API, with the difference that it allows for initialization of multiple attributes in batches. You are advised to call this API during application startup to save system environment variables to AppStorage in batches. 1496 1497This API is deprecated since API version 10. You are advised to use [envProps10+](#envprops10) instead. 1498 1499**Parameters** 1500 1501| Name | Type | Mandatory | Description | 1502| ----- | ---------------------------------------- | ---- | ------------------ | 1503| props | {key: string, defaultValue: any}[] | Yes | Array of key-value pairs consisting of system environment variables and default values.| 1504 1505 1506```ts 1507Environment.EnvProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, { 1508 key: 'languageCode', 1509 defaultValue: 'en' 1510}, { key: 'prop', defaultValue: 'hhhh' }]); 1511``` 1512 1513 1514### Keys<sup>(deprecated)</sup> 1515 1516static Keys(): Array<string> 1517 1518Array of keys of environment variables. 1519 1520This API is deprecated since API version 10. You are advised to use [keys10+](#keys10-2) instead. 1521 1522**Return value** 1523 1524| Type | Description | 1525| ------------------- | ----------- | 1526| Array<string> | Returns an array of associated system attributes.| 1527 1528 1529```ts 1530Environment.EnvProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, { 1531 key: 'languageCode', 1532 defaultValue: 'en' 1533}, { key: 'prop', defaultValue: 'hhhh' }]); 1534 1535let keys: Array<string> = Environment.Keys(); // accessibilityEnabled, languageCode, prop 1536``` 1537 1538 1539## Built-in Environment Variables 1540 1541| key | Type | Description | 1542| -------------------- | --------------- | ---------------------------------------- | 1543| accessibilityEnabled | string | Whether to enable accessibility. | 1544| colorMode | ColorMode | Color mode. The options are as follows:<br>- **ColorMode.LIGHT**: light mode.<br>- **ColorMode.DARK**: dark mode.| 1545| fontScale | number | Font scale. | 1546| fontWeightScale | number | Font weight scale. | 1547| layoutDirection | LayoutDirection | Layout direction. The options are as follows:<br>- **LayoutDirection.LTR**: from left to right.<br>- **LayoutDirection.RTL**: from right to left.| 1548| languageCode | string | Current system language. The value is in lowercase, for example, **zh**. | 1549