LocalStorage：頁面級UI狀態(tài)存儲

概述

LocalStorage是ArkTS為構(gòu)建頁面級別狀態(tài)變量提供存儲的內(nèi)存內(nèi)“數(shù)據(jù)庫”。

• 應(yīng)用程序可以創(chuàng)建多個(gè)LocalStorage實(shí)例，LocalStorage實(shí)例可以在頁面內(nèi)共享，也可以通過GetShared接口，實(shí)現(xiàn)跨頁面、UIAbility實(shí)例內(nèi)共享。
• 組件樹的根節(jié)點(diǎn)，即被@Entry裝飾的@Component，可以被分配一個(gè)LocalStorage實(shí)例，此組件的所有子組件實(shí)例將自動獲得對該LocalStorage實(shí)例的訪問權(quán)限；
• 被@Component裝飾的組件最多可以訪問一個(gè)LocalStorage實(shí)例和AppStorage，未被@Entry裝飾的組件不可被獨(dú)立分配LocalStorage實(shí)例，只能接受父組件通過@Entry傳遞來的LocalStorage實(shí)例。一個(gè)LocalStorage實(shí)例在組件樹上可以被分配給多個(gè)組件。
• LocalStorage中的所有屬性都是可變的。

應(yīng)用程序決定LocalStorage對象的生命周期。當(dāng)應(yīng)用釋放最后一個(gè)指向LocalStorage的引用時(shí)，比如銷毀最后一個(gè)自定義組件，LocalStorage將被JS Engine垃圾回收。

LocalStorage根據(jù)與@Component裝飾的組件的同步類型不同，提供了兩個(gè)裝飾器：

• @LocalStorageProp：@LocalStorageProp裝飾的變量和與LocalStorage中給定屬性建立單向同步關(guān)系。
• @LocalStorageLink：@LocalStorageLink裝飾的變量和在@Component中創(chuàng)建與LocalStorage中給定屬性建立雙向同步關(guān)系。

限制條件

• LocalStorage創(chuàng)建后，命名屬性的類型不可更改。后續(xù)調(diào)用Set時(shí)必須使用相同類型的值。
• LocalStorage是頁面級存儲，GetShared接口僅能獲取當(dāng)前Stage通過windowStage.loadContent傳入的LocalStorage實(shí)例，否則返回undefined。例子可見將LocalStorage實(shí)例從UIAbility共享到一個(gè)或多個(gè)視圖。

@LocalStorageProp

在上文中已經(jīng)提到，如果要建立LocalStorage和自定義組件的聯(lián)系，需要使用@LocalStorageProp和@LocalStorageLink裝飾器。使用@LocalStorageProp(key)/@LocalStorageLink(key)裝飾組件內(nèi)的變量，key標(biāo)識了LocalStorage的屬性。

裝飾器使用規(guī)則說明

變量的傳遞/訪問規(guī)則說明

觀察變化和行為表現(xiàn)

觀察變化

@LocalStorageLink

如果我們需要將自定義組件的狀態(tài)變量的更新同步回LocalStorage，就需要用到@LocalStorageLink。

@LocalStorageLink(key)是和LocalStorage中key對應(yīng)的屬性建立雙向數(shù)據(jù)同步：

1. 本地修改發(fā)生，該修改會被寫回LocalStorage中；
2. LocalStorage中的修改發(fā)生后，該修改會被同步到所有綁定LocalStorage對應(yīng)key的屬性上，包括單向（@LocalStorageProp和通過prop創(chuàng)建的單向綁定變量）、雙向（@LocalStorageLink和通過link創(chuàng)建的雙向綁定變量）變量。

裝飾器使用規(guī)則說明

變量的傳遞/訪問規(guī)則說明

觀察變化和行為表現(xiàn)

觀察變化

使用場景

應(yīng)用邏輯使用LocalStorage

let storage = new LocalStorage({ 'PropA': 47 }); // 創(chuàng)建新實(shí)例并使用給定對象初始化
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內(nèi)部使用LocalStorage

除了應(yīng)用程序邏輯使用LocalStorage，還可以借助LocalStorage相關(guān)的兩個(gè)裝飾器@LocalStorageProp和@LocalStorageLink，在UI組件內(nèi)部獲取到LocalStorage實(shí)例中存儲的狀態(tài)變量。

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

• 使用構(gòu)造函數(shù)創(chuàng)建LocalStorage實(shí)例storage；
• 使用@Entry裝飾器將storage添加到CompA頂層組件中；
• @LocalStorageLink綁定LocalStorage對給定的屬性，建立雙向數(shù)據(jù)同步。

  // 創(chuàng)建新實(shí)例并使用給定對象初始化
  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實(shí)例的訪問權(quán)限。
        Child()
      }
    }
  }

@LocalStorageProp和LocalStorage單向同步的簡單場景

在下面的示例中，CompA 組件和Child組件分別在本地創(chuàng)建了與storage的'PropA'對應(yīng)屬性的單向同步的數(shù)據(jù)，我們可以看到：

• CompA中對this.storProp1的修改，只會在CompA中生效，并沒有同步回storage；
• Child組件中，Text綁定的storProp2 依舊顯示47。

  // 創(chuàng)建新實(shí)例并使用給定對象初始化
  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 }) {
        // 點(diǎn)擊后從47開始加1，只改變當(dāng)前組件顯示的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 }) {
        // 當(dāng)CompA改變時(shí)，當(dāng)前storProp2不會改變，顯示47
        Text(`Parent from LocalStorage ${this.storProp2}`)
      }
    }
  }

@LocalStorageLink和LocalStorage雙向同步的簡單場景

下面的示例展示了@LocalStorageLink裝飾的數(shù)據(jù)和LocalStorage雙向同步的場景

// 構(gòu)造LocalStorage實(shí)例
let storage = new LocalStorage({ 'PropA': 47 });
// 調(diào)用link（api9以上）接口構(gòu)造'PropA'的雙向同步數(shù)據(jù)，linkToPropA 是全局變量
let linkToPropA = storage.link('PropA');

@Entry(storage)
@Component
struct CompA {

  // @LocalStorageLink('PropA')在CompA自定義組件中創(chuàng)建'PropA'的雙向同步數(shù)據(jù)，初始值為47，因?yàn)樵跇?gòu)造LocalStorage已經(jīng)給“PropA”設(shè)置47
  @LocalStorageLink('PropA') storLink: number = 1;

  build() {
    Column() {
      Text(`incr @LocalStorageLink variable`)
        // 點(diǎn)擊“incr @LocalStorageLink variable”，this.storLink加1，改變同步回storage，全局變量linkToPropA也會同步改變 

        .onClick(() => this.storLink += 1)

      // 并不建議在組件內(nèi)使用全局變量linkToPropA.get()，因?yàn)榭赡軙猩芷诓煌鸬腻e(cuò)誤。
      Text(`@LocalStorageLink: ${this.storLink} - linkToPropA: ${linkToPropA.get()}`)
    }
  }
}

兄弟節(jié)點(diǎn)之間同步狀態(tài)變量

下面的示例展示了通過@LocalStorageLink雙向同步兄弟節(jié)點(diǎn)之間的狀態(tài)。

先看Parent自定義組件中發(fā)生的變化：

1. 點(diǎn)擊“playCount ${this.playCount} dec by 1”，this.playCount減1，修改同步回LocalStorage中，Child組件中的playCountLink綁定的組件會同步刷新；
2. 點(diǎn)擊“countStorage ${this.playCount} incr by 1”，調(diào)用LocalStorage的set接口，更新LocalStorage中“countStorage”對應(yīng)的屬性，Child組件中的playCountLink綁定的組件會同步刷新；
3. Text組件“playCount in LocalStorage for debug ${storage.get<number>('countStorage')}”沒有同步刷新，因?yàn)閟torage.get<number>('countStorage')返回的是常規(guī)變量，常規(guī)變量的更新并不會引起Text組件的重新渲染。

Child自定義組件中的變化：

1. playCountLink的刷新會同步回LocalStorage，并且引起兄弟組件和父組件相應(yīng)的刷新。

   let storage = new LocalStorage({ countStorage: 1 });
   
   @Component
   struct Child {
     // 子組件實(shí)例的名字
     label: string = 'no name';
     // 和LocalStorage中“countStorage”的雙向綁定數(shù)據(jù)
     @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實(shí)例從UIAbility共享到一個(gè)或多個(gè)視圖

上面的實(shí)例中，LocalStorage的實(shí)例僅僅在一個(gè)@Entry裝飾的組件和其所屬的子組件（一個(gè)頁面）中共享，如果希望其在多個(gè)視圖中共享，可以在所屬UIAbility中創(chuàng)建LocalStorage實(shí)例，并調(diào)用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實(shí)例
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)
    }
  }
}