状态管理模块提供了应用的数据存储能力、持久化数据管理能力、UIAbility数据存储能力和环境状态查询能力。AppStorage是与应用进程绑定的全局UI状态存储中心,LocalStorage提供了页面级的UI状态存储能力,PersistentStorage提供了状态变量持久化的能力,Environment提供了读取系统环境变量并将其值写入AppStorage的能力。
开发指南参考:AppStorage:应用全局的UI状态存储、LocalStorage:页面级UI状态存储、PersistentStorage:持久化存储UI状态和Environment:设备环境查询。
本模块首批接口从API version 7开始支持,后续版本的新增接口,采用上角标单独标记接口的起始版本。
本文中T和S的含义如下:
| 类型 | 说明 |
|---|---|
| T | Class、number、boolean、string及这些类型的数组形式。 |
| S | number、boolean、string。 |
AppStorage是与应用进程绑定的全局UI状态存储中心,由UI框架在应用启动时创建,将UI状态数据存储于运行内存,实现应用级全局状态共享。具体UI使用说明,详见AppStorage:应用全局的UI状态存储。
static ref<T>(propName: string): AbstractProperty<T> | undefined
如果给定的propName在AppStorage中存在,则返回AppStorage中propName对应属性的引用。否则,返回undefined。
与link的功能基本一致,区别在于不需要手动释放返回的AbstractProperty<T>类型的变量。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
返回值:
| 类型 | 说明 |
|---|---|
| AbstractProperty<T> | undefined | 返回AppStorage中propName对应属性的引用,如果AppStorage中不存在对应的propName,则返回undefined。 |
示例:
AppStorage.setOrCreate('PropA', 47);
let refToPropA1: AbstractProperty<number> | undefined = AppStorage.ref('PropA');
let refToPropA2: AbstractProperty<number> | undefined = AppStorage.ref('PropA'); // refToPropA2.get() == 47
refToPropA1?.set(48); // 同步修改AppStorage:refToPropA1.get() == refToPropA2.get() == 48 static setAndRef<T>(propName: string, defaultValue: T): AbstractProperty<T>
与ref接口类似,如果给定的propName在AppStorage中存在,则返回AppStorage中propName对应属性的引用。如果不存在,则使用defaultValue在AppStorage中创建和初始化propName对应的属性,并返回其引用。
与setAndLink的功能基本一致,区别在于不需要手动释放返回的AbstractProperty<T>类型的变量。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
| defaultValue | T | 是 | 当propName在AppStorage中不存在时,使用defaultValue在AppStorage中初始化propName对应属性的值,defaultValue可以为null或undefined。 |
返回值:
| 类型 | 说明 |
|---|---|
| AbstractProperty<T> | AbstractProperty<T>的实例,为AppStorage中propName对应属性的引用。 |
示例:
AppStorage.setOrCreate('PropA', 47);
let ref1: AbstractProperty<number> = AppStorage.setAndRef('PropB', 49); // 用默认值49创建PropB
let ref2: AbstractProperty<number> = AppStorage.setAndRef('PropA', 50); // PropA已存在,值为47 static link<T>(propName: string): SubscribedAbstractProperty<T>
与AppStorage中对应的propName建立双向数据绑定。如果给定的propName在AppStorage中存在,返回AppStorage中propName对应属性的双向绑定数据。与prop的单向数据绑定不同,link的修改会同步回AppStorage,AppStorage会将变化同步到所有绑定该propName的数据和自定义组件中。
如果AppStorage中不存在propName,则返回undefined。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
返回值:
| 类型 | 说明 |
|---|---|
| SubscribedAbstractProperty<T> | 返回双向绑定的数据,如果AppStorage中不存在对应的propName,则返回undefined。 |
示例:
AppStorage.setOrCreate('PropA', 47);
let linkToPropA1: SubscribedAbstractProperty<number> = AppStorage.link('PropA');
let linkToPropA2: SubscribedAbstractProperty<number> = AppStorage.link('PropA'); // linkToPropA2.get() == 47
linkToPropA1.set(48); // 双向同步:linkToPropA1.get() == linkToPropA2.get() == 48 static setAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T>
与link接口类似,如果给定的propName在AppStorage中存在,则返回该propName对应的属性的双向绑定数据。如果不存在,则使用defaultValue在AppStorage中创建和初始化propName对应的属性,返回其双向绑定数据。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
| defaultValue | T | 是 | 当propName在AppStorage中不存在时,使用defaultValue在AppStorage中初始化propName对应属性的值。从API version 12开始,defaultValue可以为null或undefined。 |
返回值:
| 类型 | 说明 |
|---|---|
| SubscribedAbstractProperty<T> | SubscribedAbstractProperty<T>的实例,为AppStorage中propName对应属性的双向绑定的数据。 |
示例:
AppStorage.setOrCreate('PropA', 47);
let link1: SubscribedAbstractProperty<number> = AppStorage.setAndLink('PropB', 49); // 用默认值49创建PropB
let link2: SubscribedAbstractProperty<number> = AppStorage.setAndLink('PropA', 50); // PropA已存在,值为47 static prop<T>(propName: string): SubscribedAbstractProperty<T>
与AppStorage中对应的propName建立单向数据绑定。如果给定的propName在AppStorage中存在,则返回与AppStorage中propName对应属性的单向绑定数据。如果AppStorage中不存在propName,则返回undefined。单向绑定数据的修改不会同步回AppStorage中。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
返回值:
| 类型 | 说明 |
|---|---|
| SubscribedAbstractProperty<T> | 返回单向绑定的数据,如果AppStorage中不存在对应的propName,则返回undefined。 |
示例:
AppStorage.setOrCreate('PropA', 47);
let prop1: SubscribedAbstractProperty<number> = AppStorage.prop('PropA');
let prop2: SubscribedAbstractProperty<number> = AppStorage.prop('PropA');
prop1.set(1); // 单向同步:prop1.get()的值为1,prop2.get()的值为47 static setAndProp<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T>
与prop接口类似,如果给定的propName在AppStorage中存在,则返回该propName对应的属性的单向绑定数据。如果不存在,则使用defaultValue在AppStorage中创建和初始化propName对应的属性,返回其单向绑定数据。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
| defaultValue | T | 是 | 当propName在AppStorage中不存在时,使用defaultValue在AppStorage中初始化propName对应属性的值。从API version 12开始,defaultValue可以为null或undefined。 |
返回值:
| 类型 | 说明 |
|---|---|
| SubscribedAbstractProperty<T> | SubscribedAbstractProperty<T>的实例,为AppStorage中propName对应属性的单向绑定的数据。 |
示例:
AppStorage.setOrCreate('PropA', 47);
let prop: SubscribedAbstractProperty<number> = AppStorage.setAndProp('PropB', 49); // PropA -> 47, PropB -> 49 static has(propName: string): boolean
判断propName对应的属性是否在AppStorage中存在。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
返回值:
| 类型 | 说明 |
|---|---|
| boolean | 如果propName对应的属性在AppStorage中存在,则返回true。不存在则返回false。 |
示例:
AppStorage.has('simpleProp'); static get<T>(propName: string): T | undefined
获取propName在AppStorage中对应的属性值。如果不存在则返回undefined。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
返回值:
| 类型 | 说明 |
|---|---|
| T | undefined | AppStorage中propName对应的属性值,如果不存在则返回undefined。 |
示例:
AppStorage.setOrCreate('PropA', 47);
let value: number = AppStorage.get('PropA') as number; // 47 static set<T>(propName: string, newValue: T): boolean
在AppStorage中设置propName对应属性的值。如果newValue与propName对应属性的值相同,则不做赋值操作,状态变量不会通知UI刷新propName对应属性的值。与setOrCreate不同,set仅在propName已存在时生效,propName不存在时返回false。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
| newValue | T | 是 | propName对应属性的新值,从API version 12开始可以为null或undefined。 |
返回值:
| 类型 | 说明 |
|---|---|
| boolean | 如果AppStorage中不存在propName对应的属性,或设值失败,则返回false。设置成功则返回true。 |
示例:
AppStorage.setOrCreate('PropA', 48);
let res: boolean = AppStorage.set('PropA', 47); // true
let res1: boolean = AppStorage.set('PropB', 47); // false static setOrCreate<T>(propName: string, newValue: T): void
如果propName已经在AppStorage中存在,并且newValue和propName对应属性的值不同,则设置propName对应属性的值为newValue,否则状态变量不会通知UI刷新propName对应属性的值。
如果propName不存在,则创建propName属性,值为newValue。setOrCreate仅可创建单个AppStorage的键值对,如需创建多个AppStorage键值对,可多次调用此方法。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
| newValue | T | 是 | propName对应属性的新值,从API version 12开始可以为null或undefined。 |
示例:
AppStorage.setOrCreate('simpleProp', 121); static delete(propName: string): boolean
在AppStorage中删除propName对应的属性。
仅当AppStorage中该属性没有任何订阅者时可删除成功并返回true;如果有订阅者,则返回false。
属性的订阅者为:
@StorageLink、@StorageProp装饰的变量。
通过link、prop、setAndLink、setAndProp接口返回的SubscribedAbstractProperty的实例。
如需删除这些订阅者,可通过以下方式:
删除@StorageLink、@StorageProp所在的自定义组件。删除自定义组件请参考自定义组件的删除。
对link、prop、setAndLink、setAndProp接口返回的SubscribedAbstractProperty的实例调用aboutToBeDeleted接口。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
返回值:
| 类型 | 说明 |
|---|---|
| boolean | 如果AppStorage中有对应的属性,且该属性已经没有订阅者,则删除成功,返回true。如果属性不存在,或者该属性还存在订阅者,则返回false。 |
示例:
AppStorage.setOrCreate('PropA', 47);
AppStorage.link<number>('PropA');
let res: boolean = AppStorage.delete('PropA'); // false,PropA 还存在订阅者
AppStorage.setOrCreate('PropB', 48);
let res1: boolean = AppStorage.delete('PropB'); // true,PropB 已从AppStorage成功删除 static keys(): IterableIterator<string>
返回AppStorage中所有的属性名。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
| 类型 | 说明 |
|---|---|
| IterableIterator<string> | AppStorage中所有的属性名。 |
示例:
AppStorage.setOrCreate('PropB', 48);
let keys: IterableIterator<string> = AppStorage.keys(); static clear(): boolean
删除AppStorage中所有属性。仅当AppStorage没有任何订阅者时可删除成功并返回true;如果有订阅者,clear不会生效并返回false。
订阅者的含义参考delete。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
| 类型 | 说明 |
|---|---|
| boolean | 如果AppStorage中的属性已经没有订阅者则删除成功,返回true;如果当前仍有订阅者,返回false。 |
示例:
AppStorage.setOrCreate('PropA', 47);
let res: boolean = AppStorage.clear(); // true,已经没有订阅者 static size(): number
返回AppStorage中的属性数量。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
| 类型 | 说明 |
|---|---|
| number | AppStorage中属性的数量。 |
示例:
AppStorage.setOrCreate('PropB', 48);
let res: number = AppStorage.size(); // 1 static Link(propName: string): any
与AppStorage中对应的propName建立双向数据绑定。如果给定的propName在AppStorage中存在,返回与AppStorage中propName对应属性的双向绑定数据。
双向绑定数据的修改会同步回AppStorage中,AppStorage会将变化同步到所有绑定该propName的数据和自定义组件中。
如果AppStorage中不存在propName,则返回undefined。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
返回值:
| 类型 | 说明 |
|---|---|
| any | 返回双向绑定的数据,如果AppStorage中不存在对应的propName,则返回undefined。 |
示例:
AppStorage.SetOrCreate('PropA', 47);
let linkToPropA1: SubscribedAbstractProperty<number> = AppStorage.Link('PropA');
let linkToPropA2: SubscribedAbstractProperty<number> = AppStorage.Link('PropA'); // linkToPropA2.get() == 47
linkToPropA1.set(48); // 双向同步:linkToPropA1.get() == linkToPropA2.get() == 48 static SetAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T>
与Link接口类似,如果给定的propName在AppStorage中存在,则返回该propName对应的属性的双向绑定数据。如果不存在,则使用defaultValue在AppStorage中创建和初始化propName对应的属性,并返回其双向绑定数据。defaultValue必须为T类型,且不能为null或undefined。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
| defaultValue | T | 是 | 当propName在AppStorage中不存在时,使用defaultValue在AppStorage中初始化propName对应属性的值,defaultValue不能为null或undefined。 |
返回值:
| 类型 | 说明 |
|---|---|
| SubscribedAbstractProperty<T> | SubscribedAbstractProperty<T>的实例,为AppStorage中propName对应属性的双向绑定的数据。 |
示例:
AppStorage.SetOrCreate('PropA', 47);
let link1: SubscribedAbstractProperty<number> = AppStorage.SetAndLink('PropB', 49); // 用默认值49创建PropB
let link2: SubscribedAbstractProperty<number> = AppStorage.SetAndLink('PropA', 50); // PropA已存在,值为47 static Prop(propName: string): any
与AppStorage中对应的propName建立单向数据绑定。如果给定的propName在AppStorage中存在,则返回与AppStorage中propName对应属性的单向绑定数据。如果AppStorage中不存在propName,则返回undefined。单向绑定数据的修改不会同步回AppStorage中。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
返回值:
| 类型 | 说明 |
|---|---|
| any | 返回单向绑定的数据,如果AppStorage中不存在对应的propName,则返回undefined。 |
示例:
AppStorage.SetOrCreate('PropA', 47);
let prop1: SubscribedAbstractProperty<number> = AppStorage.Prop('PropA');
let prop2: SubscribedAbstractProperty<number> = AppStorage.Prop('PropA');
prop1.set(1); // 单向同步:prop1.get()的值为1,prop2.get()的值为47 static SetAndProp<S>(propName: string, defaultValue: S): SubscribedAbstractProperty<S>
与Prop接口类似,如果给定的propName在AppStorage中存在,则返回该propName对应的属性的单向绑定数据。如果不存在,则使用defaultValue在AppStorage中创建和初始化propName对应的属性,返回其单向绑定数据。defaultValue必须为S类型,且不能为null或undefined。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
| defaultValue | S | 是 | 当propName在AppStorage中不存在时,使用defaultValue在AppStorage中初始化propName对应属性的值,defaultValue不能为null或undefined。 |
返回值:
| 类型 | 说明 |
|---|---|
| SubscribedAbstractProperty<S> | SubscribedAbstractProperty<S>的实例,为AppStorage中propName对应属性的单向绑定的数据。 |
示例:
AppStorage.SetOrCreate('PropA', 47);
let prop: SubscribedAbstractProperty<number> = AppStorage.SetAndProp('PropB', 49); // PropA -> 47, PropB -> 49 static Has(propName: string): boolean
判断propName对应的属性是否在AppStorage中存在。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
返回值:
| 类型 | 说明 |
|---|---|
| boolean | 如果propName对应的属性在AppStorage中存在,则返回true。不存在则返回false。 |
示例:
AppStorage.Has('simpleProp'); static Get<T>(propName: string): T | undefined
获取propName在AppStorage中对应的属性值。如果不存在则返回undefined。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
返回值:
| 类型 | 说明 |
|---|---|
| T | undefined | AppStorage中propName对应的属性值,如果不存在则返回undefined。 |
示例:
AppStorage.SetOrCreate('PropA', 47);
let value: number = AppStorage.Get('PropA') as number; // 47 static Set<T>(propName: string, newValue: T): boolean
在AppStorage中设置propName对应属性的值。如果newValue与propName对应属性的值相同,则不做赋值操作,状态变量不会通知UI刷新propName对应属性的值。与SetOrCreate不同,Set仅在propName已存在时生效,propName不存在时返回false。从API version 12开始,newValue可以为null或undefined。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
| newValue | T | 是 | propName对应属性的新值,从API version 12开始可以为null或undefined。 |
返回值:
| 类型 | 说明 |
|---|---|
| boolean | 如果AppStorage中不存在propName对应的属性,返回false。设置成功则返回true。 |
示例:
AppStorage.SetOrCreate('PropA', 48);
let res: boolean = AppStorage.Set('PropA', 47); // true
let res1: boolean = AppStorage.Set('PropB', 47); // false static SetOrCreate<T>(propName: string, newValue: T): void
如果propName已经在AppStorage中存在,并且newValue和propName对应属性的值不同,则设置propName对应属性的值为newValue,否则状态变量不会通知UI刷新propName对应属性的值。如果不存在,则创建propName属性,值为newValue。从API version 12开始,newValue可以为null或undefined。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
| newValue | T | 是 | propName对应属性的新值,从API version 12开始可以为null或undefined。 |
示例:
AppStorage.SetOrCreate('simpleProp', 121); static Delete(propName: string): boolean
在AppStorage中删除propName对应的属性。
仅当AppStorage中该属性没有任何订阅者时可删除成功并返回true;如果有订阅者,则返回false。
属性的订阅者为Link、Prop等接口返回的实例,以及@StorageLink和@StorageProp装饰的变量。如果@StorageLink('propName')、@StorageProp('propName')装饰的变量或SubscribedAbstractProperty实例依旧对propName有同步关系,则该属性不能从AppStorage中删除。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
返回值:
| 类型 | 说明 |
|---|---|
| boolean | 如果AppStorage中有对应的属性,且该属性已经没有订阅者,则删除成功,返回true。如果属性不存在,或者该属性还存在订阅者,则返回false。 |
示例:
AppStorage.SetOrCreate('PropA', 47);
AppStorage.Link('PropA');
let res: boolean = AppStorage.Delete('PropA'); // false,PropA 还存在订阅者
AppStorage.SetOrCreate('PropB', 48);
let res1: boolean = AppStorage.Delete('PropB'); // true,PropB 已从AppStorage成功删除 static Keys(): IterableIterator<string>
返回AppStorage中所有的属性名。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
| 类型 | 说明 |
|---|---|
| IterableIterator<string> | AppStorage中所有的属性名。 |
示例:
AppStorage.SetOrCreate('PropB', 48);
let keys: IterableIterator<string> = AppStorage.Keys(); static staticClear(): boolean
删除AppStorage中所有属性。仅当AppStorage没有任何订阅者时可删除成功并返回true;如果有订阅者,staticClear不会生效并返回false。订阅者的含义参考delete。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
| 类型 | 说明 |
|---|---|
| boolean | 删除AppStorage中所有的属性。仅当没有任何订阅者时删除成功,返回true;如果仍有订阅者,返回false。 |
示例:
let clearResult = AppStorage.staticClear();
static Clear(): boolean
删除AppStorage中所有属性。前提是AppStorage已经没有任何订阅者。如果有订阅者,Clear将不会生效并返回false。如果没有订阅者且删除成功则返回true。
订阅者的含义参考delete。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
| 类型 | 说明 |
|---|---|
| boolean | 如果AppStorage中的属性已经没有订阅者则删除成功,返回true。否则返回false。 |
示例:
AppStorage.SetOrCreate('PropA', 47);
let res: boolean = AppStorage.Clear(); // true,已经没有订阅者 static IsMutable(propName: string): boolean
返回AppStorage中propName对应的属性是否是可变的。
从API version 7开始支持,从API version 10开始废弃,暂无替代接口。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | AppStorage中的属性名。 |
返回值:
| 类型 | 说明 |
|---|---|
| boolean | 返回AppStorage中propName对应的属性是否是可变的。当前该返回值恒为true。 |
示例:
AppStorage.SetOrCreate('PropA', 47);
let res: boolean = AppStorage.IsMutable('PropA'); static Size(): number
返回AppStorage中的属性数量。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
| 类型 | 说明 |
|---|---|
| number | AppStorage中属性的数量。 |
示例:
AppStorage.SetOrCreate('PropB', 48);
let res: number = AppStorage.Size(); // 1 LocalStorage是页面级的UI状态存储,通过@Entry装饰器接收的参数可以在页面内共享同一个LocalStorage实例。具体UI使用说明,详见LocalStorage:页面级UI状态存储。
constructor(initializingProperties?: Object)
创建一个新的LocalStorage实例。使用Object.keys(initializingProperties)返回的属性名及其值,初始化LocalStorage实例。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| initializingProperties | Object | 否 | 用于初始化LocalStorage,当需要在创建时预置属性数据时传入此参数。其键作为LocalStorage中的属性名,值为对应属性的初始值。initializingProperties不能为undefined。不传入时默认值为空对象,LocalStorage中不包含任何预置属性。 |
示例:
let initialData: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(initialData); has(propName: string): boolean
判断propName对应的属性是否在LocalStorage中存在。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | LocalStorage中的属性名。 |
返回值:
| 类型 | 说明 |
|---|---|
| boolean | 如果propName对应的属性在LocalStorage中存在,则返回true。不存在则返回false。 |
示例:
let initialData: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(initialData);
storage.has('PropA'); // true get<T>(propName: string): T | undefined
获取propName在LocalStorage中对应的属性值。如果不存在则返回undefined。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | LocalStorage中的属性名。 |
返回值:
| 类型 | 说明 |
|---|---|
| T | undefined | LocalStorage中propName对应的属性值,如果不存在则返回undefined。 |
示例:
let initialData: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(initialData);
let value: number = storage.get('PropA') as number; // 47 set<T>(propName: string, newValue: T): boolean
在LocalStorage中设置propName对应属性的值。如果newValue与propName对应属性的值相同,则不做赋值操作,状态变量不会通知UI刷新propName对应属性的值。与setOrCreate不同,set仅在propName已存在时生效,propName不存在时返回false。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | LocalStorage中的属性名。 |
| newValue | T | 是 | propName对应属性的新值,从API version 12开始可以为null或undefined。 |
返回值:
| 类型 | 说明 |
|---|---|
| boolean | 如果LocalStorage中不存在propName对应的属性,返回false。设置成功返回true。 |
示例:
let initialData: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(initialData);
let res: boolean = storage.set('PropA', 47); // true
let res1: boolean = storage.set('PropB', 47); // false setOrCreate<T>(propName: string, newValue: T): boolean
如果propName已经在LocalStorage中存在,并且newValue和propName对应属性的值不同,则设置propName对应属性的值为newValue,否则状态变量不会通知UI刷新propName对应属性的值。
如果propName不存在,则创建propName属性,值为newValue。setOrCreate仅可创建单个LocalStorage的键值对,如需创建多个LocalStorage键值对,可多次调用此方法。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | LocalStorage中的属性名。 |
| newValue | T | 是 | propName对应属性的新值,从API version 12开始可以为null或undefined。 |
返回值:
| 类型 | 说明 |
|---|---|
| boolean | 如果LocalStorage中存在propName,则更新其值为newValue,返回true。 如果LocalStorage中不存在propName,则创建propName,并初始化其值为newValue,返回true。 API version 12之前,当newValue为null或undefined时返回false。 |
示例:
let initialData: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(initialData);
let res: boolean = storage.setOrCreate('PropA', 121); // true
let res1: boolean = storage.setOrCreate('PropB', 111); // true
let res2: boolean = storage.setOrCreate('PropB', null); // true(API version 12及之后返回true,API version 11及之前返回false) ref<T>(propName: string): AbstractProperty<T> | undefined
如果给定的propName在LocalStorage中存在,则返回LocalStorage中propName对应属性的引用。否则,返回undefined。
与link的功能基本一致,区别在于不需要手动释放返回的AbstractProperty<T>类型的变量。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | LocalStorage中的属性名。 |
返回值:
| 类型 | 说明 |
|---|---|
| AbstractProperty<T> | undefined | 返回LocalStorage中propName对应属性的引用,如果LocalStorage中不存在对应的propName,则返回undefined。 |
示例:
let initialData: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(initialData);
let refToPropA1: AbstractProperty<number> | undefined = storage.ref('PropA');
let refToPropA2: AbstractProperty<number> | undefined = storage.ref('PropA'); // refToPropA2.get() == 47
refToPropA1?.set(48); // refToPropA1.get() == refToPropA2.get() == 48 setAndRef<T>(propName: string, defaultValue: T): AbstractProperty<T>
与ref接口类似,如果给定的propName在LocalStorage中存在,则返回LocalStorage中propName对应属性的引用。如果不存在,则使用defaultValue在LocalStorage中创建和初始化propName对应的属性,并返回其引用。
与setAndLink的功能基本一致,区别在于不需要手动释放返回的AbstractProperty<T>类型的变量。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | LocalStorage中的属性名。 |
| defaultValue | T | 是 | 当propName在LocalStorage中不存在时,使用defaultValue在LocalStorage中初始化propName对应属性的值,defaultValue可以为null或undefined。 |
返回值:
| 类型 | 说明 |
|---|---|
| AbstractProperty<T> | AbstractProperty<T>的实例,为LocalStorage中propName对应属性的引用。 |
示例:
let initialData: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(initialData);
let ref1: AbstractProperty<number> = storage.setAndRef('PropB', 49); // 用默认值49创建PropB
let ref2: AbstractProperty<number> = storage.setAndRef('PropA', 50); // PropA已存在,值为47 link<T>(propName: string): SubscribedAbstractProperty<T>
如果给定的propName在LocalStorage实例中存在,则返回与LocalStorage中propName对应属性的双向绑定数据。与prop的单向数据绑定不同,link建立双向数据绑定,修改会同步回LocalStorage,LocalStorage会将变化同步到所有绑定该propName的数据和自定义组件中。
如果LocalStorage中不存在propName,则返回undefined。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | LocalStorage中的属性名。 |
返回值:
| 类型 | 说明 |
|---|---|
| SubscribedAbstractProperty<T> | SubscribedAbstractProperty<T>的实例,与LocalStorage中propName对应属性的双向绑定的数据,如果LocalStorage中不存在对应的propName,则返回undefined。 |
示例:
let initialData: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(initialData);
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 setAndLink<T>(propName: string, defaultValue: T): SubscribedAbstractProperty<T>
与link接口类似,如果给定的propName在LocalStorage中存在,则返回该propName对应的属性的双向绑定数据。如果不存在,则使用defaultValue在LocalStorage中创建和初始化propName对应的属性,返回其双向绑定数据。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | LocalStorage中的属性名。 |
| defaultValue | T | 是 | 当propName在LocalStorage中不存在时,使用defaultValue在LocalStorage中初始化propName对应属性的值。从API version 12开始,defaultValue可以为null或undefined。 |
返回值:
| 类型 | 说明 |
|---|---|
| SubscribedAbstractProperty<T> | SubscribedAbstractProperty<T>的实例,与LocalStorage中propName对应属性的双向绑定的数据。 |
示例:
let initialData: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(initialData);
let link1: SubscribedAbstractProperty<number> = storage.setAndLink('PropB', 49); // 用默认值49创建PropB
let link2: SubscribedAbstractProperty<number> = storage.setAndLink('PropA', 50); // PropA已存在,值为47 prop<S>(propName: string): SubscribedAbstractProperty<S>
如果给定的propName在LocalStorage中存在,则返回与LocalStorage中propName对应属性的单向绑定数据。如果LocalStorage中不存在propName,则返回undefined。单向绑定数据的修改不会同步回LocalStorage中。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | LocalStorage中的属性名。 |
返回值:
| 类型 | 说明 |
|---|---|
| SubscribedAbstractProperty<S> | SubscribedAbstractProperty<S>的实例,为LocalStorage中propName对应属性的单向绑定的数据。如果LocalStorage中不存在对应的propName,则返回undefined。 |
示例:
let initialData: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(initialData);
let prop1: SubscribedAbstractProperty<number> = storage.prop('PropA');
let prop2: SubscribedAbstractProperty<number> = storage.prop('PropA');
prop1.set(1); // 单向同步:prop1.get()的值为1,prop2.get()的值为47 setAndProp<S>(propName: string, defaultValue: S): SubscribedAbstractProperty<S>
与prop接口类似,如果给定的propName在LocalStorage中存在,则返回该propName对应的属性的单向绑定数据。如果不存在,则使用defaultValue在LocalStorage中创建和初始化propName对应的属性,返回其单向绑定数据。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | LocalStorage中的属性名。 |
| defaultValue | S | 是 | 当propName在LocalStorage中不存在时,使用defaultValue在LocalStorage中初始化propName对应属性的值。从API version 12开始,defaultValue可以为null或undefined。 |
返回值:
| 类型 | 说明 |
|---|---|
| SubscribedAbstractProperty<S> | SubscribedAbstractProperty<S>的实例,为LocalStorage中propName对应属性的单向绑定的数据。 |
示例:
let initialData: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(initialData);
let prop: SubscribedAbstractProperty<number> = storage.setAndProp('PropB', 49); // PropA -> 47, PropB -> 49 delete(propName: string): boolean
在LocalStorage中删除propName对应的属性。仅当LocalStorage中该属性没有任何订阅者时可删除成功并返回true;如果有订阅者,则返回false。
属性的订阅者为:
通过link、prop、setAndLink、setAndProp接口返回的SubscribedAbstractProperty的实例。
如需删除这些订阅者,可通过以下方式:
删除@LocalStorageLink、@LocalStorageProp所在的自定义组件。删除自定义组件请参考自定义组件的删除。
对link、prop、setAndLink、setAndProp接口返回的SubscribedAbstractProperty的实例调用aboutToBeDeleted接口。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| propName | string | 是 | LocalStorage中的属性名。 |
返回值:
| 类型 | 说明 |
|---|---|
| boolean | 如果LocalStorage中有对应的属性,且该属性已经没有订阅者,则删除成功,返回true。如果属性不存在,或者该属性还存在订阅者,则返回false。 |
示例:
let initialData: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(initialData);
storage.link<number>('PropA');
let res: boolean = storage.delete('PropA'); // false,PropA 还存在订阅者
let res1: boolean = storage.delete('PropB'); // false,PropB 不存在于storage中
storage.setOrCreate('PropB', 48);
let res2: boolean = storage.delete('PropB'); // true,PropB 已从storage成功删除 keys(): IterableIterator<string>
返回LocalStorage中所有的属性名。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
| 类型 | 说明 |
|---|---|
| IterableIterator<string> | LocalStorage中所有的属性名。 |
示例:
let initialData: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(initialData);
let keys: IterableIterator<string> = storage.keys(); size(): number
返回LocalStorage中的属性数量。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
| 类型 | 说明 |
|---|---|
| number | LocalStorage中属性的数量。 |
示例:
let initialData: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(initialData);
let res: number = storage.size(); // 1 clear(): boolean
删除LocalStorage中所有的属性。仅当LocalStorage中的属性没有任何订阅者时可删除成功并返回true;如果有订阅者,clear不会生效并返回false。
订阅者的含义参考delete。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
| 类型 | 说明 |
|---|---|
| boolean | 如果LocalStorage中的属性已经没有任何订阅者,则删除成功,并返回true。否则返回false。 |
示例:
let initialData: Record<string, number> = { 'PropA': 47 };
let storage: LocalStorage = new LocalStorage(initialData);
let res: boolean = storage.clear(); // true,已经没有订阅者 AbstractProperty是AppStorage/LocalStorage中属性的引用,提供读取、修改所引用属性数据及查询属性名的能力。与SubscribedAbstractProperty不同,AbstractProperty实例无需手动释放。
从API version 12开始,AppStorage/LocalStorage支持Map、Set、Date类型,支持null、undefined以及联合类型。
get(): T
读取AppStorage/LocalStorage中所引用属性的数据。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
| 类型 | 说明 |
|---|---|
| T | AppStorage/LocalStorage中所引用属性的数据。 |
示例:
AppStorage.setOrCreate('PropA', 47);
let ref1: AbstractProperty<number> | undefined = AppStorage.ref('PropA');
ref1?.get(); // ref1.get()=47 set(newValue: T): void
更新AppStorage/LocalStorage中所引用属性的数据,newValue必须是T类型,可以为null或undefined。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| newValue | T | 是 | AppStorage/LocalStorage中所引用属性的新值,可以为null或undefined。 |
示例:
AppStorage.setOrCreate('PropA', 47);
let ref1: AbstractProperty<number> | undefined = AppStorage.ref('PropA');
ref1?.set(1); // ref1.get()=1
let mapValue: Map<string, number> = new Map([['1', 0]]);
let ref2 = AppStorage.setAndRef('MapA', mapValue);
ref2.set(mapValue);
let setValue: Set<string> = new Set(['1']);
let ref3 = AppStorage.setAndRef('SetB', setValue);
ref3.set(setValue);
let dateValue: Date = new Date('2024');
let ref4 = AppStorage.setAndRef('DateC', dateValue);
ref4.set(dateValue);
ref2.set(null);
ref3.set(undefined); info(): string
读取AppStorage/LocalStorage中所引用属性的属性名。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
| 类型 | 说明 |
|---|---|
| string | AppStorage/LocalStorage中所引用属性的属性名。 |
示例:
AppStorage.setOrCreate('PropA', 47);
let ref1: AbstractProperty<number> | undefined = AppStorage.ref('PropA');
ref1?.info(); // ref1.info()='PropA' SubscribedAbstractProperty是AppStorage/LocalStorage中属性的单/双向同步绑定对象,用于与AppStorage/LocalStorage中的属性建立数据同步关系。SubscribedAbstractProperty实例需要通过aboutToBeDeleted接口手动释放,以取消同步关系并无效化实例。
从API version 12开始,AppStorage/LocalStorage支持Map、Set、Date类型,支持null、undefined以及联合类型。
abstract get(): T
读取AppStorage/LocalStorage中所同步属性的数据。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
| 类型 | 说明 |
|---|---|
| T | AppStorage/LocalStorage同步属性的数据。 |
示例:
AppStorage.setOrCreate('PropA', 47);
let prop1: SubscribedAbstractProperty<number> = AppStorage.prop('PropA');
prop1.get(); // prop1.get()=47 abstract set(newValue: T): void
设置AppStorage/LocalStorage中所同步属性的数据,newValue必须是T类型,从API version 12开始可以为null或undefined。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| newValue | T | 是 | AppStorage/LocalStorage中所同步属性的新值,从API version 12开始可以为null或undefined。 |
示例:
AppStorage.setOrCreate('PropA', 47);
let prop1: SubscribedAbstractProperty<number> = AppStorage.prop('PropA');
prop1.set(1); // prop1.get()=1
// 从API version 12开始支持Map、Set、Date类型,支持null、undefined以及联合类型。
let mapValue: Map<string, number> = new Map([['1', 0]]);
let prop2 = AppStorage.setAndProp('MapA', mapValue);
prop2.set(mapValue);
let setValue: Set<string> = new Set(['1']);
let prop3 = AppStorage.setAndProp('SetB', setValue);
prop3.set(setValue);
let dateValue: Date = new Date('2024');
let prop4 = AppStorage.setAndProp('DateC', dateValue);
prop4.set(dateValue);
prop2.set(null);
prop3.set(undefined); abstract aboutToBeDeleted(): void
取消SubscribedAbstractProperty实例对AppStorage/LocalStorage的单向或双向同步关系,并无效化SubscribedAbstractProperty实例。即调用aboutToBeDeleted方法之后,不能再使用SubscribedAbstractProperty实例调用set或get方法。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
示例:
AppStorage.setOrCreate('PropA', 47);
let link = AppStorage.setAndLink('PropB', 49); // PropA -> 47, PropB -> 49
link.aboutToBeDeleted(); info(): string
返回AppStorage/LocalStorage中所同步属性的属性名。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
| 类型 | 说明 |
|---|---|
| string | AppStorage/LocalStorage中所同步属性的属性名。 |
示例:
AppStorage.setOrCreate('PropA', 47);
let prop1: SubscribedAbstractProperty<number> = AppStorage.prop('PropA');
prop1.info(); // prop1.info() = 'PropA' 用于指定持久化属性及其默认值的键值对对象,作为persistProps参数传入。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| key | string | 否 | 否 | 要持久化的属性名。 |
| defaultValue | number | string | boolean | Object | 否 | 否 | 在PersistentStorage和AppStorage中未查询到时,则使用默认值进行初始化。从API version 12开始,defaultValue可以为null或undefined。 |
PersistentStorage提供了UI状态的持久化存储能力,将选定的AppStorage属性持久化到文件中,在应用重启时从文件中恢复这些属性值并写入到AppStorage。具体UI使用说明,详见PersistentStorage:持久化存储UI状态。
从API version 12开始,PersistentStorage支持null、undefined。
static persistProp<T>(key: string, defaultValue: T): void
将AppStorage中key对应的属性持久化到文件中。该接口通常在访问AppStorage之前调用。
确定属性的类型和值的顺序如下:
如果PersistentStorage文件中存在key对应的属性,在AppStorage中创建对应的key,并用在PersistentStorage中找到的key的属性初始化。
如果PersistentStorage文件中没有查询到key对应的属性,则在AppStorage中查找key对应的属性。如果找到key对应的属性,则将该属性持久化。
如果AppStorage中也没查找到key对应的属性,则在AppStorage中创建key对应的属性。用defaultValue初始化其值,并将该属性持久化。
根据上述的初始化流程,如果AppStorage中有该属性,则会使用其值覆盖PersistentStorage文件中的值。由于AppStorage是内存中的数据,这种操作会使持久化文件中的数据被内存数据覆盖,导致持久化数据失去意义。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | string | 是 | 要持久化的属性名。 |
| defaultValue | T | 是 | 在PersistentStorage和AppStorage中未查询到时,则使用默认值进行初始化。从API version 12开始可以为null或undefined。 |
示例:
persistProp具体用法详见从AppStorage中访问PersistentStorage初始化的属性。
static deleteProp(key: string): void
是persistProp的逆向操作。将key对应的属性从PersistentStorage中删除,后续AppStorage的操作对PersistentStorage不会再有影响。如需再次持久化,可再次调用persistProp接口。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | string | 是 | PersistentStorage中的属性名。 |
示例:
PersistentStorage.deleteProp('highScore'); static persistProps(props: PersistPropsOptions[]): void
行为与persistProp类似,不同在于可以一次性持久化多个数据。该接口通常在访问AppStorage之前调用,适合在应用启动时初始化。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| props | PersistPropsOptions[] | 是 | 持久化数组,每项包含属性名和默认值。 |
示例:
PersistentStorage.persistProps([{ key: 'highScore', defaultValue: '0' }, { key: 'weightScore', defaultValue: '1' }]); static keys(): Array<string>
返回所有持久化属性的属性名的数组。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
| 类型 | 说明 |
|---|---|
| Array<string> | 返回所有持久化属性的属性名的数组。 |
示例:
let keys: Array<string> = PersistentStorage.keys();
static PersistProp<T>(key: string, defaultValue: T): void
将AppStorage中key对应的属性持久化到文件中。该接口应在访问AppStorage之前调用。
确定属性的类型和值的顺序如下:
如果PersistentStorage文件中存在key对应的属性,在AppStorage中创建对应的key,并用在PersistentStorage中找到的key的属性初始化。
如果PersistentStorage文件中没有查询到key对应的属性,则在AppStorage中查找key对应的属性。如果找到key对应的属性,则将该属性持久化。
如果AppStorage也没查找到key对应的属性,则在AppStorage中创建key对应的属性。用defaultValue初始化其值,并将该属性持久化。
根据上述的初始化流程,如果AppStorage中有该属性,则会使用其值覆盖PersistentStorage文件中的值。由于AppStorage是内存中的数据,这种操作会使持久化文件中的数据被内存数据覆盖,导致持久化数据失去意义。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | string | 是 | 要持久化的属性名。 |
| defaultValue | T | 是 | 在PersistentStorage和AppStorage中未查询到时,则使用默认值进行初始化。默认值不允许为null或undefined。 |
示例:
PersistentStorage.PersistProp('highScore', '0'); static DeleteProp(key: string): void
是PersistProp的逆向操作。将key对应的属性从PersistentStorage中删除,后续AppStorage的操作对PersistentStorage不会再有影响。如需再次持久化,可再次调用PersistProp接口。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | string | 是 | PersistentStorage中的属性名。 |
示例:
PersistentStorage.DeleteProp('highScore'); static PersistProps(properties: {key: string; defaultValue: any;}[]): void
行为与PersistProp类似,不同在于可以一次性持久化多个数据。该接口应在访问AppStorage之前调用,适合在应用启动时初始化。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| properties | {key: string; defaultValue: any}[] | 是 | 持久化数组,其中key为属性名,defaultValue为默认值。规则同PersistProp。 |
示例:
PersistentStorage.PersistProps([{ key: 'highScore', defaultValue: '0' }, { key: 'weightScore', defaultValue: '1' }]); static Keys(): Array<string>
返回所有持久化属性的属性名的数组。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
| 类型 | 说明 |
|---|---|
| Array<string> | 返回所有持久化属性的属性名的数组。 |
示例:
let keys: Array<string> = PersistentStorage.Keys();
用于指定环境变量名称及其默认值的键值对对象,作为envProps参数传入。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| key | string | 否 | 否 | 环境变量名称,支持的范围详见内置环境变量说明。 |
| defaultValue | number | string | boolean | 否 | 否 | 查询不到环境变量key,则使用defaultValue作为默认值存入AppStorage中。 |
Environment提供设备环境状态的查询能力,可将系统环境变量(如深浅色模式、语言、字体缩放、布局方向等)注入AppStorage,使应用能够感知和响应设备环境变化。具体UI使用说明,详见Environment:设备环境查询。
static envProp<S>(key: string, value: S): boolean
将Environment的内置环境变量key存入AppStorage中。如果系统中未查询到Environment环境变量key的值,则使用默认值value存入AppStorage并返回true。如果AppStorage中已经有对应的key,则返回false。
在没有调用envProp的情况下,直接使用AppStorage读取环境变量,将无法获取到对应的环境变量值。建议在应用启动时调用该接口。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | string | 是 | 环境变量名称,支持的范围详见内置环境变量说明。 |
| value | S | 是 | 查询不到环境变量key时,则使用value作为默认值存入AppStorage中。 |
返回值:
| 类型 | 说明 |
|---|---|
| boolean | 如果key对应的属性在AppStorage中存在,则返回false。不存在则在AppStorage中用value作为默认值创建key对应的属性,返回true。 |
示例:
envProp具体使用,详见从UI中访问Environment参数。
static envProps(props: EnvPropsOptions[]): void
和envProp功能类似,不同点在于参数为数组,可以一次性初始化多个数据。在没有调用envProps的情况下,直接使用AppStorage读取环境变量,将无法获取到对应的环境变量值。建议在应用启动时调用,将系统环境变量批量存入AppStorage中。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| props | EnvPropsOptions[] | 是 | 系统环境变量和默认值的键值对的数组。 |
示例:
Environment.envProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, {
key: 'languageCode',
defaultValue: 'en'
}, { key: 'prop', defaultValue: 'hhhh' }]); static keys(): Array<string>
返回环境变量的属性key的数组。
元服务API: 从API version 11开始,该接口支持在元服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
| 类型 | 说明 |
|---|---|
| Array<string> | 返回环境变量的属性key的数组。 |
示例:
Environment.envProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, {
key: 'languageCode',
defaultValue: 'en'
}, { key: 'prop', defaultValue: 'hhhh' }]);
let keys: Array<string> = Environment.keys(); // keys 包含 accessibilityEnabled、languageCode、prop static EnvProp<S>(key: string, value: S): boolean
将Environment的内置环境变量key存入AppStorage中。如果系统中未查询到Environment环境变量key的值,则使用默认值value存入AppStorage并返回true。如果AppStorage中已经有对应的key,则返回false。
在没有调用EnvProp的情况下,直接使用AppStorage读取环境变量,将无法获取到对应的环境变量值。建议在应用启动时调用该接口。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | string | 是 | 环境变量名称,支持的范围详见内置环境变量说明。 |
| value | S | 是 | 查询不到环境变量key时,则使用value作为默认值存入AppStorage中。 |
返回值:
| 类型 | 说明 |
|---|---|
| boolean | 如果key对应的属性在AppStorage中存在,则返回false。不存在则在AppStorage中用value作为默认值创建key对应的属性,返回true。 |
示例:
Environment.EnvProp('accessibilityEnabled', 'default'); static EnvProps(props: {key: string; defaultValue: any;}[]): void
和EnvProp功能类似,不同点在于参数为数组,可以一次性初始化多个数据。在没有调用EnvProps的情况下,直接使用AppStorage读取环境变量,将无法获取到对应的环境变量值。建议在应用启动时调用,将系统环境变量批量存入AppStorage中。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| props | {key: string; defaultValue: any}[] | 是 | 系统环境变量和默认值的键值对的数组。 |
示例:
Environment.EnvProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, {
key: 'languageCode',
defaultValue: 'en'
}, { key: 'prop', defaultValue: 'hhhh' }]); static Keys(): Array<string>
返回环境变量的属性key的数组。
系统能力: SystemCapability.ArkUI.ArkUI.Full
返回值:
| 类型 | 说明 |
|---|---|
| Array<string> | 返回环境变量的属性key的数组。 |
示例:
Environment.EnvProps([{ key: 'accessibilityEnabled', defaultValue: 'default' }, {
key: 'languageCode',
defaultValue: 'en'
}, { key: 'prop', defaultValue: 'hhhh' }]);
let keys: Array<string> = Environment.Keys(); // keys 包含 accessibilityEnabled、languageCode、prop | key | 类型 | 说明 |
|---|---|---|
| accessibilityEnabled | string | 无障碍屏幕朗读是否启用。当无法获取环境变量中的accessibilityEnabled的值时,将通过envProp、envProps等接口传入的开发者指定的默认值添加到AppStorage中。 |
| colorMode | ColorMode | 深浅色模式,可选值为: - ColorMode.LIGHT:浅色模式; - ColorMode.DARK:深色模式。 |
| fontScale | number | 字体大小比例。 |
| fontWeightScale | number | 字重比例。 |
| layoutDirection | LayoutDirection | 布局方向类型,可选值为: - LayoutDirection.LTR:从左到右; - LayoutDirection.RTL:从右到左; - LayoutDirection.Auto:跟随系统。 |
| languageCode | string | 当前系统语言,小写字母,例如zh。 |