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