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.

The meanings of T and S in this topic are as follows:

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

AppStorage

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

link¹⁰⁺

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

Establishes two-way data binding with the given attribute (specified by propName) in AppStorage. If the given attribute exists in AppStorage, the two-way bound data of the attribute in AppStorage is returned.

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

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

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

Return value

Type	Description
SubscribedAbstractProperty<T>	Returns two-way bound data if specified attribute exists in AppStorage; returns undefined otherwise.

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>

Works in a way similar to the link API. If the given attribute exists in AppStorage, the two-way bound data of the attribute in AppStorage is returned. If the given attribute does not exist, it is created and initialized with defaultValue in AppStorage, and two-way bound data is returned. The value of defaultValue must be of the T type and cannot be undefined or null.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
propName	string	Yes	Attribute name in AppStorage.
defaultValue	T	Yes	Default value used to initialize the attribute with the specified attribute name in AppStorage. The value cannot be undefined or null.

Return value

Type	Description
SubscribedAbstractProperty<T>	Instance of SubscribedAbstractProperty<T> and two-way bound data of the given attribute 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 one-way data binding with the given attribute (specified by propName) in AppStorage. If the given attribute exists in AppStorage, the one-way bound data of the attribute in AppStorage is returned. If the given attribute does not exist in AppStorage, undefined is returned. Updates of the one-way bound data are not synchronized back to AppStorage.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

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

Return value

Type	Description
SubscribedAbstractProperty<T>	Returns one-way bound data if specified attribute exists in AppStorage; returns undefined otherwise.

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>

Works in a way similar to the prop API. If the given attribute exists in AppStorage, the one-way bound data of the attribute in AppStorage is returned. If the given attribute does not exist, it is created and initialized with defaultValue in AppStorage, and one-way bound data is returned. The value of defaultValue must be of the T type and cannot be undefined or null.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
propName	string	Yes	Attribute name in AppStorage.
defaultValue	T	Yes	Default value used to initialize the attribute with the specified attribute name in AppStorage. The value cannot be undefined or null.

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 attribute with the specified attribute name exists in AppStorage.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

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

Return value

Type	Description
boolean	Returns true if the attribute with the specified attribute name exists in AppStorage; returns false otherwise.

Example

AppStorage.has('simpleProp');

get¹⁰⁺

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

Obtains the attribute with the specified attribute name in AppStorage. If the attribute does not exist, undefined is returned.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

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

Return value

Type	Description
T \| undefined	Returns the attribute with the specified attribute name in AppStorage; returns undefined if the attribute 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 for the attribute with the specified attribute name in AppStorage. If the value of newValue is the same as the value of the attribute with the specified attribute name, that is, no value needs to be assigned, the state variable will not instruct the UI to update the value of attribute.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

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

Return value

Type	Description
boolean	Returns true if the operation is successful; return false if the attribute with the specified attribute name does not exist in AppStorage, or the value to set is undefined or null.

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 a new value for the attribute with the specified attribute name in AppStorage or, if the attribute does not exist, creates one with the specified attribute name and the set value. If the new value is the same as the existing value of the attribute with the specified attribute name, the state variable will not instruct the UI to update the value of the attribute. This setOrCreate method creates only one AppStorage key-value pair. To create multiple key-value pairs, call this method multiple times.

The value of newValue cannot be undefined or null.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

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

Example

AppStorage.setOrCreate('simpleProp', 121);

delete¹⁰⁺

static delete(propName: string): boolean

Deletes the attribute with the specified attribute name from AppStorage under the prerequisite that the attribute does not have a subscriber. If there is a subscriber, false is returned. If the deletion is successful, true is returned.

The subscribers of the attribute are attributes with the same name bound to APIs such as link and prop, @StorageLink('propName'), and @StorageProp('propName'). This means that if @StorageLink('propName') and @StorageProp('propName') are used in a custom component or if there is still a SubscribedAbstractProperty instance in sync with the attribute, the attribute cannot be deleted from AppStorage.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
propName	string	Yes	Attribute 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 attribute names in AppStorage.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

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

Example

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

clear¹⁰⁺

static clear(): boolean

Deletes all attributes from AppStorage under the prerequisite that none of the attributes has a subscriber. If any of the attributes has a subscriber, this API does not take effect and false is returned. If the deletion is successful, true is returned.

For details about the subscriber, see delete.

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 attributes in AppStorage.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
number	Number of attributes 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 attribute.

If the given attribute 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	Attribute name in AppStorage.

Return value

Type	Description
any	Returns two-way bound data if specified attribute exists in AppStorage; returns undefined otherwise.

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>

Works in a way similar to the Link API. If the given attribute exists in AppStorage, the two-way bound data of the attribute in AppStorage is returned. If the given attribute does not exist, it is created and initialized with defaultValue in AppStorage, and two-way bound data is returned. The value of defaultValue must be of the T type and cannot be undefined or null.

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	Attribute name in AppStorage.
defaultValue	T	Yes	Default value used to initialize the attribute with the specified attribute name in AppStorage. The value cannot be undefined or null.

Return value

Type	Description
SubscribedAbstractProperty<T>	Instance of SubscribedAbstractProperty<T> and two-way bound data of the given attribute 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	Attribute name in AppStorage.

Return value

Type	Description
any	Returns one-way bound data if specified attribute exists in AppStorage; returns undefined otherwise.

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>

Works in a way similar to the Prop API. If the given attribute exists in AppStorage, the one-way bound data of the attribute in AppStorage is returned. If the given attribute does not exist, it is created and initialized with defaultValue in AppStorage, and one-way bound data is returned. The value of defaultValue must be of the S type and cannot be undefined or null.

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	Attribute name in AppStorage.
defaultValue	S	Yes	Default value used to initialize the attribute with the specified attribute name in AppStorage. The value cannot be undefined or null.

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 attribute with the specified attribute name 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	Attribute name in AppStorage.

Return value

Type	Description
boolean	Returns true if the attribute with the specified attribute name exists in AppStorage; returns false otherwise.

Example

AppStorage.Has('simpleProp');

Get^(deprecated)

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

Obtains the attribute with the specified attribute name in AppStorage. If the attribute does not exist, undefined is returned.

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	Attribute name in AppStorage.

Return value

Type	Description
T \| undefined	Returns the attribute with the specified attribute name in AppStorage; returns undefined if the attribute 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 for the attribute with the specified attribute name 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	Attribute name in AppStorage.
newValue	T	Yes	Attribute value, which cannot be undefined or null.

Return value

Type	Description
boolean	Returns true if the operation is successful; return false if the attribute with the specified attribute name does not exist in AppStorage, or the value to set is undefined or null.

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 a new value for the attribute with the specified attribute name in AppStorage or, if the attribute does not exist, creates one with the specified attribute name and default value.

The value of newValue cannot be undefined or null.

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	Attribute name in AppStorage.
newValue	T	Yes	Attribute value, which cannot be undefined or null.

Example

AppStorage.SetOrCreate('simpleProp', 121);

Delete^(deprecated)

static Delete(propName: string): boolean

The subscribers of the attribute are attributes with the same name bound to APIs such as Link and Prop, @StorageLink('propName'), and @StorageProp('propName'). This means that if @StorageLink('propName') and @StorageProp('propName') are used in a custom component or if there is still a SubscribedAbstractProperty instance in sync with the attribute, the attribute cannot be deleted from AppStorage.

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	Attribute 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 attribute 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 attribute names in AppStorage.

Example

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

staticClear^(deprecated)

static staticClear(): boolean

Deletes all attributes.

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 attributes are deleted; returns false if any of the attributes 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 given attribute in AppStorage name 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	Attribute name in AppStorage.

Return value

Type	Description
boolean	Whether the given attribute in AppStorage name is mutable.

Example

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

Size^(deprecated)

static Size(): number

Obtains the number of attributes 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 attributes 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.

constructor⁹⁺

constructor(initializingProperties?: Object)

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

NOTE

Since API version 9, this API is supported in ArkTS widgets.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
initializingProperties	Object	No	Attributes 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 by the current stage.

NOTE

Since API version 9, this API is supported in ArkTS widgets.

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 getShared, see Sharing a LocalStorage Instance from UIAbility to One or More Pages.

has⁹⁺

has(propName: string): boolean

Checks whether the attribute with the specified attribute name exists in LocalStorage.

NOTE

Since API version 9, this API is supported in ArkTS widgets.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

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

Return value

Type	Description
boolean	Returns true if the attribute with the specified attribute name 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 attribute with the specified attribute name in LocalStorage.

NOTE

Since API version 9, this API is supported in ArkTS widgets.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

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

Return value

Type	Description
T \| undefined	Returns the attribute with the specified attribute name in LocalStorage; returns undefined if the attribute 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 a value for the attribute with the specified attribute name in LocalStorage. If the value of newValue is the same as the value of the attribute with the specified attribute name, that is, no value needs to be assigned, the state variable will not instruct the UI to update the value of attribute.

NOTE

Since API version 9, this API is supported in ArkTS widgets.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

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

Return value

Type	Description
boolean	Returns true if the operation is successful; return false if the attribute with the specified attribute name does not exist in LocalStorage, or the value to set is undefined or null.

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 a new value for the attribute with the specified attribute name in LocalStorage or, if the attribute does not exist, creates one with the specified attribute name and the set value. If the new value is the same as the existing value of the attribute with the specified attribute name, the state variable will not instruct the UI to update the value of the attribute. This setOrCreate method creates only one LocalStorage key-value pair. To create multiple key-value pairs, call this method multiple times.

NOTE

Since API version 9, this API is supported in ArkTS widgets.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

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

Return value

Type	Description
boolean	Returns false if newValue is set to undefined or null. Updates the target attribute with the new value and returns true if the attribute exists in LocalStorage. Creates an attribute with the specified attribute name and default value if the attribute does not exist in LocalStorage.

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

link⁹⁺

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

Establishes two-way data binding with the given attribute in this LocalStorage instance. If the given attribute exists, the two-way bound data of the attribute in LocalStorage is returned.

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

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

NOTE

Since API version 9, this API is supported in ArkTS widgets.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

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

Return value

Type	Description
SubscribedAbstractProperty<T>	Returns the SubscribedAbstractProperty<T> instance if the given attribute 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>

Works in a way similar to the link API. If the given attribute exists in LocalStorage, the two-way bound data of the attribute in AppStorage is returned. If the given attribute does not exist, it is created and initialized with defaultValue in LocalStorage, and two-way bound data is returned. The value of defaultValue must be of the T type and cannot be undefined or null.

NOTE

Since API version 9, this API is supported in ArkTS widgets.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
propName	string	Yes	Attribute name in LocalStorage.
defaultValue	T	Yes	Default value used to initialize the attribute with the specified attribute name in LocalStorage. The value cannot be undefined or null.

Return value

Type	Description
SubscribedAbstractProperty<T>	Instance of SubscribedAbstractProperty<T> and two-way bound data of the given attribute 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 one-way data binding with the given attribute in this LocalStorage instance. If the given attribute exists, the one-way bound data of the attribute in LocalStorage is returned. If the given attribute does not exist in LocalStorage, undefined is returned. Updates of the one-way bound data are not synchronized back to LocalStorage.

NOTE

Since API version 9, this API is supported in ArkTS widgets.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

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

Return value

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

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>

Works in a way similar to the prop API. If the given attribute exists in LocalStorage, the one-way bound data of the attribute in LocalStorage is returned. If the given attribute does not exist, it is created and initialized with defaultValue in LocalStorage, and one-way bound data is returned. The value of defaultValue must be of the S type and cannot be undefined or null.

NOTE

Since API version 9, this API is supported in ArkTS widgets.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
propName	string	Yes	Attribute name in LocalStorage.
defaultValue	S	Yes	Default value used to initialize the attribute with the specified attribute name in LocalStorage. The value cannot be undefined or null.

Return value

Type	Description
SubscribedAbstractProperty<S>	Instance of SubscribedAbstractProperty<S> and one-way bound data of the given attribute 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 attribute with the specified attribute name from LocalStorage under the prerequisite that the attribute does not have a subscriber. If there is a subscriber, false is returned. If the deletion is successful, true is returned.

The subscribers of the attribute are attributes with the same name bound to APIs such as link and prop, and @StorageLink('propName') and @StorageProp('propName'). This means that if @StorageLink('propName') and @StorageProp('propName') are used in a custom component or if there is still a SubscribedAbstractProperty instance in sync with the attribute, the attribute cannot be deleted from LocalStorage.

NOTE

Since API version 9, this API is supported in ArkTS widgets.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
propName	string	Yes	Attribute 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 attribute names in LocalStorage.

NOTE

Since API version 9, this API is supported in ArkTS widgets.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
IterableIterator<string>	All attribute 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 attributes in LocalStorage.

NOTE

Since API version 9, this API is supported in ArkTS widgets.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
number	Number of attributes 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 attributes from LocalStorage under the prerequisite that none of the attributes has a subscriber. If any of the attributes has a subscriber, this API does not take effect and false is returned. If the deletion is successful, true is returned.

For details about the subscriber, see delete.

NOTE

Since API version 9, this API is supported in ArkTS widgets.

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 by the current stage.

NOTE

Since API version 9, this API is supported in ArkTS widgets.

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

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

SubscribedAbstractProperty

get⁹⁺

abstract get(): T

Obtains attribute data synchronized from AppStorage or LocalStorage.

NOTE

Since API version 9, this API is supported in ArkTS widgets.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
T	Attribute data synchronized from 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 attribute data synchronized from AppStorage or LocalStorage. The value of newValue must be of the T type and cannot be undefined or null.

NOTE

Since API version 9, this API is supported in ArkTS widgets.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
newValue	T	Yes	Data to set. The value cannot be undefined or null.

Example

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

aboutToBeDeleted¹⁰⁺

abstract aboutToBeDeleted(): void

Cancels one-way or two-way synchronization between the SubscribedAbstractProperty instance and AppStorage or LocalStorage, and invalidates the instance. After this API is called, the SubscribedAbstractProperty instance cannot be used to call the setter or getter.

System capability: SystemCapability.ArkUI.ArkUI.Full

Example

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

PersistentStorage

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

PersistPropsOptions

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Attribute name.
defaultValue	number \| string \| boolean \| Object	Yes	Default value used to initialize the created attribute when the corresponding attribute is not found in PersistentStorage and AppStorage. The value cannot be undefined or null.

persistProp¹⁰⁺

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

Persists the attribute with the specified key in AppStorage to a file. This API is usually called before access to AppStorage.

The sequence of determining the type and value of an attribute is as follows:

If the PersistentStorage file contains the attribute with the specified key, an attribute with the key as the name is created in AppStorage and initialized with the attribute of the key found in PersistentStorage.
If the attribute with the specified key is not found in the PersistentStorage file, AppStorage is searched for the attribute corresponding to the key. If the matching attribute is found, it is persisted.
If no matching attribute is found in AppStorage, it is created in AppStorage, initialized with the value of defaultValue, and persisted.

According to the preceding initialization process, if AppStorage contains the matching attribute, the value of this attribute is used to overwrite the value in the PersistentStorage file. Because AppStorage stores data in the memory, the attribute value becomes nonpersistent.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Attribute name.
defaultValue	T	Yes	Default value used to initialize the created attribute. The value cannot be undefined or null.

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 attribute corresponding to the specified key from PersistentStorage. Subsequent AppStorage operations do not affect data in PersistentStorage.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

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

Example

PersistentStorage.deleteProp('highScore');

persistProps¹⁰⁺

static persistProps(props: PersistPropsOptions[]): void

Works in a way similar to the persistProp API, with the difference that it allows for persistence in batches and is therefore ideal for initialization during application startup.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
props	PersistPropsOptions[]	Yes	Array of persistent attributes.

Example

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

keys¹⁰⁺

static keys(): Array<string>

Obtains an array of keys for all persistent attributes.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
Array<string>	Array of keys of all persistent attributes.

Example

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

PersistProp^(deprecated)

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

Persists the attribute with the specified key in AppStorage to a file. This API is usually called before access to AppStorage.

The sequence of determining the type and value of an attribute is as follows:

If the PersistentStorage file contains the attribute with the specified key, an attribute with the key as the name is created in AppStorage and initialized with the attribute of the key found in PersistentStorage.
If the attribute with the specified key is not found in the PersistentStorage file, AppStorage is searched for the attribute corresponding to the key. If the matching attribute is found, it is persisted.
If no matching attribute 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	Attribute name.
defaultValue	T	Yes	Default value used to initialize the created attribute. The value cannot be undefined or null.

Example

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

DeleteProp^(deprecated)

static DeleteProp(key: string): void

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

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	Attribute name in PersistentStorage.

Example

PersistentStorage.DeleteProp('highScore');

PersistProps^(deprecated)

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

Works in a way similar to the PersistProp API, with the difference that it allows for persistence in batches and is therefore ideal for initialization during application startup.

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 attributes to persist. key: attribute 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>

Obtains an array of keys for all persistent attributes.

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 keys of all persistent attributes.

Example

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

Environment

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

EnvPropsOptions

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 environment variable key is not found in AppStorage.

envProp¹⁰⁺

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

Saves the built-in environment variable key in environment to AppStorage. If the value of the environment variable key is not found in AppStorage, the default value is used. If the value is successfully saved, true is returned. If the value of the environment variable key is found in AppStorage, false is returned.

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.

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 attribute corresponding to the key exists in AppStorage; creates an attribute 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 attributes in batches. You are advised to call this API during application startup to save system environment variables to AppStorage in batches.

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>

Array of keys of environment variables.

System capability: SystemCapability.ArkUI.ArkUI.Full

Return value

Type	Description
Array<string>	Returns an array of associated system attributes.

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 attribute corresponding to the key exists in AppStorage; creates an attribute 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 attributes in batches. You are advised to call this API during application startup to save 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>	Returns an array of associated system attributes.

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.
languageCode	string	Current system language. The value is in lowercase, for example, zh.

State Management with Application-level Variables

AppStorage

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+

link9+

setAndLink9+

prop9+

setAndProp9+

delete9+

keys9+

size9+

clear9+

GetShared(deprecated)

SubscribedAbstractProperty

get9+

set9+

aboutToBeDeleted10+

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

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⁹⁺

link⁹⁺

setAndLink⁹⁺

prop⁹⁺

setAndProp⁹⁺

delete⁹⁺

keys⁹⁺

size⁹⁺

clear⁹⁺

GetShared^(deprecated)

get⁹⁺

set⁹⁺

aboutToBeDeleted¹⁰⁺

persistProp¹⁰⁺

deleteProp¹⁰⁺

persistProps¹⁰⁺

keys¹⁰⁺

PersistProp^(deprecated)

DeleteProp^(deprecated)

PersistProps^(deprecated)

Keys^(deprecated)

envProp¹⁰⁺

envProps¹⁰⁺

keys¹⁰⁺

EnvProp^(deprecated)

EnvProps^(deprecated)

Keys^(deprecated)