目录

State Management with Application-Level Variables

The state management module provides data storage, persistent data management, UIAbility data storage, and environment state required by applications.

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.

T and S in this topic represent the types as described below.

Type Description
T Class, number, boolean, string, and arrays of these types.
S number, boolean, string.

AppStorage

For details about how to use AppStorage, see AppStorage: Storing Application-wide UI State.

[h2]ref12+

static ref<T>(propName: string): AbstractProperty<T> | undefined

Returns a reference to the property corresponding to propName in AppStorage. If the provided propName does not exist, this API returns undefined.

This API is similar to link but does not require manually releasing the returned variable of the AbstractProperty type.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.

Return value

Type Description
AbstractProperty<T> | undefined A reference to the property in AppStorage, or undefined if the property does not exist.

Example

AppStorage.setOrCreate('PropA', 47);
let refToPropA1: AbstractProperty<number> | undefined = AppStorage.ref('PropA');
let refToPropA2: AbstractProperty<number> | undefined = AppStorage.ref('PropA'); // refToPropA2.get() == 47
refToPropA1?.set(48); // Synchronously modify AppStorage: refToPropA1.get() == refToPropA2.get() == 48.

[h2]setAndRef12+

static setAndRef<T>(propName: string, defaultValue: T): AbstractProperty<T>

Similar to the ref API, returns a reference to the property corresponding to propName in AppStorage. If the given property does not exist, this API creates and initializes the property in AppStorage using defaultValue and returns its reference.

This API is similar to setAndLink but does not require manually releasing the returned variable of the AbstractProperty type.

Since API version 12, AppStorage supports Map, Set, Date, null, undefined, and union types.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.
defaultValue T Yes Default value used to initialize the property corresponding to propName in AppStorage if propName does not exist. The value can be null or undefined.

Return value

Type Description
AbstractProperty<T> Instance of AbstractProperty<T>, which is a reference to the property in AppStorage corresponding to propName.

Example

AppStorage.setOrCreate('PropA', 47);
let ref1: AbstractProperty<number> = AppStorage.setAndRef('PropB', 49); // Create PropB with the default value 49.
let ref2: AbstractProperty<number> = AppStorage.setAndRef('PropA', 50); // PropA already exists with the value 47.

[h2]link10+

static link<T>(propName: string): SubscribedAbstractProperty<T>

Establishes a two-way data binding with the property corresponding to propName in AppStorage. If the given property exists in AppStorage, the two-way bound data of the property in AppStorage is returned.

Any update of the data is synchronized back to AppStorage, which then synchronizes the update to all data and custom components bound to the property.

If the given property does not exist in AppStorage, undefined is returned.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.

Return value

Type Description
SubscribedAbstractProperty<T> Two-way bound data of the specified property in AppStorage, or undefined if the property does not exist.

Example

AppStorage.setOrCreate('PropA', 47);
let linkToPropA1: SubscribedAbstractProperty<number> = AppStorage.link('PropA');
let linkToPropA2: SubscribedAbstractProperty<number> = AppStorage.link('PropA'); // linkToPropA2.get() == 47
linkToPropA1.set(48); // Two-way synchronization: linkToPropA1.get() == linkToPropA2.get() == 48

[h2]setAndLink10+

static setAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T>

Similar to the link API, establishes a two-way data binding with the property corresponding to propName in AppStorage. 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.

Since API version 12, AppStorage supports Map, Set, Date, null, undefined, and union types.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.
defaultValue T Yes Default value used to initialize the property corresponding to propName in AppStorage if propName does not exist. Since API version 12, defaultValue can be null or undefined.

Return value

Type Description
SubscribedAbstractProperty<T> Instance of SubscribedAbstractProperty<T>, which is two-way bound data of the given property in AppStorage.

Example

AppStorage.setOrCreate('PropA', 47);
let link1: SubscribedAbstractProperty<number> = AppStorage.setAndLink('PropB', 49); // Create PropB with the default value 49.
let link2: SubscribedAbstractProperty<number> = AppStorage.setAndLink('PropA', 50); // PropA already exists with the value 47.

[h2]prop10+

static prop<T>(propName: string): SubscribedAbstractProperty<T>

Establishes a one-way data binding with the property corresponding to propName in AppStorage. 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.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.

Return value

Type Description
SubscribedAbstractProperty<T> One-way bound data of the specified property in AppStorage, or undefined if the property does not exist.

Example

AppStorage.setOrCreate('PropA', 47);
let prop1: SubscribedAbstractProperty<number> = AppStorage.prop('PropA');
let prop2: SubscribedAbstractProperty<number> = AppStorage.prop('PropA');
prop1.set(1); // One-way synchronization: prop1.get() returns 1, while prop2.get() returns 47.

[h2]setAndProp10+

static setAndProp<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T>

Similar to the prop API, establishes a one-way data binding with the property corresponding to propName in AppStorage. 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.

Since API version 12, AppStorage supports Map, Set, Date, null, undefined, and union types.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.
defaultValue T Yes Default value used to initialize the property corresponding to propName in AppStorage if propName does not exist. Since API version 12, defaultValue can be null or undefined.

Return value

Type Description
SubscribedAbstractProperty<T> Instance of SubscribedAbstractProperty<T>.

Example

AppStorage.setOrCreate('PropA', 47);
let prop: SubscribedAbstractProperty<number> = AppStorage.setAndProp('PropB', 49); // PropA -> 47, PropB -> 49

[h2]has10+

static has(propName: string): boolean

Checks whether the property corresponding to propName exists in AppStorage.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.

Return value

Type Description
boolean Returns true if the property exists in AppStorage; returns false otherwise.

Example

AppStorage.has('simpleProp');

[h2]get10+

static get<T>(propName: string): T | undefined

Obtains the value of the property corresponding to propName from AppStorage. If the property does not exist, this API returns undefined.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.

Return value

Type Description
T | undefined Value of the property corresponding to propName in AppStorage, or undefined if it does not exist.

Example

AppStorage.setOrCreate('PropA', 47);
let value: number = AppStorage.get('PropA') as number; // 47

[h2]set10+

static set<T>(propName: string, newValue: T): boolean

Sets the value of the property corresponding to propName in AppStorage. 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, AppStorage supports Map, Set, Date, null, undefined, and union types.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.
newValue T Yes Property value. Since API version 12, the value can be null or undefined.

Return value

Type Description
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.

Example

AppStorage.setOrCreate('PropA', 48);
let res: boolean = AppStorage.set('PropA', 47) // true
let res1: boolean = AppStorage.set('PropB', 47) // false

[h2]setOrCreate10+

static setOrCreate<T>(propName: string, newValue: T): void

Sets the value of the property corresponding to propName in AppStorage 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.

If 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, AppStorage supports Map, Set, Date, null, undefined, and union types.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.
newValue T Yes Property value. Since API version 12, the value can be null or undefined.

Example

AppStorage.setOrCreate('simpleProp', 121);

[h2]delete10+

static delete(propName: string): boolean

Deletes the property corresponding to propName from AppStorage.

The deletion is only successful if the property has no subscribers. If there is a subscriber, the deletion fails and false is returned. If there are no subscribers, the deletion is successful and true is returned.

The property subscribers include the following:

  1. Variables decorated by @StorageLink or @StorageProp

  2. Instances of SubscribedAbstractProperty returned by link, prop, setAndLink, or setAndProp

To delete these subscribers:

  1. Remove the custom component containing @StorageLink or @StorageProp. For details, see Custom Component Deletion.

  2. Call the aboutToBeDeleted API on instances of SubscribedAbstractProperty returned by link, prop, setAndLink, or setAndProp.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.

Return value

Type Description
boolean Returns true if the operation is successful; returns false if the operation fails.

Example

AppStorage.setOrCreate('PropA', 47);
AppStorage.link<number>('PropA');
let res: boolean = AppStorage.delete('PropA'); // false: PropA still has subscribers.

AppStorage.setOrCreate('PropB', 48);
let res1: boolean = AppStorage.delete('PropB'); // true: PropB is successfully deleted from AppStorage.

[h2]keys10+

static keys(): IterableIterator<string>

Obtains all property names in AppStorage.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
IterableIterator<string> All property names in AppStorage.

Example

AppStorage.setOrCreate('PropB', 48);
let keys: IterableIterator<string> = AppStorage.keys();

[h2]clear10+

static clear(): boolean

Deletes all properties from AppStorage. 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 there are no subscribers, the deletion is successful and true is returned.

For details about the subscriber, see delete.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
boolean Returns true if the properties in AppStorage have no subscribers and the deletion is successful; returns false if there are still subscribers.

Example

AppStorage.setOrCreate('PropA', 47);
let res: boolean = AppStorage.clear(); // true: There are no subscribers.

[h2]size10+

static size(): number

Obtains the number of properties in AppStorage.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
number Number of properties in AppStorage.

Example

AppStorage.setOrCreate('PropB', 48);
let res: number = AppStorage.size(); // 1

[h2]Link(deprecated)

static Link(propName: string): any

Establishes a two-way data binding with the property corresponding to propName in AppStorage. If the given property exists in AppStorage, the two-way bound data of the property in AppStorage is returned.

Any update of the data is synchronized back to AppStorage, which then synchronizes the update to all data and custom components bound to the property.

If the given property does not exist in AppStorage, undefined is returned.

This API is supported since API version 7 and deprecated since API version 10. You are advised to use link instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.

Return value

Type Description
any Two-way bound data of the specified property in AppStorage, or undefined if the property does not exist.

Example

AppStorage.SetOrCreate('PropA', 47);
let linkToPropA1: SubscribedAbstractProperty<number> = AppStorage.Link('PropA');
let linkToPropA2: SubscribedAbstractProperty<number> = AppStorage.Link('PropA'); // linkToPropA2.get() == 47
linkToPropA1.set(48); // Two-way synchronization: linkToPropA1.get() == linkToPropA2.get() == 48

[h2]SetAndLink(deprecated)

static SetAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T>

Similar to the Link API, establishes a two-way data binding with the property corresponding to propName in AppStorage. 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.

This API is supported since API version 7 and deprecated since API version 10. You are advised to use setAndLink instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.
defaultValue T Yes Default value used to initialize the property corresponding to propName in AppStorage if propName does not exist. The value cannot be null or undefined.

Return value

Type Description
SubscribedAbstractProperty<T> Instance of SubscribedAbstractProperty<T> and two-way bound data of the given property in AppStorage.

Example

AppStorage.SetOrCreate('PropA', 47);
let link1: SubscribedAbstractProperty<number> = AppStorage.SetAndLink('PropB', 49); // Create PropB with the default value 49.
let link2: SubscribedAbstractProperty<number> = AppStorage.SetAndLink('PropA', 50); // PropA already exists with the value 47.

[h2]Prop(deprecated)

static Prop(propName: string): any

Establishes a one-way data binding with the property corresponding to propName in AppStorage. 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.

Prop supports only simple types.

This API is supported since API version 7 and deprecated since API version 10. You are advised to use prop instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.

Return value

Type Description
any One-way bound data of the specified property in AppStorage, or undefined if the property does not exist.

Example

AppStorage.SetOrCreate('PropA', 47);
let prop1: SubscribedAbstractProperty<number> = AppStorage.Prop('PropA');
let prop2: SubscribedAbstractProperty<number> = AppStorage.Prop('PropA');
prop1.set(1); // One-way synchronization: prop1.get() returns 1, while prop2.get() returns 47.

[h2]SetAndProp(deprecated)

static SetAndProp<S>(propName: string, defaultValue: S): SubscribedAbstractProperty<S>

Similar to the Prop API, establishes a one-way data binding with the property corresponding to propName in AppStorage. 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.

This API is supported since API version 7 and deprecated since API version 10. You are advised to use setAndProp instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.
defaultValue S Yes Default value used to initialize the property corresponding to propName in AppStorage if propName does not exist. The value cannot be null or undefined.

Return value

Type Description
SubscribedAbstractProperty<S> Instance of SubscribedAbstractProperty<S>.

Example

AppStorage.SetOrCreate('PropA', 47);
let prop: SubscribedAbstractProperty<number> = AppStorage.SetAndProp('PropB', 49); // PropA -> 47, PropB -> 49

[h2]Has(deprecated)

static Has(propName: string): boolean

Checks whether the property corresponding to propName exists in AppStorage.

This API is supported since API version 7 and deprecated since API version 10. You are advised to use has instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.

Return value

Type Description
boolean Returns true if the property exists in AppStorage; returns false otherwise.

Example

AppStorage.Has('simpleProp');

[h2]Get(deprecated)

static Get<T>(propName: string): T | undefined

Obtains the value of the property corresponding to propName from AppStorage. If the property does not exist, this API returns undefined.

This API is supported since API version 7 and deprecated since API version 10. You are advised to use get instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.

Return value

Type Description
T | undefined Value of the property corresponding to propName in AppStorage, or undefined if it does not exist.

Example

AppStorage.SetOrCreate('PropA', 47);
let value: number = AppStorage.Get('PropA') as number; // 47

[h2]Set(deprecated)

static Set<T>(propName: string, newValue: T): boolean

Sets the value of the property corresponding to propName in AppStorage. 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. Starting from API version 12, newValue can be null or undefined.

This API is supported since API version 7 and deprecated since API version 10. You are advised to use set instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.
newValue T Yes Property value. Since API version 12, the value can be null or undefined.

Return value

Type Description
boolean Returns false if the property corresponding to propName does not exist in AppStorage. Returns true if the operation is successful.

Example

AppStorage.SetOrCreate('PropA', 48);
let res: boolean = AppStorage.Set('PropA', 47) // true
let res1: boolean = AppStorage.Set('PropB', 47) // false

[h2]SetOrCreate(deprecated)

static SetOrCreate<T>(propName: string, newValue: T): void

Sets the value of the property corresponding to propName in AppStorage to a new value, if the property exists. If the property does not exist, this API creates it with the value of newValue.

The value of newValue cannot be null or undefined.

This API is supported since API version 7 and deprecated since API version 10. You are advised to use setOrCreate instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.
newValue T Yes Property value, which cannot be null or undefined.

Example

AppStorage.SetOrCreate('simpleProp', 121);

[h2]Delete(deprecated)

static Delete(propName: string): boolean

Deletes the property corresponding to propName from AppStorage.

The deletion is only successful if the property has no subscribers. If there is a subscriber, the deletion fails and false is returned. If there are no subscribers, the deletion is successful and true is returned.

Subscribers include properties bound using Link and Prop APIs, as well as those decorated with @StorageLink('propName') and @StorageProp('propName'). This means that if @StorageLink('propName') and @StorageProp('propName') are used in a custom component or if there is still a SubscribedAbstractProperty instance in a synchronization relationship with the property, the property cannot be deleted from AppStorage.

This API is supported since API version 7 and deprecated since API version 10. You are advised to use delete instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.

Return value

Type Description
boolean Returns true if the operation is successful; returns false if the operation fails.

Example

AppStorage.SetOrCreate('PropA', 47);
AppStorage.Link('PropA');
let res: boolean = AppStorage.Delete('PropA'); // false: PropA still has subscribers.

AppStorage.SetOrCreate('PropB', 48);
let res1: boolean = AppStorage.Delete('PropB'); // true: PropB is successfully deleted from AppStorage.

[h2]Keys(deprecated)

static Keys(): IterableIterator<string>

Obtains all property names in AppStorage.

This API is supported since API version 7 and deprecated since API version 10. You are advised to use keys instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
IterableIterator<string> All property names in AppStorage.

Example

AppStorage.SetOrCreate('PropB', 48);
let keys: IterableIterator<string> = AppStorage.Keys();

[h2]staticClear(deprecated)

static staticClear(): boolean

Deletes all properties.

This API is supported since API version 7 and deprecated since API version 9. You are advised to use clear instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
boolean Deletes all properties. Returns true if all properties are deleted; returns false if any of the properties is being referenced by a state variable.

Example

let simple = AppStorage.staticClear();

[h2]Clear(deprecated)

static Clear(): boolean

Deletes all properties from AppStorage. 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 there are no subscribers, the deletion is successful and true is returned.

For details about the subscriber, see delete.

This API is supported since API version 9 and deprecated since API version 10. You are advised to use clear instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
boolean Returns true if the operation is successful; returns false otherwise.

Example

AppStorage.SetOrCreate('PropA', 47);
let res: boolean = AppStorage.Clear(); // true: There are no subscribers.

[h2]IsMutable(deprecated)

static IsMutable(propName: string): boolean

Checks whether the property corresponding to propName in AppStorage is mutable.

This API is supported since API version 7 and deprecated since API version 10.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in AppStorage.

Return value

Type Description
boolean Whether the property corresponding to propName is mutable. Currently, this return value is always true.

Example

AppStorage.SetOrCreate('PropA', 47);
let res: boolean = AppStorage.IsMutable('PropA');

[h2]Size(deprecated)

static Size(): number

Obtains the number of properties in AppStorage.

This API is supported since API version 7 and deprecated since API version 10. You are advised to use size instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
number Number of properties in AppStorage.

Example

AppStorage.SetOrCreate('PropB', 48);
let res: number = AppStorage.Size(); // 1

LocalStorage9+

For details about how to use LocalStorage on the UI, see LocalStorage: UI State Storage.

[h2]constructor9+

constructor(initializingProperties?: Object)

Creates a LocalStorage instance and initializes it using the properties and values returned by Object.keys(initializingProperties).

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
initializingProperties Object No Properties and values used to initialize the LocalStorage instance. initializingProperties cannot be set to undefined. The default value is an empty object, meaning no properties are added to LocalStorage during initialization.

Example

let para: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(para);

[h2]getShared(deprecated)

static getShared(): LocalStorage

Obtains the LocalStorage instance shared across the current stage.

This API is supported since API version 10 and deprecated since API version 18. You are advised to use getSharedLocalStorage in UIContext instead.

Since API version 12, you can use the getSharedLocalStorage API in UIContext to specify the UI execution context.

Widget capability: This API can be used in ArkTS widgets since API version 10.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Model restriction: This API can be used only in the stage model.

Return value

Type Description
LocalStorage LocalStorage instance.

[h2]has9+

has(propName: string): boolean

Checks whether the property corresponding to propName exists in LocalStorage.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in LocalStorage.

Return value

Type Description
boolean Returns true if the property exists in LocalStorage; returns false otherwise.

Example

let para: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(para);
storage.has('PropA'); // true

[h2]get9+

get<T>(propName: string): T | undefined

Obtains the value of the property corresponding to propName from LocalStorage.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in LocalStorage.

Return value

Type Description
T | undefined Value of the property corresponding to propName in LocalStorage, or undefined if it does not exist.

Example

let para: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(para);
let value: number = storage.get('PropA') as number; // 47

[h2]set9+

set<T>(propName: string, newValue: T): boolean

Sets the value of the property corresponding to propName in LocalStorage. 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, LocalStorage supports Map, Set, Date, null, undefined, and union types.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in LocalStorage.
newValue T Yes Property value. Since API version 12, the value can be null or undefined.

Return value

Type Description
boolean Returns false if the property corresponding to propName does not exist in LocalStorage. Returns true if the operation is successful.

Example

let para: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(para);
let res: boolean = storage.set('PropA', 47); // true
let res1: boolean = storage.set('PropB', 47); // false

[h2]setOrCreate9+

setOrCreate<T>(propName: string, newValue: T): boolean

Sets the value of the property corresponding to propName in LocalStorage 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.

If the property does not exist, this API creates it with the value of newValue. This setOrCreate API can create only one LocalStorage key-value pair each time. To create multiple key-value pairs, call this API multiple times.

Since API version 12, LocalStorage supports Map, Set, Date, null, undefined, and union types.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in LocalStorage.
newValue T Yes Property value. Since API version 12, the value can be null or undefined.

Return value

Type Description
boolean

Returns true if the property corresponding to propName exists and its value is updated to the value of newValue,

or if propName is created with the value of newValue.

Example

let para: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(para);
let res: boolean = storage.setOrCreate('PropA', 121); // true
let res1: boolean = storage.setOrCreate('PropB', 111); // true
let res2: boolean = storage.setOrCreate('PropB', null); // true (API version 12 and later) or false (API version 11 and earlier)

[h2]ref12+

ref<T>(propName: string): AbstractProperty<T> | undefined

Returns a reference to the property corresponding to propName in LocalStorage. If the provided propName does not exist, this API returns undefined.

This API is similar to link but does not require manually releasing the returned variable of the AbstractProperty type.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in LocalStorage.

Return value

Type Description
AbstractProperty<T> | undefined A reference to the property in LocalStorage, or undefined if the property does not exist.

Example

let para: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(para);
let refToPropA1: AbstractProperty<number> | undefined = storage.ref('PropA');
let refToPropA2: AbstractProperty<number> | undefined = storage.ref('PropA'); // refToPropA2.get() == 47
refToPropA1?.set(48); // refToPropA1.get() == refToPropA2.get() == 48

[h2]setAndRef12+

setAndRef<T>(propName: string, defaultValue: T): AbstractProperty<T>

Similar to the ref API, returns a reference to the property corresponding to propName in LocalStorage. If the given property does not exist, this API creates and initializes the property in LocalStorage using defaultValue and returns its reference.

This API is similar to setAndLink but does not require manually releasing the returned variable of the AbstractProperty type.

Since API version 12, LocalStorage supports Map, Set, Date, null, undefined, and union types.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in LocalStorage.
defaultValue T Yes Default value used to initialize the property corresponding to propName in LocalStorage if propName does not exist. The value can be null or undefined.

Return value

Type Description
AbstractProperty<T> Instance of AbstractProperty<T>, which is a reference to the property in LocalStorage corresponding to propName.

Example

let para: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(para);
let ref1: AbstractProperty<number> = storage.setAndRef('PropB', 49); // Create PropB with the default value 49.
let ref2: AbstractProperty<number> = storage.setAndRef('PropA', 50); // PropA already exists with the value 47.

[h2]link9+

link<T>(propName: string): SubscribedAbstractProperty<T>

Establishes a two-way data binding with the property corresponding to propName in LocalStorage. If the given property exists in LocalStorage, this API returns the two-way bound data for the property.

Any update of the data is synchronized back to LocalStorage, which then synchronizes the update to all data and components bound to the property.

If the given property does not exist in LocalStorage, undefined is returned.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in LocalStorage.

Return value

Type Description
SubscribedAbstractProperty<T> Returns the SubscribedAbstractProperty<T> instance if the given property exists in LocalStorage; returns undefined otherwise.

Example

let para: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(para);
let linkToPropA1: SubscribedAbstractProperty<number> = storage.link('PropA');
let linkToPropA2: SubscribedAbstractProperty<number> = storage.link('PropA'); // linkToPropA2.get() == 47
linkToPropA1.set(48); // Two-way synchronization: linkToPropA1.get() == linkToPropA2.get() == 48

[h2]setAndLink9+

setAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T>

Similar to the link API, establishes a two-way data binding with the property corresponding to propName in LocalStorage. 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.

Since API version 12, LocalStorage supports Map, Set, Date, null, undefined, and union types.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in LocalStorage.
defaultValue T Yes Default value used to initialize the property corresponding to propName in LocalStorage if propName does not exist. Since API version 12, defaultValue can be null or undefined.

Return value

Type Description
SubscribedAbstractProperty<T> Instance of SubscribedAbstractProperty<T> and two-way bound data of the given property in LocalStorage.

Example

let para: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(para);
let link1: SubscribedAbstractProperty<number> = storage.setAndLink('PropB', 49); // Create PropB with the default value 49.
let link2: SubscribedAbstractProperty<number> = storage.setAndLink('PropA', 50); // PropA already exists with the value 47.

[h2]prop9+

prop<S>(propName: string): SubscribedAbstractProperty<S>

Establishes a one-way data binding with the property corresponding to propName in LocalStorage. 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 in LocalStorage, undefined is returned. Updates of the one-way bound data are not synchronized back to LocalStorage.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in LocalStorage.

Return value

Type Description
SubscribedAbstractProperty<S> Instance of SubscribedAbstractProperty<S> and one-way bound data of the given property in LocalStorage. If the given property does not exist in LocalStorage, undefined is returned.

Example

let para: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(para);
let prop1: SubscribedAbstractProperty<number> = storage.prop('PropA');
let prop2: SubscribedAbstractProperty<number> = storage.prop('PropA');
prop1.set(1); // One-way synchronization: prop1.get() returns 1, while prop2.get() returns 47.

[h2]setAndProp9+

setAndProp<S>(propName: string, defaultValue: S): SubscribedAbstractProperty<S>

Similar to the prop API, establishes a one-way data binding with the property corresponding to propName in LocalStorage. 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.

Since API version 12, LocalStorage supports Map, Set, Date, null, undefined, and union types.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in LocalStorage.
defaultValue S Yes Default value used to initialize the property corresponding to propName in LocalStorage if propName does not exist. Since API version 12, defaultValue can be null or undefined.

Return value

Type Description
SubscribedAbstractProperty<S> Instance of SubscribedAbstractProperty<S> and one-way bound data of the given property in LocalStorage.

Example

let para: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(para);
let prop: SubscribedAbstractProperty<number> = storage.setAndProp('PropB', 49); // PropA -> 47, PropB -> 49

[h2]delete9+

delete(propName: string): boolean

Deletes the property corresponding to propName from LocalStorage. The deletion is only successful if the property has no subscribers. If there is a subscriber, the deletion fails and false is returned. If there are no subscribers, the deletion is successful and true is returned.

The property subscribers include the following:

  1. Variables decorated by @LocalStorageLink or @LocalStorageProp

  2. Instances of SubscribedAbstractProperty returned by link, prop, setAndLink, or setAndProp

To delete these subscribers:

  1. Remove the custom component containing @LocalStorageLink or @LocalStorageProp. For details, see Custom Component Deletion.

  2. Call the aboutToBeDeleted API on instances of SubscribedAbstractProperty returned by link, prop, setAndLink, or setAndProp.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
propName string Yes Property name in LocalStorage.

Return value

Type Description
boolean Returns true if the operation is successful; returns false if the operation fails.

Example

let para: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(para);
storage.link<number>('PropA');
let res: boolean = storage.delete('PropA'); // false: PropA still has subscribers.
let res1: boolean = storage.delete('PropB'); // false: PropB does not exist in LocalStorage.
storage.setOrCreate('PropB', 48);
let res2: boolean = storage.delete('PropB'); // true: PropB is successfully deleted from LocalStorage.

[h2]keys9+

keys(): IterableIterator<string>

Obtains all property names in LocalStorage.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
IterableIterator<string> All property names in LocalStorage.

Example

let para: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(para);
let keys: IterableIterator<string> = storage.keys();

[h2]size9+

size(): number

Obtains the number of properties in LocalStorage.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
number Number of properties in LocalStorage.

Example

let para: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(para);
let res: number = storage.size(); // 1

[h2]clear9+

clear(): boolean

Deletes all properties from LocalStorage. 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 there are no subscribers, the deletion is successful and true is returned.

For details about the subscriber, see delete.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
boolean Returns true if the operation is successful; returns false otherwise.

Example

let para: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(para);
let res: boolean = storage.clear(); // true: There are no subscribers.

[h2]GetShared(deprecated)

static GetShared(): LocalStorage

Obtains the LocalStorage instance shared across the current stage.

This API is supported since API version 9 and deprecated since API version 10. You are advised to use getSharedLocalStorage in UIContext instead.

Widget capability: This API can be used in ArkTS widgets since API version 9.

System capability: SystemCapability.ArkUI.ArkUI.Full

Model restriction: This API can be used only in the stage model.

Return value

Type Description
LocalStorage LocalStorage instance.

Example

let storage: LocalStorage = LocalStorage.GetShared();

AbstractProperty12+

Provides a reference to properties stored in AppStorage or LocalStorage.

[h2]get12+

get(): T

Reads data of the referenced property from AppStorage or LocalStorage.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
T Data of the referenced property in AppStorage or LocalStorage.

Example

AppStorage.setOrCreate('PropA', 47);
let ref1: AbstractProperty<number> | undefined = AppStorage.ref('PropA');
ref1?.get(); //  ref1.get()=47

[h2]set12+

set(newValue: T): void

Updates the data of the referenced property in AppStorage or LocalStorage. The value of newValue must be of the T type and can be null or undefined.

Since API version 12, AppStorage and LocalStorage support the Map, Set, Date types, as well as null, undefined, and union types.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
newValue T Yes New data to update. The value can be null or undefined.

Example

AppStorage.setOrCreate('PropA', 47);
let ref1: AbstractProperty<number> | undefined = AppStorage.ref('PropA');
ref1?.set(1); //  ref1.get()=1
let a: Map<string, number> = new Map([['1', 0]]);
let ref2 = AppStorage.setAndRef('MapA', a);
ref2.set(a);
let b: Set<string> = new Set('1');
let ref3 = AppStorage.setAndRef('SetB', b);
ref3.set(b);
let c: Date = new Date('2024');
let ref4 = AppStorage.setAndRef('DateC', c);
ref4.set(c);
ref2.set(null);
ref3.set(undefined);

[h2]info12+

info(): string

Reads the property name of the referenced property from AppStorage or LocalStorage.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
string Property name of the referenced property in AppStorage or LocalStorage.

Example

AppStorage.setOrCreate('PropA', 47);
let ref1: AbstractProperty<number> | undefined = AppStorage.ref('PropA');
ref1?.info(); //  ref1.info()='PropA'

SubscribedAbstractProperty

Represents a synchronized property from AppStorage or LocalStorage.

[h2]get9+

abstract get(): T

Reads the data of the synchronized property from AppStorage or LocalStorage.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
T Data of the synchronized property in AppStorage or LocalStorage.

Example

AppStorage.setOrCreate('PropA', 47);
let prop1: SubscribedAbstractProperty<number> = AppStorage.prop('PropA');
prop1.get(); //  prop1.get()=47

[h2]set9+

abstract set(newValue: T): void

Sets the data of the synchronized property in AppStorage or LocalStorage. The value of newValue must be of the T type. Since API version 12, it can be null or undefined.

Since API version 12, AppStorage and LocalStorage support the Map, Set, Date types, as well as null, undefined, and union types.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
newValue T Yes Data to set. Since API version 12, the value can be null or undefined.

Example

AppStorage.setOrCreate('PropA', 47);
let prop1: SubscribedAbstractProperty<number> = AppStorage.prop('PropA');
prop1.set(1); //  prop1.get()=1
// Since API version 12, the Map, Set, Date types, as well as null, undefined, and union types are supported.
let a: Map<string, number> = new Map([['1', 0]]);
let prop2 = AppStorage.setAndProp('MapA', a);
prop2.set(a);
let b: Set<string> = new Set('1');
let prop3 = AppStorage.setAndProp('SetB', b);
prop3.set(b);
let c: Date = new Date('2024');
let prop4 = AppStorage.setAndProp('DateC', c);
prop4.set(c);
prop2.set(null);
prop3.set(undefined);

[h2]aboutToBeDeleted10+

abstract aboutToBeDeleted(): void

Cancels the synchronization relationship between the SubscribedAbstractProperty instance and AppStorage or LocalStorage, 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 or get API.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Example

AppStorage.setOrCreate('PropA', 47);
let link = AppStorage.setAndLink('PropB', 49); // PropA -> 47, PropB -> 49
link.aboutToBeDeleted();

[h2]info10+

info(): string

Property name.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
string Property name.

Example

AppStorage.setOrCreate('PropA', 47);
let prop1: SubscribedAbstractProperty<number> = AppStorage.prop('PropA');
prop1.info(); // prop1.info() = 'PropA'

PersistPropsOptions10+

Defines a key-value pair object used to specify persistent properties and their default values, passed as a parameter to persistProps.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Read-Only Optional Description
key string No No Property name.
defaultValue number | string | boolean | Object No No Default value used for initialization if the specified key is not found in PersistentStorage and AppStorage. Since API version 12, defaultValue can be set to null or undefined.

PersistentStorage

For details about how to use PersistentStorage on the UI, see PersistentStorage: Persisting Application State.

Since API version 12, PersistentStorage supports null and undefined.

[h2]persistProp10+

static persistProp<T>(key: string, defaultValue: T): void

Persists the property corresponding to key from AppStorage to a file. This API is usually called before access to AppStorage.

The order for determining the type and value of a property is as follows:

  1. If the property with the specified key is found in the PersistentStorage file, the corresponding property is created in AppStorage and initialized with the value found in PersistentStorage.

  2. 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.

  3. If no matching property is found in AppStorage, it is created in AppStorage, initialized with the value of defaultValue, and persisted.

According 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.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
key string Yes Property name.
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.

Example

For details about how to use persistProp, see Accessing a PersistentStorage-Initialized Property from AppStorage.

[h2]deleteProp10+

static deleteProp(key: string): void

Performs the reverse operation of persistProp. Specifically, this API deletes the property corresponding to the specified key from PersistentStorage. Subsequent operations on AppStorage 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 API.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
key string Yes Property name in PersistentStorage.

Example

PersistentStorage.deleteProp('highScore');

[h2]persistProps10+

static persistProps(props: PersistPropsOptions[]): void

Persists multiple properties. This API is similar to persistProp, but allows multiple properties to be persisted at once, making it suitable for initializing during application startup.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
props PersistPropsOptions[] Yes Array of properties to persist.

Example

PersistentStorage.persistProps([{ key: 'highScore', defaultValue: '0' }, { key: 'wightScore', defaultValue: '1' }]);

[h2]keys10+

static keys(): Array<string>

Returns an array of all persisted property names.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
Array<string> Returns an array of all persisted property names.

Example

let keys: Array<string> = PersistentStorage.keys();

[h2]PersistProp(deprecated)

static PersistProp<T>(key: string, defaultValue: T): void

Persists the property corresponding to key from AppStorage to a file. This API is usually called before access to AppStorage.

The order for determining the type and value of a property is as follows:

  1. If the property with the specified key is found in the PersistentStorage file, the corresponding property is created in AppStorage and initialized with the value found in PersistentStorage.

  2. 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.

  3. If no matching property is found in AppStorage, it is created in AppStorage, initialized with the value of defaultValue, and persisted.

According 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.

This API is supported since API version 7 and deprecated since API version 10. You are advised to use persistProp instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
key string Yes Property name.
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.

Example

PersistentStorage.PersistProp('highScore', '0');

[h2]DeleteProp(deprecated)

static DeleteProp(key: string): void

Performs the reverse operation of PersistProp. Specifically, this API deletes the property corresponding to the specified key from PersistentStorage. Subsequent operations on AppStorage do not affect data in PersistentStorage.

This API is supported since API version 7 and deprecated since API version 10. You are advised to use deleteProp instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
key string Yes Property name in PersistentStorage.

Example

PersistentStorage.DeleteProp('highScore');

[h2]PersistProps(deprecated)

static PersistProps(properties: {key: string; defaultValue: any;}[]): void

Persists multiple properties. This API is similar to PersistProp, but allows multiple properties to be persisted at once, making it suitable for initializing during application startup.

This API is supported since API version 7 and deprecated since API version 10. You are advised to use persistProps instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
properties {key: string; defaultValue: any}[] Yes

Array of properties to persist.

key: property name.

defaultValue: default value. The rule is the same as that for PersistProp.

Example

PersistentStorage.PersistProps([{ key: 'highScore', defaultValue: '0' }, { key: 'wightScore', defaultValue: '1' }]);

[h2]Keys(deprecated)

static Keys(): Array<string>

Returns an array of all persisted property names.

This API is supported since API version 7 and deprecated since API version 10. You are advised to use keys instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
Array<string> Returns an array of all persisted property names.

Example

let keys: Array<string> = PersistentStorage.Keys();

EnvPropsOptions10+

Defines a key-value pair object used to specify environment variable names and their default values, passed as a parameter to envProps.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Read-Only Optional Description
key string No No Environment variable name. For details about the value range, see Built-in Environment Variables.
defaultValue number | string | boolean No No Default value used if the value of the specified environment variable key is not found in AppStorage.

Environment

For details about how to use environment parameters, see Environment: Device Environment Query.

[h2]envProp10+

static envProp<S>(key: string, value: S): boolean

Stores the built-in environment variable key from Environment into AppStorage. 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.

You are advised to call this API when the application is started.

It is incorrect to use AppStorage to read environment variables without calling envProp first.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
key string Yes Environment variable name. For details about the value range, see Built-in Environment Variables.
value S Yes Default value used if the value of the environment variable key is not found in AppStorage.

Return value

Type Description
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.

Example

For details about how to use envProp, see Accessing Environment Parameters from the UI.

[h2]envProps10+

static envProps(props: EnvPropsOptions[]): void

Works in a way similar to the envProp API, with the difference that it allows for initialization of multiple attributes in batches. It is recommended that this API be called during application startup to store system environment variables to AppStorage in batches.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
props EnvPropsOptions[] Yes Array of key-value pairs consisting of system environment variables and default values.

Example

Environment.envProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, {
  key: 'languageCode',
  defaultValue: 'en'
}, { key: 'prop', defaultValue: 'hhhh' }]);

[h2]keys10+

static keys(): Array<string>

Returns the property key array of environment variables.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
Array<string> Property key array of environment variables.

Example

Environment.envProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, {
  key: 'languageCode',
  defaultValue: 'en'
}, { key: 'prop', defaultValue: 'hhhh' }]);

let keys: Array<string> = Environment.keys(); // keys contains accessibilityEnabled, languageCode, and prop.

[h2]EnvProp(deprecated)

static EnvProp<S>(key: string, value: S): boolean

Stores the built-in environment variable key from Environment into AppStorage. 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.

You are advised to call this API when the application is started.

It is incorrect to use AppStorage to read environment variables without calling EnvProp first.

This API is supported since API version 7 and deprecated since API version 10. You are advised to use envProp instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
key string Yes Environment variable name. For details about the value range, see Built-in Environment Variables.
value S Yes Default value used if the value of the environment variable key is not found in AppStorage.

Return value

Type Description
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.

Example

Environment.EnvProp('accessibilityEnabled', 'default');

[h2]EnvProps(deprecated)

static EnvProps(props: {key: string; defaultValue: any;}[]): void

Works in a way similar to the EnvProp API, with the difference that it allows for initialization of multiple attributes in batches. It is recommended that this API be called during application startup to store system environment variables to AppStorage in batches.

This API is supported since API version 7 and deprecated since API version 10. You are advised to use envProps instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
props {key: string; defaultValue: any}[] Yes Array of key-value pairs consisting of system environment variables and default values.

Example

Environment.EnvProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, {
  key: 'languageCode',
  defaultValue: 'en'
}, { key: 'prop', defaultValue: 'hhhh' }]);

[h2]Keys(deprecated)

static Keys(): Array<string>

Returns the property key array of environment variables.

This API is supported since API version 7 and deprecated since API version 10. You are advised to use keys instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type Description
Array<string> Property key array of environment variables.

Example

Environment.EnvProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, {
  key: 'languageCode',
  defaultValue: 'en'
}, { key: 'prop', defaultValue: 'hhhh' }]);

let keys: Array<string> = Environment.Keys(); // keys contains accessibilityEnabled, languageCode, and prop.

Built-in Environment Variables

key Type Description
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.
colorMode ColorMode

Color mode. The options are as follows:

- ColorMode.LIGHT: light mode.

- ColorMode.DARK: dark mode.
fontScale number Font scale.
fontWeightScale number Font weight ratio.
layoutDirection LayoutDirection

Layout direction. The options are as follows:

- LayoutDirection.LTR: from left to right.

- LayoutDirection.RTL: from right to left.

- Auto: follows the system settings.
languageCode string Current system language, which is in lowercase letters, for example, zh.