Arkts应用全局UI状态存储和持久化V2（AppStorageV2、PersistenceV2和@Type）

目录

应用全局UI状态存储和持久化V2版本

AppStorageV2

connect

remove

keys

示例

使用限制

PersistenceV2

connect

remove

keys

save

notifyOnError

 示例

使用限制

@Type

 使用限制

---

应用全局UI状态存储和持久化V2版本

以下实例AppStorageV2、PersistenceV2和装饰器@Type都需要搭配@ComponentV2使用。

AppStorageV2

AppStorageV2是在应用UI启动时会被创建的单例。它的目的是为了提供应用状态数据的中心存储，这些状态数据在应用级别都是可访问的。AppStorageV2将在应用运行过程保留其数据。数据通过唯一的键字符串值访问。

AppStorageV2支持应用的主线程内多个UIAbility实例间的状态共享

connect

用于在AppStorageV2实例中创建键值对数据或者获取实例中key对应的值，返回创建或获取的值（类实例|undefinded）。返回的不为undefined情况下，该值改变，对应AppStorageV2存储中的值也会改变。

AppStorageV2.connect<T extends object>(type: TypeConstructorWithArgs<T>, keyOrDefaultCreator?: string | StorageDefaultCreator<T>, defaultCreator?: StorageDefaultCreator<T>): T | undefined;

参数名	类型	必填	说明
type	TypeConstructorWithArgs<T>	是	指定的类型，若未指定key，则使用type的name作为key。
keyOrDefaultCreator	string | StorageDefaultCreator<T>	否	指定的key，或者是获取默认值的构造器。
defaultCreator	StorageDefaultCreator<T>	否	获取默认值的构造器。

有4种形式入参：

AppStorageV2.connect(Sample)

1个参数，类名。相当于AppStorageV2.connect(Sample,"Sample")。

AppStorageV2.connect(Sample,"Sample1")

2个参数，类名+字符串。表示获取AppStorageV2中"Sample1"对应的值，该值的类型为Sample，获取不到返回undefined。

AppStorageV2.connect(Sample,()=>new Sample())

2个参数，类名+默认值构造器。相当于AppStorageV2.connect(Sample,"Sample",()=>new Sample)

AppStorageV2.connect(Sample,"Sample2",()=>new Sample())

3个参数，类名+字符串+默认值构造器。先获取AppStorageV2中"Sample2"对应的值，如果获取不到，则通过调用默认值构造器，将结果存入AppStorageV2值中，key为"Sample2"。

注意：使用时，该方法可能返回undefined，故在给@Local等装饰器修饰的变量赋值时需要在最后加上感叹号！，用来避过undefined的类型检测，表示我确认不会返回undefined。

 

remove

用于删除AppStorageV2实例中指定的键值对数据，返回undefined。

AppStorageV2.remove<T>(keyOrType: string | TypeConstructorWithArgs<T>): void

参数名	类型	必填	说明
keyOrType	string | TypeConstructorWithArgs<T>	是	需要删除的key；如果指定的是type类型，删除的key为type的name。

只有一种入参方式，可以传类名或者字符串。传类名表示直接删除类名对应字符串后的键值对。 

注意：删除AppStorageV2中不存在的key会有Warning提示The key to be deleted does not exist。

keys

AppStorageV2.keys(): Array<string>

返回AppStorageV2实例中的所有key（Array<string>）。

示例

Navigation组件跳转页面时，首页不会重复渲染，返回不会重复渲染，pushPathByName会重新渲染新页面，故下例中首页只会渲染一次，每次跳到page2页面都会渲染一个新的。

1.点击Page1 p1、Page2 p2，p1数字会变动，p2不会，由于@Trace只装饰了p1，p2的实际值增加了，但是由于UI没刷新（在第2步中可以看出来）。

2.点击跳转page2，p1、p2的数字都同步过去了，由于都是在AppStorageV2实例中获取的Sample键值对。

3.点击Page2中按钮，在AppStorageV2中创建一个新的键值对Sample1，当前页面p1、p2的值会还原。

4.点击返回，由于首页不会刷新，这时无变化。

5.点击all keys in AppStorage，触发该段文字ui刷新，发现多了一个Sample1的key。

6.点击remove key按钮AppStorageV2中的Sample键值对删除了。

7.点击跳转page2，发现应用直接报错了，这是由于page2页面重新渲染，其中下面代码AppStorageV2.connect(Sample)返回undefined，@Local不能初始化值传入undefined。

@Local prop: Sample = AppStorageV2.connect(Sample)!;

注意：需要在真机环境运行，在预览环境会报错。

Index.ets页面

// Index.ets
import { AppStorageV2 } from '@kit.ArkUI';// 数据中心
@ObservedV2
export class Sample {@Trace p1: number = 0;p2: number = 10;
}@Entry
@ComponentV2
struct Page1 {// 在AppStorageV2中创建一个key为Sample的键值对（如果存在，则返回AppStorageV2中的数据），并且和prop关联@Local prop: Sample = AppStorageV2.connect(Sample,'Sample',()=>new Sample())!;@Local prop1: String = "1"pageStack: NavPathStack = new NavPathStack();fontSize(){console.log("all keys in AppStorage:渲染了一次")return 30}build() {Navigation(this.pageStack) {Column() {Button('Go to page2').onClick(() => {this.pageStack.pushPathByName('Page2', null);})Button('Page1 connect the key Sample').onClick(() => {// 在AppStorageV2中创建一个key为Sample的键值对（如果存在，则返回AppStorageV2中的数据），并且和prop关联this.prop = AppStorageV2.connect(Sample,()=>new Sample())!;})Button('Page1 remove the key Sample').onClick(() => {// 从AppStorageV2中删除后，prop将不会再与key为Sample的值关联AppStorageV2.remove(Sample);})Text(`Page1 p1: ${this.prop.p1}`).fontSize(30).onClick(() => {this.prop.p1++;})Text(`Page1 p2: ${this.prop.p2}`).fontSize(30).onClick(() => {// 页面不刷新，但是p2的值改变了this.prop.p2++;})// 获取当前AppStorageV2里面的所有keyText(`${this.prop1}all keys in AppStorage: ${AppStorageV2.keys()}`).fontSize(this.fontSize()).onClick(() => {// 页面不刷新，但是p2的值改变了this.prop1 = this.prop1+'1'})}}}
}

Index2.ets页面

// Page2.ets
import { AppStorageV2 } from '@kit.ArkUI';
import { Sample } from './Index';@Builder
export function Page2Builder() {Page2()
}@ComponentV2
struct Page2 {// 在AppStorageV2中创建一个key为Sample的键值对（如果存在，则返回AppStorageV2中的数据），并且和prop关联@Local prop: Sample = AppStorageV2.connect(Sample)!;pathStack: NavPathStack = new NavPathStack();fontSize(){console.log("渲染了一次11")return 30}build() {NavDestination() {Column() {Button('Page2 connect the key Sample1').onClick(() => {// 在AppStorageV2中创建一个key为Sample1的键值对（如果存在，则返回AppStorageV2中的数据），并且和prop关联this.prop = AppStorageV2.connect(Sample,"Sample1",()=>new Sample())!;})Text(`Page2 p1: ${this.prop.p1}`).fontSize(30).onClick(() => {this.prop.p1++;})Text(`Page2 p2: ${this.prop.p2}`).fontSize(this.fontSize()).onClick(() => {// 页面不刷新，但是p2的值改变了；只有重新初始化才会改变this.prop.p2++;})// 获取当前AppStorageV2里面的所有keyText(`all keys in AppStorage: ${AppStorageV2.keys()}`).fontSize(30)}}.onReady((context: NavDestinationContext) => {this.pathStack = context.pathStack;})}
}

使用Navigation组件时，需要添加配置系统路由表文件，先在module.json5中添加："routerMap": "$profile:route_map"，表示使用src/main/resources/base/profile目录下的route_map.json文件作为路由表。故在该目录下创建文件route_map.json。

{"routerMap": [{"name": "Page2","pageSourceFile": "src/main/ets/pages/Index2.ets","buildFunction": "Page2Builder","data": {"description" : "AppStorageV2 example"}}]
}

使用限制

1、需要配合UI使用（UI线程），不能在其他线程使用，如不支持@Sendable。

2、不支持collections.Set、collections.Map等类型。

3、不支持非buildin类型，如PixelMap、NativePointer、ArrayList等Native类型。

 

PersistenceV2

PersistenceV2是在应用UI启动时会被创建的单例，用于储存持久化的数据。不同于AppStorageV2它会将最新数据储存在设备磁盘上（持久化）。这意味着，应用退出再次启动后，依然能保存之前的数据。

支持应用的主线程内多个UIAbility实例间的状态共享。

注意：由于将数据存储在设备磁盘上，需要将数据进行序列化（数据转为某种固定的格式进行存储，例如全部转为二进制数据）后进行存储。

connect

remove

keys

PersistenceV2类型上继承了AppStorageV2，在AppStorageV2的基础上多实现了save和notifyOnError方法，所以上面3个方法使用同AppStorageV2。

save

PersistenceV2.save<T>(keyOrType: string | TypeConstructorWithArgs<T>): void;

对于与PersistenceV2关联的@ObservedV2对象，该对象的@Trace属性的变化，会触发整个关联对象的自动持久化；非@Trace属性的变化则不会，这时需要通过该方法进行手动持久化。

save	说明
参数	keyOrType：需要手动持久化的key；如果指定的是type类型，key为type的name。
返回值	无。

入参字符串或者类名。传类名表示对类名对应字符串后的键值对进行持久化处理。 

notifyOnError

PersistenceV2.notifyOnError(callback: PersistenceErrorCallback | undefined): void;

将数据存入磁盘时，需要对数据进行序列化；当某个key序列化失败时，错误是不可预知的；可调用该接口捕获异常。

notifyOnError	说明
参数	callback：当序列化或者反序列化失败时，执行该回调；若传入undefined，取消该回调。
返回值	无。

 示例

注意：需要在真机环境运行，在预览环境会报错。

这里示例和AppStorageV2的示例效果类似。不同在于：

1.退出应用后再次打开应用p1的值不会重置，因为使用的PersistenceV2并被@Trace修饰了，会自动持久化数据。

2.p2的值需要点击Page1 save the key Sample按钮后才会被持久化。这时退出后再打开p2的值会同步。

Index.ets页面

import { Type } from '@kit.ArkUI';
import { PersistenceV2 } from '@kit.ArkUI';// 数据中心
@ObservedV2
class SampleChild {@Trace p1: number = 0;p2: number = 10;
}@ObservedV2
export class Sample {// 对于复杂对象需要@Type修饰，确保序列化成功@Type(SampleChild)@Trace f: SampleChild = new SampleChild();
}
// 接受序列化失败的回调
PersistenceV2.notifyOnError((key: string, reason: string, msg: string) => {console.error(`error key: ${key}, reason: ${reason}, message: ${msg}`);
});@Entry
@ComponentV2
struct Page1 {// 在PersistenceV2中创建一个key为Sample的键值对（如果存在，则返回PersistenceV2中的数据），并且和prop关联// 对于需要换connect对象的prop属性，需要加@Local修饰（不建议对属性换connect的对象）@Local prop: Sample = PersistenceV2.connect(Sample, () => new Sample())!;pageStack: NavPathStack = new NavPathStack();build() {Navigation(this.pageStack) {Column() {Button('Go to page2').onClick(() => {this.pageStack.pushPathByName('Page2', null);})Button('Page1 connect the key Sample').onClick(() => {// 在PersistenceV2中创建一个key为Sample的键值对（如果存在，则返回PersistenceV2中的数据），并且和prop关联// 不建议对prop属性换connect的对象this.prop = PersistenceV2.connect(Sample, 'Sample', () => new Sample())!;})Button('Page1 remove the key Sample').onClick(() => {// 从PersistenceV2中删除后，prop将不会再与key为Sample的值关联PersistenceV2.remove(Sample);})Button('Page1 save the key Sample').onClick(() => {// 如果处于connect状态，持久化key为Sample的键值对PersistenceV2.save("Sample");})Text(`Page1 add 1 to prop.p1: ${this.prop.f.p1}`).fontSize(30).onClick(() => {this.prop.f.p1++;})Text(`Page1 add 1 to prop.p2: ${this.prop.f.p2}`).fontSize(30).onClick(() => {// 页面不刷新，但是p2的值改变了this.prop.f.p2++;})// 获取当前PersistenceV2里面的所有keyText(`all keys in PersistenceV2: ${PersistenceV2.keys()}`).fontSize(30)}}}
}

Index2.ets 

import { PersistenceV2 } from '@kit.ArkUI';
import { Sample } from './Index';@Builder
export function Page2Builder() {Page2()
}@ComponentV2
struct Page2 {// 在PersistenceV2中创建一个key为Sample的键值对（如果存在，则返回PersistenceV2中的数据），并且和prop关联// 对于需要换connect对象的prop属性，需要加@Local修饰（不建议对属性换connect的对象）@Local prop: Sample = PersistenceV2.connect(Sample, () => new Sample())!;pathStack: NavPathStack = new NavPathStack();build() {NavDestination() {Column() {Button('Page2 connect the key Sample1').onClick(() => {// 在PersistenceV2中创建一个key为Sample1的键值对（如果存在，则返回PersistenceV2中的数据），并且和prop关联// 不建议对prop属性换connect的对象this.prop = PersistenceV2.connect(Sample, 'Sample1', () => new Sample())!;})Text(`Page2 add 1 to prop.p1: ${this.prop.f.p1}`).fontSize(30).onClick(() => {this.prop.f.p1++;})Text(`Page2 add 1 to prop.p2: ${this.prop.f.p2}`).fontSize(30).onClick(() => {// 页面不刷新，但是p2的值改变了；只有重新初始化才会改变this.prop.f.p2++;})// 获取当前PersistenceV2里面的所有keyText(`all keys in PersistenceV2: ${PersistenceV2.keys()}`).fontSize(30)}}.onReady((context: NavDestinationContext) => {this.pathStack = context.pathStack;})}
}

 使用Navigation组件时，需要添加配置系统路由表文件，先在module.json5中添加："routerMap": "$profile:route_map"，表示使用src/main/resources/base/profile目录下的route_map.json文件作为路由表。故在该目录下创建文件route_map.json。

{"routerMap": [{"name": "Page2","pageSourceFile": "src/main/ets/pages/Index2.ets","buildFunction": "Page2Builder","data": {"description" : "AppStorageV2 example"}}]
}

使用限制

1、需要配合UI使用（UI线程），不能在其他线程使用，如不支持@Sendable。

2、不支持collections.Set、collections.Map等类型。

3、不支持非buildin类型，如PixelMap、NativePointer、ArrayList等Native类型。

4、单个key支持数据大小约8k，过大会导致持久化失败。

5、持久化的数据必须是class对象，不能是容器（如Array、Set、Map），不能是buildin的构造对象（如Date、Number）。

6、不支持循环引用的对象。

7、只有@Trace的数据改变会触发自动持久化，如V1状态变量、@Observed对象、普通数据的改变不会触发持久化。

8、不宜大量持久化数据，可能会导致页面卡顿。

@Type

在持久化数据时，为了实现序列化类时不丢失属性的复杂类型，可以使用@Type装饰器装饰类属性。

@Type装饰器	说明
装饰器参数	type：类型。
可装饰的类型	Object class以及Array、Date、Map、Set等内嵌类型。

class Sample {data: number = 0;
}
// Info会在PersistenceV2中使用。
//@Local prop: Info = PersistenceV2.connect(Info , () => new Info ())!;
@ObservedV2
class Info {@Type(Sample)@Trace sample: Sample = new Sample(); // 正确用法
}

 使用限制

1、只能用在@ObservedV2装饰的类中，不能用在自定义组件中。

2、不支持collections.Set、collections.Map等类型。

3、不支持非buildin类型，如PixelMap、NativePointer、ArrayList等Native类型。

4、不支持简单类型，如string、number、boolean等。