harmony 鸿蒙State Management with Application-level Variables

2025-06-12
浏览 (4)

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.

NOTE

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.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

ref¹²⁺

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

Returns a reference to the data 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 updates AppStorage: refToPropA1.get() == refToPropA2.get() == 48.

setAndRef¹²⁺

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

Similar to the ref API, returns a reference to the data corresponding to propName in AppStorage. 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.

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

NOTE

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 propName in AppStorage if it 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 49
let ref2: AbstractProperty<number> = AppStorage.setAndRef('PropA', 50); // PropA exists, remains 47

link¹⁰⁺

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

setAndLink¹⁰⁺

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. Since API version 12, it can be null or undefined.

NOTE

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 propName in AppStorage if it 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 AppStorage.

Example

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

prop¹⁰⁺

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 sync: prop1.get()=1; but prop2.get() == 47

setAndProp¹⁰⁺

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. The value of defaultValue must be of the T type. Since API version 12, it can be null or undefined.

NOTE

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 propName in AppStorage if it 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

has¹⁰⁺

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');

get¹⁰⁺

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

set¹⁰⁺

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, newValue can be null or undefined.

NOTE

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

setOrCreate¹⁰⁺

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, newValue can be null or undefined.

NOTE

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);

delete¹⁰⁺

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 the deletion is successful, true is returned.

The property subscribers include the following:

Variables decorated by \@StorageLink or \@StorageProp
Instances of SubscribedAbstractProperty returned by link, prop, setAndLink, or setAndProp

To delete these subscribers:

Remove the custom component containing @StorageLink or @StorageProp. For details, see Custom Component Deletion.
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 otherwise.

Example

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

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

keys¹⁰⁺

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();

clear¹⁰⁺

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 the deletion is successful, 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 operation is successful; returns false otherwise.

Example

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

size¹⁰⁺

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

Link^(deprecated)

static Link(propName: string): any

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.

NOTE

This API is supported since API version 7 and deprecated since API version 10. You are advised to use link10+ 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

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.

NOTE

This API is supported since API version 7 and deprecated since API version 10. You are advised to use setAndLink10+ 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 propName in AppStorage if it 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 49
let link2: SubscribedAbstractProperty<number> = AppStorage.SetAndLink('PropA', 50); // PropA exists, remains 47

Prop^(deprecated)

static Prop(propName: string): any

NOTE

Prop supports only simple types.

This API is supported since API version 7 and deprecated since API version 10. You are advised to use prop10+ 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 sync: prop1.get()=1; but prop2.get() == 47

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.

NOTE

This API is supported since API version 7 and deprecated since API version 10. You are advised to use setAndProp10+ 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 propName in AppStorage if it 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

Has^(deprecated)

static Has(propName: string): boolean

Checks whether the property corresponding to propName exists in AppStorage.

NOTE

This API is supported since API version 7 and deprecated since API version 10. You are advised to use has10+ 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');

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.

NOTE

This API is supported since API version 7 and deprecated since API version 10. You are advised to use get10+ 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

Set^(deprecated)

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

Sets the value of the property corresponding to propName in AppStorage.

NOTE

This API is supported since API version 7 and deprecated since API version 10. You are advised to use set10+ 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.

Return value

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

Example

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

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.

NOTE

This API is supported since API version 7 and deprecated since API version 10. You are advised to use setOrCreate10+ 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);

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 the deletion is successful, 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.

NOTE

This API is supported since API version 7 and deprecated since API version 10. You are advised to use delete10+ 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 otherwise.

Example

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

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

Keys^(deprecated)

static Keys(): IterableIterator<string>

Obtains all property names in AppStorage.

NOTE

This API is supported since API version 7 and deprecated since API version 10. You are advised to use keys10+ 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();

staticClear^(deprecated)

static staticClear(): boolean

Deletes all properties.

NOTE

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
boolean	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();

Clear^(deprecated)

static Clear(): boolean

For details about the subscriber, see delete.

NOTE

This API is supported since API version 9 and deprecated since API version 10. You are advised to use clear10+ 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

IsMutable^(deprecated)

static IsMutable(propName: string): boolean

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

NOTE

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.

Example

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

Size^(deprecated)

static Size(): number

Obtains the number of properties in AppStorage.

NOTE

This API is supported since API version 7 and deprecated since API version 10. You are advised to use size10+ 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

LocalStorage⁹⁺

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

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

constructor⁹⁺

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. The value cannot be undefined.

Example

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

getShared¹⁰⁺

static getShared(): LocalStorage

Obtains the LocalStorage instance shared across the current stage.

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.

Example For details about how to use the getShared API, see Example of Sharing a LocalStorage Instance from UIAbility to One or More Pages.

has⁹⁺

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

get⁹⁺

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

set⁹⁺

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, newValue can be null or undefined.

NOTE

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 operation is successful; returns false if the property corresponding to propName does not exist in LocalStorage.

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

setOrCreate⁹⁺

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

NOTE

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)

ref¹²⁺

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

Returns a reference to the data 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

setAndRef¹²⁺

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

Similar to the ref API, returns a reference to the data corresponding to propName in LocalStorage. 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.

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

NOTE

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 propName in LocalStorage if it 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 49
let ref2: AbstractProperty<number> = storage.setAndRef('PropA', 50); // PropA exists, remains 47

link⁹⁺

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 custom 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

setAndLink⁹⁺

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. The value of defaultValue must be of the T type. Since API version 12, it can be null or undefined.

NOTE

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 propName in LocalStorage if it 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 49
let link2: SubscribedAbstractProperty<number> = storage.setAndLink('PropA', 50); // PropA exists, remains 47

prop⁹⁺

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

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, or undefined if the provided propName does not exist in LocalStorage.

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 sync: prop1.get()=1; but prop2.get() == 47

setAndProp⁹⁺

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. The value of defaultValue must be of the S type. Since API version 12, it can be null or undefined.

NOTE

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 propName in LocalStorage if it 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

delete⁹⁺

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 the deletion is successful, true is returned.

The property subscribers include the following:

Variables decorated by \@LocalStorageLink or \@LocalStorageProp
Instances of SubscribedAbstractProperty returned by link, prop, setAndLink, or setAndProp

To delete these subscribers:

Remove the custom component containing \@LocalStorageLink or \@LocalStorageProp. For details, see Custom Component Deletion.
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 otherwise.

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 a subscriber
let res1: boolean = storage.delete('PropB'); // false, PropB is not in storage
storage.setOrCreate('PropB', 48);
let res2: boolean = storage.delete('PropB'); // true, PropB is deleted from storage successfully

keys⁹⁺

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();

size⁹⁺

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

clear⁹⁺

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 the deletion is successful, 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

GetShared^(deprecated)

static GetShared(): LocalStorage

Obtains the LocalStorage instance shared across the current stage.

NOTE

This API is deprecated since API version 10. You are advised to use getShared10+ 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();

AbstractProperty

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

System capability: SystemCapability.ArkUI.ArkUI.Full

get¹²⁺

get(): T

Obtains 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

set¹²⁺

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.

NOTE

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);

info¹²⁺

info(): string

Reads the property name of the referenced property in 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

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

get⁹⁺

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

set⁹⁺

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.

NOTE

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);

aboutToBeDeleted¹⁰⁺

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();

info

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.

PersistentStorage

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

System capability: SystemCapability.ArkUI.ArkUI.Full

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

NOTE

Since API version 12, PersistentStorage supports null and undefined.

PersistPropsOptions

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

persistProp¹⁰⁺

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:

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.
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.
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 PersistentStorage Initialized Attribute from AppStorage.

deleteProp¹⁰⁺

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');

persistProps¹⁰⁺

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' }]);

keys¹⁰⁺

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>	Array of all persisted property names.

Example

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

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:

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.
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.
If no matching property is found in AppStorage, it is created in AppStorage, initialized with the value of defaultValue, and persisted.

NOTE

This API is deprecated since API version 10. You are advised to use persistProp10+ 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');

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.

NOTE

This API is deprecated since API version 10. You are advised to use deleteProp10+ instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

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

Example

PersistentStorage.DeleteProp('highScore');

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.

NOTE

This API is deprecated since API version 10. You are advised to use persistProps10+ 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 rules are the same as those of PersistProp.

Example

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

Keys^(deprecated)

static Keys(): Array<string>

Returns an array of all persisted property names.

NOTE

This API is deprecated since API version 10. You are advised to use keys10+ instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

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

Example

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

Environment

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

System capability: SystemCapability.ArkUI.ArkUI.Full

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

EnvPropsOptions

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.
defaultValue	number \|string \|boolean	Yes	Default value used if the value of the specified environment variable key is not found in AppStorage.

envProp¹⁰⁺

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

envProps¹⁰⁺

static envProps(props: EnvPropsOptions[]): void

Works in a way similar to the envProp 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 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' }]);

keys¹⁰⁺

static keys(): Array<string>

Returns an array of keys 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>	Array of associated system properties.

Example

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

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

EnvProp^(deprecated)

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

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

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

NOTE

This API is deprecated since API version 10. You are advised to use envProp10+ 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');

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 properties in batches. It is recommended that this API be called during application startup to store system environment variables to AppStorage in batches.

NOTE

This API is deprecated since API version 10. You are advised to use envProps10+ 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' }]);

Keys^(deprecated)

static Keys(): Array<string>

Array of keys of environment variables.

NOTE

This API is deprecated since API version 10. You are advised to use keys10+ instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
Array<string>	Array of associated system properties.

Example

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

let keys: Array<string> = Environment.Keys(); // accessibilityEnabled, languageCode, 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 scale.
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. The value is in lowercase, for example, zh.

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ComposeListItem

harmony 鸿蒙ComposeTitleBar

harmony 鸿蒙advanced.Counter

harmony 鸿蒙Dialog Box (Dialog)

harmony 鸿蒙DialogV2

harmony 鸿蒙DownloadFileButton

0 赞

所属分类： 后端技术
本文标签：
版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/JvtUvL

harmony 鸿蒙State Management with Application-level Variables

State Management with Application-level Variables

AppStorage

ref12+

setAndRef12+

link10+

setAndLink10+

prop10+

setAndProp10+

has10+

get10+

set10+

setOrCreate10+

delete10+

keys10+

clear10+

size10+

Link(deprecated)

SetAndLink(deprecated)

Prop(deprecated)

SetAndProp(deprecated)

Has(deprecated)

Get(deprecated)

Set(deprecated)

SetOrCreate(deprecated)

Delete(deprecated)

Keys(deprecated)

staticClear(deprecated)

Clear(deprecated)

IsMutable(deprecated)

Size(deprecated)

LocalStorage9+

constructor9+

getShared10+

has9+

get9+

set9+

setOrCreate9+

ref12+

setAndRef12+

link9+

setAndLink9+

prop9+

setAndProp9+

delete9+

keys9+

size9+

clear9+

GetShared(deprecated)

AbstractProperty

get12+

set12+

info12+

SubscribedAbstractProperty

get9+

set9+

aboutToBeDeleted10+

info

PersistentStorage

PersistPropsOptions

persistProp10+

deleteProp10+

persistProps10+

keys10+

PersistProp(deprecated)

DeleteProp(deprecated)

PersistProps(deprecated)

Keys(deprecated)

Environment

EnvPropsOptions

envProp10+

envProps10+

keys10+

EnvProp(deprecated)

EnvProps(deprecated)

Keys(deprecated)

Built-in Environment Variables

你可能感兴趣的鸿蒙文章

热门推荐

标签云

ref¹²⁺

setAndRef¹²⁺

link¹⁰⁺

setAndLink¹⁰⁺

prop¹⁰⁺

setAndProp¹⁰⁺

has¹⁰⁺

get¹⁰⁺

set¹⁰⁺

setOrCreate¹⁰⁺

delete¹⁰⁺

keys¹⁰⁺

clear¹⁰⁺

size¹⁰⁺

Link^(deprecated)

SetAndLink^(deprecated)

Prop^(deprecated)

SetAndProp^(deprecated)

Has^(deprecated)

Get^(deprecated)

Set^(deprecated)

SetOrCreate^(deprecated)

Delete^(deprecated)

Keys^(deprecated)

staticClear^(deprecated)

Clear^(deprecated)

IsMutable^(deprecated)

Size^(deprecated)

LocalStorage⁹⁺

constructor⁹⁺

getShared¹⁰⁺

has⁹⁺

get⁹⁺

set⁹⁺

setOrCreate⁹⁺

ref¹²⁺

setAndRef¹²⁺

link⁹⁺

setAndLink⁹⁺

prop⁹⁺

setAndProp⁹⁺

delete⁹⁺

keys⁹⁺

size⁹⁺

clear⁹⁺

GetShared^(deprecated)

get¹²⁺

set¹²⁺

info¹²⁺

get⁹⁺

set⁹⁺

aboutToBeDeleted¹⁰⁺

persistProp¹⁰⁺

deleteProp¹⁰⁺

persistProps¹⁰⁺

keys¹⁰⁺

PersistProp^(deprecated)

DeleteProp^(deprecated)

PersistProps^(deprecated)

Keys^(deprecated)

envProp¹⁰⁺

envProps¹⁰⁺

keys¹⁰⁺

EnvProp^(deprecated)

EnvProps^(deprecated)

Keys^(deprecated)