鸿蒙：应用级变量的状态管理_appstorage.setorcreate

状态管理模块提供了应用程序的数据存储能力、持久化数据管理能力、UIAbility数据存储能力和应用程序需要的环境状态。

说明

本模块首批接口从API version 7开始支持，后续版本的新增接口，采用上角标单独标记接口的起始版本。

本文中T和S的含义如下：

AppStorage

Link

static Link(propName: string): any

与AppStorage中对应的propName建立双向数据绑定。如果给定的propName在AppStorage中存在，返回与AppStorage中propName对应属性的双向绑定数据。

双向绑定数据的修改会同步回AppStorage中，AppStorage会将变化同步到所有绑定该propName的数据和自定义组件中。

如果AppStorage中不存在propName，则返回undefined。

参数：

返回值：

AppStorage.SetOrCreate('PropA', 47);
let linkToPropA1 = AppStorage.Link('PropA');
let linkToPropA2 = AppStorage.Link('PropA'); // linkToPropA2.get() == 47
linkToPropA1.set(48); // 双向同步: linkToPropA1.get() == linkToPropA2.get() == 48

SetAndLink

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

与Link接口类似，如果给定的propName在AppStorage中存在，则返回该propName对应的属性的双向绑定数据。如果不存在，则使用defaultValue在AppStorage创建和初始化propName，返回其双向绑定数据。

参数：

返回值：

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(propName: string): any

与AppStorage中对应的propName建立单向属性绑定。如果给定的propName在AppStorage中存在，则返回与AppStorage中propName对应属性的单向绑定数据。如果AppStorage中不存在propName，则返回undefined。单向绑定数据的修改不会被同步回AppStorage中。

参数：

返回值：

AppStorage.SetOrCreate('PropA', 47);
let prop1 = AppStorage.Prop('PropA');
let prop2 = AppStorage.Prop('PropA');
prop1.set(1); // one-way sync: prop1.get()=1; but prop2.get() == 47

SetAndProp

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

与Prop接口类似。如果给定的propName在AppStorage存在，则返回该propName对应的属性的单向绑定数据。如果不存在，则使用defaultValue在AppStorage创建和初始化propName对应的属性，返回其单向绑定数据。

参数：

返回值：

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

Has

static Has(propName: string): boolean

判断propName对应的属性是否在AppStorage中存在。

参数：

返回值：

AppStorage.Has('simpleProp');

Get

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

获取propName在AppStorage中对应的属性。如果不存在返回undefined。

参数：

返回值：

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

Set

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

在AppStorage中设置propName对应属性的值。如果newValue的值和propName对应属性的值相同，即不需要做赋值操作，状态变量不会通知UI刷新propName对应属性的值。

参数：

返回值：

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

如果propName已经在AppStorage中存在，并且newValue和propName对应属性的值不同，则设置propName对应属性的值为newValue，否则状态变量不会通知UI刷新propName对应属性的值。

如果propName不存在，则创建propName属性，值为newValue。setOrCreate只可以创建单个AppStorage的键值对，如果想创建多个AppStorage键值对，可以多次调用此方法。

参数：

AppStorage.SetOrCreate('simpleProp', 121);

Delete

static Delete(propName: string): boolean

在AppStorage中删除propName对应的属性。

在AppStorage中删除该属性的前提是必须保证该属性没有订阅者。如果有订阅者，则返回false。删除成功返回true。

属性的订阅者为Link、Prop等接口绑定的propName，以及@StorageLink('propName')和@StorageProp('propName')。这就意味着如果自定义组件中使用@StorageLink('propName')和@StorageProp('propName')或者SubscribedAbstractProperty实例依旧对propName有同步关系，则该属性不能从AppStorage中删除。

参数：

返回值：

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

static Keys(): IterableIterator<string>

返回AppStorage中所有的属性名。

返回值：

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

staticClear

static staticClear(): boolean

删除所有的属性。

从API version 9开始废弃，推荐使用Clear9+。

返回值：

let simple = AppStorage.staticClear();

Clear9+

static Clear(): boolean

清除AppStorage的所有的属性。在AppStorage中清除所有属性的前提是，已经没有任何订阅者。如果有，则什么都不做返回false；删除成功返回true。

订阅者的含义和参考Delete。

返回值：

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

IsMutable

static IsMutable(propName: string): boolean

返回AppStorage中propName对应的属性是否是可变的。

参数：

返回值：

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

Size

static Size(): number

返回AppStorage中的属性数量。

返回值：

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

LocalStorage9+

constructor9+

constructor(initializingProperties?: Object)

创建一个新的LocalStorage实例。使用Object.keys(initializingProperties)返回的属性和其数值，初始化LocalStorage实例。

从API version 9开始，该接口支持在ArkTS卡片中使用。

参数：

let storage: LocalStorage = new LocalStorage({ 'PropA': 47 });

GetShared9+

static GetShared(): LocalStorage

获取当前stage共享的LocalStorage实例。使用案例可参考将LocalStorage实例从UIAbility共享到一个或多个视图。

从API version 9开始，该接口支持在ArkTS卡片中使用。

模型约束：此接口仅可在Stage模型下使用。

返回值：

let storage: LocalStorage = LocalStorage.GetShared();

has9+

has(propName: string): boolean

判断propName对应的属性是否在LocalStorage中存在。

从API version 9开始，该接口支持在ArkTS卡片中使用。

参数：

返回值：

let storage: LocalStorage = new LocalStorage({ 'PropA': 47 });
storage.has('PropA'); // true

get9+

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

获取propName在LocalStorage中对应的属性。

从API version 9开始，该接口支持在ArkTS卡片中使用。

参数：

返回值：

let storage: LocalStorage = new LocalStorage({ 'PropA': 47 });
let value: number = storage.get('PropA'); // 47

set9+

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

在LocalStorage中设置propName对应属性的值。如果newValue的值和propName对应属性的值相同，即不需要做赋值操作，状态变量不会通知UI刷新propName对应属性的值。

从API version 9开始，该接口支持在ArkTS卡片中使用。

参数：

返回值：

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

setOrCreate9+

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

如果propName已经在LoStorage中存在，并且newValue和propName对应属性的值不同，则设置propName对应属性的值为newValue，否则状态变量不会通知UI刷新propName对应属性的值。

如果propName不存在，则创建propName属性，值为newValue。setOrCreate只可以创建单个LocalStorage的键值对，如果想创建多个LocalStorage键值对，可以多次调用此方法。

从API version 9开始，该接口支持在ArkTS卡片中使用。

参数：

返回值：

let storage: LocalStorage = new LocalStorage({ 'PropA': 47 });
let res: boolean =storage.setOrCreate('PropA', 121); // true
let res1: boolean =storage.setOrCreate('PropB', 111); // true
let res2: boolean =storage.setOrCreate('PropB', undefined); // false

link9+

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

如果给定的propName在LocalStorage实例中存在，则返回与LocalStorage中propName对应属性的双向绑定数据。

双向绑定数据的修改会被同步回LocalStorage中，LocalStorage会将变化同步到所有绑定该propName的数据和Component中。

如果LocalStorage中不存在propName，则返回undefined。

从API version 9开始，该接口支持在ArkTS卡片中使用。

参数：

返回值：

let storage: LocalStorage = new LocalStorage({ 'PropA': 47 });
let linkToPropA1: SubscribedAbstractProperty<number> = storage.link('PropA');
let linkToPropA2: SubscribedAbstractProperty<number> = storage.link('PropA'); // linkToPropA2.get() == 47
linkToPropA1.set(48); // 双向同步: linkToPropA1.get() == linkToPropA2.get() == 48

setAndLink9+

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

与Link接口类似，如果给定的propName在LocalStorage存在，则返回该propName对应的属性的双向绑定数据。如果不存在，则使用defaultValue在LocalStorage创建和初始化propName，返回其双向绑定数据。

从API version 9开始，该接口支持在ArkTS卡片中使用。

参数：

返回值：

let storage: LocalStorage = new LocalStorage({ 'PropA': 47 });
let link1: SubscribedAbstractProperty<number> = storage.setAndLink('PropB', 49); // Create PropB 49
var link2: SubscribedAbstractProperty<number> = storage.setAndLink('PropA', 50); // PropA exists, remains 47

prop9+

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

如果给定的propName在LocalStorage存在，则返回与LocalStorage中propName对应属性的单向绑定数据。如果LocalStorage中不存在propName，则返回undefined。单向绑定数据的修改不会被同步回LocalStorage中。

从API version 9开始，该接口支持在ArkTS卡片中使用。

参数：

返回值：

let storage: LocalStorage = new LocalStorage({ 'PropA': 47 });
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

setAndProp9+

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

propName在LocalStorage存在，则返回该propName对应的属性的单向绑定数据。如果不存在，则使用defaultValue在LocalStorage创建和初始化propName对应的属性，返回其单向绑定数据。

从API version 9开始，该接口支持在ArkTS卡片中使用。

参数：

返回值：

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

delete9+

delete(propName: string): boolean

在LocalStorage中删除propName对应的属性。删除属性的前提是该属性已经没有订阅者，如果有则返回false。删除成功则返回true。

属性的订阅者是link，prop接口绑定的propName，以及@LocalStorageLink('propName')和@LocalStorageProp('propName')。如果自定义组件Component中使用或者SubscribedAbstractProperty（link和prop接口的返回类型）依旧有同步关系，则该属性不能从LocalStorage中删除。

从API version 9开始，该接口支持在ArkTS卡片中使用。

参数：

返回值：

let storage: LocalStorage = new LocalStorage({ 'PropA': 47 });
storage.link('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

keys9+

keys(): IterableIterator<string>

返回LocalStorage中所有的属性名。

从API version 9开始，该接口支持在ArkTS卡片中使用。

返回值：

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

size9+

size(): number

返回LocalStorage中的属性数量。

从API version 9开始，该接口支持在ArkTS卡片中使用。

返回值：

let storage: LocalStorage = new LocalStorage({ 'PropA': 47 });
let res: number = storage.size(); // 1

clear9+

clear(): boolean

清除LocalStorage的所有的属性。在LocalStorage中清除所有属性的前提是已经没有任何订阅者。如果有则返回false；清除成功返回true。

从API version 9开始，该接口支持在ArkTS卡片中使用。

返回值：

let storage: LocalStorage = new LocalStorage({ 'PropA': 47 });
let res: boolean = storage.clear(); // true, there are no subscribers

SubscribedAbstractProperty

get9+

abstract get(): T

读取从AppStorage/LocalStorage同步属性的数据。

从API version 9开始，该接口支持在ArkTS卡片中使用。

返回值：

AppStorage.SetOrCreate('PropA', 47);
let prop1 = AppStorage.Prop('PropA');
prop1.get(); // prop1.get()=47

set9+

abstract set(newValue: T): void

设置AppStorage/LocalStorage同步属性的数据。

从API version 9开始，该接口支持在ArkTS卡片中使用。

参数：

AppStorage.SetOrCreate('PropA', 47);
let prop1 = AppStorage.Prop('PropA');
prop1.set(1); // prop1.get()=1

PersistentStorage

PersistProp

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

将AppStorage中key对应的属性持久化到文件中。该接口的调用通常在访问AppStorage之前。

确定属性的类型和值的顺序如下：

1. 如果PersistentStorage文件中存在key对应的属性，在AppStorage中创建对应的propName，并用在PersistentStorage中找到的key的属性初始化；
2. 如果PersistentStorage文件中没有查询到key对应的属性，则在AppStorage中查找key对应的属性。如果找到key对应的属性，则将该属性持久化；
3. 如果AppStorage也没查找到key对应的属性，则在AppStorage中创建key对应的属性。用defaultValue初始化其值，并将该属性持久化。

根据上述的初始化流程，如果AppStorage中有该属性，则会使用其值，覆盖掉PersistentStorage文件中的值。由于AppStorage是内存内数据，该行为会导致数据丧失持久化能力。示例请参考在PersistentStorage之前访问AppStorage中的属性。

参数：

说明

AppStorage的属性向PersistentStorage中持久化的允许的类型是：

• number，string，boolean，enum基础类型。
• Object中可序列化的属性。
• 不允许undefined和null。

示例：

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

DeleteProp

static DeleteProp(key: string): void

PersistProp的逆向操作。将key对应的属性从PersistentStorage删除，后续AppStorage的操作，对PersistentStorage不会再有影响。

参数：

PersistentStorage.DeleteProp('highScore');

PersistProps

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

行为和PersistProp类似，不同在于可以一次性持久化多个数据，适合在应用启动的时候初始化。

参数：

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

Keys

static Keys(): Array<string>

返回所有持久化属性的key的数组。

返回值：

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

Environment

EnvProp

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

将Environment的内置环境变量key存入AppStorage中。如果系统中未查询到Environment环境变量key的值，则使用默认值value，存入成功，返回true。如果AppStorage已经有对应的key，则返回false。

所以建议在程序启动的时候调用该接口。

在没有调用EnvProp，就使用AppStorage读取环境变量是错误的。

参数：

返回值：

示例：

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

内置环境变量说明

EnvProps

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

和EnvProp类似，不同点在于参数为数组，可以一次性初始化多个数据。建议在应用启动时调用，将系统环境变量批量存入AppStorage中。

参数：

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

Keys

static Keys(): Array<string>

返回环境变量的属性key的数组。

返回值：

Environment.EnvProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, { key: 'languageCode', defaultValue: 'en' }, { key: 'prop', defaultValue: 'hhhh' }]);
 
let keys: Array<string> = Environment.Keys(); // accessibilityEnabled, languageCode, prop