• 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

    1. let para: Record<string,number> = { 'PropA': 47 };
    2. let storage: LocalStorage = new LocalStorage(para); // 创建新实例并使用给定对象初始化
    3. let propA: number | undefined = storage.get('PropA') // propA == 47
    4. let link1: SubscribedAbstractProperty<number> = storage.link('PropA'); // link1.get() == 47
    5. let link2: SubscribedAbstractProperty<number> = storage.link('PropA'); // link2.get() == 47
    6. let prop: SubscribedAbstractProperty<number> = storage.prop('PropA'); // prop.get() = 47
    7. link1.set(48); // two-way sync: link1.get() == link2.get() == prop.get() == 48
    8. prop.set(1); // one-way sync: prop.get()=1; but link1.get() == link2.get() == 48
    9. link1.set(49); // two-way sync: link1.get() == link2.get() == prop.get() == 49

    从 UI 内部使用 LocalStorage

    除了应用程序逻辑使用 LocalStorage，还可以借助 LocalStorage 相关的两个装饰器 @LocalStorageProp 和 @LocalStorageLink，在 UI 组件内部获取到 LocalStorage 实例中存储的状态变量。

    本示例以 @LocalStorageLink 为例，展示了：

    ● 使用构造函数创建 LocalStorage 实例 storage；

    ● 使用 @Entry 装饰器将 storage 添加到 CompA 顶层组件中；

    ● @LocalStorageLink 绑定 LocalStorage 对给定的属性，建立双向数据同步。

    1. // 创建新实例并使用给定对象初始化
    2. let para:Record<string,number> = { 'PropA': 47 };
    3. let storage: LocalStorage = new LocalStorage(para);
    4.  
    5. @Component
    6. struct Child {
    7.   // @LocalStorageLink变量装饰器与LocalStorage中的'PropA'属性建立双向绑定
    8.   @LocalStorageLink('PropA') storLink2: number = 1;
    9.  
    10.   build() {
    11.     Button(`Child from LocalStorage ${this.storLink2}`)
    12.       // 更改将同步至LocalStorage中的'PropA'以及Parent.storLink1
    13.       .onClick(() => this.storLink2 += 1)
    14.   }
    15. }
    16. // 使LocalStorage可从@Component组件访问
    17. @Entry(storage)
    18. @Component
    19. struct CompA {
    20.   // @LocalStorageLink变量装饰器与LocalStorage中的'PropA'属性建立双向绑定
    21.   @LocalStorageLink('PropA') storLink1: number = 1;
    22.  
    23.   build() {
    24.     Column({ space: 15 }) {
    25.       Button(`Parent from LocalStorage ${this.storLink1}`) // initial value from LocalStorage will be 47, because 'PropA' initialized already
    26.         .onClick(() => this.storLink1 += 1)
    27.       // @Component子组件自动获得对CompA LocalStorage实例的访问权限。
    28.       Child()
    29.     }
    30.   }
    31. }

    @LocalStorageProp 和 LocalStorage 单向同步的简单场景

    在下面的示例中，CompA 组件和 Child 组件分别在本地创建了与 storage 的'PropA'对应属性的单向同步的数据，我们可以看到：

    ● CompA 中对 this.storProp1 的修改，只会在 CompA 中生效，并没有同步回 storage；

    ● Child 组件中，Text 绑定的 storProp2 依旧显示 47。

    1. // 创建新实例并使用给定对象初始化
    2. let para:Record<string,number> = { 'PropA': 47 };
    3. let storage: LocalStorage = new LocalStorage(para);
    4. // 使LocalStorage可从@Component组件访问
    5. @Entry(storage)
    6. @Component
    7. struct CompA {
    8.   // @LocalStorageProp变量装饰器与LocalStorage中的'PropA'属性建立单向绑定
    9.   @LocalStorageProp('PropA') storProp1: number = 1;
    10.  
    11.   build() {
    12.     Column({ space: 15 }) {
    13.       // 点击后从47开始加1，只改变当前组件显示的storProp1，不会同步到LocalStorage中
    14.       Button(`Parent from LocalStorage ${this.storProp1}`)
    15.         .onClick(() => this.storProp1 += 1)
    16.       Child()
    17.     }
    18.   }
    19. }
    20.  
    21. @Component
    22. struct Child {
    23.   // @LocalStorageProp变量装饰器与LocalStorage中的'PropA'属性建立单向绑定
    24.   @LocalStorageProp('PropA') storProp2: number = 2;
    25.  
    26.   build() {
    27.     Column({ space: 15 }) {
    28.       // 当CompA改变时，当前storProp2不会改变，显示47
    29.       Text(`Parent from LocalStorage ${this.storProp2}`)
    30.     }
    31.   }
    32. }

    @LocalStorageLink 和 LocalStorage 双向同步的简单场景

    下面的示例展示了 @LocalStorageLink 装饰的数据和 LocalStorage 双向同步的场景：

    1. // 构造LocalStorage实例
    2. let para:Record<string,number> = { 'PropA': 47 };
    3. let storage: LocalStorage = new LocalStorage(para);
    4. // 调用link9+接口构造'PropA'的双向同步数据，linkToPropA 是全局变量
    5. let linkToPropA: SubscribedAbstractProperty<object> = storage.link('PropA');
    6.  
    7. @Entry(storage)
    8. @Component
    9. struct CompA {
    10.  
    11.   // @LocalStorageLink('PropA')在CompA自定义组件中创建'PropA'的双向同步数据，初始值为47，因为在构造LocalStorage已经给“PropA”设置47
    12.   @LocalStorageLink('PropA') storLink: number = 1;
    13.  
    14.   build() {
    15.     Column() {
    16.       Text(`incr @LocalStorageLink variable`)
    17.         // 点击“incr @LocalStorageLink variable”，this.storLink加1，改变同步回storage，全局变量linkToPropA也会同步改变
    18.  
    19.         .onClick(() => this.storLink += 1)
    20.  
    21.       // 并不建议在组件内使用全局变量linkToPropA.get()，因为可能会有生命周期不同引起的错误。
    22.       Text(`@LocalStorageLink: ${this.storLink} - linkToPropA: ${linkToPropA.get()}`)
    23.     }
    24.   }
    25. }

    兄弟组件之间同步状态变量

    下面的示例展示了通过 @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('countStorage')}”没有同步刷新，因为 storage.get('countStorage')返回的是常规变量，常规变量的更新并不会引起 Text 组件的重新渲染。

    Child 自定义组件中的变化：

    1.  playCountLink 的刷新会同步回 LocalStorage，并且引起兄弟组件和父组件相应的刷新。

    1. let ls:Record<string,number> = { 'countStorage': 1}
    2. let storage:LocalStorage = new LocalStorage(ls);
    3. @Component
    4. struct Child {
    5.   // 子组件实例的名字
    6.   label: string = 'no name';
    7.   // 和LocalStorage中“countStorage”的双向绑定数据
    8.   @LocalStorageLink('countStorage') playCountLink: number = 0;
    9.  
    10.   build() {
    11.     Row() {
    12.       Text(this.label)
    13.         .width(50).height(60).fontSize(12)
    14.       Text(`playCountLink ${this.playCountLink}: inc by 1`)
    15.         .onClick(() => {
    16.           this.playCountLink += 1;
    17.         })
    18.         .width(200).height(60).fontSize(12)
    19.     }.width(300).height(60)
    20.   }
    21. }
    22.  
    23. @Entry(storage)
    24. @Component
    25. struct Parent {
    26.   @LocalStorageLink('countStorage') playCount: number = 0;
    27.  
    28.   build() {
    29.     Column() {
    30.       Row() {
    31.         Text('Parent')
    32.           .width(50).height(60).fontSize(12)
    33.         Text(`playCount ${this.playCount} dec by 1`)
    34.           .onClick(() => {
    35.             this.playCount -= 1;
    36.           })
    37.           .width(250).height(60).fontSize(12)
    38.       }.width(300).height(60)
    39.  
    40.       Row() {
    41.         Text('LocalStorage')
    42.           .width(50).height(60).fontSize(12)
    43.         Text(`countStorage ${this.playCount} incr by 1`)
    44.           .onClick(() => {
    45.             storage.set<number|undefined>('countStorage', Number(storage.get<number>('countStorage')) + 1);
    46.           })
    47.           .width(250).height(60).fontSize(12)
    48.       }.width(300).height(60)
    49.  
    50.       Child({ label: 'ChildA' })
    51.       Child({ label: 'ChildB' })
    52.  
    53.       Text(`playCount in LocalStorage for debug ${storage.get<number>('countStorage')}`)
    54.         .width(300).height(60).fontSize(12)
    55.     }
    56.   }
    57. }

    将 LocalStorage 实例从 UIAbility 共享到一个或多个视图

    上面的实例中，LocalStorage 的实例仅仅在一个 @Entry 装饰的组件和其所属的子组件（一个页面）中共享，如果希望其在多个视图中共享，可以在所属 UIAbility 中创建 LocalStorage 实例，并调用 windowStage.loadContent。

    1. // EntryAbility.ts
    2. import UIAbility from '@ohos.app.ability.UIAbility';
    3. import window from '@ohos.window';
    4. let para:Record<string,number> = { 'PropA': 47 };
    5. let localStorage: LocalStorage = new LocalStorage(para);
    6. export default class EntryAbility extends UIAbility {
    7. storage: LocalStorage = localStorage
    8.  
    9. onWindowStageCreate(windowStage: window.WindowStage) {
    10. windowStage.loadContent('pages/Index', this.storage);
    11. }
    12. }

    在 UI 页面通过 getShared 接口获取在通过 loadContent 共享的 LocalStorage 实例。

    1. // 通过getShared接口获取stage共享的LocalStorage实例
    2. let storage = LocalStorage.getShared()
    3.  
    4. @Entry(storage)
    5. @Component
    6. struct CompA {
    7.   // can access LocalStorage instance using 
    8.   // @LocalStorageLink/Prop decorated variables
    9.   @LocalStorageLink('PropA') varA: number = 1;
    10.  
    11.   build() {
    12.     Column() {
    13.       Text(`${this.varA}`).fontSize(50)
    14.     }
    15.   }
    16. }

    说明：

    对于开发者更建议使用这个方式来构建 LocalStorage 的实例，并且在创建 LocalStorage 实例的时候就写入默认值，因为默认值可以作为运行异常的备份，也可以用作页面的单元测试。

  • 相关阅读:
    去中心化金融 Defi 之稳定币、借贷与聚合器
    MongoDB搭建及基础操作
    基于android的车辆违章停放执法移动APP-计算机毕业设计
    充电器快充取电芯片XSP06Q+锂电池5A电流快速充电
    groovy：SimpleDateFormat 打印当前时间
    React【组件生命周期 、组件生命周期_挂载、 组件生命周期_更新 、组件生命周期_卸载、表单_受控组件、表单_受控组件处理多个输入】(三)
    基于MFC的MVC框架的编程实践
    裸片-PCBA
    SpringAMQP
    MySQL迁移到ClickHouse
  • 原文地址：https://blog.csdn.net/OpenHarmony_dev/article/details/133885647