OpenHarmony 页面级 UI 状态存储：LocalStorage
LocalStorage 是页面级的 UI 状态存储，通过 @Entry 装饰器接收的参数可以在页面内共享同一个 LocalStorage 实例。LocalStorage 也可以在 UIAbility 内，页面间共享状态。
本文仅介绍 LocalStorage 使用场景和相关的装饰器：@LocalStorageProp 和 @LocalStorageLink。
说明：
LocalStorage 从 API version 9 开始支持。
概述
LocalStorage 是 ArkTS 为构建页面级别状态变量提供存储的内存内“数据库”。
● 应用程序可以创建多个 LocalStorage 实例，LocalStorage 实例可以在页面内共享，也可以通过 GetShared 接口，获取在 UIAbility 里创建的 GetShared，实现跨页面、UIAbility 内共享。
● 组件树的根节点，即被 @Entry 装饰的 @Component，可以被分配一个 LocalStorage 实例，此组件的所有子组件实例将自动获得对该 LocalStorage 实例的访问权限。
● 被 @Component 装饰的组件最多可以访问一个 LocalStorage 实例和AppStorage，未被 @Entry 装饰的组件不可被独立分配 LocalStorage 实例，只能接受父组件通过 @Entry 传递来的 LocalStorage 实例。一个 LocalStorage 实例在组件树上可以被分配给多个组件。
● LocalStorage 中的所有属性都是可变的。
应用程序决定 LocalStorage 对象的生命周期。当应用释放最后一个指向 LocalStorage 的引用时，比如销毁最后一个自定义组件，LocalStorage 将被 JS Engine 垃圾回收。
LocalStorage 根据与 @Component 装饰的组件的同步类型不同，提供了两个装饰器：
● @LocalStorageProp：@LocalStorageProp 装饰的变量和与 LocalStorage 中给定属性建立单向同步关系。
● @LocalStorageLink：@LocalStorageLink 装饰的变量和在 @Component 中创建与 LocalStorage 中给定属性建立双向同步关系。
限制条件
● LocalStorage 创建后，命名属性的类型不可更改。后续调用 Set 时必须使用相同类型的值。
● LocalStorage 是页面级存储，GetShared接口仅能获取当前 Stage 通过windowStage.loadContent传入的 LocalStorage 实例，否则返回 undefined。例子可见将LocalStorage实例从UIAbility共享到一个或多个视图。
@LocalStorageProp
在上文中已经提到，如果要建立 LocalStorage 和自定义组件的联系，需要使用 @LocalStorageProp 和 @LocalStorageLink 装饰器。使用 @LocalStorageProp(key)/@LocalStorageLink(key)装饰组件内的变量，key 标识了 LocalStorage 的属性。
当自定义组件初始化的时候，@LocalStorageProp(key)/@LocalStorageLink(key)装饰的变量会通过给定的 key，绑定 LocalStorage 对应的属性，完成初始化。本地初始化是必要的，因为无法保证 LocalStorage 一定存在给定的 key（这取决于应用逻辑是否在组件初始化之前在 LocalStorage 实例中存入对应的属性）。
说明：
从 API version 9 开始，该装饰器支持在 ArkTS 卡片中使用。
@LocalStorageProp(key)是和 LocalStorage 中 key 对应的属性建立单向数据同步，我们允许本地改变的发生，但是对于 @LocalStorageProp，本地的修改永远不会同步回 LocalStorage 中，相反，如果 LocalStorage 给定 key 的属性发生改变，改变会被同步给 @LocalStorageProp，并覆盖掉本地的修改。
装饰器使用规则说明
变量的传递/访问规则说明
图 1 @LocalStorageProp 初始化规则图示
观察变化和行为表现
观察变化
● 当装饰的数据类型为 boolean、string、number 类型时，可以观察到数值的变化。
● 当装饰的数据类型为 class 或者 Object 时，可以观察到赋值和属性赋值的变化，即 Object.keys(observedObject)返回的所有属性。
● 当装饰的对象是 array 时，可以观察到数组添加、删除、更新数组单元的变化。
框架行为
● 当 @LocalStorageProp(key)装饰的数值改变被观察到时，修改不会被同步回 LocalStorage 对应属性键值 key 的属性中。
● 当前 @LocalStorageProp(key)单向绑定的数据会被修改，即仅限于当前组件的私有成员变量改变，其他的绑定该 key 的数据不会同步改变。
● 当 @LocalStorageProp(key)装饰的数据本身是状态变量，它的改变虽然不会同步回 LocalStorage 中，但是会引起所属的自定义组件的重新渲染。
● 当 LocalStorage 中 key 对应的属性发生改变时，会同步给所有 @LocalStorageProp(key)装饰的数据，@LocalStorageProp(key)本地的修改将被覆盖。
@LocalStorageLink
如果我们需要将自定义组件的状态变量的更新同步回 LocalStorage，就需要用到 @LocalStorageLink。
@LocalStorageLink(key)是和 LocalStorage 中 key 对应的属性建立双向数据同步：
1. 本地修改发生，该修改会被回 LocalStorage 中；
2. LocalStorage 中的修改发生后，该修改会被同步到所有绑定 LocalStorage 对应 key 的属性上，包括单向（@LocalStorageProp 和通过 prop 创建的单向绑定变量）、双向（@LocalStorageLink 和通过 link 创建的双向绑定变量）变量。
装饰器使用规则说明
变量的传递/访问规则说明
图 2 @LocalStorageLink 初始化规则图示
观察变化和行为表现
观察变化
● 当装饰的数据类型为 boolean、string、number 类型时，可以观察到数值的变化。
● 当装饰的数据类型为 class 或者 Object 时，可以观察到赋值和属性赋值的变化，即 Object.keys(observedObject)返回的所有属性。
● 当装饰的对象是 array 时，可以观察到数组添加、删除、更新数组单元的变化。
框架行为
1. 当 @LocalStorageLink(key)装饰的数值改变被观察到时，修改将被同步回 LocalStorage 对应属性键值 key 的属性中。
2. LocalStorage 中属性键值 key 对应的数据一旦改变，属性键值 key 绑定的所有的数据（包括双向 @LocalStorageLink 和单向 @LocalStorageProp）都将同步修改；
3. 当 @LocalStorageLink(key)装饰的数据本身是状态变量，它的改变不仅仅会同步回 LocalStorage 中，还会引起所属的自定义组件的重新渲染。
使用场景
应用逻辑使用 LocalStorage
从 UI 内部使用 LocalStorage
除了应用程序逻辑使用 LocalStorage，还可以借助 LocalStorage 相关的两个装饰器 @LocalStorageProp 和 @LocalStorageLink，在 UI 组件内部获取到 LocalStorage 实例中存储的状态变量。
本示例以 @LocalStorageLink 为例，展示了：
● 使用构造函数创建 LocalStorage 实例 storage；
● 使用 @Entry 装饰器将 storage 添加到 CompA 顶层组件中；
● @LocalStorageLink 绑定 LocalStorage 对给定的属性，建立双向数据同步。
@LocalStorageProp 和 LocalStorage 单向同步的简单场景
在下面的示例中，CompA 组件和 Child 组件分别在本地创建了与 storage 的'PropA'对应属性的单向同步的数据，我们可以看到：
● CompA 中对 this.storProp1 的修改，只会在 CompA 中生效，并没有同步回 storage；
● Child 组件中，Text 绑定的 storProp2 依旧显示 47。
@LocalStorageLink 和 LocalStorage 双向同步的简单场景
下面的示例展示了 @LocalStorageLink 装饰的数据和 LocalStorage 双向同步的场景：
兄弟组件之间同步状态变量
下面的示例展示了通过 @LocalStorageLink 双向同步兄弟组件之间的状态。
先看 Parent 自定义组件中发生的变化：
1. 点击“playCount ${this.playCount} dec by 1”，this.playCount 减 1，修改同步回 LocalStorage 中，Child 组件中的 playCountLink 绑定的组件会同步刷新；
2. 点击“countStorage ${this.playCount} incr by 1”，调用 LocalStorage 的 set 接口，更新 LocalStorage 中“countStorage”对应的属性，Child 组件中的 playCountLink 绑定的组件会同步刷新；
3. Text 组件“playCount in LocalStorage for debug ${storage.get<number>('countStorage')}”没有同步刷新，因为 storage.get<number>('countStorage')返回的是常规变量，常规变量的更新并不会引起 Text 组件的重新渲染。
Child 自定义组件中的变化：
1. playCountLink 的刷新会同步回 LocalStorage，并且引起兄弟组件和父组件相应的刷新。
将 LocalStorage 实例从 UIAbility 共享到一个或多个视图
上面的实例中，LocalStorage 的实例仅仅在一个 @Entry 装饰的组件和其所属的子组件（一个页面）中共享，如果希望其在多个视图中共享，可以在所属 UIAbility 中创建 LocalStorage 实例，并调用 windowStage.loadContent。
在 UI 页面通过 getShared 接口获取在通过 loadContent 共享的 LocalStorage 实例。
说明：
对于开发者更建议使用这个方式来构建 LocalStorage 的实例，并且在创建 LocalStorage 实例的时候就写入默认值，因为默认值可以作为运行异常的备份，也可以用作页面的单元测试。
OpenHarmony开发者官方账号 2021-12-15 加入
OpenHarmony是由开放原子开源基金会（OpenAtom Foundation）孵化及运营的开源项目，目标是面向全场景、全连接、全智能时代，基于开源的方式，搭建一个智能终端设备操作系统的框架和平台，促进万物互联产业的繁荣发展
评论