LocalStorage：页面级UI状态存储

概述

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的属性。

装饰器使用规则说明

变量的传递/访问规则说明

观察变化和行为表现

观察变化

@LocalStorageLink

如果我们需要将自定义组件的状态变量的更新同步回LocalStorage，就需要用到@LocalStorageLink。

@LocalStorageLink(key)是和LocalStorage中key对应的属性建立双向数据同步：

1. 本地修改发生，该修改会被写回LocalStorage中；
2. LocalStorage中的修改发生后，该修改会被同步到所有绑定LocalStorage对应key的属性上，包括单向（@LocalStorageProp和通过prop创建的单向绑定变量）、双向（@LocalStorageLink和通过link创建的双向绑定变量）变量。

装饰器使用规则说明

变量的传递/访问规则说明

观察变化和行为表现

观察变化

使用场景

应用逻辑使用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实例中存储的状态变量。

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

• 使用构造函数创建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<number>('countStorage')}”没有同步刷新，因为storage.get<number>('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<number>('countStorage', 1 + storage.get<number>('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<number>('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<string,number> = { '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);
  }
}

// 通过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)
    }
  }
}