應用級變量的狀態(tài)管理

AppStorage

Link

static Link(propName: string): any

與AppStorage中對應的propName建立雙向數(shù)據(jù)綁定。如果給定的propName在AppStorage中存在，返回與AppStorage中propName對應屬性的雙向綁定數(shù)據(jù)。

雙向綁定數(shù)據(jù)的修改會同步回AppStorage中，AppStorage會將變化同步到所有綁定該propName的數(shù)據(jù)和自定義組件中。

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

參數(shù)：

返回值：

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對應的屬性的雙向綁定數(shù)據(jù)。如果不存在，則使用defaultValue在AppStorage創(chuàng)建和初始化propName，返回其雙向綁定數(shù)據(jù)。

參數(shù)：

返回值：

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對應屬性的單向綁定數(shù)據(jù)。如果AppStorage中不存在propName，則返回undefined。單向綁定數(shù)據(jù)的修改不會被同步回AppStorage中。

參數(shù)：

返回值：

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對應的屬性的單向綁定數(shù)據(jù)。如果不存在，則使用defaultValue在AppStorage創(chuàng)建和初始化propName對應的屬性，返回其單向綁定數(shù)據(jù)。

參數(shù)：

返回值：

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

Has

static Has(propName: string): boolean

判斷propName對應的屬性是否在AppStorage中存在。

參數(shù)：

返回值：

AppStorage.Has('simpleProp');

Get

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

獲取propName在AppStorage中對應的屬性。如果不存在返回undefined。

參數(shù)：

返回值：

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

Set

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

在AppStorage中設置propName對應屬性的值。如果newValue的值和propName對應屬性的值相同，即不需要做賦值操作，狀態(tài)變量不會通知UI刷新propName對應屬性的值。

參數(shù)：

返回值：

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已經(jīng)在AppStorage中存在，并且newValue和propName對應屬性的值不同，則設置propName對應屬性的值為newValue，否則狀態(tài)變量不會通知UI刷新propName對應屬性的值。

如果propName不存在，則創(chuàng)建propName屬性，值為newValue。setOrCreate只可以創(chuàng)建單個AppStorage的鍵值對，如果想創(chuàng)建多個AppStorage鍵值對，可以多次調用此方法。

參數(shù)：

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中刪除。

參數(shù)：

返回值：

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中清除所有屬性的前提是，已經(jīng)沒有任何訂閱者。如果有，則什么都不做返回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對應的屬性是否是可變的。

參數(shù)：

返回值：

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

Size

static Size(): number

返回AppStorage中的屬性數(shù)量。

返回值：

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

LocalStorage9+

constructor9+

constructor(initializingProperties?: Object)

創(chuàng)建一個新的LocalStorage實例。使用Object.keys(initializingProperties)返回的屬性和其數(shù)值，初始化LocalStorage實例。

從API version 9開始，該接口支持在ArkTS卡片中使用。

參數(shù)：

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卡片中使用。

參數(shù)：

返回值：

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

get9+

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

獲取propName在LocalStorage中對應的屬性。

從API version 9開始，該接口支持在ArkTS卡片中使用。

參數(shù)：

返回值：

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對應屬性的值相同，即不需要做賦值操作，狀態(tài)變量不會通知UI刷新propName對應屬性的值。

從API version 9開始，該接口支持在ArkTS卡片中使用。

參數(shù)：

返回值：

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已經(jīng)在LoStorage中存在，并且newValue和propName對應屬性的值不同，則設置propName對應屬性的值為newValue，否則狀態(tài)變量不會通知UI刷新propName對應屬性的值。

如果propName不存在，則創(chuàng)建propName屬性，值為newValue。setOrCreate只可以創(chuàng)建單個LocalStorage的鍵值對，如果想創(chuàng)建多個LocalStorage鍵值對，可以多次調用此方法。

從API version 9開始，該接口支持在ArkTS卡片中使用。

參數(shù)：

返回值：

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對應屬性的雙向綁定數(shù)據(jù)。

雙向綁定數(shù)據(jù)的修改會被同步回LocalStorage中，LocalStorage會將變化同步到所有綁定該propName的數(shù)據(jù)和Component中。

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

從API version 9開始，該接口支持在ArkTS卡片中使用。

參數(shù)：

返回值：

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對應的屬性的雙向綁定數(shù)據(jù)。如果不存在，則使用defaultValue在LocalStorage創(chuàng)建和初始化propName，返回其雙向綁定數(shù)據(jù)。

從API version 9開始，該接口支持在ArkTS卡片中使用。

參數(shù)：

返回值：

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對應屬性的單向綁定數(shù)據(jù)。如果LocalStorage中不存在propName，則返回undefined。單向綁定數(shù)據(jù)的修改不會被同步回LocalStorage中。

從API version 9開始，該接口支持在ArkTS卡片中使用。

參數(shù)：

返回值：

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對應的屬性的單向綁定數(shù)據(jù)。如果不存在，則使用defaultValue在LocalStorage創(chuàng)建和初始化propName對應的屬性，返回其單向綁定數(shù)據(jù)。

從API version 9開始，該接口支持在ArkTS卡片中使用。

參數(shù)：

返回值：

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對應的屬性。刪除屬性的前提是該屬性已經(jīng)沒有訂閱者，如果有則返回false。刪除成功則返回true。

屬性的訂閱者是link，prop接口綁定的propName，以及@LocalStorageLink('propName')和@LocalStorageProp('propName')。如果自定義組件Component中使用或者SubscribedAbstractProperty（link和prop接口的返回類型）依舊有同步關系，則該屬性不能從LocalStorage中刪除。

從API version 9開始，該接口支持在ArkTS卡片中使用。

參數(shù)：

返回值：

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中的屬性數(shù)量。

從API version 9開始，該接口支持在ArkTS卡片中使用。

返回值：

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

clear9+

clear(): boolean

SubscribedAbstractProperty

get9+

abstract get(): T

讀取從AppStorage/LocalStorage同步屬性的數(shù)據(jù)。

從API version 9開始，該接口支持在ArkTS卡片中使用。

返回值：

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

set9+

abstract set(newValue: T): void

PersistentStorage

PersistProp

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

將AppStorage中key對應的屬性持久化到文件中。該接口的調用通常在訪問AppStorage之前。

確定屬性的類型和值的順序如下：

1. 如果PersistentStorage文件中存在key對應的屬性，在AppStorage中創(chuàng)建對應的propName，并用在PersistentStorage中找到的key的屬性初始化；
2. 如果PersistentStorage文件中沒有查詢到key對應的屬性，則在AppStorage中查找key對應的屬性。如果找到key對應的屬性，則將該屬性持久化；
3. 如果AppStorage也沒查找到key對應的屬性，則在AppStorage中創(chuàng)建key對應的屬性。用defaultValue初始化其值，并將該屬性持久化。

根據(jù)上述的初始化流程，如果AppStorage中有該屬性，則會使用其值，覆蓋掉PersistentStorage文件中的值。由于AppStorage是內存內數(shù)據(jù)，該行為會導致數(shù)據(jù)喪失持久化能力。示例請參考在PersistentStorage之前訪問AppStorage中的屬性。

參數(shù)：

DeleteProp

static DeleteProp(key: string): void

PersistProp的逆向操作。將key對應的屬性從PersistentStorage刪除，后續(xù)AppStorage的操作，對PersistentStorage不會再有影響。

參數(shù)：

PersistentStorage.DeleteProp('highScore');

PersistProps

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

行為和PersistProp類似，不同在于可以一次性持久化多個數(shù)據(jù)，適合在應用啟動的時候初始化。

參數(shù)：

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

Keys

static Keys(): Array<string>

返回所有持久化屬性的key的數(shù)組。

返回值：

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

Environment

EnvProp

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

將Environment的內置環(huán)境變量key存入AppStorage中。如果系統(tǒng)中未查詢到Environment環(huán)境變量key的值，則使用默認值value，存入成功，返回true。如果AppStorage已經(jīng)有對應的key，則返回false。

所以建議在程序啟動的時候調用該接口。

在沒有調用EnvProp，就使用AppStorage讀取環(huán)境變量是錯誤的。

參數(shù)：

返回值：

示例：

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

內置環(huán)境變量說明

EnvProps

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

和EnvProp類似，不同點在于參數(shù)為數(shù)組，可以一次性初始化多個數(shù)據(jù)。建議在應用啟動時調用，將系統(tǒng)環(huán)境變量批量存入AppStorage中。

參數(shù)：

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

Keys

static Keys(): Array<string>

返回環(huán)境變量的屬性key的數(shù)組。

返回值：

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

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