From 02ec9efb510d34eba9e269c62e2a18265462016c Mon Sep 17 00:00:00 2001 From: zhuzijia Date: Thu, 13 Jul 2023 18:44:44 +0800 Subject: [PATCH] =?UTF-8?q?=E5=B0=8F=E9=A9=BC=E5=B3=B0=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E4=BF=AE=E6=94=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: zhuzijia Change-Id: Ida7f88ee0250705ff6a3bc4f33728700321481f7 --- .../reference/arkui-ts/ts-state-management.md | 605 +++++++++++++++++- 1 file changed, 573 insertions(+), 32 deletions(-) diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-state-management.md b/zh-cn/application-dev/reference/arkui-ts/ts-state-management.md index d097a205da..f9c7b26b89 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-state-management.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-state-management.md @@ -21,7 +21,310 @@ ## AppStorage -### Link +### link10+ + +static link(propName: string): SubscribedAbstractProperty + +与AppStorage中对应的propName建立双向数据绑定。如果给定的propName在AppStorage中存在，返回与AppStorage中propName对应属性的双向绑定数据。 + +双向绑定数据的修改会同步回AppStorage中，AppStorage会将变化同步到所有绑定该propName的数据和自定义组件中。 + +如果AppStorage中不存在propName，则返回undefined。 + + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | ---- | ---------------- | +| propName | string | 是 | AppStorage中的属性名。 | + +**返回值：** + +| 类型 | 描述 | +| ----------------------------------- | ---------------------------------------- | +| SubscribedAbstractProperty<T> | 返回双向绑定的数据，如果AppStorage不存在对应的propName，则返回undefined。 | + + +```ts +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 +``` + + +### setAndLink10+ + +static setAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T> + +与Link接口类似，如果给定的propName在AppStorage中存在，则返回该propName对应的属性的双向绑定数据。如果不存在，则使用defaultValue在AppStorage创建和初始化propName，返回其双向绑定数据。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| ------------ | ------ | ---- | ---------------------------------------- | +| propName | string | 是 | AppStorage中的属性名。 | +| defaultValue | T | 是 | 当propName在AppStorage中不存在，使用defaultValue在AppStorage中初始化对应的propName。 | + +**返回值：** + +| 类型 | 描述 | +| ----------------------------------- | ---------------------------------------- | +| SubscribedAbstractProperty<T> | SubscribedAbstractProperty<T>的实例，和AppStorage中propName对应属性的双向绑定的数据。 | + + +```ts +AppStorage.setOrCreate('PropA', 47); +let link1: SubscribedAbstractProperty = AppStorage.setAndLink('PropB', 49); // Create PropB 49 +let link2: SubscribedAbstractProperty = AppStorage.setAndLink('PropA', 50); // PropA exists, remains 47 +``` + + +### prop10+ + +static prop<T>(propName: string): SubscribedAbstractProperty<T> + +与AppStorage中对应的propName建立单向属性绑定。如果给定的propName在AppStorage中存在，则返回与AppStorage中propName对应属性的单向绑定数据。如果AppStorage中不存在propName，则返回undefined。单向绑定数据的修改不会被同步回AppStorage中。 + +>**说明：** +> Prop仅支持简单类型。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | ---- | ---------------- | +| propName | string | 是 | AppStorage中的属性名。 | + +**返回值：** + +| 类型 | 描述 | +| ----------------------------------- | ---------------------------------------- | +| SubscribedAbstractProperty<T> | 返回单向绑定的数据，如果AppStorage不存在对应的propName，则返回undefined。 | + + +```ts +AppStorage.setOrCreate('PropA', 47); +let prop1: SubscribedAbstractProperty = AppStorage.prop('PropA'); +let prop2: SubscribedAbstractProperty = AppStorage.prop('PropA'); +prop1.set(1); // one-way sync: prop1.get()=1; but prop2.get() == 47 +``` + + +### setAndProp10+ + +static setAndProp<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T> + +与Prop接口类似。如果给定的propName在AppStorage存在，则返回该propName对应的属性的单向绑定数据。如果不存在，则使用defaultValue在AppStorage创建和初始化propName对应的属性，返回其单向绑定数据。 + + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| ------------ | ------ | ---- | ---------------------------------------- | +| propName | string | 是 | AppStorage中的属性名。 | +| defaultValue | T | 是 | 当propName在AppStorage中不存在时，使用default在AppStorage中初始化对应的propName。 | + +**返回值：** + +| 类型 | 描述 | +| ----------------------------------- | --------------------------------------- | +| SubscribedAbstractProperty<T> | SubscribedAbstractProperty<T>的实例。 | + + +```ts +AppStorage.setOrCreate('PropA', 47); +let prop: SubscribedAbstractProperty = AppStorage.setAndProp('PropB', 49); // PropA -> 47, PropB -> 49 +``` + + +### has10+ + +static has(propName: string): boolean + +判断propName对应的属性是否在AppStorage中存在。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | ---- | ---------------- | +| propName | string | 是 | AppStorage中的属性名。 | + +**返回值：** + +| 类型 | 描述 | +| ------- | ---------------------------------------- | +| boolean | 如果propName对应的属性在AppStorage中存在，则返回true。不存在则返回false。 | + + +```ts +AppStorage.has('simpleProp'); +``` + + +### get10+ + +static get<T>(propName: string): T | undefined + +获取propName在AppStorage中对应的属性。如果不存在返回undefined。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | ---- | ---------------- | +| propName | string | 是 | AppStorage中的属性名。 | + +**返回值：** + +| 类型 | 描述 | +| ------------------------ | ---------------------------------------- | +| T \| undefined | AppStorage中propName对应的属性，如果不存在返回undefined。 | + + +```ts +AppStorage.setOrCreate('PropA', 47); +let value: number = AppStorage.get('PropA'); // 47 +``` + + +### set10+ + +static set<T>(propName: string, newValue: T): boolean + +在AppStorage中设置propName对应属性的值。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | ---- | ---------------------- | +| propName | string | 是 | AppStorage中的属性名。 | +| newValue | T | 是 | 属性值，不能为undefined或null。 | + +**返回值：** + +| 类型 | 描述 | +| ------- | ---------------------------------------- | +| boolean | 如果AppStorage不存在propName对应的属性，或者设置的newValue是undefined或者null，返回false。设置成功则返回true。 | + + +```ts +AppStorage.setOrCreate('PropA', 48); +let res: boolean = AppStorage.set('PropA', 47) // true +let res1: boolean = AppStorage.set('PropB', 47) // false +``` + + +### setOrCreate10+ + +static setOrCreate<T>(propName: string, newValue: T): void + +propName如果已经在AppStorage中存在，则设置propName对应是属性的值为newValue。如果不存在，则创建propName属性，值为newValue。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | ---- | ---------------------- | +| propName | string | 是 | AppStorage中的属性名。 | +| newValue | T | 是 | 属性值，不能为undefined或null。 | + + +```ts +AppStorage.setOrCreate('simpleProp', 121); +``` + + +### delete10+ + +static delete(propName: string): boolean + +在AppStorage中删除propName对应的属性。 + +在AppStorage中删除该属性的前提是必须保证该属性没有订阅者。如果有订阅者，则返回false。删除成功返回true。 + +属性的订阅者为Link、Prop等接口绑定的propName，以及\@StorageLink('propName')和\@StorageProp('propName')。这就意味着如果自定义组件中使用\@StorageLink('propName')和\@StorageProp('propName')或者SubscribedAbstractProperty实例依旧对propName有同步关系，则该属性不能从AppStorage中删除。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | ---- | ---------------- | +| propName | string | 是 | AppStorage中的属性名。 | + +**返回值：** + +| 类型 | 描述 | +| ------- | ---------------------------------------- | +| boolean | 如果AppStorage中有对应的属性，且该属性已经没有订阅者，则删除成功，返回true。如果属性不存在，或者该属性还存在订阅者，则返回false。 | + + +```ts +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 +``` + + +### keys10+ + +static keys(): IterableIterator<string> + +返回AppStorage中所有的属性名。 + +**返回值：** + +| 类型 | 描述 | +| ------------------------------ | ------------------ | +| IterableIterator<string> | AppStorage中所有的属性名。 | + + +```ts +AppStorage.setOrCreate('PropB', 48); +let keys: IterableIterator = AppStorage.keys(); +``` + + +### clear10+ + +static clear(): boolean + +清除AppStorage的所有的属性。在AppStorage中清除所有属性的前提是，已经没有任何订阅者。如果有，则什么都不做返回false；删除成功返回true。 + +订阅者的含义和参考[Delete](#delete)。 + +**返回值：** + +| 类型 | 描述 | +| ------- | ---------------------------------------- | +| boolean | 如果AppStorage中的属性已经没有订阅者，则清除成功，返回true。否则返回false。 | + + +```ts +AppStorage.setOrCreate('PropA', 47); +let res: boolean = AppStorage.clear(); // true, there are no subscribers +``` + + +### size10+ + +static size(): number + +返回AppStorage中的属性数量。 + +**返回值：** + +| 类型 | 描述 | +| ------ | ------------------- | +| number | 返回AppStorage中属性的数量。 | + + +```ts +AppStorage.setOrCreate('PropB', 48); +let res: number = AppStorage.size(); // 1 +``` + + +### Link(deprecated) static Link(propName: string): any @@ -31,6 +334,9 @@ static Link(propName: string): any 如果AppStorage中不存在propName，则返回undefined。 +从API version 10开始废弃，推荐使用[link10+](#link10)。 + + **参数：** | 参数名 | 类型 | 必填 | 参数描述 | @@ -52,12 +358,14 @@ linkToPropA1.set(48); // 双向同步: linkToPropA1.get() == linkToPropA2.get() ``` -### SetAndLink +### SetAndLink(deprecated) static SetAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T> 与Link接口类似，如果给定的propName在AppStorage中存在，则返回该propName对应的属性的双向绑定数据。如果不存在，则使用defaultValue在AppStorage创建和初始化propName，返回其双向绑定数据。 +从API version 10开始废弃，推荐使用[setAndLink10+](#setandlink10)。 + **参数：** | 参数名 | 类型 | 必填 | 参数描述 | @@ -78,8 +386,7 @@ let link1: SubscribedAbstractProperty = AppStorage.SetAndLink('PropB', 4 let link2: SubscribedAbstractProperty = AppStorage.SetAndLink('PropA', 50); // PropA exists, remains 47 ``` - -### Prop +### Prop(deprecated) static Prop(propName: string): any @@ -87,6 +394,7 @@ static Prop(propName: string): any >**说明：** > Prop仅支持简单类型。 +> 从API version 10开始废弃，推荐使用[prop10+](#prop10)。 **参数：** @@ -98,7 +406,7 @@ static Prop(propName: string): any | 类型 | 描述 | | ---- | ---------------------------------------- | -| any | 返回单向绑定的数据，如果AppStorage不存在对应的propName，在返回undefined。 | +| any | 返回单向绑定的数据，如果AppStorage不存在对应的propName，则返回undefined。 | ```ts @@ -109,12 +417,14 @@ prop1.set(1); // one-way sync: prop1.get()=1; but prop2.get() == 47 ``` -### SetAndProp +### SetAndProp(deprecated) static SetAndProp<S>(propName: string, defaultValue: S): SubscribedAbstractProperty<S> 与Prop接口类似。如果给定的propName在AppStorage存在，则返回该propName对应的属性的单向绑定数据。如果不存在，则使用defaultValue在AppStorage创建和初始化propName对应的属性，返回其单向绑定数据。 +从API version 10开始废弃，推荐使用[setAndProp10+](#setandprop10)。 + **参数：** | 参数名 | 类型 | 必填 | 参数描述 | @@ -135,12 +445,14 @@ let prop: SubscribedAbstractProperty = AppStorage.SetAndProp('PropB', 49 ``` -### Has +### Has(deprecated) static Has(propName: string): boolean 判断propName对应的属性是否在AppStorage中存在。 +从API version 10开始废弃，推荐使用[has10+](#has10)。 + **参数：** | 参数名 | 类型 | 必填 | 参数描述 | @@ -159,12 +471,14 @@ AppStorage.Has('simpleProp'); ``` -### Get +### Get(deprecated) static Get<T>(propName: string): T | undefined 获取propName在AppStorage中对应的属性。如果不存在返回undefined。 +从API version 10开始废弃，推荐使用[get10+](#get10)。 + **参数：** | 参数名 | 类型 | 必填 | 参数描述 | @@ -184,12 +498,14 @@ let value: number = AppStorage.Get('PropA'); // 47 ``` -### Set +### Set(deprecated) static Set<T>(propName: string, newValue: T): boolean 在AppStorage中设置propName对应属性的值。 +从API version 10开始废弃，推荐使用[set10+](#set10)。 + **参数：** | 参数名 | 类型 | 必填 | 参数描述 | @@ -211,12 +527,14 @@ let res1: boolean = AppStorage.Set('PropB', 47) // false ``` -### SetOrCreate +### SetOrCreate(deprecated) static SetOrCreate<T>(propName: string, newValue: T): void propName如果已经在AppStorage中存在，则设置propName对应是属性的值为newValue。如果不存在，则创建propName属性，值为newValue。 +从API version 10开始废弃，推荐使用[setOrCreate10+](#setorcreate10)。 + **参数：** | 参数名 | 类型 | 必填 | 参数描述 | @@ -230,7 +548,7 @@ AppStorage.SetOrCreate('simpleProp', 121); ``` -### Delete +### Delete(deprecated) static Delete(propName: string): boolean @@ -240,6 +558,8 @@ static Delete(propName: string): boolean 属性的订阅者为Link、Prop等接口绑定的propName，以及\@StorageLink('propName')和\@StorageProp('propName')。这就意味着如果自定义组件中使用\@StorageLink('propName')和\@StorageProp('propName')或者SubscribedAbstractProperty实例依旧对propName有同步关系，则该属性不能从AppStorage中删除。 +从API version 10开始废弃，推荐使用[delete10+](#delete10)。 + **参数：** | 参数名 | 类型 | 必填 | 参数描述 | @@ -263,12 +583,14 @@ let res1: boolean = AppStorage.Delete('PropB'); // true, PropB is deleted from A ``` -### Keys +### Keys(deprecated) static Keys(): IterableIterator<string> 返回AppStorage中所有的属性名。 +从API version 10开始废弃，推荐使用[keys10+](#keys10)。 + **返回值：** | 类型 | 描述 | @@ -282,7 +604,7 @@ let keys: IterableIterator = AppStorage.Keys(); ``` -### staticClear +### staticClear(deprecated) static staticClear(): boolean @@ -302,7 +624,7 @@ let simple = AppStorage.staticClear(); ``` -### Clear9+ +### Clear(deprecated) static Clear(): boolean @@ -310,6 +632,8 @@ static Clear(): boolean 订阅者的含义和参考[Delete](#delete)。 +从API version 10开始废弃，推荐使用[clear10+](#clear10)。 + **返回值：** | 类型 | 描述 | @@ -323,12 +647,14 @@ let res: boolean = AppStorage.Clear(); // true, there are no subscribers ``` -### IsMutable +### IsMutable(deprecated) static IsMutable(propName: string): boolean 返回AppStorage中propName对应的属性是否是可变的。 +从API version 10开始废弃。 + **参数：** | 参数名 | 类型 | 必填 | 参数描述 | @@ -348,12 +674,14 @@ let res: boolean = AppStorage.IsMutable('simpleProp'); ``` -### Size +### Size(deprecated) static Size(): number 返回AppStorage中的属性数量。 +从API version 10开始废弃，推荐使用[size10+](#size10)。 + **返回值：** | 类型 | 描述 | @@ -390,9 +718,9 @@ let storage: LocalStorage = new LocalStorage({ 'PropA': 47 }); ``` -### GetShared9+ +### getShared10+ -static GetShared(): LocalStorage +static getShared(): LocalStorage 获取当前stage共享的LocalStorage实例。 @@ -408,7 +736,7 @@ static GetShared(): LocalStorage ```ts -let storage: LocalStorage = LocalStorage.GetShared(); +let storage: LocalStorage = LocalStorage.getShared(); ``` @@ -743,6 +1071,30 @@ let res: boolean = storage.clear(); // true, there are no subscribers ``` +### GetShared(deprecated) + +static GetShared(): LocalStorage + +获取当前stage共享的LocalStorage实例。 + +从API version 9开始，该接口支持在ArkTS卡片中使用。 + +从API version 10开始废弃，推荐使用[getShared10+](#getshared10)。 + +**模型约束：**此接口仅可在Stage模型下使用。 + +**返回值：** + +| 类型 | 描述 | +| ------------------------------ | ----------------- | +| [LocalStorage](#localstorage9) | 返回LocalStorage实例。 | + + +```ts +let storage: LocalStorage = LocalStorage.GetShared(); +``` + + ## SubscribedAbstractProperty @@ -809,10 +1161,17 @@ link.set(50); // PropB -> 49, link.get() --> undefined ## PersistentStorage +### PersistPropsOptions -### PersistProp +| 参数名 | 类型 | 必填 | 参数描述 | +| ------------ | ----------------------- | ---- | ------------------------------------------------------------ | +| key | string | 是 | 属性名。 | +| defaultValue | number\|string\|boolean | 是 | 在PersistentStorage和AppStorage未查询到时，则使用默认值初始化初始化它。不允许为undefined和null。 | -static PersistProp<T>(key: string, defaultValue: T): void + +### persistProp10+ + +static persistProp<T>(key: string, defaultValue: T): void 将AppStorage中key对应的属性持久化到文件中。该接口的调用通常在访问AppStorage之前。 @@ -837,18 +1196,107 @@ static PersistProp<T>(key: string, defaultValue: T): void **示例：** +```ts +PersistentStorage.persistProp('highScore', '0'); +``` + + +### deleteProp10+ + +static deleteProp(key: string): void + +PersistProp的逆向操作。将key对应的属性从PersistentStorage删除，后续AppStorage的操作，对PersistentStorage不会再有影响。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| ---- | ------ | ---- | ----------------------- | +| key | string | 是 | PersistentStorage中的属性名。 | + + +```ts +PersistentStorage.deleteProp('highScore'); +``` + + +### persistProps10+ + +static persistProps(props: PersistPropsOptions[]): void + +行为和PersistProp类似，不同在于可以一次性持久化多个数据，适合在应用启动的时候初始化。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| ---------- | ---------------------------------------- | ---- | ---------------------------------------- | +| props | [PersistPropsOptions](#persistpropsoptions)[] | 是 | 持久化数组。 | + + +```ts +PersistentStorage.persistProps([{ key: 'highScore', defaultValue: '0' }, { key: 'wightScore', defaultValue: '1' }]); +``` + + +### keys10+ + +static keys(): Array<string> + +返回所有持久化属性的key的数组。 + +**返回值：** + +| 类型 | 描述 | +| ------------------- | ----------------- | +| Array<string> | 返回所有持久化属性的key的数组。 | + + +```ts +let keys: Array = PersistentStorage.keys(); +``` + + +### PersistProp(deprecated) + +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是内存内数据，该行为会导致数据丧失持久化能力。 + +从API version 10开始废弃，推荐使用[persistProp10+](#persistprop10)。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| ------------ | ------ | ---- | ---------------------------------------- | +| key | string | 是 | 属性名。 | +| defaultValue | T | 是 | 在PersistentStorage和AppStorage未查询到时，则使用默认值初始化初始化它。不允许为undefined和null。 | + + +**示例：** + ```ts PersistentStorage.PersistProp('highScore', '0'); ``` -### DeleteProp +### DeleteProp(deprecated) static DeleteProp(key: string): void PersistProp的逆向操作。将key对应的属性从PersistentStorage删除，后续AppStorage的操作，对PersistentStorage不会再有影响。 +从API version 10开始废弃，推荐使用[deleteProp10+](#deleteprop10)。 + **参数：** | 参数名 | 类型 | 必填 | 参数描述 | @@ -861,17 +1309,19 @@ PersistentStorage.DeleteProp('highScore'); ``` -### PersistProps +### PersistProps(deprecated) static PersistProps(properties: {key: string, defaultValue: any;}[]): void 行为和PersistProp类似，不同在于可以一次性持久化多个数据，适合在应用启动的时候初始化。 +从API version 10开始废弃，推荐使用[persistProps10+](#persistprops10)。 + **参数：** -| 参数名 | 类型 | 必填 | 参数描述 | -| ---------- | ---------------------------------------- | ---- | ---------------------------------------- | -| properties | {key: string, defaultValue: any}[] | 是 | 持久化数组，启动key为属性名，defaultValue为默认值。规则同PersistProp。 | +| 参数名 | 类型 | 必填 | 参数描述 | +| ---------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | +| properties | {key: string, defaultValue: any}[] | 是 | 持久化数组，启动key为属性名，defaultValue为默认值。规则同PersistProp。 | ```ts @@ -879,12 +1329,14 @@ PersistentStorage.PersistProps([{ key: 'highScore', defaultValue: '0' }, { key: ``` -### Keys +### Keys(deprecated) static Keys(): Array<string> 返回所有持久化属性的key的数组。 +从API version 10开始废弃，推荐使用[keys10+](#keys10-1)。 + **返回值：** | 类型 | 描述 | @@ -900,9 +1352,17 @@ let keys: Array = PersistentStorage.Keys(); ## Environment -### EnvProp +### EnvPropsOptions + +| 参数名 | 类型 | 必填 | 参数描述 | +| ------------ | ----------------------- | ---- | ------------------------------------------------------------ | +| key | string | 是 | 环境变量名称，支持的范围详见[内置环境变量说明](#内置环境变量说明)。 | +| defaultValue | number\|string\|boolean | 是 | 查询不到环境变量key，则使用defaultValue作为默认值存入AppStorage中。 | -static EnvProp<S>(key: string, value: S): boolean + +### envProp10+ + +static envProp<S>(key: string, value: S): boolean 将Environment的内置环境变量key存入AppStorage中。如果系统中未查询到Environment环境变量key的值，则使用默认值value，存入成功，返回true。如果AppStorage已经有对应的key，则返回false。 @@ -927,7 +1387,7 @@ static EnvProp<S>(key: string, value: S): boolean ```ts -Environment.EnvProp('accessibilityEnabled', 'default'); +Environment.envProp('accessibilityEnabled', 'default'); ``` @@ -943,12 +1403,91 @@ Environment.EnvProp('accessibilityEnabled', 'default'); | languageCode | string | 当前系统语言，小写字母，例如zh。 | -### EnvProps +### envProps10+ + +static envProps(props: EnvPropsOptions[]): void + +和EnvProp类似，不同点在于参数为数组，可以一次性初始化多个数据。建议在应用启动时调用，将系统环境变量批量存入AppStorage中。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| ------ | --------------------------------------------- | ---- | ------------------------------------ | +| props | [EnvPropsOptions](#envpropsoptions)[] | 是 | 系统环境变量和默认值的键值对的数组。 | + + +```ts +Environment.envProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, { + key: 'languageCode', + defaultValue: 'en' +}, { key: 'prop', defaultValue: 'hhhh' }]); +``` + + +### keys10+ + +static keys(): Array<string> + +返回环境变量的属性key的数组。 + +**返回值：** + +| 类型 | 描述 | +| ------------------- | ----------- | +| Array<string> | 返回关联的系统项数组。 | + + +```ts +Environment.envProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, { + key: 'languageCode', + defaultValue: 'en' +}, { key: 'prop', defaultValue: 'hhhh' }]); + +let keys: Array = Environment.keys(); // accessibilityEnabled, languageCode, prop +``` + + +### EnvProp(deprecated) + +static EnvProp<S>(key: string, value: S): boolean + +将Environment的内置环境变量key存入AppStorage中。如果系统中未查询到Environment环境变量key的值，则使用默认值value，存入成功，返回true。如果AppStorage已经有对应的key，则返回false。 + +所以建议在程序启动的时候调用该接口。 + +在没有调用EnvProp，就使用AppStorage读取环境变量是错误的。 + +从API version 10开始废弃，推荐使用[envProp10+](#envprop10)。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| ----- | ------ | ---- | --------------------------------------- | +| key | string | 是 | 环境变量名称，支持的范围详见[内置环境变量说明](#内置环境变量说明)。 | +| value | S | 是 | 查询不到环境变量key，则使用value作为默认值存入AppStorage中。 | + +**返回值：** + +| 类型 | 描述 | +| ------- | ---------------------------------------- | +| boolean | 如果key对应的属性在AppStorage中存在，则返回false。不存在则在AppStorage中创建key对应的属性，返回true。 | + +**示例：** + + +```ts +Environment.EnvProp('accessibilityEnabled', 'default'); +``` + + +### EnvProps(deprecated) static EnvProps(props: {key: string; defaultValue: any;}[]): void 和EnvProp类似，不同点在于参数为数组，可以一次性初始化多个数据。建议在应用启动时调用，将系统环境变量批量存入AppStorage中。 +从API version 10开始废弃，推荐使用[envProps10+](#envprops10)。 + **参数：** | 参数名 | 类型 | 必填 | 参数描述 | @@ -964,12 +1503,14 @@ Environment.EnvProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, ``` -### Keys +### Keys(deprecated) static Keys(): Array<string> 返回环境变量的属性key的数组。 +从API version 10开始废弃，推荐使用[keys10+](#keys10-2)。 + **返回值：** | 类型 | 描述 | -- GitLab