应用级变量的状态管理


应用级变量的状态管理

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

说明:

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

AppStorage

Link(propName: string): any

与localStorage双向数据绑定。

参数:

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

返回值:

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

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

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

参数:

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

返回值:

类型 描述
@Link 与Link接口类似,如果当前的key保存于AppStorage,返回该key值对应的value值。如果该key值未被创建,则创建一个对应的defaultValue的Link返回。
let simple = AppStorage.SetAndLink('simpleProp', 121)
1

Prop

Prop(propName: string): any

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

参数:

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

返回值:

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

SetAndProp

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

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

参数:

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

返回值:

类型 描述
@Prop 如果当前的key保存与AppStorage,返回该key值对应的value值。如果该key值未被创建,则创建一个对应的defaultValue的Prop返回。
let simple = AppStorage.SetAndProp('simpleProp', 121)
1

Has

Has(propName: string): boolean

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

参数:

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

返回值:

类型 描述
boolean 返回属性的属性值是否存在。
let simple = AppStorage.Has('simpleProp')
1

Get

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

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

参数:

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

返回值:

类型 描述
T或undefined 属性存在返回属性值,属性不存在返回undefined。
let simple = AppStorage.Get('simpleProp')
1

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', 121);
1

SetOrCreate

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

创建或更新setOrCreate内部的值。

参数:

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

返回值:

类型 描述
boolean 如果已存在与给定键名字相同的属性,更新其值且返回true。如果不存在具有给定名称的属性,在AppStorage中创建具有给定默认值的新属性,默认值必须是T类型。不允许undefined 或 null 返回true。
let simple = AppStorage.SetOrCreate('simpleProp', 121)
1

Delete

Delete(propName: string): boolean

删除key指定的键值对。

参数:

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

返回值:

类型 描述
boolean 删除key指定的键值对,如果存在且删除成功返回true,不存在或删除失败返回false。
let simple = AppStorage.Delete('simpleProp')
1

keys

keys(): IterableIterator<string>

查找所有键。

返回值:

类型 描述
array<string> 返回包含所有键的字符串数组。
let simple = AppStorage.Keys()
1

staticClear

staticClear(): boolean

删除所有的属性。

从API version 9开始废弃,推荐使用Clear

返回值:

类型 描述
boolean 删除所有的属性,如果当前有状态变量依旧引用此属性,返回false。
let simple = AppStorage.staticClear()
1

Clear9+

Clear(): boolean

删除所有的属性。

返回值:

类型 描述
boolean 删除所有的属性,如果当前有状态变量依旧引用此属性,返回false。
let simple = AppStorage.Clear()
1

IsMutable

IsMutable(propName: string): boolean

查询属性及状态。

参数:

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

返回值:

类型 描述
boolean 返回此属性是否存在并且是否可以改变。
let simple = AppStorage.IsMutable('simpleProp')
1

Size

Size(): number

存在的键值对的个数。

返回值:

类型 描述
number 返回键值对的数量。
let simple = AppStorage.Size()
1

LocalStorage9+

constructor9+

constructor(initializingProperties?: Object)

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

参数:

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

GetShared9+

static GetShared(): LocalStorage

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

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

返回值:

类型 描述
LocalStorage 返回LocalStorage对象。
let storage = LocalStorage.GetShared()
1

has9+

has(propName: string): boolean

判断属性值是否存在。

参数:

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

返回值:

类型 描述
boolean 返回属性的属性值是否存在。
this.storage = new LocalStorage()
this.storage.has('storageSimpleProp')
1
2

get9+

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')
1
2

set9+

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)
1
2

setOrCreate9+

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)
1
2

link9+

link<T>(propName: string): T

与localStorage双向数据绑定。

参数:

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

返回值:

类型 描述
T 如果存在具有给定键的属性,返回到此属性的双向绑定,该双向绑定意味着变量或者组件对数据的更改将同步到LocalStorage,然后通过LocalStorage实例同步到任何变量或组件。如果不存在给定键的属性,返回undefined。
this.storage = new LocalStorage()
let localStorage = this.storage.link('storageSimpleProp')
1
2

setAndLink9+

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)
1
2

prop9+

prop<T>(propName: string): T

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

参数:

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

返回值:

类型 描述
@Prop 如果存在具有给定键的属性,返回此属性的单向数据绑定。该单向绑定意味着只能通过LocalStorage将属性的更改同步到变量或组件。该方法返回的变量为不可变变量,适用于可变和不可变的状态变量。如果此键的属性不存在则返回undefined。
this.storage = new LocalStorage()
let localStorage = this.storage.prop('storageSimpleProp')
1
2

setAndProp9+

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)
1
2

delete9+

delete(propName: string): boolean

删除key指定的键值对。

参数:

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

返回值:

类型 描述
boolean 删除key指定的键值对。存在且删除成功,返回true。不存在、删除失败或有状态变量依旧引用propName,返回false。
this.storage = new LocalStorage()
this.storage.delete('storageSimpleProp')
1
2

keys9+

keys(): IterableIterator<string>

查找所有键。

返回值:

类型 描述
array<string> 返回包含所有键不可序列化的字符串数组。
this.storage = new LocalStorage()
let simple = this.storage.keys()
1
2

size9+

size(): number

存在的键值对的个数。

返回值:

类型 描述
number 返回键值对的数量。
this.storage = new LocalStorage()
let simple = this.storage.size()
1
2

Clear9+

clear(): boolean

删除所有的属性。

返回值:

类型 描述
boolean 删除所有的属性,如果当前有状态变量依旧引用此属性,返回false。
this.storage = new LocalStorage()
let simple = this.storage.clear()
1
2

PersistentStorage

constructor

constructor(appStorage: AppStorage, storage: Storage)

创建一个新的persistentstorage对象。

参数:

参数名 类型 必填 参数描述
appStorage AppStorage 保存所有属性及属性值的单例对象。
storage Storage Storage实例对象。
this.persistentstorage = new PersistentStorage(AppStorage,Storage)
1

PersistProp

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

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

参数:

参数名 类型 必填 参数描述
key string 要关联的属性的key值。
defaultValue T 要关联的属性的value值。
PersistentStorage.PersistProp('highScore', '0')
1

DeleteProp

DeleteProp(key: string): void

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

参数:

参数名 类型 必填 参数描述
key string 要取消的属性的key值。
PersistentStorage.DeleteProp('highScore')
1

PersistProps

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

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

参数:

参数名 类型 必填 参数描述
key {key: string, defaultValue: any}[] 要关联的属性数组。
PersistentStorage.PersistProps([{key: 'highScore', defaultValue: '0'},{key: 'wightScore',defaultValue: '1'}])
1

Keys

Keys(): Array<string>

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

返回值:

类型 描述
Array<string> 返回所有持久化属性的标记。
let simple = PersistentStorage.Keys()
1

说明:

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

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

Environment

constructor

创建一个environment对象。

let simple = new Environment()
1

EnvProp

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

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

参数:

参数名 类型 必填 参数描述 参数描述
key string 要关联的key值 要关联的key值,支持的范围详见内置环境变量说明。
value S 要关联的value值 要关联的value值。

返回值:

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

内置环境变量说明:

key 类型 说明
accessibilityEnabled string 无障碍屏幕朗读是否启用。
colorMode ColorMode 深浅色模式,可选值为:
- ColorMode.LIGHT:浅色模式;
- ColorMode.DARK:深色模式。
fontScale number 字体大小比例。
fontWeightScale number 字重比例。
layoutDirection LayoutDirection 布局方向类型,可选值为:
- LayoutDirection.LTR:从左到右;
- LayoutDirection.RTL:从右到左。
languageCode string 当前系统语言,小写字母,例如zh。
Environment.EnvProp('accessibilityEnabled', 'default')
1

EnvProps

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

关联此系统项数组到AppStorage中

参数:

参数名 类型 必填 参数描述 参数描述
key {key: string, defaultValue: any}[] 要关联的属性数组。 要关联的属性数组。
Environment.EnvProps([{key: 'accessibilityEnabled', defaultValue: 'default'},{key: 'accessibilityUnEnabled', defaultValue: 'undefault'}])
1

Keys

Keys(): Array<string>

返回关联的系统项。

返回值:

类型 描述
Array<string> 返回关联的系统项数组。
let simple = Environment.Keys()
1