HarmonyOS—LocalStorage：页面级UI状态存储

LocalStorage是页面级的UI状态存储，通过@Entry装饰器接收的参数可以在页面内共享同一个LocalStorage实例。LocalStorage也可以在UIAbility实例内，在页面间共享状态。

本文仅介绍LocalStorage使用场景和相关的装饰器：@LocalStorageProp和@LocalStorageLink。

说明

本模块从API version 9开始支持。

概述

LocalStorage是ArkTS为构建页面级别状态变量提供存储的内存内“数据库”。

• 应用程序可以创建多个LocalStorage实例，LocalStorage实例可以在页面内共享，也可以通过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

            let storage = new LocalStorage({ 'PropA': 47 }); // 创建新实例并使用给定对象初始化
            let propA = storage.get('PropA') // propA == 47
            let link1 = storage.link('PropA'); // link1.get() == 47
            let link2 = storage.link('PropA'); // link2.get() == 47
            let prop = storage.prop('PropA'); // prop.get() = 47
            link1.set(48); // two-way sync: link1.get() == link2.get() == prop.get() == 48
            prop.set(1); // one-way sync: prop.get()=1; but link1.get() == link2.get() == 48
            link1.set(49); // two-way sync: link1.get() == link2.get() == prop.get() == 49
            

            从UI内部使用LocalStorage

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

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

            • 使用构造函数创建LocalStorage实例storage；
            • 使用@Entry装饰器将storage添加到CompA顶层组件中；
            • @LocalStorageLink绑定LocalStorage对给定的属性，建立双向数据同步。

              // 创建新实例并使用给定对象初始化
              let storage = new LocalStorage({ 'PropA': 47 });
              @Component
              struct Child {
                // @LocalStorageLink变量装饰器与LocalStorage中的'PropA'属性建立双向绑定
                @LocalStorageLink('PropA') storLink2: number = 1;
                build() {
                  Button(`Child from LocalStorage ${this.storLink2}`)
                    // 更改将同步至LocalStorage中的'PropA'以及Parent.storLink1
                    .onClick(() => this.storLink2 += 1)
                }
              }
              // 使LocalStorage可从@Component组件访问
              @Entry(storage)
              @Component
              struct CompA {
                // @LocalStorageLink变量装饰器与LocalStorage中的'PropA'属性建立双向绑定
                @LocalStorageLink('PropA') storLink1: number = 1;
                build() {
                  Column({ space: 15 }) {
                    Button(`Parent from LocalStorage ${this.storLink1}`) // initial value from LocalStorage will be 47, because 'PropA' initialized already
                      .onClick(() => this.storLink1 += 1)
                    // @Component子组件自动获得对CompA LocalStorage实例的访问权限。
                    Child()
                  }
                }
              }
              

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

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

              • CompA中对this.storProp1的修改，只会在CompA中生效，并没有同步回storage；
              • Child组件中，Text绑定的storProp2 依旧显示47。

                // 创建新实例并使用给定对象初始化
                let storage = new LocalStorage({ 'PropA': 47 });
                // 使LocalStorage可从@Component组件访问
                @Entry(storage)
                @Component
                struct CompA {
                  // @LocalStorageProp变量装饰器与LocalStorage中的'PropA'属性建立单向绑定
                  @LocalStorageProp('PropA') storProp1: number = 1;
                  build() {
                    Column({ space: 15 }) {
                      // 点击后从47开始加1，只改变当前组件显示的storProp1，不会同步到LocalStorage中
                      Button(`Parent from LocalStorage ${this.storProp1}`)
                        .onClick(() => this.storProp1 += 1)
                      Child()
                    }
                  }
                }
                @Component
                struct Child {
                  // @LocalStorageProp变量装饰器与LocalStorage中的'PropA'属性建立单向绑定
                  @LocalStorageProp('PropA') storProp2: number = 2;
                  build() {
                    Column({ space: 15 }) {
                      // 当CompA改变时，当前storProp2不会改变，显示47
                      Text(`Parent from LocalStorage ${this.storProp2}`)
                    }
                  }
                }
                

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

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

                // 构造LocalStorage实例
                let storage = new LocalStorage({ 'PropA': 47 });
                // 调用link（api9以上）接口构造'PropA'的双向同步数据，linkToPropA 是全局变量
                let linkToPropA = storage.link('PropA');
                @Entry(storage)
                @Component
                struct CompA {
                  // @LocalStorageLink('PropA')在CompA自定义组件中创建'PropA'的双向同步数据，初始值为47，因为在构造LocalStorage已经给“PropA”设置47
                  @LocalStorageLink('PropA') storLink: number = 1;
                  build() {
                    Column() {
                      Text(`incr @LocalStorageLink variable`)
                        // 点击“incr @LocalStorageLink variable”，this.storLink加1，改变同步回storage，全局变量linkToPropA也会同步改变 
                        .onClick(() => this.storLink += 1)
                      // 并不建议在组件内使用全局变量linkToPropA.get()，因为可能会有生命周期不同引起的错误。
                      Text(`@LocalStorageLink: ${this.storLink} - linkToPropA: ${linkToPropA.get()}`)
                    }
                  }
                }
                

                兄弟节点之间同步状态变量

                下面的示例展示了通过@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，并且引起兄弟组件和父组件相应的刷新。

                let storage = new LocalStorage({ countStorage: 1 });
                @Component
                struct Child {
                  // 子组件实例的名字
                  label: string = 'no name';
                  // 和LocalStorage中“countStorage”的双向绑定数据
                  @LocalStorageLink('countStorage') playCountLink: number = 0;
                  build() {
                    Row() {
                      Text(this.label)
                        .width(50).height(60).fontSize(12)
                      Text(`playCountLink ${this.playCountLink}: inc by 1`)
                        .onClick(() => {
                          this.playCountLink += 1;
                        })
                        .width(200).height(60).fontSize(12)
                    }.width(300).height(60)
                  }
                }
                @Entry(storage)
                @Component
                struct Parent {
                  @LocalStorageLink('countStorage') playCount: number = 0;
                  build() {
                    Column() {
                      Row() {
                        Text('Parent')
                          .width(50).height(60).fontSize(12)
                        Text(`playCount ${this.playCount} dec by 1`)
                          .onClick(() => {
                            this.playCount -= 1;
                          })
                          .width(250).height(60).fontSize(12)
                      }.width(300).height(60)
                      Row() {
                        Text('LocalStorage')
                          .width(50).height(60).fontSize(12)
                        Text(`countStorage ${this.playCount} incr by 1`)
                          .onClick(() => {
                            storage.set('countStorage', 1 + storage.get('countStorage'));
                          })
                          .width(250).height(60).fontSize(12)
                      }.width(300).height(60)
                      Child({ label: 'ChildA' })
                      Child({ label: 'ChildB' })
                      Text(`playCount in LocalStorage for debug ${storage.get('countStorage')}`)
                        .width(300).height(60).fontSize(12)
                    }
                  }
                }
                

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

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

                // EntryAbility.ts
                import UIAbility from '@ohos.app.ability.UIAbility';
                import window from '@ohos.window';
                let para:Record = { 'PropA': 47 };
                let localStorage: LocalStorage = new LocalStorage(para);
                export default class EntryAbility extends UIAbility {
                  storage: LocalStorage = localStorage
                  onWindowStageCreate(windowStage: window.WindowStage) {
                    windowStage.loadContent('pages/Index', this.storage);
                  }
                }
                

                说明

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

                LocalStorage.getShared只在模拟器或者实机上才有效，不能在Preview预览器中使用。

                // 通过GetShared接口获取stage共享的LocalStorage实例
                let storage = LocalStorage.GetShared()
                @Entry(storage)
                @Component
                struct CompA {
                  // can access LocalStorage instance using 
                  // @LocalStorageLink/Prop decorated variables
                  @LocalStorageLink('PropA') varA: number = 1;
                  build() {
                    Column() {
                      Text(`${this.varA}`).fontSize(50)
                    }
                  }
                }
                

                说明

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

                为了能够让大家跟上互联网时代的技术迭代，在这里跟大家分享一下我自己近期学习心得以及参考网上资料整理出的一份最新版的鸿蒙学习提升资料，有需要的小伙伴自行领取，限时开源，先到先得~~~~

                领取以下高清学习路线原图请点击→《鸿蒙全套学习指南》纯血鸿蒙HarmonyOS基础技能学习路线图
                

                领取以上完整高清学习路线图，请点击→《鸿蒙 (Harmony OS)开发学习手册》小编自己整理的部分学习资料（包含有高清视频、开发文档、电子书籍等）
                

                以上分享的学习路线都适合哪些人跟着学习？

                -应届生/计算机专业通过学习鸿蒙新兴技术，入行互联网，未来高起点就业。

                -0基础转行提前布局新方向，抓住风口，自我提升，获得更多就业机会。

                -技术提升/进阶跳槽发展瓶颈期，提升职场竞争力，快速掌握鸿蒙技术，享受蓝海红利。

                

                最后

                鸿蒙开发学习是一个系统化的过程，从基础知识的学习到实战技能的锤炼，再到对前沿技术的探索，每一环节都至关重要。希望这份教程资料能帮助您快速入门并在鸿蒙开发之路上步步攀升，成就一番事业。让我们一起乘风破浪，拥抱鸿蒙生态的广阔未来！

                如果你觉得这篇内容对你有帮助，我想麻烦大家动动小手给我：点赞，转发，有你们的 『点赞和评论』，才是我创造的动力。

                关注我，同时可以期待后续文章ing，不定期分享原创知识。

                想要获取更多完整鸿蒙最新VIP学习资料，请点击→《鸿蒙基础入门学习指南》