diff --git a/zh-cn/application-dev/quick-start/arkts-state-mgmt-application-level.md b/zh-cn/application-dev/quick-start/arkts-state-mgmt-application-level.md index 042cf54d6fb8a055cddebca958d51c9cfcf96fee..9d0f3886baee6b3ab8519deb0866327e921b05e7 100644 --- a/zh-cn/application-dev/quick-start/arkts-state-mgmt-application-level.md +++ b/zh-cn/application-dev/quick-start/arkts-state-mgmt-application-level.md @@ -16,7 +16,7 @@ AppStorage的选择状态属性可以与不同的数据源或数据接收器同 默认情况下，AppStorage中的属性是可变的，AppStorage还可使用不可变（只读）属性。 - AppStorage的具体接口请参考[状态管理]() + AppStorage的具体接口请参考[状态管理](../reference/arkui-ts/ts-state-management.md)。 ### @StorageLink装饰器 @@ -93,6 +93,8 @@ Ability： 一个应用程序可以拥有多个Ability，一个Ability中的所 一个组件最多可以访问一个LocalStorage实例，一个LocalStorage对象可以分配给多个组件。 +LocalStorage的具体接口请参考[状态管理](../reference/arkui-ts/ts-state-management.md)。 + ## @LocalStorageLink装饰器 组件通过使用@LocalStorageLink(key)装饰的状态变量，key值为LocalStorage中的属性键值，与LocalStorage建立双向数据绑定。当创建包含@LocalStorageLink的状态变量的组件时，该状态变量的值将会使用LocalStorage中的值进行初始化。如果LocalStorage中未定义初始值，将使用@LocalStorageLink定义的初始值。在UI组件中对@LocalStorageLink的状态变量所做的更改将同步到LocalStorage中，并从LocalStorage同步到Ability下的组件中。 @@ -145,12 +147,28 @@ struct LocalStorageComponent { @LocalStorageLink("storageSimpleProp") simpleVarName: number = 0 build() { Column(){ - Text(this.simpleVarName.toString()) + Button(`LocalStorageLink: ${ this.simpleVarName.toString() }`) .onClick(()=>{ this.simpleVarName +=1; }) Text(JSON.stringify(this.simpleVarName)) .fontSize(50) + LocalStorageComponentProp(); + } + .height(500) + } +} +@Component +struct LocalStorageComponentProp { + @LocalStorageProp("storageSimpleProp") simpleVarName: number = 0 + build() { + Column() { + Button(`LocalStorageProp: ${ this.simpleVarName.toString() }`) + .onClick(() => { + this.simpleVarName += 1; + }) + Text(JSON.stringify(this.simpleVarName)) + .fontSize(50) } .height(500) } 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 new file mode 100644 index 0000000000000000000000000000000000000000..2f2f59a2351e2894d9e853805b42746830af27c8 --- /dev/null +++ b/zh-cn/application-dev/reference/arkui-ts/ts-state-management.md @@ -0,0 +1,733 @@ +# 状态管理 + +状态管理模块提供了应用程序的数据存储能力、持久化数据管理能力、Ability数据存储能力和应用程序需要的环境状态，其中Ability数据存储从API version9开始支持。 + +> 说明：本模块首批接口从API version 7开始支持，后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +## AppStorage + +### Link + +Link(propName: string): any + +与localStorage双向数据绑定。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | :--- | :--------------------- | +| propName | string | 是 | 要双向绑定的属性名称。 | + +**返回值：** + +| 类型 | 描述 | +| ----- | ------------------------------------------------------------ | +| @Link | 在具有给定键的数据，则返回到此属性的双向数据绑定，该双向绑定意味着变量或者组件对数据的更改将同步到AppStorage，通过AppStorage对数据的修改将同步到变量或者组件。 | + +```ts +let simple = AppStorage.Link('simpleProp'); +``` + +### SetAndLink + +SetAndLink\(propName: string, defaultValue: T): SubscribedAbstractProperty\ + +与Link接口类似，如果当前的key保存于AppStorage，则返回该key对应的value。如果该key未被创建，则创建一个对应default值的Link返回。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| ------------ | ------ | :--- | -------------------- | +| propName | string | 是 | 要进行创建的key值。 | +| defaultValue | T | 是 | 要进行设置的默认值。 | + +**返回值：** + +| 类型 | 描述 | +| ----- | ------------------------------------------------------------ | +| @Link | 与Link接口类似，如果当前的key保存于LocalStorage，返回该key值对应的value值。如果该key值未被创建，则创建一个对应的defaultValue的Link返回。 | + +```ts +let simple = AppStorage.SetAndLink('simpleProp',121); +``` + +### Prop + +Prop(propName: string): any + +单向属性绑定的一种。更新组件的状态。。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | :--: | ------------------- | +| propName | string | 是 | 要进行创建的key值。 | + +**返回值：** + +| 类型 | 描述 | +| ----- | ------------------------------------------------------------ | +| @Prop | 如果存在具有给定键的属性，则返回此属性的单向数据绑定。该单向绑定意味着只能通过AppStorage将属性的更改同步到变量或者组件。该方法返回的变量为不可变变量，适用于可变和不可变的状态属性，如果具有此键的属性不存在则返回undefined。 | + +```ts +let simple = AppStorage.Prop('simpleProp'); +``` + +### SetAndProp + +SetAndProp\(propName: string, defaultValue: S): SubscribedAbstractProperty\; + +与Prop接口类似，如果当前的key保存于AppStorage，则返回该key对应的value。如果该key未被创建，则创建一个对应default值的Prop返回。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| ------------ | ------ | :--: | --------------------------- | +| propName | string | 是 | 要保存的的键值对中的key值。 | +| defaultValue | S | 是 | 创建的默认值。 | + +**返回值：** + +| 类型 | 描述 | +| ----- | ------------------------------------------------------------ | +| @Prop | 如果当前的key保存与LocalStorage，返回该key值对应的value值。如果该key值未被创建，则创建一个对应的defaultValue的Prop返回。 | + +```ts +let simple = AppStorage.SetAndProp('simpleProp',121); +``` + +### Has + +Has(propName: string): boolean + +判断对应键值的属性是否存在。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | :--- | -------------- | +| propName | string | 是 | 属性的属性值。 | + +**返回值：** + +| 类型 | 描述 | +| ------- | -------------------------- | +| boolean | 返回属性的属性值是否存在。 | + +```ts +let simple = AppStorage.Has('simpleProp'); +``` + +### Get + +Get\(propName: string): T | undefined + +通过此接口获取对应key值的value。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | ---- | ------------------- | +| propName | string | 是 | 要获取对应的key值。 | + +**返回值：** + +| 类型 | 描述 | +| ------------------ | -------------------------- | +| boolean或undefined | 返回属性的属性值是否存在。 | + +```ts +let simple = AppStorage.Get('simpleProp'); +``` + +### Set + +Set(propName: string, newValue: T): boolean + +对已保存的key值，替换其value值。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | :--- | ----------------- | +| propName | string | 是 | 要设置的key值。 | +| newValue | T | 是 | 要设置的value值。 | + +**返回值：** + +| 类型 | 描述 | +| ------- | ----------------------------------------------------- | +| boolean | 如果存在key值，设置value值并返回true，否则返回false。 | + +```ts +let simple = AppStorage.Set('simpleProp'); +``` + +### SetOrCreate + +SetOrCreate(propName: string, newValue: T): void + +创建或更新setOrCreate内部的值。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | :--- | ------------------------- | +| propName | string | 是 | 要更新或者创建的key值。 | +| newValue | T | 是 | 要更新或者创建的value值。 | + +**返回值：** + +| 类型 | 描述 | +| ------- | ------------------------------------------------------------ | +| boolean | 如果已存在与给定键名字相同的属性，更新其值且返回true。如果不存在具有给定名称的属性，在LocalStorage中创建具有给定默认值的新属性，默认值必须是T类型。不允许undefined 或 null 返回true。 | + +```ts +let simple = AppStorage.SetOrCreate('simpleProp',121); +``` + +### Delete + +Delete(propName: string): boolean + +删除key指定的键值对。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | :--- | --------------------- | +| propName | string | 是 | 要删除的属性的key值。 | + +**返回值：** + +| 类型 | 描述 | +| ------- | ------------------------------------------------------------ | +| boolean | 删除key指定的键值对，如果存在且删除成功返回true，不存在或删除失败返回false。 | + +```ts +let simple = AppStorage.Delete('simpleProp'); +``` + +### keys + +keys(): IterableIterator\ + +查找所有键。 + +**返回值：** + +| 类型 | 描述 | +| -------------- | ---------------------------- | +| array\ | 返回包含所有键的字符串数组。 | + +```ts +let simple = AppStorage.Keys(); +``` + +### staticClear + +staticClear(): boolean + +删除所有的属性。 + +**返回值：** + +| 类型 | 描述 | +| ------- | ------------------------------------------------------------ | +| boolean | 删除所有的属性，如果当前有状态变量依旧引用此属性，返回false。 | + +```ts +let simple = AppStorage.staticClear(); +``` + +### IsMutable + +IsMutable(propName: string): boolean + +查询属性及状态。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | :--- | --------------------- | +| propName | string | 是 | 要查询的属性的key值。 | + +**返回值：** + +| 类型 | 描述 | +| ------- | ------------------------------------ | +| boolean | 返回此属性是否存在并且是否可以改变。 | + +```ts +let simple = AppStorage.IsMutable(); +``` + +### Size + +Size(): number + +存在的键值对的个数。 + +**返回值：** + +| 类型 | 描述 | +| ------ | ------------------ | +| number | 返回键值对的数量。 | + +```ts +let simple = AppStorage.Size(); +``` + +## LocalStorage9+ + +### constructor9+ + +constructor(initializingProperties?: Object) + +创建一个新的LocalStorage对象，并进行初始化。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| ---------------------- | ------ | ---- | ------------------------------------------------------------ | +| initializingProperties | Object | 否 | object.keys(obj)返回的所有对象属性及其值都将添加到LocalStorage。 | + +```ts +this.storage = new LocalStorage(); +``` + +### GetShared9+ + +static GetShared(): LocalStorage + +获取当前的共享的LocalStorage对象。 + +此接口仅可在Stage模型下使用。 + +**返回值：** + +| 类型 | 描述 | +| ----------------------------- | ---------------------- | +| [LocalStorage](#localstorage) | 返回LocalStorage对象。 | + +```ts +let storage = LocalStorage.GetShared(); +``` + +### has9+ + +has(propName: string): boolean + +判断属性值是否存在。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | :--- | -------------- | +| propName | string | 是 | 属性的属性值。 | + +**返回值：** + +| 类型 | 描述 | +| ------- | -------------------------- | +| boolean | 返回属性的属性值是否存在。 | + +```ts +this.storage = new LocalStorage(); +this.storage.has("storageSimpleProp"); +``` + +### get9+ + +get\(propName: string): T + +获取对应key值的value。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | :--- | ------------------- | +| propName | string | 是 | 要获取对应的key值。 | + +**返回值：** + +| 类型 | 描述 | +| -------------- | ------------------------------------------------------- | +| T \| undefined | 当keyvalue存在时，返回keyvalue值。不存在返回undefined。 | + +```ts +this.storage = new LocalStorage(); +let simpleValue = this.storage.get("storageSimpleProp"); +``` + +### set9+ + +set\(propName: string, newValue: T): boolean + +存储对象值。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | :--- | ----------------- | +| propName | string | 是 | 要设置的key值。 | +| newValue | T | 是 | 要设置的value值。 | + +**返回值：** + +| 类型 | 描述 | +| ------- | ----------------------------------------------------- | +| boolean | 如果存在key值，设置value值并返回true，否则返回false。 | + +```ts +this.storage = new LocalStorage(); +this.storage.set("storageSimpleProp",121); +``` + +### setOrCreate9+ + +setOrCreate\(propName: string, newValue: T): boolean + +创建或更新setOrCreate内部的值。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | :--- | ----------------------- | +| propName | string | 是 | 要更新或创建的key值。 | +| newValue | T | 是 | 要更新或创建的value值。 | + +**返回值：** + +| 类型 | 描述 | +| ------- | ------------------------------------------------------------ | +| boolean | 如果已存在与给定键名字相同的属性，更新其值且返回true。如果不存在具有给定名称的属性，在LocalStorage中创建具有给定默认值的新属性，默认值必须是T类型，不允许undefined 或 null 。 | + +```ts +this.storage = new LocalStorage(); +this.storage.setOrCreate("storageSimpleProp",121); +``` + +### link9+ + +link\(propName: string): T + +与localStorage双向数据绑定。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | :--- | ---------------------- | +| propName | string | 是 | 要双向绑定的属性名称。 | + +**返回值：** + +| 类型 | 描述 | +| ---- | ------------------------------------------------------------ | +| T | 如果存在具有给定键的属性，返回到此属性的双向绑定，该双向绑定意味着变量或者组件对数据的更改将同步到LocalStorage，然后通过LocalStorage实例同步到任何变量或组件。如果不存在给定键的属性，返回undefined。 | + +```ts +this.storage = new LocalStorage(); +let localStorage = this.storage.link("storageSimpleProp"); +``` + +### setAndLink9+ + +setAndLink\(propName: string, defaultValue: T): T + +与link接口类似，双向数据绑定localStorage。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| ------------ | ------ | :--- | -------------------- | +| propName | string | 是 | 要进行创建的key值。 | +| defaultValue | T | 是 | 要进行设置的默认值。 | + +**返回值：** + +| 类型 | 描述 | +| ------------------------------------ | ------------------------------------------------------------ | +| @Link | 与Link接口类似，如果当前的key保存于LocalStorage，返回该key值对应的value值。如果该key值未被创建，则创建一个对应的defaultValue的Link返回。 | + +```ts +this.storage = new LocalStorage(); +let localStorage = this.storage.setAndLink("storageSimpleProp",121); +``` + +### prop9+ + +prop\(propName: string): T + +单向属性绑定的一种。更新组件的状态。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | :--- | ----------------------- | +| propName | string | 是 | 要单向数据绑定的key值。 | + +**返回值：** + +| 类型 | 描述 | +| ------------------------------------ | ------------------------------------------------------------ | +| @Prop | 如果存在具有给定键的属性，返回此属性的单向数据绑定。该单向绑定意味着只能通过LocalStorage将属性的更改同步到变量或组件。该方法返回的变量为不可变变量，适用于可变和不可变的状态变量。如果此键的属性不存在则返回undefined。 | + +```ts +this.storage = new LocalStorage(); +let localStorage = this.storage.prop("storageSimpleProp"); +``` + +### setAndProp9+ + +setAndProp\(propName: string, defaultValue: T): T + +与Prop接口类似，存在localStorage的单向数据绑定prop值。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| ------------ | ------ | :--- | ------------------------- | +| propName | string | 是 | 要保存的键值对中的key值。 | +| defaultValue | T | 是 | 创建的默认值。 | + +**返回值：** + +| 类型 | 描述 | +| ------------------------------------ | ------------------------------------------------------------ | +| @Prop | 如果当前的key保存与LocalStorage，返回该key值对应的value值。如果该key值未被创建，则创建一个对应的defaultValue的Prop返回。 | + +```ts +this.storage = new LocalStorage(); +let localStorage = this.storage.setAndProp("storageSimpleProp",121); +``` + +### delete9+ + +delete(propName: string): boolean + +删除key指定的键值对。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| -------- | ------ | :--- | --------------------- | +| propName | string | 是 | 要删除的属性的key值。 | + +**返回值：** + +| 类型 | 描述 | +| ------- | ------------------------------------------------------------ | +| boolean | 删除key指定的键值对，如果存在且删除成功返回true，不存在或删除失败返回false。 | + +```ts +this.storage = new LocalStorage(); +this.storage.delete("storageSimpleProp"); +``` + +### keys9+ + +keys(): IterableIterator\ + +查找所有键。 + +**返回值：** + +| 类型 | 描述 | +| -------------- | ---------------------------- | +| array\ | 返回包含所有键的字符串数组。 | + +```ts +this.storage = new LocalStorage(); +let simple = this.storage.keys(); +``` + +### size9+ + +size(): number + +存在的键值对的个数。 + +**返回值：** + +| 类型 | 描述 | +| ------ | ------------------ | +| number | 返回键值对的数量。 | + +```ts +this.storage = new LocalStorage(); +let simple = this.storage.size(); +``` + +### Clear9+ + +clear(): boolean + +删除所有的属性。 + +**返回值：** + +| 类型 | 描述 | +| ------- | ------------------------------------------------------------ | +| boolean | 删除所有的属性，如果当前有状态变量依旧引用此属性，返回false。 | + +```ts +this.storage = new LocalStorage(); +let simple = this.storage.clear(); +``` + +## Persistentstorage + +### constructor + +constructor(appStorage: AppStorage, storage: Storage) + +创建一个新的persistentstorage对象。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| ---------- | ---------- | :--- | -------------------------------- | +| appStorage | AppStorage | 是 | 保存所有属性及属性值的单例对象。 | +| storage | Storage | 是 | Storage实例对象。 | + +```ts +this.persistentstorage = new PersistentStorage(AppStorage,Storage); +``` + +### PersistProp + +PersistProp(key:string,defaultValue:T):void + +关联命名的属性再AppStorage变为持久化数据。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| ------------ | ------ | :--- | ----------------------- | +| key | string | 是 | 要关联的属性的key值。 | +| defaultValue | T | 是 | 要关联的属性的value值。 | + +```ts +PersistentStorage.PersistProp("highScore", "0"); +``` + +### DeleteProp + +DeleteProp(key: string): void + +取消双向数据绑定，该属性值将从持久存储中删除。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| ------ | ------ | :--- | --------------------- | +| key | string | 是 | 要取消的属性的key值。 | + +```ts +PersistentStorage.DeleteProp("highScore"); +``` + +### PersistProps + +PersistProps(properties: {key: string, defaultValue: any}[]): void; + +关联多个命名的属性绑定。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | +| ------ | ---------------------------------- | :--: | ------------------ | +| key | {key: string, defaultValue: any}[] | 是 | 要关联的属性数组。 | + +```ts +PersistentStorage.PersistProps([{"highScore", "0"},{"wightScore","1"}]); +``` + +### Keys + +Keys(): Array + +返回所有持久化属性的标记。 + +**返回值：** + +| 类型 | 描述 | +| ------------- | -------------------------- | +| Array | 返回所有持久化属性的标记。 | + +```ts +let simple = PersistentStorage.Keys(); +``` + +> **说明：** +> +> - PersistProp接口使用时，需要保证输入对应的key应当在AppStorage存在。 +> +> - DeleteProp接口使用时，只能对本次启动已经link过的数据生效。 + +## Environment + +### constructor + +创建一个environment对象。 + +```ts +let simple = new Environment(); +``` + +### EnvProp + +EnvProp\(key: string, value: S): boolean + +关联此系统项到AppStorage中，建议在app启动时使用此接口。如果该属性在AppStorage已存在，返回false。请勿使用AppStorage中的变量，在调用此方法关联环境变量。 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | 参数描述 | +| ------ | ------ | :--- | --------------- | ----------------- | +| key | string | 是 | 要关联的key值 | 要关联的key值。 | +| value | S | 是 | 要关联的value值 | 要关联的value值。 | + +**返回值：** + +| 类型 | 描述 | +| ------- | ---------------------------------- | +| boolean | 返回该属性在AppStorage中是否存在。 | + +```ts +Environment.EnvProp("accessibilityEnabled", "default"); +``` + +### EnvProps + +EnvProps(props: {key: string;defaultValue: any}[]): void + +关联此系统项数组到AppStorage中 + +**参数：** + +| 参数名 | 类型 | 必填 | 参数描述 | 参数描述 | +| ------ | ---------------------------------- | :--- | ------------------ | ------------------ | +| key | {key: string, defaultValue: any}[] | 是 | 要关联的属性数组。 | 要关联的属性数组。 | + +```ts +Environment.EnvProps([{"accessibilityEnabled", "default"},{"accessibilityUnEnabled","undefault"}]); +``` + +### Keys + +Keys(): Array + +返回关联的系统项。 + +**返回值：** + +| 类型 | 描述 | +| ------------- | ---------------------- | +| Array | 返回关联的系统项数组。 | + +```ts +let simple = Environment.Keys(); +``` +