1# State Management with Application-level Variables 2 3The state management module provides APIs for data storage, persistent data management, **Ability** data storage, and environment status required by applications. The APIs for **Ability** data storage are supported since API version 9. 4 5> **NOTE** 6> 7> 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. 8 9## AppStorage 10 11### Link 12 13Link(propName: string): any 14 15Establishes two-way data binding between an attribute and this **LocalStorage** instance. 16 17**Parameters** 18 19| Name | Type | Mandatory | Description | 20| -------- | ------ | ---- | ----------- | 21| propName | string | Yes | Name of the target attribute.| 22 23**Return value** 24 25| Type | Description | 26| ----- | ---------------------------------------- | 27| @Link | Returns two-way binding to this attribute if there is data with a given key. This means that attribute changes made by a variable or component will be synchronized to the **AppStorage**, and attribute changes made through the **AppStorage** will be synchronized to the variable or component.| 28 29```ts 30let simple = AppStorage.Link('simpleProp') 31``` 32 33### SetAndLink 34 35SetAndLink\<T>(propName: string, defaultValue: T): SubscribedAbstractProperty\<T> 36 37Works in a way similar to the **Link** API. If the current key is stored in the **AppStorage**, the value corresponding to the key is returned. If the key has not been created, a **Link** instance corresponding to the default value is created and returned. 38 39**Parameters** 40 41| Name | Type | Mandatory | Description | 42| ------------ | ------ | ---- | ----------- | 43| propName | string | Yes | Target key.| 44| defaultValue | T | Yes | Default value to set. | 45 46**Return value** 47 48| Type | Description | 49| ----- | ---------------------------------------- | 50| @Link | Returns the value corresponding to the key if the current key is stored in the **AppStorage**; creates and returns a **Link** instance corresponding to the default value if the key has not been created.| 51 52```ts 53let simple = AppStorage.SetAndLink('simpleProp', 121) 54``` 55 56### Prop 57 58Prop(propName: string): any 59 60Establishes one-way data binding with an attribute to update its status. 61 62**Parameters** 63 64| Name | Type | Mandatory | Description | 65| -------- | ------ | ---- | ----------- | 66| propName | string | Yes | Target key.| 67 68**Return value** 69 70| Type | Description | 71| ----- | ---------------------------------------- | 72| @Prop | Returns one-way binding to an attribute with a given key if the attribute exists; returns **undefined** otherwise. One-way binding means that attribute changes made through the **AppStorage** will be synchronized to the variable or component, but attribute changes made by the variable or component will not be synchronized to the **AppStorage**. This API returns immutable variables and is applicable to mutable and immutable state variables alike.| 73 74```ts 75let simple = AppStorage.Prop('simpleProp') 76``` 77 78### SetAndProp 79 80SetAndProp\<S>(propName: string, defaultValue: S): SubscribedAbstractProperty\<S> 81 82Works in a way similar to the **Prop** API. If the current key is stored in the **AppStorage**, the value corresponding to the key is returned. If the key has not been created, a **Prop** instance corresponding to the default value is created and returned. 83 84**Parameters** 85 86| Name | Type | Mandatory | Description | 87| ------------ | ------ | ---- | --------------- | 88| propName | string | Yes | Key of the target key-value pair.| 89| defaultValue | S | Yes | Default value to set. | 90 91**Return value** 92 93| Type | Description | 94| ----- | ---------------------------------------- | 95| @Prop | Returns the value corresponding to the key if the current key is stored in the **AppStorage**; creates and returns a **Prop** instance corresponding to the default value otherwise.| 96 97```ts 98let simple = AppStorage.SetAndProp('simpleProp', 121) 99``` 100 101### Has 102 103Has(propName: string): boolean 104 105Checks whether the attribute corresponding to the specified key exists. 106 107**Parameters** 108 109| Name | Type | Mandatory | Description | 110| -------- | ------ | ---- | ------- | 111| propName | string | Yes | Key of the attribute.| 112 113**Return value** 114 115| Type | Description | 116| ------- | ------------- | 117| boolean | Returns whether the attribute exists.| 118 119```ts 120let simple = AppStorage.Has('simpleProp') 121``` 122 123### Get 124 125Get\<T>(propName: string): T | undefined 126 127Obtains the value of the specified key. 128 129**Parameters** 130 131| Name | Type | Mandatory | Description | 132| -------- | ------ | ---- | ----------- | 133| propName | string | Yes | Key of the value to obtain.| 134 135**Return value** 136 137| Type | Description | 138| ----------------- | ------------- | 139| T or undefined| Returns the attribute value if the attribute exists; returns **undefined** otherwise.| 140 141```ts 142let simple = AppStorage.Get('simpleProp') 143``` 144 145### Set 146 147Set\<T>(propName: string, newValue: T): boolean 148 149Replaces the value of a saved key. 150 151**Parameters** 152 153| Name | Type | Mandatory | Description | 154| -------- | ------ | ---- | ----------- | 155| propName | string | Yes | Key to set. | 156| newValue | T | Yes | Value to set.| 157 158**Return value** 159 160| Type | Description | 161| ------- | ----------------------------------- | 162| boolean | Returns **true** and the value if the key exists; returns **false** otherwise.| 163 164```ts 165let simple = AppStorage.Set('simpleProp', 121) 166``` 167 168### SetOrCreate 169 170SetOrCreate\<T>(propName: string, newValue: T): void 171 172Creates or updates the value of the specified key. 173 174**Parameters** 175 176| Name | Type | Mandatory | Description | 177| -------- | ------ | ---- | --------------- | 178| propName | string | Yes | Key to set. | 179| newValue | T | Yes | Value to be updated or created.| 180 181**Return value** 182 183| Type | Description | 184| ------- | ---------------------------------------- | 185| boolean | Updates the value of the attribute and returns **true** if an attribute that has the same name as the specified key exists; creates an attribute with the specified value as its default value and returns **false** otherwise. **undefined** and **null** are not allowed to return **true**.| 186 187```ts 188let simple = AppStorage.SetOrCreate('simpleProp', 121) 189``` 190 191### Delete 192 193Delete(propName: string): boolean 194 195Deletes the key-value pair that matches the specified key. 196 197**Parameters** 198 199| Name | Type | Mandatory | Description | 200| -------- | ------ | ---- | ------------ | 201| propName | string | Yes | Key of the target key-value pair.| 202 203**Return value** 204 205| Type | Description | 206| ------- | ---------------------------------------- | 207| boolean | Returns **true** if the key-value pair exists and is successfully deleted; returns **false** otherwise.| 208 209```ts 210let simple = AppStorage.Delete('simpleProp') 211``` 212 213### keys 214 215keys(): IterableIterator\<string> 216 217Searches for all keys. 218 219**Return value** 220 221| Type | Description | 222| -------------- | -------------- | 223| array\<string> | Returns an array of strings containing all keys.| 224 225```ts 226let simple = AppStorage.Keys() 227``` 228 229### staticClear 230 231staticClear(): boolean 232 233Deletes all attributes. 234 235This API is deprecated since API version 9. You are advised to use [Clear](#clear) instead. 236 237**Return value** 238 239| Type | Description | 240| ------- | --------------------------------- | 241| boolean | Returns **true** if all attributes are deleted; returns **false** if any of the attributes is being referenced by a state variable.| 242 243```ts 244let simple = AppStorage.staticClear() 245``` 246 247### Clear<sup>9+</sup> 248 249Clear(): boolean 250 251Deletes all attributes. 252 253**Return value** 254 255| Type | Description | 256| ------- | --------------------------------- | 257| boolean | Returns **true** if all attributes are deleted; returns **false** if any of the attributes is being referenced by a state variable.| 258 259```typescript 260let simple = AppStorage.Clear() 261``` 262 263### IsMutable 264 265IsMutable(propName: string): boolean 266 267Checks whether an attribute exists and can be changed. 268 269**Parameters** 270 271| Name | Type | Mandatory | Description | 272| -------- | ------ | :--- | ------------ | 273| propName | string | Yes | Key of the target attribute.| 274 275**Return value** 276 277| Type | Description | 278| ------- | ------------------ | 279| boolean | Returns whether the attribute exists and can be changed.| 280 281```ts 282let simple = AppStorage.IsMutable('simpleProp') 283``` 284 285### Size 286 287Size(): number 288 289Obtains the number of existing key-value pairs. 290 291**Return value** 292 293| Type | Description | 294| ------ | --------- | 295| number | Returns the number of key-value pairs.| 296 297```ts 298let simple = AppStorage.Size() 299``` 300 301## LocalStorage<sup>9+</sup> 302 303### constructor<sup>9+</sup> 304 305constructor(initializingProperties?: Object) 306 307Creates and initializes a **LocalStorage** object. 308 309**Parameters** 310 311| Name | Type | Mandatory | Description | 312| ---------------------- | ------ | ---- | ---------------------------------------- | 313| initializingProperties | Object | No | All object attributes and their values returned by **object.keys(obj)**.| 314 315```ts 316let storage = new LocalStorage() 317``` 318 319### GetShared<sup>9+</sup> 320 321static GetShared(): LocalStorage 322 323Obtains the **LocalStorage** object being shared. 324 325This API can be used only in the stage model. 326 327**Return value** 328 329| Type | Description | 330| ----------------------------- | ----------------- | 331| [LocalStorage](#localstorage) | **LocalStorage** object.| 332 333```ts 334let storage = LocalStorage.GetShared() 335``` 336 337### has<sup>9+</sup> 338 339has(propName: string): boolean 340 341Checks whether the **LocalStorage** contains the specified attribute. 342 343**Parameters** 344 345| Name | Type | Mandatory | Description | 346| -------- | ------ | ---- | ------- | 347| propName | string | Yes | Key of the attribute.| 348 349**Return value** 350 351| Type | Description | 352| ------- | ------------- | 353| boolean | Returns whether the attribute exists.| 354 355```ts 356let storage = new LocalStorage() 357storage.has('storageSimpleProp') 358``` 359 360### get<sup>9+</sup> 361 362get\<T>(propName: string): T 363 364Obtains the value of the specified key. 365 366**Parameters** 367 368| Name | Type | Mandatory | Description | 369| -------- | ------ | ---- | ----------- | 370| propName | string | Yes | Key of the value to obtain.| 371 372**Return value** 373 374| Type | Description | 375| -------------- | ---------------------------------------- | 376| T \| undefined | Returns the value of the specified key if it exists; returns **undefined** otherwise.| 377 378```ts 379let storage = new LocalStorage() 380let simpleValue = storage.get('storageSimpleProp') 381``` 382 383### set<sup>9+</sup> 384 385set\<T>(propName: string, newValue: T): boolean 386 387Sets a new value for the specified key. 388 389**Parameters** 390 391| Name | Type | Mandatory | Description | 392| -------- | ------ | ---- | ----------- | 393| propName | string | Yes | Key to set. | 394| newValue | T | Yes | Value to set.| 395 396**Return value** 397 398| Type | Description | 399| ------- | ----------------------------------- | 400| boolean | Returns **true** and the value if the key exists; returns **false** otherwise.| 401 402```ts 403let storage = new LocalStorage() 404storage.set('storageSimpleProp', 121) 405``` 406 407### setOrCreate<sup>9+</sup> 408 409setOrCreate\<T>(propName: string, newValue: T): boolean 410 411Creates or updates the value of the specified key. 412 413**Parameters** 414 415| Name | Type | Mandatory | Description | 416| -------- | ------ | :--- | -------------- | 417| propName | string | Yes | Key of the value to create or update. | 418| newValue | T | Yes | Value to be updated or created.| 419 420**Return value** 421 422| Type | Description | 423| ------- | ---------------------------------------- | 424| boolean | Updates the value of the attribute and returns **true** if an attribute that has the same name as the specified key exists; creates an attribute with the specified value as its default value and returns false otherwise. **undefined** and **null** are not allowed.| 425 426```ts 427let storage = new LocalStorage() 428storage.setOrCreate('storageSimpleProp', 121) 429``` 430 431### link<sup>9+</sup> 432 433link\<T>(propName: string): T 434 435Establishes two-way data binding between an attribute and this **LocalStorage** instance. 436 437**Parameters** 438 439| Name | Type | Mandatory | Description | 440| -------- | ------ | ---- | ----------- | 441| propName | string | Yes | Name of the target attribute.| 442 443**Return value** 444 445| Type | Description | 446| ---- | ---------------------------------------- | 447| T | Returns two-way binding to this attribute if there is data with a given key. This means that attribute changes made by a variable or component will be synchronized to the **LocalStorage**, and attribute changes made through the **LocalStorage** will be synchronized to the variable or component. returns **undefined** if the attribute with the given key does not exist.| 448 449```ts 450let storage = new LocalStorage() 451let localStorage = storage.link('storageSimpleProp') 452``` 453 454### setAndLink<sup>9+</sup> 455 456setAndLink\<T>(propName: string, defaultValue: T): T 457 458Works in a way similar to the **Link** API. 459 460**Parameters** 461 462| Name | Type | Mandatory | Description | 463| ------------ | ------ | ---- | ----------- | 464| propName | string | Yes | Target key.| 465| defaultValue | T | Yes | Default value to set. | 466 467**Return value** 468 469| Type | Description | 470| ----- | ---------------------------------------- | 471| @Link | Returns the value corresponding to the key if the current key is stored in the **LocalStorage**; creates and returns a **Link** instance corresponding to the default value if the key has not been created.| 472 473```ts 474let storage = new LocalStorage() 475let localStorage = storage.setAndLink('storageSimpleProp', 121) 476``` 477 478### prop<sup>9+</sup> 479 480prop\<T>(propName: string): T 481 482Establishes one-way data binding with an attribute to update its status. 483 484**Parameters** 485 486| Name | Type | Mandatory | Description | 487| -------- | ------ | ---- | ------------- | 488| propName | string | Yes | Key of the attribute.| 489 490**Return value** 491 492| Type | Description | 493| ----- | ---------------------------------------- | 494| @Prop | Returns one-way binding to an attribute with a given key if the attribute exists; returns **undefined** otherwise. One-way binding means that attribute changes made through the **LocalStorage** will be synchronized to the variable or component, but attribute changes made by the variable or component will not be synchronized to the **LocalStorage**. This API returns immutable variables and is applicable to mutable and immutable state variables alike. | 495 496```ts 497let storage = new LocalStorage() 498let localStorage = storage.prop('storageSimpleProp') 499``` 500 501### setAndProp<sup>9+</sup> 502 503setAndProp\<T>(propName: string, defaultValue: T): T 504 505Works in a way similar to the **Prop** API. 506 507**Parameters** 508 509| Name | Type | Mandatory | Description | 510| ------------ | ------ | ---- | -------------- | 511| propName | string | Yes | Key of the target key-value pair.| 512| defaultValue | T | Yes | Default value to set. | 513 514**Return value** 515 516| Type | Description | 517| ----- | ---------------------------------------- | 518| @Prop | Returns the value corresponding to the given key if the key is stored in the **LocalStorage**; creates and returns a **Prop** instance corresponding to the default value if the key has not been created.| 519 520```ts 521let storage = new LocalStorage() 522let localStorage = storage.setAndProp('storageSimpleProp', 121) 523``` 524 525### delete<sup>9+</sup> 526 527delete(propName: string): boolean 528 529Deletes the key-value pair that matches the specified key. 530 531**Parameters** 532 533| Name | Type | Mandatory | Description | 534| -------- | ------ | :--- | ------------ | 535| propName | string | Yes | Key of the target key-value pair.| 536 537**Return value** 538 539| Type | Description | 540| ------- | ---------------------------------------- | 541| boolean | Returns **true** if the key-value pair exists and is successfully deleted; returns **false** otherwise.| 542 543```ts 544let storage = new LocalStorage() 545storage.delete('storageSimpleProp') 546``` 547 548### keys<sup>9+</sup> 549 550keys(): IterableIterator\<string> 551 552Searches for all keys. 553 554**Return value** 555 556| Type | Description | 557| -------------- | ------------------- | 558| array\<string> | Returns an array of strings containing all keys that are not serializable.| 559 560```ts 561let storage = new LocalStorage() 562let simple = storage.keys() 563``` 564 565### size<sup>9+</sup> 566 567size(): number 568 569Obtains the number of existing key-value pairs. 570 571**Return value** 572 573| Type | Description | 574| ------ | --------- | 575| number | Returns the number of key-value pairs.| 576 577```ts 578let storage = new LocalStorage() 579let simple = storage.size() 580``` 581 582### Clear<sup>9+</sup> 583 584clear(): boolean 585 586Deletes all attributes. 587 588**Return value** 589 590| Type | Description | 591| ------- | --------------------------------- | 592| boolean | Returns **true** if all attributes are deleted; returns **false** if any of the attributes is being referenced by a state variable.| 593 594```ts 595let storage = new LocalStorage() 596let simple = storage.clear() 597``` 598 599## PersistentStorage 600 601### constructor 602 603constructor(appStorage: AppStorage, storage: Storage) 604 605Creates a **persistentstorage** object. 606 607**Parameters** 608 609| Name | Type | Mandatory | Description | 610| ---------- | ---------- | ---- | ---------------- | 611| appStorage | AppStorage | Yes | Singleton object that saves all attributes and attribute values.| 612| storage | Storage | Yes | **Storage** object. | 613 614```ts 615let persistentstorage = new PersistentStorage(AppStorage,Storage) 616``` 617 618### PersistProp 619 620PersistProp(key:string,defaultValue:T): void 621 622Changes the attribute that matches the specified key to persistent data in the **AppStorage**. 623 624**Parameters** 625 626| Name | Type | Mandatory | Description | 627| ------------ | ------ | ---- | -------------- | 628| key | string | Yes | Key of the target attribute. | 629| defaultValue | T | Yes | Value of the target attribute.| 630 631```ts 632PersistentStorage.PersistProp('highScore', '0') 633``` 634 635### DeleteProp 636 637DeleteProp(key: string): void 638 639Cancels two-way binding. The value of this attribute will be deleted from the persistent storage. 640 641**Parameters** 642 643| Name | Type | Mandatory | Description | 644| ---- | ------ | ---- | ------------ | 645| key | string | Yes | Key of the target attribute.| 646 647```ts 648PersistentStorage.DeleteProp('highScore') 649``` 650 651### PersistProps 652 653PersistProps(properties: {key: string, defaultValue: any}[]): void 654 655Changes the attributes that match the specified keys to persistent data in the **AppStorage**. 656 657**Parameters** 658 659| Name | Type | Mandatory | Description | 660| ---- | ---------------------------------- | ---- | --------- | 661| key | {key: string, defaultValue: any}[] | Yes | Keys of the target attributes.| 662 663```ts 664PersistentStorage.PersistProps([{key: 'highScore', defaultValue: '0'},{key: 'wightScore',defaultValue: '1'}]) 665``` 666 667### Keys 668 669Keys(): Array\<string> 670 671Returns the flags of all persistent attributes. 672 673**Return value** 674 675| Type | Description | 676| -------------- | ------------- | 677| Array\<string> | Returns the flags of all persistent attributes.| 678 679```ts 680let simple = PersistentStorage.Keys() 681``` 682 683> **NOTE** 684> 685> - When using **PersistProp**, ensure that the input key exists in the **AppStorage**. 686> 687> - **DeleteProp** takes effect only for the data that has been linked during the current startup. 688 689## Environment 690 691### constructor 692 693Creates an **Environment** object. 694 695```ts 696let simple = new Environment() 697``` 698 699### EnvProp 700 701EnvProp\<S>(key: string, value: S): boolean 702 703Binds this system attribute to the **AppStorage**. You are advised to use this API during application startup. If the attribute already exists in the **AppStorage**, **false** is returned. Do not use the variables in the **AppStorage**. Instead, call this API to bind environment variables. 704 705**Parameters** 706 707| Name | Type | Mandatory | Description | Description | 708| ----- | ------ | ---- | ---------- | ------------------------- | 709| key | string | Yes | Key of the target attribute. | For details, see **Built-in environment variables**.| 710| value | S | Yes | Value of the target attribute.| Value of the target attribute. | 711 712**Return value** 713 714| Type | Description | 715| ------- | ---------------------- | 716| boolean | Returns whether the attribute exists in the **AppStorage**.| 717 718**Built-in environment variables** 719 720| key | Type | Description | 721| -------------------- | --------------- | ---------------------------------------- | 722| accessibilityEnabled | string | Whether to enable accessibility. | 723| colorMode | ColorMode | Color mode. The options are as follows:<br>- **ColorMode.LIGHT**: light mode.<br>- **ColorMode.DARK**: dark mode.| 724| fontScale | number | Font scale. | 725| fontWeightScale | number | Font weight scale. | 726| layoutDirection | LayoutDirection | Layout direction. The options are as follows:<br>- **LayoutDirection.LTR**: The direction is from left to right.<br>- **LayoutDirection.RTL**: The direction is from right to left.| 727| languageCode | string | Current system language. The value is in lowercase, for example, **zh**. | 728 729```ts 730Environment.EnvProp('accessibilityEnabled', 'default') 731``` 732 733### EnvProps 734 735EnvProps(props: {key: string, defaultValue: any}[]): void 736 737Associates this system item array with the **AppStorage**. 738 739**Parameters** 740 741| Name | Type | Mandatory | Description | Description | 742| ---- | ---------------------------------- | ---- | --------- | --------- | 743| key | {key: string, defaultValue: any}[] | Yes | Keys of the target attributes.| Keys of the target attributes.| 744 745```ts 746Environment.EnvProps([{key: 'accessibilityEnabled', defaultValue: 'default'},{key: 'accessibilityUnEnabled', defaultValue: 'undefault'}]) 747``` 748 749### Keys 750 751Keys(): Array\<string> 752 753Returns an array of associated system attributes. 754 755**Return value** 756 757| Type | Description | 758| -------------- | ----------- | 759| Array\<string> | Returns an array of associated system attributes.| 760 761```ts 762let simple = Environment.Keys() 763``` 764