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 12T and S in this topic represent the types as described below. 13 14 15| Type | Description | 16| ---- | -------------------------------------- | 17| T | Class, number, boolean, string, and arrays of these types.| 18| S | number, boolean, string. | 19 20 21## AppStorage 22 23For details about how to use AppStorage, see [AppStorage: Storing Application-wide UI State](../../../quick-start/arkts-appstorage.md). 24 25**Atomic service API**: This API can be used in atomic services since API version 11. 26 27**System capability**: SystemCapability.ArkUI.ArkUI.Full 28 29### ref<sup>12+</sup> 30 31static ref\<T\>(propName: string): AbstractProperty\<T\> | undefined 32 33Returns a reference to the data corresponding to **propName** in [AppStorage](../../../quick-start/arkts-appstorage.md). If the provided **propName** does not exist, this API returns **undefined**. 34 35This API is similar to [link](#link10) but does not require manually releasing the returned variable of the [AbstractProperty](#abstractproperty) type. 36 37**Atomic service API**: This API can be used in atomic services since API version 12. 38 39**System capability**: SystemCapability.ArkUI.ArkUI.Full 40 41**Parameters** 42 43| Name | Type | Mandatory| Description | 44| -------- | ------ | ---- | ---------------------- | 45| propName | string | Yes | Property name in AppStorage.| 46 47**Return value** 48 49| Type | Description | 50| -------------------------------------- | ------------------------------------------------------------ | 51| [AbstractProperty<T>](#abstractproperty) \| undefined | A reference to the property in AppStorage, or **undefined** if the property does not exist.| 52 53**Example** 54 55```ts 56AppStorage.setOrCreate('PropA', 47); 57let refToPropA1: AbstractProperty<number> | undefined = AppStorage.ref('PropA'); 58let refToPropA2: AbstractProperty<number> | undefined = AppStorage.ref('PropA'); // refToPropA2.get() == 47 59refToPropA1?.set(48); // Synchronously updates AppStorage: refToPropA1.get() == refToPropA2.get() == 48. 60``` 61 62### setAndRef<sup>12+</sup> 63 64static setAndRef<T>(propName: string, defaultValue: T): AbstractProperty<T> 65 66Similar to the [ref](#ref12) API, returns a reference to the data corresponding to **propName** in [AppStorage](../../../quick-start/arkts-appstorage.md). If **propName** does not exist, this API creates and initializes the property in AppStorage using **defaultValue** and returns its reference. **defaultValue** must be of the **T** type and can be **null** or **undefined**. 67 68This API is similar to [setAndLink](#setandlink10) but does not require manually releasing the returned variable of the [AbstractProperty](#abstractproperty) type. 69 70> **NOTE** 71> 72> Since API version 12, AppStorage supports [Map](../../../quick-start/arkts-appstorage.md#decorating-variables-of-the-map-type), [Set](../../../quick-start/arkts-appstorage.md#decorating-variables-of-the-set-type), [Date](../../../quick-start/arkts-appstorage.md#decorating-variables-of-the-date-type), **null**, **undefined**, and [union](../../../quick-start/arkts-appstorage.md#union-type) types. 73 74**Atomic service API**: This API can be used in atomic services since API version 12. 75 76**System capability**: SystemCapability.ArkUI.ArkUI.Full 77 78**Parameters** 79 80| Name | Type | Mandatory| Description | 81| ------------ | ------ | ---- | ------------------------------------------------------------ | 82| propName | string | Yes | Property name in AppStorage. | 83| defaultValue | T | Yes | Default value used to initialize **propName** in AppStorage if it does not exist. The value can be **null** or **undefined**.| 84 85**Return value** 86 87| Type | Description | 88| ------------------------- | ------------------------------------------------------------ | 89| [AbstractProperty<T>](#abstractproperty) | Instance of **AbstractProperty<T>**, which is a reference to the property in AppStorage corresponding to **propName**.| 90 91**Example** 92 93```ts 94AppStorage.setOrCreate('PropA', 47); 95let ref1: AbstractProperty<number> = AppStorage.setAndRef('PropB', 49); // Create PropB 49 96let ref2: AbstractProperty<number> = AppStorage.setAndRef('PropA', 50); // PropA exists, remains 47 97``` 98 99 100### link<sup>10+</sup> 101 102static link<T>(propName: string): SubscribedAbstractProperty<T> 103 104Establishes a two-way data binding with the property corresponding to **propName** in [AppStorage](../../../quick-start/arkts-appstorage.md). If the given property exists in AppStorage, the two-way bound data of the property in AppStorage is returned. 105 106Any update of the data is synchronized back to AppStorage, which then synchronizes the update to all data and custom components bound to the property. 107 108If the given property does not exist in AppStorage, **undefined** is returned. 109 110**Atomic service API**: This API can be used in atomic services since API version 11. 111 112**System capability**: SystemCapability.ArkUI.ArkUI.Full 113 114**Parameters** 115 116| Name | Type | Mandatory | Description | 117| -------- | ------ | ---- | ---------------- | 118| propName | string | Yes | Property name in AppStorage.| 119 120**Return value** 121 122| Type | Description | 123| ----------------------------------- | ------------------------------------------------------------ | 124| [SubscribedAbstractProperty<T>](#subscribedabstractproperty) | Two-way bound data of the specified property in AppStorage, or **undefined** if the property does not exist.| 125 126**Example** 127```ts 128AppStorage.setOrCreate('PropA', 47); 129let linkToPropA1: SubscribedAbstractProperty<number> = AppStorage.link('PropA'); 130let linkToPropA2: SubscribedAbstractProperty<number> = AppStorage.link('PropA'); // linkToPropA2.get() == 47 131linkToPropA1.set(48); // Two-way synchronization: linkToPropA1.get() == linkToPropA2.get() == 48 132``` 133 134 135### setAndLink<sup>10+</sup> 136 137static setAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T> 138 139Similar to the [link](#link10) API, establishes a two-way data binding with the property corresponding to **propName** in [AppStorage](../../../quick-start/arkts-appstorage.md). If the given property exists in AppStorage, this API returns the two-way bound data for the property. If the given property does not exist, this API creates and initializes the property in AppStorage using **defaultValue** and returns its two-way bound data. The value of **defaultValue** must be of the **T** type. Since API version 12, it can be **null** or **undefined**. 140 141> **NOTE** 142> 143> Since API version 12, AppStorage supports [Map](../../../quick-start/arkts-appstorage.md#decorating-variables-of-the-map-type), [Set](../../../quick-start/arkts-appstorage.md#decorating-variables-of-the-set-type), [Date](../../../quick-start/arkts-appstorage.md#decorating-variables-of-the-date-type), **null**, **undefined**, and [union](../../../quick-start/arkts-appstorage.md#union-type) types. 144 145**Atomic service API**: This API can be used in atomic services since API version 11. 146 147**System capability**: SystemCapability.ArkUI.ArkUI.Full 148 149**Parameters** 150 151| Name | Type | Mandatory| Description | 152| ------------ | ------ | ---- | ------------------------------------------------------------ | 153| propName | string | Yes | Property name in AppStorage. | 154| defaultValue | T | Yes | Default value used to initialize **propName** in AppStorage if it does not exist. Since API version 12, **defaultValue** can be **null** or **undefined**.| 155 156**Return value** 157 158| Type | Description | 159| ----------------------------------- | ---------------------------------------- | 160| [SubscribedAbstractProperty<T>](#subscribedabstractproperty) | Instance of **SubscribedAbstractProperty<T>** and two-way bound data of the given property in AppStorage.| 161 162**Example** 163```ts 164AppStorage.setOrCreate('PropA', 47); 165let link1: SubscribedAbstractProperty<number> = AppStorage.setAndLink('PropB', 49); // Create PropB 49 166let link2: SubscribedAbstractProperty<number> = AppStorage.setAndLink('PropA', 50); // PropA exists, remains 47 167``` 168 169 170### prop<sup>10+</sup> 171 172static prop<T>(propName: string): SubscribedAbstractProperty<T> 173 174Establishes a one-way data binding with the property corresponding to **propName** in [AppStorage](../../../quick-start/arkts-appstorage.md). If the given property exists in AppStorage, the one-way bound data of the property in AppStorage is returned. If the given property does not exist in AppStorage, **undefined** is returned. Updates of the one-way bound data are not synchronized back to AppStorage. 175 176**Atomic service API**: This API can be used in atomic services since API version 11. 177 178**System capability**: SystemCapability.ArkUI.ArkUI.Full 179 180**Parameters** 181 182| Name | Type | Mandatory | Description | 183| -------- | ------ | ---- | ---------------- | 184| propName | string | Yes | Property name in AppStorage.| 185 186**Return value** 187 188| Type | Description | 189| ----------------------------------- | ------------------------------------------------------------ | 190| [SubscribedAbstractProperty<T>](#subscribedabstractproperty) | One-way bound data of the specified property in AppStorage, or **undefined** if the property does not exist.| 191 192**Example** 193 194```ts 195AppStorage.setOrCreate('PropA', 47); 196let prop1: SubscribedAbstractProperty<number> = AppStorage.prop('PropA'); 197let prop2: SubscribedAbstractProperty<number> = AppStorage.prop('PropA'); 198prop1.set(1); // one-way sync: prop1.get()=1; but prop2.get() == 47 199``` 200 201 202### setAndProp<sup>10+</sup> 203 204static setAndProp<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T> 205 206Similar to the [prop](#prop10) API, establishes a one-way data binding with the property corresponding to **propName** in [AppStorage](../../../quick-start/arkts-appstorage.md). If the given property exists in AppStorage, this API returns the one-way bound data for the property. If the given property does not exist, this API creates and initializes the property in AppStorage using **defaultValue** and returns its one-way bound data. The value of **defaultValue** must be of the **T** type. Since API version 12, it can be **null** or **undefined**. 207 208> **NOTE** 209> 210> Since API version 12, AppStorage supports [Map](../../../quick-start/arkts-appstorage.md#decorating-variables-of-the-map-type), [Set](../../../quick-start/arkts-appstorage.md#decorating-variables-of-the-set-type), [Date](../../../quick-start/arkts-appstorage.md#decorating-variables-of-the-date-type), **null**, **undefined**, and [union](../../../quick-start/arkts-appstorage.md#union-type) types. 211 212**Atomic service API**: This API can be used in atomic services since API version 11. 213 214**System capability**: SystemCapability.ArkUI.ArkUI.Full 215 216**Parameters** 217 218| Name | Type | Mandatory| Description | 219| ------------ | ------ | ---- | ------------------------------------------------------------ | 220| propName | string | Yes | Property name in AppStorage. | 221| defaultValue | T | Yes | Default value used to initialize **propName** in AppStorage if it does not exist. Since API version 12, **defaultValue** can be **null** or **undefined**.| 222 223**Return value** 224 225| Type | Description | 226| ----------------------------------- | --------------------------------------- | 227| [SubscribedAbstractProperty<T>](#subscribedabstractproperty) | Instance of **SubscribedAbstractProperty<T>**.| 228 229**Example** 230```ts 231AppStorage.setOrCreate('PropA', 47); 232let prop: SubscribedAbstractProperty<number> = AppStorage.setAndProp('PropB', 49); // PropA -> 47, PropB -> 49 233``` 234 235 236### has<sup>10+</sup> 237 238static has(propName: string): boolean 239 240Checks whether the property corresponding to **propName** exists in [AppStorage](../../../quick-start/arkts-appstorage.md). 241 242**Atomic service API**: This API can be used in atomic services since API version 11. 243 244**System capability**: SystemCapability.ArkUI.ArkUI.Full 245 246**Parameters** 247 248| Name | Type | Mandatory | Description | 249| -------- | ------ | ---- | ---------------- | 250| propName | string | Yes | Property name in AppStorage.| 251 252**Return value** 253 254| Type | Description | 255| ------- | ---------------------------------------- | 256| boolean | Returns **true** if the property exists in AppStorage; returns **false** otherwise.| 257 258**Example** 259```ts 260AppStorage.has('simpleProp'); 261``` 262 263 264### get<sup>10+</sup> 265 266static get<T>(propName: string): T | undefined 267 268Obtains the value of the property corresponding to **propName** from [AppStorage](../../../quick-start/arkts-appstorage.md). If the property does not exist, this API returns **undefined**. 269 270**Atomic service API**: This API can be used in atomic services since API version 11. 271 272**System capability**: SystemCapability.ArkUI.ArkUI.Full 273 274**Parameters** 275 276| Name | Type | Mandatory | Description | 277| -------- | ------ | ---- | ---------------- | 278| propName | string | Yes | Property name in AppStorage.| 279 280**Return value** 281 282| Type | Description | 283| ------------------------ | ----------------------------------------------------------- | 284| T \| undefined | Value of the property corresponding to **propName** in AppStorage, or **undefined** if it does not exist.| 285 286**Example** 287```ts 288AppStorage.setOrCreate('PropA', 47); 289let value: number = AppStorage.get('PropA') as number; // 47 290``` 291 292 293### set<sup>10+</sup> 294 295static set<T>(propName: string, newValue: T): boolean 296 297Sets the value of the property corresponding to **propName** in [AppStorage](../../../quick-start/arkts-appstorage.md). If the value of **newValue** is the same as the current value of the property, no assignment is performed, and the state variable does not instruct the UI to update the value of the property. Since API version 12, **newValue** can be **null** or **undefined**. 298 299> **NOTE** 300> 301> Since API version 12, AppStorage supports [Map](../../../quick-start/arkts-appstorage.md#decorating-variables-of-the-map-type), [Set](../../../quick-start/arkts-appstorage.md#decorating-variables-of-the-set-type), [Date](../../../quick-start/arkts-appstorage.md#decorating-variables-of-the-date-type), **null**, **undefined**, and [union](../../../quick-start/arkts-appstorage.md#union-type) types. 302 303**Atomic service API**: This API can be used in atomic services since API version 11. 304 305**System capability**: SystemCapability.ArkUI.ArkUI.Full 306 307**Parameters** 308 309| Name | Type | Mandatory | Description | 310| -------- | ------ | ---- | ---------------------- | 311| propName | string | Yes | Property name in AppStorage. | 312| newValue | T | Yes | Property value. Since API version 12, the value can be **null** or **undefined**.| 313 314**Return value** 315 316| Type | Description | 317| ------- | ------------------------------------------------------------ | 318| boolean | Returns **false** if the property corresponding to **propName** does not exist in AppStorage or if the assignment fails. Returns **true** if the assignment is successful.| 319 320**Example** 321```ts 322AppStorage.setOrCreate('PropA', 48); 323let res: boolean = AppStorage.set('PropA', 47) // true 324let res1: boolean = AppStorage.set('PropB', 47) // false 325``` 326 327 328### setOrCreate<sup>10+</sup> 329 330static setOrCreate<T>(propName: string, newValue: T): void 331 332Sets the value of the property corresponding to **propName** in [AppStorage](../../../quick-start/arkts-appstorage.md) to a new value, if the property exists and the new value is different from the current value. If the new value is the same as the current value of the property, no assignment is performed, and the state variable does not instruct the UI to update the value of the property. 333If the property does not exist, this API creates it with the value of **newValue**. This **setOrCreate** API can create only one AppStorage key-value pair each time. To create multiple key-value pairs, call this API multiple times. Since API version 12, **newValue** can be **null** or **undefined**. 334 335> **NOTE** 336> 337> Since API version 12, AppStorage supports [Map](../../../quick-start/arkts-appstorage.md#decorating-variables-of-the-map-type), [Set](../../../quick-start/arkts-appstorage.md#decorating-variables-of-the-set-type), [Date](../../../quick-start/arkts-appstorage.md#decorating-variables-of-the-date-type), **null**, **undefined**, and [union](../../../quick-start/arkts-appstorage.md#union-type) types. 338 339**Atomic service API**: This API can be used in atomic services since API version 11. 340 341**System capability**: SystemCapability.ArkUI.ArkUI.Full 342 343**Parameters** 344 345| Name | Type | Mandatory | Description | 346| -------- | ------ | ---- | ---------------------- | 347| propName | string | Yes | Property name in AppStorage. | 348| newValue | T | Yes | Property value. Since API version 12, the value can be **null** or **undefined**.| 349 350**Example** 351```ts 352AppStorage.setOrCreate('simpleProp', 121); 353``` 354 355 356### delete<sup>10+</sup> 357 358static delete(propName: string): boolean 359 360Deletes the property corresponding to **propName** from [AppStorage](../../../quick-start/arkts-appstorage.md). 361 362The deletion is only successful if the property has no subscribers. If there is a subscriber, the deletion fails and **false** is returned. If the deletion is successful, **true** is returned. 363 364The property subscribers include the following: 365 3661. Variables decorated by [\@StorageLink](../../../quick-start/arkts-appstorage.md#storagelink) or [\@StorageProp](../../../quick-start/arkts-appstorage.md#storageprop) 367 3682. Instances of [SubscribedAbstractProperty](#subscribedabstractproperty) returned by [link](#link10), [prop](#prop10), [setAndLink](#setandlink10), or [setAndProp](#setandprop10) 369 370To delete these subscribers: 371 3721. Remove the custom component containing @StorageLink or @StorageProp. For details, see [Custom Component Deletion](../../../quick-start/arkts-page-custom-components-lifecycle.md#custom-component-deletion). 373 3742. Call the [aboutToBeDeleted](#abouttobedeleted10) API on instances of **SubscribedAbstractProperty** returned by **link**, **prop**, **setAndLink**, or **setAndProp**. 375 376**Atomic service API**: This API can be used in atomic services since API version 11. 377 378**System capability**: SystemCapability.ArkUI.ArkUI.Full 379 380**Parameters** 381 382| Name | Type | Mandatory | Description | 383| -------- | ------ | ---- | ---------------- | 384| propName | string | Yes | Property name in AppStorage.| 385 386**Return value** 387 388| Type | Description | 389| ------- | ---------------------------------------- | 390| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 391 392**Example** 393```ts 394AppStorage.setOrCreate('PropA', 47); 395AppStorage.link<number>('PropA'); 396let res: boolean = AppStorage.delete('PropA'); // false, PropA still has a subscriber 397 398AppStorage.setOrCreate('PropB', 48); 399let res1: boolean = AppStorage.delete('PropB'); // true, PropB is deleted from AppStorage successfully 400``` 401 402 403### keys<sup>10+</sup> 404 405static keys(): IterableIterator<string> 406 407Obtains all property names in [AppStorage](../../../quick-start/arkts-appstorage.md). 408 409**Atomic service API**: This API can be used in atomic services since API version 11. 410 411**System capability**: SystemCapability.ArkUI.ArkUI.Full 412 413**Return value** 414 415| Type | Description | 416| ------------------------------ | ------------------ | 417| IterableIterator<string> | All property names in AppStorage.| 418 419**Example** 420```ts 421AppStorage.setOrCreate('PropB', 48); 422let keys: IterableIterator<string> = AppStorage.keys(); 423``` 424 425 426### clear<sup>10+</sup> 427 428static clear(): boolean 429 430Deletes all properties from [AppStorage](../../../quick-start/arkts-appstorage.md). The deletion is only successful if none of the properties in AppStorage have any subscribers. If there are subscribers, this API does not take effect and **false** is returned. If the deletion is successful, **true** is returned. 431 432For details about the subscriber, see [delete](#delete10). 433 434**Atomic service API**: This API can be used in atomic services since API version 11. 435 436**System capability**: SystemCapability.ArkUI.ArkUI.Full 437 438**Return value** 439 440| Type | Description | 441| ------- | ------------------------------------------------------------ | 442| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 443 444**Example** 445```ts 446AppStorage.setOrCreate('PropA', 47); 447let res: boolean = AppStorage.clear(); // true, there are no subscribers 448``` 449 450 451### size<sup>10+</sup> 452 453static size(): number 454 455Obtains the number of properties in [AppStorage](../../../quick-start/arkts-appstorage.md). 456 457**Atomic service API**: This API can be used in atomic services since API version 11. 458 459**System capability**: SystemCapability.ArkUI.ArkUI.Full 460 461**Return value** 462 463| Type | Description | 464| ------ | ------------------- | 465| number | Number of properties in AppStorage.| 466 467**Example** 468```ts 469AppStorage.setOrCreate('PropB', 48); 470let res: number = AppStorage.size(); // 1 471``` 472 473 474### Link<sup>(deprecated)</sup> 475 476static Link(propName: string): any 477 478Establishes a two-way data binding with the property corresponding to **propName** in [AppStorage](../../../quick-start/arkts-appstorage.md). If the given property exists in AppStorage, the two-way bound data of the property in AppStorage is returned. 479 480Any update of the data is synchronized back to AppStorage, which then synchronizes the update to all data and custom components bound to the property. 481 482If the given property does not exist in AppStorage, **undefined** is returned. 483 484> **NOTE** 485> 486> This API is supported since API version 7 and deprecated since API version 10. You are advised to use [link10+](#link10) instead. 487 488**System capability**: SystemCapability.ArkUI.ArkUI.Full 489 490**Parameters** 491 492| Name | Type | Mandatory | Description | 493| -------- | ------ | ---- | ---------------- | 494| propName | string | Yes | Property name in AppStorage.| 495 496**Return value** 497 498| Type | Description | 499| -------------------------------- | ------------------------------------------------------------ | 500| any | Two-way bound data of the specified property in AppStorage, or **undefined** if the property does not exist.| 501 502**Example** 503```ts 504AppStorage.SetOrCreate('PropA', 47); 505let linkToPropA1: SubscribedAbstractProperty<number> = AppStorage.Link('PropA'); 506let linkToPropA2: SubscribedAbstractProperty<number> = AppStorage.Link('PropA'); // linkToPropA2.get() == 47 507linkToPropA1.set(48); // Two-way synchronization: linkToPropA1.get() == linkToPropA2.get() == 48 508``` 509 510### SetAndLink<sup>(deprecated)</sup> 511 512static SetAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T> 513 514Similar to the [Link](#linkdeprecated) API, establishes a two-way data binding with the property corresponding to **propName** in [AppStorage](../../../quick-start/arkts-appstorage.md). If the given property exists in AppStorage, this API returns the two-way bound data for the property. If the given property does not exist, this API creates and initializes the property in AppStorage using **defaultValue** and returns its two-way bound data. The value of **defaultValue** must be of the **T** type and cannot be **null** or **undefined**. 515 516> **NOTE** 517> 518> This API is supported since API version 7 and deprecated since API version 10. You are advised to use [setAndLink10+](#setandlink10) instead. 519 520**System capability**: SystemCapability.ArkUI.ArkUI.Full 521 522**Parameters** 523 524| Name | Type | Mandatory| Description | 525| ------------ | ------ | ---- | ------------------------------------------------------------ | 526| propName | string | Yes | Property name in AppStorage. | 527| defaultValue | T | Yes | Default value used to initialize **propName** in AppStorage if it does not exist. The value cannot be **null** or **undefined**.| 528 529**Return value** 530 531| Type | Description | 532| ----------------------------------- | ---------------------------------------- | 533| [SubscribedAbstractProperty<T>](#subscribedabstractproperty) | Instance of **SubscribedAbstractProperty<T>** and two-way bound data of the given property in AppStorage.| 534 535**Example** 536```ts 537AppStorage.SetOrCreate('PropA', 47); 538let link1: SubscribedAbstractProperty<number> = AppStorage.SetAndLink('PropB', 49); // Create PropB 49 539let link2: SubscribedAbstractProperty<number> = AppStorage.SetAndLink('PropA', 50); // PropA exists, remains 47 540``` 541 542 543### Prop<sup>(deprecated)</sup> 544 545static Prop(propName: string): any 546 547Establishes a one-way data binding with the property corresponding to **propName** in [AppStorage](../../../quick-start/arkts-appstorage.md). If the given property exists in AppStorage, the one-way bound data of the property in AppStorage is returned. If the given property does not exist in AppStorage, **undefined** is returned. Updates of the one-way bound data are not synchronized back to AppStorage. 548 549> **NOTE** 550> 551> **Prop** supports only simple types. 552> 553> This API is supported since API version 7 and deprecated since API version 10. You are advised to use [prop10+](#prop10) instead. 554 555**System capability**: SystemCapability.ArkUI.ArkUI.Full 556 557**Parameters** 558 559| Name | Type | Mandatory | Description | 560| -------- | ------ | ---- | ---------------- | 561| propName | string | Yes | Property name in AppStorage.| 562 563**Return value** 564 565| Type | Description | 566| -------------------------------- | ------------------------------------------------------------ | 567| any | One-way bound data of the specified property in AppStorage, or **undefined** if the property does not exist.| 568 569**Example** 570```ts 571AppStorage.SetOrCreate('PropA', 47); 572let prop1: SubscribedAbstractProperty<number> = AppStorage.Prop('PropA'); 573let prop2: SubscribedAbstractProperty<number> = AppStorage.Prop('PropA'); 574prop1.set(1); // one-way sync: prop1.get()=1; but prop2.get() == 47 575``` 576 577### SetAndProp<sup>(deprecated)</sup> 578 579static SetAndProp<S>(propName: string, defaultValue: S): SubscribedAbstractProperty<S> 580 581Similar to the [Prop](#propdeprecated) API, establishes a one-way data binding with the property corresponding to **propName** in [AppStorage](../../../quick-start/arkts-appstorage.md). If the given property exists in AppStorage, this API returns the one-way bound data for the property. If the given property does not exist, this API creates and initializes the property in AppStorage using **defaultValue** and returns its one-way bound data. The value of **defaultValue** must be of the **S** type and cannot be **null** or **undefined**. 582 583> **NOTE** 584> 585> This API is supported since API version 7 and deprecated since API version 10. You are advised to use [setAndProp10+](#setandprop10) instead. 586 587**System capability**: SystemCapability.ArkUI.ArkUI.Full 588 589**Parameters** 590 591| Name | Type | Mandatory| Description | 592| ------------ | ------ | ---- | ------------------------------------------------------------ | 593| propName | string | Yes | Property name in AppStorage. | 594| defaultValue | S | Yes | Default value used to initialize **propName** in AppStorage if it does not exist. The value cannot be **null** or **undefined**.| 595 596**Return value** 597 598| Type | Description | 599| ----------------------------------- | --------------------------------------- | 600| [SubscribedAbstractProperty<S>](#subscribedabstractproperty) | Instance of **SubscribedAbstractProperty<S>**.| 601 602**Example** 603```ts 604AppStorage.SetOrCreate('PropA', 47); 605let prop: SubscribedAbstractProperty<number> = AppStorage.SetAndProp('PropB', 49); // PropA -> 47, PropB -> 49 606``` 607 608### Has<sup>(deprecated)</sup> 609 610static Has(propName: string): boolean 611 612Checks whether the property corresponding to **propName** exists in [AppStorage](../../../quick-start/arkts-appstorage.md). 613 614> **NOTE** 615> 616> This API is supported since API version 7 and deprecated since API version 10. You are advised to use [has10+](#has10) instead. 617 618**System capability**: SystemCapability.ArkUI.ArkUI.Full 619 620**Parameters** 621 622| Name | Type | Mandatory | Description | 623| -------- | ------ | ---- | ---------------- | 624| propName | string | Yes | Property name in AppStorage.| 625 626**Return value** 627 628| Type | Description | 629| ------- | ---------------------------------------- | 630| boolean | Returns **true** if the property exists in AppStorage; returns **false** otherwise.| 631 632**Example** 633```ts 634AppStorage.Has('simpleProp'); 635``` 636 637### Get<sup>(deprecated)</sup> 638 639static Get<T>(propName: string): T | undefined 640 641Obtains the value of the property corresponding to **propName** from [AppStorage](../../../quick-start/arkts-appstorage.md). If the property does not exist, this API returns **undefined**. 642 643> **NOTE** 644> 645> This API is supported since API version 7 and deprecated since API version 10. You are advised to use [get10+](#get10) instead. 646 647**System capability**: SystemCapability.ArkUI.ArkUI.Full 648 649**Parameters** 650 651| Name | Type | Mandatory | Description | 652| -------- | ------ | ---- | ---------------- | 653| propName | string | Yes | Property name in AppStorage.| 654 655**Return value** 656 657| Type | Description | 658| ------------------------ | ------------------------------------------------------------ | 659| T \| undefined | Value of the property corresponding to **propName** in AppStorage, or **undefined** if it does not exist.| 660 661**Example** 662```ts 663AppStorage.SetOrCreate('PropA', 47); 664let value: number = AppStorage.Get('PropA') as number; // 47 665``` 666 667### Set<sup>(deprecated)</sup> 668 669static Set<T>(propName: string, newValue: T): boolean 670 671Sets the value of the property corresponding to **propName** in [AppStorage](../../../quick-start/arkts-appstorage.md). 672 673> **NOTE** 674> 675> This API is supported since API version 7 and deprecated since API version 10. You are advised to use [set10+](#set10) instead. 676 677**System capability**: SystemCapability.ArkUI.ArkUI.Full 678 679**Parameters** 680 681| Name | Type | Mandatory| Description | 682| -------- | ------ | ---- | ------------------------------- | 683| propName | string | Yes | Property name in AppStorage. | 684| newValue | T | Yes | Property value, which cannot be **null** or **undefined**.| 685 686**Return value** 687 688| Type | Description | 689| ------- | ------------------------------------------------------------ | 690| boolean | Returns **true** if the operation is successful; returns **false** if the property corresponding to **propName** does not exist in AppStorage, or the value to set is **undefined** or **null**. | 691 692**Example** 693```ts 694AppStorage.SetOrCreate('PropA', 48); 695let res: boolean = AppStorage.Set('PropA', 47) // true 696let res1: boolean = AppStorage.Set('PropB', 47) // false 697``` 698 699### SetOrCreate<sup>(deprecated)</sup> 700 701static SetOrCreate<T>(propName: string, newValue: T): void 702 703Sets the value of the property corresponding to **propName** in [AppStorage](../../../quick-start/arkts-appstorage.md) to a new value, if the property exists. If the property does not exist, this API creates it with the value of **newValue**. 704 705The value of **newValue** cannot be **null** or **undefined**. 706 707> **NOTE** 708> 709> This API is supported since API version 7 and deprecated since API version 10. You are advised to use [setOrCreate10+](#setorcreate10) instead. 710 711**System capability**: SystemCapability.ArkUI.ArkUI.Full 712 713**Parameters** 714 715| Name | Type | Mandatory| Description | 716| -------- | ------ | ---- | ------------------------------- | 717| propName | string | Yes | Property name in AppStorage. | 718| newValue | T | Yes | Property value, which cannot be **null** or **undefined**.| 719 720**Example** 721```ts 722AppStorage.SetOrCreate('simpleProp', 121); 723``` 724 725### Delete<sup>(deprecated)</sup> 726 727static Delete(propName: string): boolean 728 729Deletes the property corresponding to **propName** from [AppStorage](../../../quick-start/arkts-appstorage.md). 730 731The deletion is only successful if the property has no subscribers. If there is a subscriber, the deletion fails and **false** is returned. If the deletion is successful, **true** is returned. 732 733Subscribers include properties bound using [Link](#linkdeprecated) and [Prop](#propdeprecated) APIs, as well as those decorated with [\@StorageLink('propName')](../../../quick-start/arkts-appstorage.md#storagelink) and [\@StorageProp('propName')](../../../quick-start/arkts-appstorage.md#storageprop). This means that if @StorageLink('propName') and @StorageProp('propName') are used in a custom component or if there is still a **SubscribedAbstractProperty** instance in a synchronization relationship with the property, the property cannot be deleted from AppStorage. 734 735> **NOTE** 736> 737> This API is supported since API version 7 and deprecated since API version 10. You are advised to use [delete10+](#delete10) instead. 738 739**System capability**: SystemCapability.ArkUI.ArkUI.Full 740 741**Parameters** 742 743| Name | Type | Mandatory | Description | 744| -------- | ------ | ---- | ---------------- | 745| propName | string | Yes | Property name in AppStorage.| 746 747**Return value** 748 749| Type | Description | 750| ------- | ---------------------------------------- | 751| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 752 753**Example** 754```ts 755AppStorage.SetOrCreate('PropA', 47); 756AppStorage.Link('PropA'); 757let res: boolean = AppStorage.Delete('PropA'); // false, PropA still has a subscriber 758 759AppStorage.SetOrCreate('PropB', 48); 760let res1: boolean = AppStorage.Delete('PropB'); // true, PropB is deleted from AppStorage successfully 761``` 762 763### Keys<sup>(deprecated)</sup> 764 765static Keys(): IterableIterator<string> 766 767Obtains all property names in [AppStorage](../../../quick-start/arkts-appstorage.md). 768 769> **NOTE** 770> 771> This API is supported since API version 7 and deprecated since API version 10. You are advised to use [keys10+](#keys10) instead. 772 773**System capability**: SystemCapability.ArkUI.ArkUI.Full 774 775**Return value** 776 777| Type | Description | 778| ------------------------------ | ------------------ | 779| IterableIterator<string> | All property names in AppStorage.| 780 781**Example** 782```ts 783AppStorage.SetOrCreate('PropB', 48); 784let keys: IterableIterator<string> = AppStorage.Keys(); 785``` 786 787 788### staticClear<sup>(deprecated)</sup> 789 790static staticClear(): boolean 791 792Deletes all properties. 793 794> **NOTE** 795> 796> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [clear10+](#clear10) instead. 797 798**System capability**: SystemCapability.ArkUI.ArkUI.Full 799 800**Return value** 801 802| Type | Description | 803| ------- | --------------------------------- | 804| boolean | Returns **true** if all properties are deleted; returns **false** if any of the properties is being referenced by a state variable.| 805 806**Example** 807```ts 808let simple = AppStorage.staticClear(); 809``` 810 811 812### Clear<sup>(deprecated)</sup> 813 814static Clear(): boolean 815 816Deletes all properties from [AppStorage](../../../quick-start/arkts-appstorage.md). The deletion is only successful if none of the properties in AppStorage have any subscribers. If there are subscribers, this API does not take effect and **false** is returned. If the deletion is successful, **true** is returned. 817 818For details about the subscriber, see [delete](#delete10). 819 820> **NOTE** 821> 822> This API is supported since API version 9 and deprecated since API version 10. You are advised to use [clear10+](#clear10) instead. 823 824**System capability**: SystemCapability.ArkUI.ArkUI.Full 825 826**Return value** 827 828| Type | Description | 829| ------- | ------------------------------------------------------------ | 830| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 831 832**Example** 833```typescript 834AppStorage.SetOrCreate('PropA', 47); 835let res: boolean = AppStorage.Clear(); // true, there are no subscribers 836``` 837 838 839### IsMutable<sup>(deprecated)</sup> 840 841static IsMutable(propName: string): boolean 842 843Checks whether the property corresponding to **propName** in [AppStorage](../../../quick-start/arkts-appstorage.md) is mutable. 844 845> **NOTE** 846> 847> This API is supported since API version 7 and deprecated since API version 10. 848 849**System capability**: SystemCapability.ArkUI.ArkUI.Full 850 851**Parameters** 852 853| Name | Type | Mandatory | Description | 854| -------- | ------ | ---- | ---------------- | 855| propName | string | Yes | Property name in AppStorage.| 856 857**Return value** 858 859| Type | Description | 860| ------- | -------------------------------- | 861| boolean | Whether the property corresponding to **propName** is mutable.| 862 863**Example** 864```ts 865AppStorage.SetOrCreate('PropA', 47); 866let res: boolean = AppStorage.IsMutable('simpleProp'); 867``` 868 869 870### Size<sup>(deprecated)</sup> 871 872static Size(): number 873 874Obtains the number of properties in [AppStorage](../../../quick-start/arkts-appstorage.md). 875 876> **NOTE** 877> 878> This API is supported since API version 7 and deprecated since API version 10. You are advised to use [size10+](#size10) instead. 879 880**System capability**: SystemCapability.ArkUI.ArkUI.Full 881 882**Return value** 883 884| Type | Description | 885| ------ | ------------------- | 886| number | Number of properties in AppStorage.| 887 888**Example** 889```ts 890AppStorage.SetOrCreate('PropB', 48); 891let res: number = AppStorage.Size(); // 1 892``` 893 894 895## LocalStorage<sup>9+</sup> 896 897 898For details about how to use LocalStorage on the UI, see [LocalStorage: UI State Storage](../../../quick-start/arkts-localstorage.md). 899 900**Widget capability**: This API can be used in ArkTS widgets since API version 9. 901 902**Atomic service API**: This API can be used in atomic services since API version 11. 903 904**System capability**: SystemCapability.ArkUI.ArkUI.Full 905 906### constructor<sup>9+</sup> 907 908constructor(initializingProperties?: Object) 909 910Creates a [LocalStorage](../../../quick-start/arkts-localstorage.md) instance and initializes it using the properties and values returned by **Object.keys(initializingProperties)**. 911 912**Widget capability**: This API can be used in ArkTS widgets since API version 9. 913 914**Atomic service API**: This API can be used in atomic services since API version 11. 915 916**System capability**: SystemCapability.ArkUI.ArkUI.Full 917 918**Parameters** 919 920| Name | Type | Mandatory | Description | 921| ---------------------- | ------ | ---- | ---------------------------------------- | 922| initializingProperties | Object | No | Properties and values used to initialize the **LocalStorage** instance. The value cannot be **undefined**.| 923 924**Example** 925```ts 926let para: Record<string, number> = { 'PropA': 47 }; 927let storage: LocalStorage = new LocalStorage(para); 928``` 929 930 931### getShared<sup>10+</sup> 932 933static getShared(): LocalStorage 934 935Obtains the [LocalStorage](../../../quick-start/arkts-localstorage.md) instance shared across the current stage. 936 937**Widget capability**: This API can be used in ArkTS widgets since API version 10. 938 939**Atomic service API**: This API can be used in atomic services since API version 11. 940 941**System capability**: SystemCapability.ArkUI.ArkUI.Full 942 943**Model restriction**: This API can be used only in the stage model. 944 945**Return value** 946 947| Type | Description | 948| ------------------------------ | ----------------- | 949| [LocalStorage](#localstorage9) | **LocalStorage** instance.| 950 951**Example** 952For details about how to use the **getShared** API, see [Example of 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). 953 954 955### has<sup>9+</sup> 956 957has(propName: string): boolean 958 959Checks whether the property corresponding to **propName** exists in [LocalStorage](../../../quick-start/arkts-localstorage.md). 960 961**Widget capability**: This API can be used in ArkTS widgets since API version 9. 962 963**Atomic service API**: This API can be used in atomic services since API version 11. 964 965**System capability**: SystemCapability.ArkUI.ArkUI.Full 966 967**Parameters** 968 969| Name | Type | Mandatory | Description | 970| -------- | ------ | ---- | ------------------ | 971| propName | string | Yes | Property name in LocalStorage.| 972 973**Return value** 974 975| Type | Description | 976| ------- | ------------------------------------------------------------ | 977| boolean | Returns **true** if the property exists in LocalStorage; returns **false** otherwise.| 978 979**Example** 980```ts 981let para: Record<string, number> = { 'PropA': 47 }; 982let storage: LocalStorage = new LocalStorage(para); 983storage.has('PropA'); // true 984``` 985 986 987### get<sup>9+</sup> 988 989get<T>(propName: string): T | undefined 990 991Obtains the value of the property corresponding to **propName** from [LocalStorage](../../../quick-start/arkts-localstorage.md). 992 993**Widget capability**: This API can be used in ArkTS widgets since API version 9. 994 995**Atomic service API**: This API can be used in atomic services since API version 11. 996 997**System capability**: SystemCapability.ArkUI.ArkUI.Full 998 999**Parameters** 1000 1001| Name | Type | Mandatory | Description | 1002| -------- | ------ | ---- | ------------------ | 1003| propName | string | Yes | Property name in LocalStorage.| 1004 1005**Return value** 1006 1007| Type | Description | 1008| ------------------------ | ------------------------------------------------------------ | 1009| T \| undefined | Value of the property corresponding to **propName** in LocalStorage, or **undefined** if it does not exist.| 1010 1011**Example** 1012```ts 1013let para: Record<string, number> = { 'PropA': 47 }; 1014let storage: LocalStorage = new LocalStorage(para); 1015let value: number = storage.get('PropA') as number; // 47 1016``` 1017 1018 1019### set<sup>9+</sup> 1020 1021set<T>(propName: string, newValue: T): boolean 1022 1023Sets the value of the property corresponding to **propName** in [LocalStorage](../../../quick-start/arkts-localstorage.md). If the value of **newValue** is the same as the current value of the property, no assignment is performed, and the state variable does not instruct the UI to update the value of the property. Since API version 12, **newValue** can be **null** or **undefined**. 1024 1025> **NOTE** 1026> 1027> Since API version 12, LocalStorage supports [Map](../../../quick-start/arkts-localstorage.md#decorating-variables-of-the-map-type), [Set](../../../quick-start/arkts-localstorage.md#decorating-variables-of-the-set-type), [Date](../../../quick-start/arkts-localstorage.md#decorating-variables-of-the-date-type), **null**, **undefined**, and [union](../../../quick-start/arkts-localstorage.md#union-type) types. 1028 1029**Widget capability**: This API can be used in ArkTS widgets since API version 9. 1030 1031**Atomic service API**: This API can be used in atomic services since API version 11. 1032 1033**System capability**: SystemCapability.ArkUI.ArkUI.Full 1034 1035**Parameters** 1036 1037| Name | Type | Mandatory | Description | 1038| -------- | ------ | ---- | ----------------------- | 1039| propName | string | Yes | Property name in LocalStorage. | 1040| newValue | T | Yes | Property value. Since API version 12, the value can be **null** or **undefined**.| 1041 1042**Return value** 1043 1044| Type | Description | 1045| ------- | ------------------------------------------------------------ | 1046| boolean | Returns **true** if the operation is successful; returns **false** if the property corresponding to **propName** does not exist in LocalStorage. | 1047 1048**Example** 1049 1050```ts 1051let para: Record<string, number> = { 'PropA': 47 }; 1052let storage: LocalStorage = new LocalStorage(para); 1053let res: boolean = storage.set('PropA', 47); // true 1054let res1: boolean = storage.set('PropB', 47); // false 1055``` 1056 1057 1058### setOrCreate<sup>9+</sup> 1059 1060setOrCreate<T>(propName: string, newValue: T): boolean 1061 1062Sets the value of the property corresponding to **propName** in [LocalStorage](../../../quick-start/arkts-localstorage.md) to a new value, if the property exists and the new value is different from the current value. If the new value is the same as the current value of the property, no assignment is performed, and the state variable does not instruct the UI to update the value of the property. 1063If the property does not exist, this API creates it with the value of **newValue**. This **setOrCreate** method creates only one LocalStorage key-value pair. To create multiple key-value pairs, call this method multiple times. Since API version 12, **newValue** can be **null** or **undefined**. 1064 1065> **NOTE** 1066> 1067> Since API version 12, LocalStorage supports [Map](../../../quick-start/arkts-localstorage.md#decorating-variables-of-the-map-type), [Set](../../../quick-start/arkts-localstorage.md#decorating-variables-of-the-set-type), [Date](../../../quick-start/arkts-localstorage.md#decorating-variables-of-the-date-type), **null**, **undefined**, and [union](../../../quick-start/arkts-localstorage.md#union-type) types. 1068 1069**Widget capability**: This API can be used in ArkTS widgets since API version 9. 1070 1071**Atomic service API**: This API can be used in atomic services since API version 11. 1072 1073**System capability**: SystemCapability.ArkUI.ArkUI.Full 1074 1075**Parameters** 1076 1077| Name | Type | Mandatory | Description | 1078| -------- | ------ | ---- | ----------------------- | 1079| propName | string | Yes | Property name in LocalStorage. | 1080| newValue | T | Yes | Property value. Since API version 12, the value can be **null** or **undefined**.| 1081 1082**Return value** 1083 1084| Type | Description | 1085| ------- | ------------------------------------------------------------ | 1086| boolean | Returns **true** if the property corresponding to **propName** exists and its value is updated to the value of **newValue**,<br>or if **propName** is created with the value of **newValue**.| 1087 1088**Example** 1089 1090```ts 1091let para: Record<string, number> = { 'PropA': 47 }; 1092let storage: LocalStorage = new LocalStorage(para); 1093let res: boolean = storage.setOrCreate('PropA', 121); // true 1094let res1: boolean = storage.setOrCreate('PropB', 111); // true 1095let res2: boolean = storage.setOrCreate('PropB', null); // true (API version 12 and later) or false (API version 11 and earlier) 1096``` 1097 1098### ref<sup>12+</sup> 1099 1100public ref\<T\>(propName: string): AbstractProperty\<T\> | undefined 1101 1102Returns a reference to the data corresponding to **propName** in [LocalStorage](../../../quick-start/arkts-localstorage.md). If the provided **propName** does not exist, this API returns **undefined**. 1103 1104This API is similar to [link](#link9) but does not require manually releasing the returned variable of the [AbstractProperty](#abstractproperty) type. 1105 1106**Atomic service API**: This API can be used in atomic services since API version 12. 1107 1108**System capability**: SystemCapability.ArkUI.ArkUI.Full 1109 1110**Parameters** 1111 1112| Name | Type | Mandatory| Description | 1113| -------- | ------ | ---- | ------------------------ | 1114| propName | string | Yes | Property name in LocalStorage.| 1115 1116**Return value** 1117 1118| Type | Description | 1119| -------------------------------------- | ------------------------------------------------------------ | 1120| [AbstractProperty<T>](#abstractproperty) \| undefined | A reference to the property in LocalStorage, or **undefined** if the property does not exist.| 1121 1122**Example** 1123 1124```ts 1125let para: Record<string, number> = { 'PropA': 47 }; 1126let storage: LocalStorage = new LocalStorage(para); 1127let refToPropA1: AbstractProperty<number> | undefined = storage.ref('PropA'); 1128let refToPropA2: AbstractProperty<number> | undefined = storage.ref('PropA'); // refToPropA2.get() == 47 1129refToPropA1?.set(48); // refToPropA1.get() == refToPropA2.get() == 48 1130``` 1131 1132### setAndRef<sup>12+</sup> 1133 1134public setAndRef<T>(propName: string, defaultValue: T): AbstractProperty<T> 1135 1136Similar to the [ref](#ref12-1) API, returns a reference to the data corresponding to **propName** in [LocalStorage](../../../quick-start/arkts-localstorage.md). If **propName** does not exist, this API creates and initializes the property in LocalStorage using **defaultValue** and returns its reference. **defaultValue** must be of the **T** type and can be **null** or **undefined**. 1137 1138This API is similar to [setAndLink](#setandlink9) but does not require manually releasing the returned variable of the [AbstractProperty](#abstractproperty) type. 1139 1140> **NOTE** 1141> 1142> Since API version 12, LocalStorage supports [Map](../../../quick-start/arkts-localstorage.md#decorating-variables-of-the-map-type), [Set](../../../quick-start/arkts-localstorage.md#decorating-variables-of-the-set-type), [Date](../../../quick-start/arkts-localstorage.md#decorating-variables-of-the-date-type), **null**, **undefined**, and [union](../../../quick-start/arkts-localstorage.md#union-type) types. 1143 1144**Atomic service API**: This API can be used in atomic services since API version 12. 1145 1146**System capability**: SystemCapability.ArkUI.ArkUI.Full 1147 1148**Parameters** 1149 1150| Name | Type | Mandatory| Description | 1151| ------------ | ------ | ---- | ------------------------------------------------------------ | 1152| propName | string | Yes | Property name in LocalStorage. | 1153| defaultValue | T | Yes | Default value used to initialize **propName** in LocalStorage if it does not exist. The value can be **null** or **undefined**.| 1154 1155**Return value** 1156 1157| Type | Description | 1158| ------------------------- | ------------------------------------------------------------ | 1159| [AbstractProperty<T>](#abstractproperty) | Instance of **AbstractProperty<T>**, which is a reference to the property in LocalStorage corresponding to **propName**.| 1160 1161**Example** 1162 1163```ts 1164let para: Record<string, number> = { 'PropA': 47 }; 1165let storage: LocalStorage = new LocalStorage(para); 1166let ref1: AbstractProperty<number> = storage.setAndRef('PropB', 49); // Create PropB 49 1167let ref2: AbstractProperty<number> = storage.setAndRef('PropA', 50); // PropA exists, remains 47 1168``` 1169 1170### link<sup>9+</sup> 1171 1172link<T>(propName: string): SubscribedAbstractProperty<T> 1173 1174Establishes a two-way data binding with the property corresponding to **propName** in [LocalStorage](../../../quick-start/arkts-localstorage.md). If the given property exists in LocalStorage, this API returns the two-way bound data for the property. 1175 1176Any update of the data is synchronized back to LocalStorage, which then synchronizes the update to all data and custom components bound to the property. 1177 1178If the given property does not exist in LocalStorage, **undefined** is returned. 1179 1180**Widget capability**: This API can be used in ArkTS widgets since API version 9. 1181 1182**Atomic service API**: This API can be used in atomic services since API version 11. 1183 1184**System capability**: SystemCapability.ArkUI.ArkUI.Full 1185 1186**Parameters** 1187 1188| Name | Type | Mandatory | Description | 1189| -------- | ------ | ---- | ------------------ | 1190| propName | string | Yes | Property name in LocalStorage.| 1191 1192**Return value** 1193 1194| Type | Description | 1195| ----------------------------------- | ------------------------------------------------------------ | 1196| [SubscribedAbstractProperty<T>](#subscribedabstractproperty) | Returns the **SubscribedAbstractProperty<T>** instance if the given property exists in LocalStorage; returns undefined otherwise.| 1197 1198**Example** 1199```ts 1200let para: Record<string, number> = { 'PropA': 47 }; 1201let storage: LocalStorage = new LocalStorage(para); 1202let linkToPropA1: SubscribedAbstractProperty<number> = storage.link('PropA'); 1203let linkToPropA2: SubscribedAbstractProperty<number> = storage.link('PropA'); // linkToPropA2.get() == 47 1204linkToPropA1.set(48); // Two-way synchronization: linkToPropA1.get() == linkToPropA2.get() == 48 1205``` 1206 1207 1208### setAndLink<sup>9+</sup> 1209 1210setAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T> 1211 1212Similar to the [link](#link9) API, establishes a two-way data binding with the property corresponding to **propName** in [LocalStorage](../../../quick-start/arkts-localstorage.md). If the given property exists in LocalStorage, this API returns the two-way bound data for the property. If the given property does not exist, this API creates and initializes the property in LocalStorage using **defaultValue** and returns its two-way bound data. The value of **defaultValue** must be of the **T** type. Since API version 12, it can be **null** or **undefined**. 1213 1214> **NOTE** 1215> 1216> Since API version 12, LocalStorage supports [Map](../../../quick-start/arkts-localstorage.md#decorating-variables-of-the-map-type), [Set](../../../quick-start/arkts-localstorage.md#decorating-variables-of-the-set-type), [Date](../../../quick-start/arkts-localstorage.md#decorating-variables-of-the-date-type), **null**, **undefined**, and [union](../../../quick-start/arkts-localstorage.md#union-type) types. 1217 1218**Widget capability**: This API can be used in ArkTS widgets since API version 9. 1219 1220**Atomic service API**: This API can be used in atomic services since API version 11. 1221 1222**System capability**: SystemCapability.ArkUI.ArkUI.Full 1223 1224**Parameters** 1225 1226| Name | Type | Mandatory| Description | 1227| ------------ | ------ | ---- | ------------------------------------------------------------ | 1228| propName | string | Yes | Property name in LocalStorage. | 1229| defaultValue | T | Yes | Default value used to initialize **propName** in LocalStorage if it does not exist. Since API version 12, **defaultValue** can be **null** or **undefined**.| 1230 1231**Return value** 1232 1233| Type | Description | 1234| ----------------------------------- | ------------------------------------------------------------ | 1235| [SubscribedAbstractProperty<T>](#subscribedabstractproperty) | Instance of **SubscribedAbstractProperty<T>** and two-way bound data of the given property in LocalStorage.| 1236 1237**Example** 1238```ts 1239let para: Record<string, number> = { 'PropA': 47 }; 1240let storage: LocalStorage = new LocalStorage(para); 1241let link1: SubscribedAbstractProperty<number> = storage.setAndLink('PropB', 49); // Create PropB 49 1242let link2: SubscribedAbstractProperty<number> = storage.setAndLink('PropA', 50); // PropA exists, remains 47 1243``` 1244 1245 1246### prop<sup>9+</sup> 1247 1248prop<S>(propName: string): SubscribedAbstractProperty<S> 1249 1250Establishes a one-way data binding with the property corresponding to **propName** in [LocalStorage](../../../quick-start/arkts-localstorage.md). If the given property exists in LocalStorage, this API returns the two-way bound data for the property. If the given property does not exist in LocalStorage, **undefined** is returned. Updates of the one-way bound data are not synchronized back to LocalStorage. 1251 1252**Widget capability**: This API can be used in ArkTS widgets since API version 9. 1253 1254**Atomic service API**: This API can be used in atomic services since API version 11. 1255 1256**System capability**: SystemCapability.ArkUI.ArkUI.Full 1257 1258**Parameters** 1259 1260| Name | Type | Mandatory | Description | 1261| -------- | ------ | ---- | ------------------ | 1262| propName | string | Yes | Property name in LocalStorage.| 1263 1264**Return value** 1265 1266| Type | Description | 1267| ----------------------------------- | ------------------------------------------------------------ | 1268| [SubscribedAbstractProperty<S>](#subscribedabstractproperty) | Instance of **SubscribedAbstractProperty<S>** and one-way bound data of the given property in LocalStorage, or **undefined** if the provided **propName** does not exist in LocalStorage.| 1269 1270**Example** 1271```ts 1272let para: Record<string, number> = { 'PropA': 47 }; 1273let storage: LocalStorage = new LocalStorage(para); 1274let prop1: SubscribedAbstractProperty<number> = storage.prop('PropA'); 1275let prop2: SubscribedAbstractProperty<number> = storage.prop('PropA'); 1276prop1.set(1); // one-way sync: prop1.get()=1; but prop2.get() == 47 1277``` 1278 1279 1280### setAndProp<sup>9+</sup> 1281 1282setAndProp<S>(propName: string, defaultValue: S): SubscribedAbstractProperty<S> 1283 1284Similar to the [prop](#prop9) API, establishes a one-way data binding with the property corresponding to **propName** in [LocalStorage](../../../quick-start/arkts-localstorage.md). If the given property exists in LocalStorage, this API returns the one-way bound data for the property. If the given property does not exist, this API creates and initializes the property in LocalStorage using **defaultValue** and returns its one-way bound data. The value of **defaultValue** must be of the **S** type. Since API version 12, it can be **null** or **undefined**. 1285 1286> **NOTE** 1287> 1288> Since API version 12, LocalStorage supports [Map](../../../quick-start/arkts-localstorage.md#decorating-variables-of-the-map-type), [Set](../../../quick-start/arkts-localstorage.md#decorating-variables-of-the-set-type), [Date](../../../quick-start/arkts-localstorage.md#decorating-variables-of-the-date-type), **null**, **undefined**, and [union](../../../quick-start/arkts-localstorage.md#union-type) types. 1289 1290**Widget capability**: This API can be used in ArkTS widgets since API version 9. 1291 1292**Atomic service API**: This API can be used in atomic services since API version 11. 1293 1294**System capability**: SystemCapability.ArkUI.ArkUI.Full 1295 1296**Parameters** 1297 1298| Name | Type | Mandatory| Description | 1299| ------------ | ------ | ---- | ------------------------------------------------------------ | 1300| propName | string | Yes | Property name in LocalStorage. | 1301| defaultValue | S | Yes | Default value used to initialize **propName** in LocalStorage if it does not exist. Since API version 12, **defaultValue** can be **null** or **undefined**.| 1302 1303**Return value** 1304 1305| Type | Description | 1306| ----------------------------------- | ------------------------------------------------------------ | 1307| [SubscribedAbstractProperty<S>](#subscribedabstractproperty) | Instance of **SubscribedAbstractProperty<S>** and one-way bound data of the given property in LocalStorage.| 1308 1309**Example** 1310 1311```ts 1312let para: Record<string, number> = { 'PropA': 47 }; 1313let storage: LocalStorage = new LocalStorage(para); 1314let prop: SubscribedAbstractProperty<number> = storage.setAndProp('PropB', 49); // PropA -> 47, PropB -> 49 1315``` 1316 1317 1318### delete<sup>9+</sup> 1319 1320delete(propName: string): boolean 1321 1322Deletes the property corresponding to **propName** from [LocalStorage](../../../quick-start/arkts-localstorage.md). The deletion is only successful if the property has no subscribers. If there is a subscriber, the deletion fails and **false** is returned. If the deletion is successful, **true** is returned. 1323 1324The property subscribers include the following: 1325 13261. Variables decorated by [\@LocalStorageLink](../../../quick-start/arkts-localstorage.md#localstoragelink) or [\@LocalStorageProp](../../../quick-start/arkts-localstorage.md#localstorageprop) 1327 13282. Instances of [SubscribedAbstractProperty](#subscribedabstractproperty) returned by [link](#link9), [prop](#prop9), [setAndLink](#setandlink9), or [setAndProp](#setandprop9) 1329 1330To delete these subscribers: 1331 13321. Remove the custom component containing \@LocalStorageLink or \@LocalStorageProp. For details, see [Custom Component Deletion](../../../quick-start/arkts-page-custom-components-lifecycle.md#custom-component-deletion). 1333 13342. Call the [aboutToBeDeleted](#abouttobedeleted10) API on instances of **SubscribedAbstractProperty** returned by **link**, **prop**, **setAndLink**, or **setAndProp**. 1335 1336**Widget capability**: This API can be used in ArkTS widgets since API version 9. 1337 1338**Atomic service API**: This API can be used in atomic services since API version 11. 1339 1340**System capability**: SystemCapability.ArkUI.ArkUI.Full 1341 1342**Parameters** 1343 1344| Name | Type | Mandatory | Description | 1345| -------- | ------ | ---- | ------------------ | 1346| propName | string | Yes | Property name in LocalStorage.| 1347 1348**Return value** 1349 1350| Type | Description | 1351| ------- | ------------------------------------------------------------ | 1352| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 1353 1354**Example** 1355```ts 1356let para: Record<string, number> = { 'PropA': 47 }; 1357let storage: LocalStorage = new LocalStorage(para); 1358storage.link<number>('PropA'); 1359let res: boolean = storage.delete('PropA'); // false, PropA still has a subscriber 1360let res1: boolean = storage.delete('PropB'); // false, PropB is not in storage 1361storage.setOrCreate('PropB', 48); 1362let res2: boolean = storage.delete('PropB'); // true, PropB is deleted from storage successfully 1363``` 1364 1365 1366### keys<sup>9+</sup> 1367 1368keys(): IterableIterator<string> 1369 1370Obtains all property names in [LocalStorage](../../../quick-start/arkts-localstorage.md). 1371 1372**Widget capability**: This API can be used in ArkTS widgets since API version 9. 1373 1374**Atomic service API**: This API can be used in atomic services since API version 11. 1375 1376**System capability**: SystemCapability.ArkUI.ArkUI.Full 1377 1378**Return value** 1379 1380| Type | Description | 1381| ------------------------------ | -------------------- | 1382| IterableIterator<string> | All property names in LocalStorage.| 1383 1384**Example** 1385```ts 1386let para: Record<string, number> = { 'PropA': 47 }; 1387let storage: LocalStorage = new LocalStorage(para); 1388let keys: IterableIterator<string> = storage.keys(); 1389``` 1390 1391 1392### size<sup>9+</sup> 1393 1394size(): number 1395 1396Obtains the number of properties in [LocalStorage](../../../quick-start/arkts-localstorage.md). 1397 1398**Widget capability**: This API can be used in ArkTS widgets since API version 9. 1399 1400**Atomic service API**: This API can be used in atomic services since API version 11. 1401 1402**System capability**: SystemCapability.ArkUI.ArkUI.Full 1403 1404**Return value** 1405 1406| Type | Description | 1407| ------ | ---------------------------- | 1408| number | Number of properties in LocalStorage.| 1409 1410**Example** 1411```ts 1412let para: Record<string, number> = { 'PropA': 47 }; 1413let storage: LocalStorage = new LocalStorage(para); 1414let res: number = storage.size(); // 1 1415``` 1416 1417 1418### clear<sup>9+</sup> 1419 1420clear(): boolean 1421 1422Deletes all properties from [LocalStorage](../../../quick-start/arkts-localstorage.md). The deletion is only successful if none of the properties in LocalStorage have any subscribers. If there are subscribers, this API does not take effect and **false** is returned. If the deletion is successful, **true** is returned. 1423 1424For details about the subscriber, see [delete](#delete9). 1425 1426**Widget capability**: This API can be used in ArkTS widgets since API version 9. 1427 1428**Atomic service API**: This API can be used in atomic services since API version 11. 1429 1430**System capability**: SystemCapability.ArkUI.ArkUI.Full 1431 1432**Return value** 1433 1434 1435| Type | Description | 1436| ------- | ------------------------------------------------------------ | 1437| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 1438 1439 1440**Example** 1441```ts 1442let para: Record<string, number> = { 'PropA': 47 }; 1443let storage: LocalStorage = new LocalStorage(para); 1444let res: boolean = storage.clear(); // true, there are no subscribers 1445``` 1446 1447 1448### GetShared<sup>(deprecated)</sup> 1449 1450static GetShared(): LocalStorage 1451 1452Obtains the [LocalStorage](../../../quick-start/arkts-localstorage.md) instance shared across the current stage. 1453 1454> **NOTE** 1455> 1456> This API is deprecated since API version 10. You are advised to use [getShared10+](#getshared10) instead. 1457 1458**Widget capability**: This API can be used in ArkTS widgets since API version 9. 1459 1460**System capability**: SystemCapability.ArkUI.ArkUI.Full 1461 1462**Model restriction**: This API can be used only in the stage model. 1463 1464**Return value** 1465 1466| Type | Description | 1467| ------------------------------ | ----------------- | 1468| [LocalStorage](#localstorage9) | **LocalStorage** instance.| 1469 1470**Example** 1471```ts 1472let storage: LocalStorage = LocalStorage.GetShared(); 1473``` 1474 1475## AbstractProperty 1476 1477**Atomic service API**: This API can be used in atomic services since API version 12. 1478 1479**System capability**: SystemCapability.ArkUI.ArkUI.Full 1480 1481### get<sup>12+</sup> 1482 1483get(): T 1484 1485Obtains data of the referenced property from [AppStorage](../../../quick-start/arkts-appstorage.md) or [LocalStorage](../../../quick-start/arkts-localstorage.md). 1486 1487**Atomic service API**: This API can be used in atomic services since API version 12. 1488 1489**System capability**: SystemCapability.ArkUI.ArkUI.Full 1490 1491**Return value** 1492 1493| Type| Description | 1494| ---- | ------------------------------------------- | 1495| T | Data of the referenced property in AppStorage or LocalStorage.| 1496 1497**Example** 1498 1499```ts 1500AppStorage.setOrCreate('PropA', 47); 1501let ref1: AbstractProperty<number> | undefined = AppStorage.ref('PropA'); 1502ref1?.get(); // ref1.get()=47 1503``` 1504 1505 1506### set<sup>12+</sup> 1507 1508set(newValue: T): void 1509 1510Updates the data of the referenced property in [AppStorage](../../../quick-start/arkts-appstorage.md) or [LocalStorage](../../../quick-start/arkts-localstorage.md). The value of **newValue** must be of the **T** type and can be **null** or **undefined**. 1511 1512> **NOTE** 1513> 1514> Since API version 12, AppStorage and LocalStorage support the Map, Set, Date types, as well as **null**, **undefined**, and union types. 1515 1516**Atomic service API**: This API can be used in atomic services since API version 12. 1517 1518**System capability**: SystemCapability.ArkUI.ArkUI.Full 1519 1520 1521**Parameters** 1522 1523 1524| Name | Type| Mandatory| Description | 1525| -------- | ---- | ---- | ------------------------------------- | 1526| newValue | T | Yes | New data to update. The value can be **null** or **undefined**.| 1527 1528 1529**Example** 1530 1531```ts 1532AppStorage.setOrCreate('PropA', 47); 1533let ref1: AbstractProperty<number> | undefined = AppStorage.ref('PropA'); 1534ref1?.set(1); // ref1.get()=1 1535let a: Map<string, number> = new Map([['1', 0]]); 1536let ref2 = AppStorage.setAndRef('MapA', a); 1537ref2.set(a); 1538let b: Set<string> = new Set('1'); 1539let ref3 = AppStorage.setAndRef('SetB', b); 1540ref3.set(b); 1541let c: Date = new Date('2024'); 1542let ref4 = AppStorage.setAndRef('DateC', c); 1543ref4.set(c); 1544ref2.set(null); 1545ref3.set(undefined); 1546``` 1547 1548### info<sup>12+</sup> 1549 1550info(): string 1551 1552Reads the property name of the referenced property in [AppStorage](../../../quick-start/arkts-appstorage.md) or [LocalStorage](../../../quick-start/arkts-localstorage.md). 1553 1554**Atomic service API**: This API can be used in atomic services since API version 12. 1555 1556**System capability**: SystemCapability.ArkUI.ArkUI.Full 1557 1558**Return value** 1559 1560| Type | Description | 1561| ------ | --------------------------------------------- | 1562| string | Property name of the referenced property in AppStorage or LocalStorage.| 1563 1564**Example** 1565 1566```ts 1567AppStorage.setOrCreate('PropA', 47); 1568let ref1: AbstractProperty<number> | undefined = AppStorage.ref('PropA'); 1569ref1?.info(); // ref1.info()='PropA' 1570``` 1571 1572## SubscribedAbstractProperty 1573 1574**Widget capability**: This API can be used in ArkTS widgets since API version 9. 1575 1576**Atomic service API**: This API can be used in atomic services since API version 11. 1577 1578**System capability**: SystemCapability.ArkUI.ArkUI.Full 1579 1580### get<sup>9+</sup> 1581 1582abstract get(): T 1583 1584Reads the data of the synchronized property from [AppStorage](../../../quick-start/arkts-appstorage.md) or [LocalStorage](../../../quick-start/arkts-localstorage.md). 1585 1586**Widget capability**: This API can be used in ArkTS widgets since API version 9. 1587 1588**Atomic service API**: This API can be used in atomic services since API version 11. 1589 1590**System capability**: SystemCapability.ArkUI.ArkUI.Full 1591 1592**Return value** 1593 1594| Type | Description | 1595| ---- | ------------------------------- | 1596| T | Data of the synchronized property in AppStorage or LocalStorage.| 1597 1598**Example** 1599```ts 1600AppStorage.setOrCreate('PropA', 47); 1601let prop1: SubscribedAbstractProperty<number> = AppStorage.prop('PropA'); 1602prop1.get(); // prop1.get()=47 1603``` 1604 1605 1606### set<sup>9+</sup> 1607 1608abstract set(newValue: T): void 1609 1610Sets the data of the synchronized property in [AppStorage](../../../quick-start/arkts-appstorage.md) or [LocalStorage](../../../quick-start/arkts-localstorage.md). The value of **newValue** must be of the **T** type. Since API version 12, it can be **null** or **undefined**. 1611 1612> **NOTE** 1613> 1614>Since API version 12, AppStorage and LocalStorage support the Map, Set, Date types, as well as **null**, **undefined**, and union types. 1615 1616**Widget capability**: This API can be used in ArkTS widgets since API version 9. 1617 1618**Atomic service API**: This API can be used in atomic services since API version 11. 1619 1620**System capability**: SystemCapability.ArkUI.ArkUI.Full 1621 1622 1623**Parameters** 1624 1625 1626| Name | Type| Mandatory| Description | 1627| -------- | ---- | ---- | --------------------------------------------------------- | 1628| newValue | T | Yes | Data to set. Since API version 12, the value can be **null** or **undefined**.| 1629 1630 1631**Example** 1632```ts 1633AppStorage.setOrCreate('PropA', 47); 1634let prop1: SubscribedAbstractProperty<number> = AppStorage.prop('PropA'); 1635prop1.set(1); // prop1.get()=1 1636// Since API version 12, the Map, Set, Date types, as well as null, undefined, and union types are supported. 1637let a: Map<string, number> = new Map([['1', 0]]); 1638let prop2 = AppStorage.setAndProp('MapA', a); 1639prop2.set(a); 1640let b: Set<string> = new Set('1'); 1641let prop3 = AppStorage.setAndProp('SetB', b); 1642prop3.set(b); 1643let c: Date = new Date('2024'); 1644let prop4 = AppStorage.setAndProp('DateC', c); 1645prop4.set(c); 1646prop2.set(null); 1647prop3.set(undefined); 1648``` 1649 1650### aboutToBeDeleted<sup>10+</sup> 1651 1652abstract aboutToBeDeleted(): void 1653 1654Cancels the synchronization relationship between the [SubscribedAbstractProperty](#subscribedabstractproperty) instance and [AppStorage](../../../quick-start/arkts-appstorage.md) or [LocalStorage](../../../quick-start/arkts-localstorage.md), whether it is a one-way or two-way binding. After **aboutToBeDeleted** is called, the **SubscribedAbstractProperty** instance is invalidated, meaning it can no longer be used to call the [set](#set9-1) or [get](#get9-1) API. 1655 1656**Atomic service API**: This API can be used in atomic services since API version 11. 1657 1658**System capability**: SystemCapability.ArkUI.ArkUI.Full 1659 1660**Example** 1661```ts 1662AppStorage.setOrCreate('PropA', 47); 1663let link = AppStorage.setAndLink('PropB', 49); // PropA -> 47, PropB -> 49 1664link.aboutToBeDeleted(); 1665``` 1666 1667### info 1668 1669info(): string; 1670 1671Property name. 1672 1673**Atomic service API**: This API can be used in atomic services since API version 11. 1674 1675**System capability**: SystemCapability.ArkUI.ArkUI.Full 1676 1677**Return value** 1678 1679|Type |Description | 1680|---------|-------------| 1681|string |Property name. | 1682 1683 1684## PersistentStorage 1685 1686**Atomic service API**: This API can be used in atomic services since API version 11. 1687 1688**System capability**: SystemCapability.ArkUI.ArkUI.Full 1689 1690For details about how to use PersistentStorage on the UI, see [PersistentStorage: Persisting Application State](../../../quick-start/arkts-persiststorage.md). 1691 1692> **NOTE** 1693> 1694> Since API version 12, PersistentStorage supports **null** and **undefined**. 1695 1696### PersistPropsOptions 1697 1698**Atomic service API**: This API can be used in atomic services since API version 11. 1699 1700**System capability**: SystemCapability.ArkUI.ArkUI.Full 1701 1702**Parameters** 1703 1704| Name | Type | Mandatory| Description | 1705| ------------ | ------------------------------------- | ---- | ------------------------------------------------------------ | 1706| key | string | Yes | Property name. | 1707| defaultValue | number \| string \| boolean \| Object | Yes | Default value used to initialize the property when it does not exist in PersistentStorage and AppStorage. Since API version 12, **defaultValue** can be **null** or **undefined**.| 1708 1709 1710### persistProp<sup>10+</sup> 1711 1712static persistProp<T>(key: string, defaultValue: T): void 1713 1714Persists the property corresponding to **key** from [AppStorage](../../../quick-start/arkts-appstorage.md) to a file. This API is usually called before access to AppStorage. 1715 1716The order for determining the type and value of a property is as follows: 1717 17181. If the property with the specified key is found in the [PersistentStorage](../../../quick-start/arkts-persiststorage.md) file, the corresponding property is created in AppStorage and initialized with the value found in PersistentStorage. 1719 17202. If the property with the specified key is not found in the PersistentStorage file, AppStorage is searched for the property. If the property is found, it is persisted. 1721 17223. If no matching property is found in AppStorage, it is created in AppStorage, initialized with the value of **defaultValue**, and persisted. 1723 1724According to the preceding initialization process, if the property exists in AppStorage, its value will be used, overriding the value in the PersistentStorage file. Because AppStorage stores data in the memory, the property value becomes nonpersistent. 1725 1726**Atomic service API**: This API can be used in atomic services since API version 11. 1727 1728**System capability**: SystemCapability.ArkUI.ArkUI.Full 1729 1730**Parameters** 1731 1732| Name | Type | Mandatory| Description | 1733| ------------ | ------ | ---- | ------------------------------------------------------------ | 1734| key | string | Yes | Property name. | 1735| defaultValue | T | Yes | Default value used for initialization if the specified **key** is not found in PersistentStorage and AppStorage. Since API version 12, the value can be **null** or **undefined**.| 1736 1737 1738**Example** 1739 1740 1741For details about how to use persistProp, see [Accessing PersistentStorage Initialized Attribute from AppStorage](../../../quick-start/arkts-persiststorage.md#accessing-persistentstorage-initialized-attribute-from-appstorage). 1742 1743 1744### deleteProp<sup>10+</sup> 1745 1746static deleteProp(key: string): void 1747 1748Performs the reverse operation of [persistProp](#persistprop10). Specifically, this API deletes the property corresponding to the specified **key** from [PersistentStorage](../../../quick-start/arkts-persiststorage.md). Subsequent operations on [AppStorage](../../../quick-start/arkts-appstorage.md) do not affect data in PersistentStorage. This operation removes the corresponding key from the persistence file. To persist the property again, you can call the [persistProp](#persistprop10) API. 1749 1750**Atomic service API**: This API can be used in atomic services since API version 11. 1751 1752**System capability**: SystemCapability.ArkUI.ArkUI.Full 1753 1754**Parameters** 1755 1756| Name | Type | Mandatory | Description | 1757| ---- | ------ | ---- | ----------------------- | 1758| key | string | Yes | Property name in PersistentStorage.| 1759 1760**Example** 1761```ts 1762PersistentStorage.deleteProp('highScore'); 1763``` 1764 1765 1766### persistProps<sup>10+</sup> 1767 1768static persistProps(props: PersistPropsOptions[]): void 1769 1770Persists multiple properties. This API is similar to [persistProp](#persistprop10), but allows multiple properties to be persisted at once, making it suitable for initializing during application startup. 1771 1772**Atomic service API**: This API can be used in atomic services since API version 11. 1773 1774**System capability**: SystemCapability.ArkUI.ArkUI.Full 1775 1776**Parameters** 1777 1778| Name | Type | Mandatory | Description | 1779| ---------- | ---------------------------------------- | ---- | ---------------------------------------- | 1780| props | [PersistPropsOptions](#persistpropsoptions)[] | Yes| Array of properties to persist.| 1781 1782**Example** 1783```ts 1784PersistentStorage.persistProps([{ key: 'highScore', defaultValue: '0' }, { key: 'wightScore', defaultValue: '1' }]); 1785``` 1786 1787 1788### keys<sup>10+</sup> 1789 1790static keys(): Array<string> 1791 1792Returns an array of all persisted property names. 1793 1794**Atomic service API**: This API can be used in atomic services since API version 11. 1795 1796**System capability**: SystemCapability.ArkUI.ArkUI.Full 1797 1798**Return value** 1799 1800| Type | Description | 1801| ------------------- | ---------------------------------- | 1802| Array<string> | Array of all persisted property names.| 1803 1804**Example** 1805```ts 1806let keys: Array<string> = PersistentStorage.keys(); 1807``` 1808 1809 1810### PersistProp<sup>(deprecated)</sup> 1811 1812static PersistProp<T>(key: string, defaultValue: T): void 1813 1814Persists the property corresponding to **key** from [AppStorage](../../../quick-start/arkts-appstorage.md) to a file. This API is usually called before access to AppStorage. 1815 1816The order for determining the type and value of a property is as follows: 1817 18181. If the property with the specified key is found in the [PersistentStorage](../../../quick-start/arkts-persiststorage.md) file, the corresponding property is created in AppStorage and initialized with the value found in PersistentStorage. 1819 18202. If the property with the specified key is not found in the PersistentStorage file, AppStorage is searched for the property. If the property is found, it is persisted. 1821 18223. If no matching property is found in AppStorage, it is created in AppStorage, initialized with the value of **defaultValue**, and persisted. 1823 1824According to the preceding initialization process, if the property exists in AppStorage, its value will be used, overriding the value in the PersistentStorage file. Because AppStorage stores data in the memory, the property value becomes nonpersistent. 1825 1826 1827> **NOTE** 1828> 1829> This API is deprecated since API version 10. You are advised to use [persistProp10+](#persistprop10) instead. 1830 1831**System capability**: SystemCapability.ArkUI.ArkUI.Full 1832 1833**Parameters** 1834 1835| Name | Type | Mandatory| Description | 1836| ------------ | ------ | ---- | ------------------------------------------------------------ | 1837| key | string | Yes | Property name. | 1838| defaultValue | T | Yes | Default value used for initialization if the specified **key** is not found in PersistentStorage and AppStorage. The value cannot be **null** or **undefined**.| 1839 1840 1841**Example** 1842 1843 1844```ts 1845PersistentStorage.PersistProp('highScore', '0'); 1846``` 1847 1848 1849### DeleteProp<sup>(deprecated)</sup> 1850 1851static DeleteProp(key: string): void 1852 1853Performs the reverse operation of [PersistProp](#persistpropdeprecated). Specifically, this API deletes the property corresponding to the specified key from [PersistentStorage](../../../quick-start/arkts-persiststorage.md). Subsequent operations on [AppStorage](../../../quick-start/arkts-appstorage.md) do not affect data in PersistentStorage. 1854 1855 1856> **NOTE** 1857> 1858> This API is deprecated since API version 10. You are advised to use [deleteProp10+](#deleteprop10) instead. 1859 1860**System capability**: SystemCapability.ArkUI.ArkUI.Full 1861 1862**Parameters** 1863 1864| Name | Type | Mandatory | Description | 1865| ---- | ------ | ---- | ----------------------- | 1866| key | string | Yes | Property name in PersistentStorage.| 1867 1868**Example** 1869```ts 1870PersistentStorage.DeleteProp('highScore'); 1871``` 1872 1873 1874### PersistProps<sup>(deprecated)</sup> 1875 1876static PersistProps(properties: {key: string, defaultValue: any;}[]): void 1877 1878Persists multiple properties. This API is similar to [PersistProp](#persistpropdeprecated), but allows multiple properties to be persisted at once, making it suitable for initializing during application startup. 1879 1880> **NOTE** 1881> 1882> This API is deprecated since API version 10. You are advised to use [persistProps10+](#persistprops10) instead. 1883 1884**System capability**: SystemCapability.ArkUI.ArkUI.Full 1885 1886**Parameters** 1887 1888| Name | Type | Mandatory| Description | 1889| ---------- | ---------------------------------- | ---- | ------------------------------------------------------------ | 1890| properties | {key: string, defaultValue: any}[] | Yes | Array of properties to persist.<br>**key**: property name.<br>**defaultValue**: default value. The rules are the same as those of **PersistProp**.| 1891 1892**Example** 1893 1894```ts 1895PersistentStorage.PersistProps([{ key: 'highScore', defaultValue: '0' }, { key: 'wightScore', defaultValue: '1' }]); 1896``` 1897 1898 1899### Keys<sup>(deprecated)</sup> 1900 1901static Keys(): Array<string> 1902 1903Returns an array of all persisted property names. 1904 1905> **NOTE** 1906> 1907> This API is deprecated since API version 10. You are advised to use [keys10+](#keys10-1) instead. 1908 1909**System capability**: SystemCapability.ArkUI.ArkUI.Full 1910 1911**Return value** 1912 1913| Type | Description | 1914| ------------------- | ---------------------------------- | 1915| Array<string> | Array of all persisted property names.| 1916 1917**Example** 1918```ts 1919let keys: Array<string> = PersistentStorage.Keys(); 1920``` 1921 1922 1923## Environment 1924 1925**Atomic service API**: This API can be used in atomic services since API version 11. 1926 1927**System capability**: SystemCapability.ArkUI.ArkUI.Full 1928 1929For details about how to use environment parameters, see [Environment: Device Environment Query](../../../quick-start/arkts-environment.md). 1930 1931### EnvPropsOptions 1932 1933**Atomic service API**: This API can be used in atomic services since API version 11. 1934 1935**System capability**: SystemCapability.ArkUI.ArkUI.Full 1936 1937**Parameters** 1938 1939| Name | Type | Mandatory| Description | 1940| ------------ | --------------------------- | ---- | ------------------------------------------------------------ | 1941| key | string | Yes | Environment variable name. For details about the value range, see [Built-in Environment Variables](#built-in-environment-variables).| 1942| defaultValue | number \| string \| boolean | Yes | Default value used if the value of the specified environment variable key is not found in AppStorage.| 1943 1944 1945### envProp<sup>10+</sup> 1946 1947static envProp<S>(key: string, value: S): boolean 1948 1949Stores the built-in environment variable key from [Environment](../../../quick-start/arkts-environment.md) into [AppStorage](../../../quick-start/arkts-appstorage.md). If the value of the environment variable key is not found in AppStorage, the default value is used and stored in AppStorage. If the value is successfully stored, **true** is returned. If the value of the environment variable key already exists in AppStorage, **false** is returned. 1950 1951You are advised to call this API when the application is started. 1952 1953It is incorrect to use AppStorage to read environment variables without calling **envProp** first. 1954 1955**Atomic service API**: This API can be used in atomic services since API version 11. 1956 1957**System capability**: SystemCapability.ArkUI.ArkUI.Full 1958 1959**Parameters** 1960 1961| Name| Type | Mandatory| Description | 1962| ------ | ------ | ---- | ------------------------------------------------------------ | 1963| key | string | Yes | Environment variable name. For details about the value range, see [Built-in Environment Variables](#built-in-environment-variables).| 1964| value | S | Yes | Default value used if the value of the environment variable key is not found in AppStorage.| 1965 1966**Return value** 1967 1968| Type | Description | 1969| ------- | ------------------------------------------------------------ | 1970| boolean | Returns **false** if the property corresponding to the key exists in AppStorage; creates a property with the key and the default value and returns **true** otherwise.| 1971 1972**Example** 1973 1974 1975For details about how to use **envProp**, see [Accessing Environment Parameters from UI](../../../quick-start/arkts-environment.md#accessing-environment-parameters-from-ui). 1976 1977 1978### envProps<sup>10+</sup> 1979 1980static envProps(props: EnvPropsOptions[]): void 1981 1982Works in a way similar to the [envProp](#envprop10) API, with the difference that it allows for initialization of multiple properties in batches. It is recommended that this API be called during application startup to store system environment variables to [AppStorage](../../../quick-start/arkts-appstorage.md) in batches. 1983 1984**Atomic service API**: This API can be used in atomic services since API version 11. 1985 1986**System capability**: SystemCapability.ArkUI.ArkUI.Full 1987 1988**Parameters** 1989 1990| Name| Type | Mandatory| Description | 1991| ------ | --------------------------------------------- | ---- | ------------------------------------ | 1992| props | [EnvPropsOptions](#envpropsoptions)[] | Yes | Array of key-value pairs consisting of system environment variables and default values.| 1993 1994**Example** 1995```ts 1996Environment.envProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, { 1997 key: 'languageCode', 1998 defaultValue: 'en' 1999}, { key: 'prop', defaultValue: 'hhhh' }]); 2000``` 2001 2002 2003### keys<sup>10+</sup> 2004 2005static keys(): Array<string> 2006 2007Returns an array of keys of environment variables. 2008 2009**Atomic service API**: This API can be used in atomic services since API version 11. 2010 2011**System capability**: SystemCapability.ArkUI.ArkUI.Full 2012 2013**Return value** 2014 2015| Type | Description | 2016| ------------------- | ----------- | 2017| Array<string> | Array of associated system properties.| 2018 2019**Example** 2020```ts 2021Environment.envProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, { 2022 key: 'languageCode', 2023 defaultValue: 'en' 2024}, { key: 'prop', defaultValue: 'hhhh' }]); 2025 2026let keys: Array<string> = Environment.keys(); // accessibilityEnabled, languageCode, prop 2027``` 2028 2029 2030### EnvProp<sup>(deprecated)</sup> 2031 2032static EnvProp<S>(key: string, value: S): boolean 2033 2034Stores the built-in environment variable key from [Environment](../../../quick-start/arkts-environment.md) into [AppStorage](../../../quick-start/arkts-appstorage.md). If the value of the environment variable key is not found in AppStorage, the default value is used and stored in AppStorage. If the value is successfully stored, **true** is returned. If the value of the environment variable key already exists in AppStorage, **false** is returned. 2035 2036You are advised to call this API when the application is started. 2037 2038It is incorrect to use AppStorage to read environment variables without invoking **EnvProp** first. 2039 2040> **NOTE** 2041> 2042> This API is deprecated since API version 10. You are advised to use [envProp10+](#envprop10) instead. 2043 2044**System capability**: SystemCapability.ArkUI.ArkUI.Full 2045 2046**Parameters** 2047 2048| Name| Type | Mandatory| Description | 2049| ------ | ------ | ---- | ------------------------------------------------------------ | 2050| key | string | Yes | Environment variable name. For details about the value range, see [Built-in Environment Variables](#built-in-environment-variables).| 2051| value | S | Yes | Default value used if the value of the environment variable key is not found in AppStorage.| 2052 2053**Return value** 2054 2055| Type | Description | 2056| ------- | ------------------------------------------------------------ | 2057| boolean | Returns **false** if the property corresponding to the key exists in AppStorage; creates a property with the key and the default value and returns **true** otherwise.| 2058 2059**Example** 2060 2061 2062```ts 2063Environment.EnvProp('accessibilityEnabled', 'default'); 2064``` 2065 2066 2067### EnvProps<sup>(deprecated)</sup> 2068 2069static EnvProps(props: {key: string; defaultValue: any;}[]): void 2070 2071Works in a way similar to the [EnvProp](#envpropdeprecated) API, with the difference that it allows for initialization of multiple properties in batches. It is recommended that this API be called during application startup to store system environment variables to [AppStorage](../../../quick-start/arkts-appstorage.md) in batches. 2072 2073> **NOTE** 2074> 2075> This API is deprecated since API version 10. You are advised to use [envProps10+](#envprops10) instead. 2076 2077**System capability**: SystemCapability.ArkUI.ArkUI.Full 2078 2079**Parameters** 2080 2081| Name| Type | Mandatory| Description | 2082| ------ | ------------------------------------------------- | ---- | ------------------------------------ | 2083| props | {key: string, defaultValue: any}[] | Yes | Array of key-value pairs consisting of system environment variables and default values.| 2084 2085**Example** 2086```ts 2087Environment.EnvProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, { 2088 key: 'languageCode', 2089 defaultValue: 'en' 2090}, { key: 'prop', defaultValue: 'hhhh' }]); 2091``` 2092 2093 2094### Keys<sup>(deprecated)</sup> 2095 2096static Keys(): Array<string> 2097 2098Array of keys of environment variables. 2099 2100> **NOTE** 2101> 2102> This API is deprecated since API version 10. You are advised to use [keys10+](#keys10-2) instead. 2103 2104**System capability**: SystemCapability.ArkUI.ArkUI.Full 2105 2106**Return value** 2107 2108| Type | Description | 2109| ------------------- | ----------- | 2110| Array<string> | Array of associated system properties.| 2111 2112**Example** 2113 2114```ts 2115Environment.EnvProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, { 2116 key: 'languageCode', 2117 defaultValue: 'en' 2118}, { key: 'prop', defaultValue: 'hhhh' }]); 2119 2120let keys: Array<string> = Environment.Keys(); // accessibilityEnabled, languageCode, prop 2121``` 2122 2123 2124## Built-in Environment Variables 2125 2126| key | Type | Description | 2127| -------------------- | --------------- | ------------------------------------------------------------ | 2128| 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.| 2129| colorMode | ColorMode | Color mode. The options are as follows:<br>- **ColorMode.LIGHT**: light mode.<br>- **ColorMode.DARK**: dark mode.| 2130| fontScale | number | Font scale. | 2131| fontWeightScale | number | Font weight scale. | 2132| layoutDirection | LayoutDirection | Layout direction. The options are as follows:<br>- **LayoutDirection.LTR**: from left to right.<br>- **LayoutDirection.RTL**: from right to left.<br>- **Auto**: follows the system settings.| 2133| languageCode | string | Current system language. The value is in lowercase, for example, **zh**. | 2134