PersistentStorage：持久化存儲(chǔ)UI狀態(tài)

概述

PersistentStorage將選定的AppStorage屬性保留在設(shè)備磁盤上。應(yīng)用程序通過API，以決定哪些AppStorage屬性應(yīng)借助PersistentStorage持久化。UI和業(yè)務(wù)邏輯不直接訪問PersistentStorage中的屬性，所有屬性訪問都是對(duì)AppStorage的訪問，AppStorage中的更改會(huì)自動(dòng)同步到PersistentStorage。

PersistentStorage和AppStorage中的屬性建立雙向同步。應(yīng)用開發(fā)通常通過AppStorage訪問PersistentStorage，另外還有一些接口可以用于管理持久化屬性，但是業(yè)務(wù)邏輯始終是通過AppStorage獲取和設(shè)置屬性的。

限制條件

PersistentStorage允許的類型和值有：

• number, string, boolean, enum 等簡(jiǎn)單類型。
• 可以被JSON.stringify()和JSON.parse()重構(gòu)的對(duì)象。例如Date, Map, Set等內(nèi)置類型則不支持，以及對(duì)象的屬性方法不支持持久化。

PersistentStorage不允許的類型和值有：

• 不支持嵌套對(duì)象（對(duì)象數(shù)組，對(duì)象的屬性是對(duì)象等）。因?yàn)槟壳翱蚣軣o法檢測(cè)AppStorage中嵌套對(duì)象（包括數(shù)組）值的變化，所以無法寫回到PersistentStorage中。
• 不支持undefined 和 null 。

持久化數(shù)據(jù)是一個(gè)相對(duì)緩慢的操作，應(yīng)用程序應(yīng)避免以下情況：

• 持久化大型數(shù)據(jù)集。
• 持久化經(jīng)常變化的變量。

PersistentStorage的持久化變量最好是小于2kb的數(shù)據(jù)，不要大量的數(shù)據(jù)持久化，因?yàn)镻ersistentStorage寫入磁盤的操作是同步的，大量的數(shù)據(jù)本地化讀寫會(huì)同步在UI線程中執(zhí)行，影響UI渲染性能。如果開發(fā)者需要存儲(chǔ)大量的數(shù)據(jù)，建議使用數(shù)據(jù)庫(kù)api。

PersistentStorage只能在UI頁面內(nèi)使用，否則將無法持久化數(shù)據(jù)。

支持的接口

PersistProp

static PersistProp<T>(key: string, defaultValue: T): void

將AppStorage中key對(duì)應(yīng)的屬性持久化到文件中。該接口的調(diào)用通常在訪問AppStorage之前。

確定屬性的類型和值的順序如下：

1. 如果PersistentStorage文件中存在key對(duì)應(yīng)的屬性，在AppStorage中創(chuàng)建對(duì)應(yīng)的propName，并用在PersistentStorage中找到的key的屬性初始化。
2. 如果PersistentStorage文件中沒有查詢到key對(duì)應(yīng)的屬性，則在AppStorage中查找key對(duì)應(yīng)的屬性。如果找到key對(duì)應(yīng)的屬性，則將該屬性持久化。
3. 如果AppStorage也沒查找到key對(duì)應(yīng)的屬性，則在AppStorage中創(chuàng)建key對(duì)應(yīng)的屬性。用defaultValue初始化其值，并將該屬性持久化。

根據(jù)上述的初始化流程，如果AppStorage中有該屬性，則會(huì)使用其值，覆蓋掉PersistentStorage文件中的值。由于AppStorage是內(nèi)存內(nèi)數(shù)據(jù)，該行為會(huì)導(dǎo)致數(shù)據(jù)喪失持久化能力。

參數(shù)：

示例：

PersistentStorage.PersistProp('highScore', '0');

DeleteProp

static DeleteProp(key: string): void

將key對(duì)應(yīng)的屬性從PersistentStorage刪除，后續(xù)AppStorage的操作，對(duì)PersistentStorage不會(huì)再有影響。

參數(shù)：

示例：

PersistentStorage.DeleteProp('highScore');

PersistProps

static PersistProps(properties: {key: string, defaultValue: any;}[]): void

行為和PersistProp類似，不同在于可以一次性持久化多個(gè)數(shù)據(jù)，適合在應(yīng)用啟動(dòng)的時(shí)候初始化。

參數(shù)：

示例：

PersistentStorage.PersistProps([{ key: 'highScore', defaultValue: '0' }, { key: 'wightScore', defaultValue: '1' }]);

Keys

static Keys(): Array<string>

返回所有持久化屬性的key的數(shù)組。

返回值：

示例：

let keys: Array<string> = PersistentStorage.Keys();

使用場(chǎng)景

從AppStorage中訪問PersistentStorage初始化的屬性

1. 初始化PersistentStorage：

   PersistentStorage.PersistProp('aProp', 47);

2. 在AppStorage獲取對(duì)應(yīng)屬性：

   AppStorage.Get('aProp'); // returns 47

   或在組件內(nèi)部定義：

   @StorageLink('aProp') aProp: number = 48;

完整代碼如下：

PersistentStorage.PersistProp('aProp', 47);

@Entry
@Component
struct Index {
  @State message: string = 'Hello World'
  @StorageLink('aProp') aProp: number = 48

  build() {
    Row() {
      Column() {
        Text(this.message)
        // 應(yīng)用退出時(shí)會(huì)保存當(dāng)前結(jié)果。重新啟動(dòng)后，會(huì)顯示上一次的保存結(jié)果
        Text(`${this.aProp}`)
          .onClick(() => {
            this.aProp += 1;
          })
      }
    }
  }
}

• 新應(yīng)用安裝后首次啟動(dòng)運(yùn)行：
  1. 調(diào)用PersistProp初始化PersistentStorage，首先查詢?cè)赑ersistentStorage本地文件中是否存在“aProp”，查詢結(jié)果為不存在，因?yàn)閼?yīng)用是第一次安裝。
  2. 接著查詢屬性“aProp”在AppStorage中是否存在，依舊不存在。
  3. 在AppStorge中創(chuàng)建名為“aProp”的number類型屬性，屬性初始值是定義的默認(rèn)值47。
  4. PersistentStorage將屬性“aProp”和值47寫入磁盤，AppStorage中“aProp”對(duì)應(yīng)的值和其后續(xù)的更改將被持久化。
  5. 在Index組件中創(chuàng)建狀態(tài)變量@StorageLink('aProp') aProp，和AppStorage中“aProp”雙向綁定，在創(chuàng)建的過程中會(huì)在AppStorage中查找，成功找到“aProp”，所以使用其在AppStorage找到的值47。

• 觸發(fā)點(diǎn)擊事件后：
  1. 狀態(tài)變量@StorageLink('aProp') aProp改變，觸發(fā)Text組件重新刷新。
  2. @StorageLink裝飾的變量是和AppStorage中建立雙向同步的，所以@StorageLink('aProp') aProp的變化會(huì)被同步回AppStorage中。
  3. AppStorage中“aProp”屬性的改變會(huì)同步到所有綁定該“aProp”的單向或者雙向變量，在本示例中沒有其他的綁定“aProp”的變量。
  4. 因?yàn)椤癮Prop”對(duì)應(yīng)的屬性已經(jīng)被持久化，所以在AppStorage中“aProp”的改變會(huì)觸發(fā)PersistentStorage將新的改變寫入本地磁盤。
• 后續(xù)啟動(dòng)應(yīng)用：
  1. 執(zhí)行PersistentStorage.PersistProp('aProp', 47)，在首先查詢?cè)赑ersistentStorage本地文件查詢“aProp”屬性，成功查詢到。
  2. 將在PersistentStorage查詢到的值寫入AppStorage中。
  3. 在Index組件里，@StorageLink綁定的“aProp”為PersistentStorage寫入AppStorage中的值，即為上一次退出引用存入的值。

在PersistentStorage之前訪問AppStorage中的屬性

該示例為反例。在調(diào)用PersistentStorage.PersistProp或者PersistProps之前使用接口訪問AppStorage中的屬性是錯(cuò)誤的，因?yàn)檫@樣的調(diào)用順序會(huì)丟失上一次應(yīng)用程序運(yùn)行中的屬性值：

let aProp = AppStorage.SetOrCreate('aProp', 47);
PersistentStorage.PersistProp('aProp', 48);

應(yīng)用在非首次運(yùn)行時(shí)，先執(zhí)行AppStorage.SetOrCreate('aProp', 47)：屬性“aProp”在AppStorage中創(chuàng)建，其類型為number，其值設(shè)置為指定的默認(rèn)值47。'aProp'是持久化的屬性，所以會(huì)被寫回PersistentStorage磁盤中，PersistentStorage存儲(chǔ)的上次退出應(yīng)用的值丟失。

PersistentStorage.PersistProp('aProp', 48)：在PersistentStorage中查找到“aProp”，找到，值為47。