应用级变量的状态管理

状态管理模块提供了应用程序的数据存储能力、持久化数据管理能力、Ability 数据存储能力和应用程序需要的环境状态，其中 Ability 数据存储从 API version9 开始支持。

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

AppStorage

Link

Link(propName: string): any

与 localStorage 双向数据绑定。

参数：

参数名	类型	必填	参数描述
propName	string	是	要双向绑定的属性名称。

返回值：

类型	描述
@Link	在具有给定键的数据，则返回到此属性的双向数据绑定，该双向绑定意味着变量或者组件对数据的更改将同步到 AppStorage，通过 AppStorage 对数据的修改将同步到变量或者组件。

let simple = AppStorage.Link("simpleProp");

SetAndLink

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

与 Link 接口类似，如果当前的 key 保存于 AppStorage，则返回该 key 对应的 value。如果该 key 未被创建，则创建一个对应 default 值的 Link 返回。

参数：

参数名	类型	必填	参数描述
propName	string	是	要进行创建的 key 值。
defaultValue	T	是	要进行设置的默认值。

返回值：

类型	描述
@Link	与 Link 接口类似，如果当前的 key 保存于 LocalStorage，返回该 key 值对应的 value 值。如果该 key 值未被创建，则创建一个对应的 defaultValue 的 Link 返回。

let simple = AppStorage.SetAndLink("simpleProp", 121);

Prop

Prop(propName: string): any

单向属性绑定的一种。更新组件的状态。。

参数：

参数名	类型	必填	参数描述
propName	string	是	要进行创建的 key 值。

返回值：

类型	描述
@Prop	如果存在具有给定键的属性，则返回此属性的单向数据绑定。该单向绑定意味着只能通过 AppStorage 将属性的更改同步到变量或者组件。该方法返回的变量为不可变变量，适用于可变和不可变的状态属性，如果具有此键的属性不存在则返回 undefined。

let simple = AppStorage.Prop("simpleProp");

SetAndProp

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

与 Prop 接口类似，如果当前的 key 保存于 AppStorage，则返回该 key 对应的 value。如果该 key 未被创建，则创建一个对应 default 值的 Prop 返回。

参数：

参数名	类型	必填	参数描述
propName	string	是	要保存的的键值对中的 key 值。
defaultValue	S	是	创建的默认值。

返回值：

类型	描述
@Prop	如果当前的 key 保存与 LocalStorage，返回该 key 值对应的 value 值。如果该 key 值未被创建，则创建一个对应的 defaultValue 的 Prop 返回。

let simple = AppStorage.SetAndProp("simpleProp", 121);

Has

Has(propName: string): boolean

判断对应键值的属性是否存在。

参数：

参数名	类型	必填	参数描述
propName	string	是	属性的属性值。

返回值：

类型	描述
boolean	返回属性的属性值是否存在。

let simple = AppStorage.Has("simpleProp");

Get

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

通过此接口获取对应 key 值的 value。

参数：

参数名	类型	必填	参数描述
propName	string	是	要获取对应的 key 值。

返回值：

类型	描述
boolean 或 undefined	返回属性的属性值是否存在。

let simple = AppStorage.Get("simpleProp");

Set

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

对已保存的 key 值，替换其 value 值。

参数：

参数名	类型	必填	参数描述
propName	string	是	要设置的 key 值。
newValue	T	是	要设置的 value 值。

返回值：

类型	描述
boolean	如果存在 key 值，设置 value 值并返回 true，否则返回 false。

let simple = AppStorage.Set("simpleProp");

SetOrCreate

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

创建或更新 setOrCreate 内部的值。

参数：

参数名	类型	必填	参数描述
propName	string	是	要更新或者创建的 key 值。
newValue	T	是	要更新或者创建的 value 值。

返回值：

类型	描述
boolean	如果已存在与给定键名字相同的属性，更新其值且返回 true。如果不存在具有给定名称的属性，在 LocalStorage 中创建具有给定默认值的新属性，默认值必须是 T 类型。不允许 undefined 或 null 返回 true。

let simple = AppStorage.SetOrCreate("simpleProp", 121);

Delete

Delete(propName: string): boolean

删除 key 指定的键值对。

参数：

参数名	类型	必填	参数描述
propName	string	是	要删除的属性的 key 值。

返回值：

类型	描述
boolean	删除 key 指定的键值对，如果存在且删除成功返回 true，不存在或删除失败返回 false。

let simple = AppStorage.Delete("simpleProp");

keys

keys(): IterableIterator<string>

查找所有键。

返回值：

类型	描述
Array<string>	返回包含所有键的字符串数组。

let simple = AppStorage.Keys();

staticClear

staticClear(): boolean

删除所有的属性。

返回值：

类型	描述
boolean	删除所有的属性，如果当前有状态变量依旧引用此属性，返回 false。

let simple = AppStorage.staticClear();

IsMutable

IsMutable(propName: string): boolean

查询属性及状态。

参数：

参数名	类型	必填	参数描述
propName	string	是	要查询的属性的 key 值。

返回值：

类型	描述
boolean	返回此属性是否存在并且是否可以改变。

let simple = AppStorage.IsMutable();

Size

Size(): number

存在的键值对的个数。

返回值：

类型	描述
number	返回键值对的数量。

let simple = AppStorage.Size();

LocalStorage⁹⁺

constructor⁹⁺

constructor(initializingProperties?: Object)

创建一个新的 LocalStorage 对象，并进行初始化。

参数：

参数名	类型	必填	参数描述
initializingProperties	Object	否	object.keys(obj)返回的所有对象属性及其值都将添加到 LocalStorage。

this.storage = new LocalStorage();

GetShared⁹⁺

static GetShared(): LocalStorage

获取当前的共享的 LocalStorage 对象。

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

返回值：

类型	描述
LocalStorage	返回 LocalStorage 对象。

let storage = LocalStorage.GetShared();

has⁹⁺

has(propName: string): boolean

判断属性值是否存在。

参数：

参数名	类型	必填	参数描述
propName	string	是	属性的属性值。

返回值：

类型	描述
boolean	返回属性的属性值是否存在。

this.storage = new LocalStorage();
this.storage.has("storageSimpleProp");

get⁹⁺

get<T>(propName: string): T

获取对应 key 值的 value。

参数：

参数名	类型	必填	参数描述
propName	string	是	要获取对应的 key 值。

返回值：

类型	描述
T | undefined	当 keyvalue 存在时，返回 keyvalue 值。不存在返回 undefined。

this.storage = new LocalStorage();
let simpleValue = this.storage.get("storageSimpleProp");

set⁹⁺

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

存储对象值。

参数：

参数名	类型	必填	参数描述
propName	string	是	要设置的 key 值。
newValue	T	是	要设置的 value 值。

返回值：

类型	描述
boolean	如果存在 key 值，设置 value 值并返回 true，否则返回 false。

this.storage = new LocalStorage();
this.storage.set("storageSimpleProp", 121);

setOrCreate⁹⁺

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

创建或更新 setOrCreate 内部的值。

参数：

参数名	类型	必填	参数描述
propName	string	是	要更新或创建的 key 值。
newValue	T	是	要更新或创建的 value 值。

返回值：

类型	描述
boolean	如果已存在与给定键名字相同的属性，更新其值且返回 true。如果不存在具有给定名称的属性，在 LocalStorage 中创建具有给定默认值的新属性，默认值必须是 T 类型，不允许 undefined 或 null 。

this.storage = new LocalStorage();
this.storage.setOrCreate("storageSimpleProp", 121);

link⁹⁺

link<T>(propName: string): T

与 localStorage 双向数据绑定。

参数：

参数名	类型	必填	参数描述
propName	string	是	要双向绑定的属性名称。

返回值：

类型	描述
T	如果存在具有给定键的属性，返回到此属性的双向绑定，该双向绑定意味着变量或者组件对数据的更改将同步到 LocalStorage，然后通过 LocalStorage 实例同步到任何变量或组件。如果不存在给定键的属性，返回 undefined。

this.storage = new LocalStorage();
let localStorage = this.storage.link("storageSimpleProp");

setAndLink⁹⁺

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

与 link 接口类似，双向数据绑定 localStorage。

参数：

参数名	类型	必填	参数描述
propName	string	是	要进行创建的 key 值。
defaultValue	T	是	要进行设置的默认值。

返回值：

类型	描述
@Link	与 Link 接口类似，如果当前的 key 保存于 LocalStorage，返回该 key 值对应的 value 值。如果该 key 值未被创建，则创建一个对应的 defaultValue 的 Link 返回。

this.storage = new LocalStorage();
let localStorage = this.storage.setAndLink("storageSimpleProp", 121);

prop⁹⁺

prop<T>(propName: string): T

单向属性绑定的一种。更新组件的状态。

参数：

参数名	类型	必填	参数描述
propName	string	是	要单向数据绑定的 key 值。

返回值：

类型	描述
@Prop	如果存在具有给定键的属性，返回此属性的单向数据绑定。该单向绑定意味着只能通过 LocalStorage 将属性的更改同步到变量或组件。该方法返回的变量为不可变变量，适用于可变和不可变的状态变量。如果此键的属性不存在则返回 undefined。

this.storage = new LocalStorage();
let localStorage = this.storage.prop("storageSimpleProp");

setAndProp⁹⁺

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

与 Prop 接口类似，存在 localStorage 的单向数据绑定 prop 值。

参数：

参数名	类型	必填	参数描述
propName	string	是	要保存的键值对中的 key 值。
defaultValue	T	是	创建的默认值。

返回值：

类型	描述
@Prop	如果当前的 key 保存与 LocalStorage，返回该 key 值对应的 value 值。如果该 key 值未被创建，则创建一个对应的 defaultValue 的 Prop 返回。

this.storage = new LocalStorage();
let localStorage = this.storage.setAndProp("storageSimpleProp", 121);

delete⁹⁺

delete(propName: string): boolean

删除 key 指定的键值对。

参数：

参数名	类型	必填	参数描述
propName	string	是	要删除的属性的 key 值。

返回值：

类型	描述
boolean	删除 key 指定的键值对，如果存在且删除成功返回 true，不存在或删除失败返回 false。

this.storage = new LocalStorage();
this.storage.delete("storageSimpleProp");

keys⁹⁺

keys(): IterableIterator<string>

查找所有键。

返回值：

类型	描述
Array<string>	返回包含所有键的字符串数组。

this.storage = new LocalStorage();
let simple = this.storage.keys();

size⁹⁺

size(): number

存在的键值对的个数。

返回值：

类型	描述
number	返回键值对的数量。

this.storage = new LocalStorage();
let simple = this.storage.size();

Clear⁹⁺

clear(): boolean

删除所有的属性。

返回值：

类型	描述
boolean	删除所有的属性，如果当前有状态变量依旧引用此属性，返回 false。

this.storage = new LocalStorage();
let simple = this.storage.clear();

Persistentstorage

constructor

constructor(appStorage: AppStorage, storage: Storage)

创建一个新的 persistentstorage 对象。

参数：

参数名	类型	必填	参数描述
appStorage	AppStorage	是	保存所有属性及属性值的单例对象。
storage	Storage	是	Storage 实例对象。

this.persistentstorage = new PersistentStorage(AppStorage, Storage);

PersistProp

PersistProp(key:string,defaultValue:T):void

关联命名的属性再 AppStorage 变为持久化数据。

参数：

参数名	类型	必填	参数描述
key	string	是	要关联的属性的 key 值。
defaultValue	T	是	要关联的属性的 value 值。

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

DeleteProp

DeleteProp(key: string): void

取消双向数据绑定，该属性值将从持久存储中删除。

参数：

参数名	类型	必填	参数描述
key	string	是	要取消的属性的 key 值。

PersistentStorage.DeleteProp("highScore");

PersistProps

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

关联多个命名的属性绑定。

参数：

参数名	类型	必填	参数描述
key	{key: string, defaultValue: any}[]	是	要关联的属性数组。

PersistentStorage.PersistProps([{"highScore", "0"},{"wightScore","1"}]);

Keys

Keys(): Array<string>

返回所有持久化属性的标记。

返回值：

类型	描述
Array<string>	返回所有持久化属性的标记。

let simple = PersistentStorage.Keys();

说明：

• PersistProp 接口使用时，需要保证输入对应的 key 应当在 AppStorage 存在。

• DeleteProp 接口使用时，只能对本次启动已经 link 过的数据生效。

Environment

constructor

创建一个 environment 对象。

let simple = new Environment();

EnvProp

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

关联此系统项到 AppStorage 中，建议在 app 启动时使用此接口。如果该属性在 AppStorage 已存在，返回 false。请勿使用 AppStorage 中的变量，在调用此方法关联环境变量。

参数：

参数名	类型	必填	参数描述	参数描述
key	string	是	要关联的 key 值	要关联的 key 值。
value	S	是	要关联的 value 值	要关联的 value 值。

返回值：

类型	描述
boolean	返回该属性在 AppStorage 中是否存在。

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

EnvProps

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

关联此系统项数组到 AppStorage 中

参数：

参数名	类型	必填	参数描述	参数描述
key	{key: string, defaultValue: any}[]	是	要关联的属性数组。	要关联的属性数组。

Environment.EnvProps([{"accessibilityEnabled", "default"},{"accessibilityUnEnabled","undefault"}]);

Keys

Keys(): Array<string>

返回关联的系统项。

返回值：

类型	描述
Array<string>	返回关联的系统项数组。

let simple = Environment.Keys();