AppStorage：應(yīng)用全局的UI狀態(tài)存儲

概述

AppStorage是在應(yīng)用啟動的時(shí)候會被創(chuàng)建的單例。它的目的是為了提供應(yīng)用狀態(tài)數(shù)據(jù)的中心存儲，這些狀態(tài)數(shù)據(jù)在應(yīng)用級別都是可訪問的。AppStorage將在應(yīng)用運(yùn)行過程保留其屬性。屬性通過唯一的鍵字符串值訪問。

AppStorage可以和UI組件同步，且可以在應(yīng)用業(yè)務(wù)邏輯中被訪問。

AppStorage中的屬性可以被雙向同步，數(shù)據(jù)可以是存在于本地或遠(yuǎn)程設(shè)備上，并具有不同的功能，比如數(shù)據(jù)持久化（詳見PersistentStorage）。這些數(shù)據(jù)是通過業(yè)務(wù)邏輯中實(shí)現(xiàn)，與UI解耦，如果希望這些數(shù)據(jù)在UI中使用，需要用到@StorageProp和@StorageLink。

@StorageProp

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

當(dāng)自定義組件初始化的時(shí)候，@StorageProp(key)/@StorageLink(key)裝飾的變量會通過給定的key，綁定在AppStorage對應(yīng)的屬性，完成初始化。本地初始化是必要的，因?yàn)闊o法保證AppStorage一定存在給定的key，這取決于應(yīng)用邏輯，是否在組件初始化之前在AppStorage實(shí)例中存入對應(yīng)的屬性。

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

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

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

觀察變化

@StorageLink

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

1. 本地修改發(fā)生，該修改會被寫回AppStorage中；
2. AppStorage中的修改發(fā)生后，該修改會被同步到所有綁定AppStorage對應(yīng)key的屬性上，包括單向（@StorageProp和通過Prop創(chuàng)建的單向綁定變量）、雙向（@StorageLink和通過Link創(chuàng)建的雙向綁定變量）變量和其他實(shí)例（比如PersistentStorage）。

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

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

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

觀察變化

使用場景

從應(yīng)用邏輯使用AppStorage和LocalStorage

AppStorage是單例，它的所有API都是靜態(tài)的，使用方法類似于LocalStorage對應(yīng)的非靜態(tài)方法。

AppStorage.SetOrCreate('PropA', 47);

let storage: LocalStorage = new LocalStorage({ 'PropA': 17 });
let propA: number = AppStorage.Get('PropA') // propA in AppStorage == 47, propA in LocalStorage == 17
var link1: SubscribedAbstractProperty<number> = AppStorage.Link('PropA'); // link1.get() == 47
var link2: SubscribedAbstractProperty<number> = AppStorage.Link('PropA'); // link2.get() == 47
var prop: SubscribedAbstractProperty<number> = AppStorage.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

storage.get('PropA') // == 17 
storage.set('PropA', 101);
storage.get('PropA') // == 101

AppStorage.Get('PropA') // == 49
link1.get() // == 49
link2.get() // == 49
prop.get() // == 49

從UI內(nèi)部使用AppStorage和LocalStorage

@StorageLink變量裝飾器與AppStorage配合使用，正如@LocalStorageLink與LocalStorage配合使用一樣。此裝飾器使用AppStorage中的屬性創(chuàng)建雙向數(shù)據(jù)同步。

AppStorage.SetOrCreate('PropA', 47);
let storage = new LocalStorage({ 'PropA': 48 });

@Entry(storage)
@Component
struct CompA {
  @StorageLink('PropA') storLink: number = 1;
  @LocalStorageLink('PropA') localStorLink: number = 1;

  build() {
    Column({ space: 20 }) {
      Text(`From AppStorage ${this.storLink}`)
        .onClick(() => this.storLink += 1)

      Text(`From LocalStorage ${this.localStorLink}`)
        .onClick(() => this.localStorLink += 1)
    }
  }
}

不建議借助@StorageLink的雙向同步機(jī)制實(shí)現(xiàn)事件通知

不建議開發(fā)者使用@StorageLink和AppStorage的雙向同步的機(jī)制來實(shí)現(xiàn)事件通知，AppStorage是和UI相關(guān)的數(shù)據(jù)存儲，改變會帶來UI的刷新，相對于一般的事件通知，UI刷新的成本較大。

TapImage中的點(diǎn)擊事件，會觸發(fā)AppStorage中tapIndex對應(yīng)屬性的改變。因?yàn)锧StorageLink是雙向同步，修改會同步回AppStorage中，所以，所有綁定AppStorage的tapIndex自定義組件都會被通知UI刷新。UI刷新帶來的成本是巨大的，因此不建議開發(fā)者使用此方式來實(shí)現(xiàn)基本的事件通知功能。

// xxx.ets
class ViewData {
  title: string;
  uri: Resource;
  color: Color = Color.Black;

  constructor(title: string, uri: Resource) {
    this.title = title;
    this.uri = uri
  }
}

@Entry
@Component
struct Gallery2 {
  dataList: Array<ViewData> = [new ViewData('flower', $r('app.media.icon')), new ViewData('OMG', $r('app.media.icon')), new ViewData('OMG', $r('app.media.icon'))]
  scroller: Scroller = new Scroller()

  build() {
    Column() {
      Grid(this.scroller) {
        ForEach(this.dataList, (item: ViewData, index?: number) => {
          GridItem() {
            TapImage({
              uri: item.uri,
              index: index
            })
          }.aspectRatio(1)

        }, (item: ViewData, index?: number) => {
          return JSON.stringify(item) + index;
        })
      }.columnsTemplate('1fr 1fr')
    }

  }
}

@Component
export struct TapImage {
  @StorageLink('tapIndex') @Watch('onTapIndexChange') tapIndex: number = -1;
  @State tapColor: Color = Color.Black;
  private index: number = 0;
  private uri: Resource = {
    id: 0,
    type: 0,
    moduleName: "",
    bundleName: ""
  };

  // 判斷是否被選中
  onTapIndexChange() {
    if (this.tapIndex >= 0 && this.index === this.tapIndex) {
      console.info(`tapindex: ${this.tapIndex}, index: ${this.index}, red`)
      this.tapColor = Color.Red;
    } else {
      console.info(`tapindex: ${this.tapIndex}, index: ${this.index}, black`)
      this.tapColor = Color.Black;
    }
  }

  build() {
    Column() {
      Image(this.uri)
        .objectFit(ImageFit.Cover)
        .onClick(() => {
          this.tapIndex = this.index;
        })
        .border({ width: 5, style: BorderStyle.Dotted, color: this.tapColor })
    }

  }
}

開發(fā)者可以使用emit訂閱某個事件并接收事件回調(diào)，可以減少開銷，增強(qiáng)代碼的可讀性。

// xxx.ets
import emitter from '@ohos.events.emitter';

let NextID: number = 0;

class ViewData {
  title: string;
  uri: Resource;
  color: Color = Color.Black;
  id: number;

  constructor(title: string, uri: Resource) {
    this.title = title;
    this.uri = uri
    this.id = NextID++;
  }
}

@Entry
@Component
struct Gallery2 {
  dataList: Array<ViewData> = [new ViewData('flower', $r('app.media.icon')), new ViewData('OMG', $r('app.media.icon')), new ViewData('OMG', $r('app.media.icon'))]
  scroller: Scroller = new Scroller()
  private preIndex: number = -1

  build() {
    Column() {
      Grid(this.scroller) {
        ForEach(this.dataList, (item: ViewData) => {
          GridItem() {
            TapImage({
              uri: item.uri,
              index: item.id
            })
          }.aspectRatio(1)
          .onClick(() => {
            if (this.preIndex === item.id) {
              return
            }
            let innerEvent: emitter.InnerEvent = { eventId: item.id }
            // 選中態(tài)：黑變紅
            let eventData: emitter.EventData = {
              data: {
                "colorTag": 1
              }
            }
            emitter.emit(innerEvent, eventData)

            if (this.preIndex != -1) {
              console.info(`preIndex: ${this.preIndex}, index: ${item.id}, black`)
              let innerEvent: emitter.InnerEvent = { eventId: this.preIndex }
              // 取消選中態(tài)：紅變黑
              let eventData: emitter.EventData = {
                data: {
                  "colorTag": 0
                }
              }
              emitter.emit(innerEvent, eventData)
            }
            this.preIndex = item.id
          })
        }, (item: ViewData) => JSON.stringify(item))
      }.columnsTemplate('1fr 1fr')
    }

  }
}

@Component
export struct TapImage {
  @State tapColor: Color = Color.Black;
  private index: number = 0;
  private uri: Resource = {
    id: 0,
    type: 0,
    moduleName: "",
    bundleName: ""
  };

  onTapIndexChange(colorTag: emitter.EventData) {
    if (colorTag.data != null) {
      this.tapColor = colorTag.data.colorTag ? Color.Red : Color.Black
    }
  }

  aboutToAppear() {
    //定義事件ID
    let innerEvent: emitter.InnerEvent = { eventId: this.index }
    emitter.on(innerEvent, data => {
      this.onTapIndexChange(data)
    })
  }

  build() {
    Column() {
      Image(this.uri)
        .objectFit(ImageFit.Cover)
        .border({ width: 5, style: BorderStyle.Dotted, color: this.tapColor })
    }
  }
}

以上通知事件邏輯簡單，也可以簡化成三元表達(dá)式。

// xxx.ets
class ViewData {
  title: string;
  uri: Resource;
  color: Color = Color.Black;

  constructor(title: string, uri: Resource) {
    this.title = title;
    this.uri = uri
  }
}

@Entry
@Component
struct Gallery2 {
  dataList: Array<ViewData> = [new ViewData('flower', $r('app.media.icon')), new ViewData('OMG', $r('app.media.icon')), new ViewData('OMG', $r('app.media.icon'))]
  scroller: Scroller = new Scroller()

  build() {
    Column() {
      Grid(this.scroller) {
        ForEach(this.dataList, (item: ViewData, index?: number) => {
          GridItem() {
            TapImage({
              uri: item.uri,
              index: index
            })
          }.aspectRatio(1)

        }, (item: ViewData, index?: number) => {
          return JSON.stringify(item) + index;
        })
      }.columnsTemplate('1fr 1fr')
    }

  }
}

@Component
export struct TapImage {
  @StorageLink('tapIndex') tapIndex: number = -1;
  @State tapColor: Color = Color.Black;
  private index: number = 0;
  private uri: Resource = {
    id: 0,
    type: 0,
    moduleName: "",
    bundleName: ""
  };

  build() {
    Column() {
      Image(this.uri)
        .objectFit(ImageFit.Cover)
        .onClick(() => {
          this.tapIndex = this.index;
        })
        .border({
          width: 5,
          style: BorderStyle.Dotted,
          color: (this.tapIndex >= 0 && this.index === this.tapIndex) ? Color.Red : Color.Black
        })
    }
  }
}

限制條件

AppStorage與PersistentStorage以及Environment配合使用時(shí)，需要注意以下幾點(diǎn)：

• 在AppStorage中創(chuàng)建屬性后，調(diào)用PersistentStorage.persistProp()接口時(shí)，會使用在AppStorage中已經(jīng)存在的值，并覆蓋PersistentStorage中的同名屬性，所以建議要使用相反的調(diào)用順序，反例可見在PersistentStorage之前訪問AppStorage中的屬性。
• 如果在AppStorage中已經(jīng)創(chuàng)建屬性后，再調(diào)用Environment.envProp()創(chuàng)建同名的屬性，會調(diào)用失敗。因?yàn)锳ppStorage已經(jīng)有同名屬性，Environment環(huán)境變量不會再寫入AppStorage中，所以建議AppStorage中屬性不要使用Environment預(yù)置環(huán)境變量名。
• 狀態(tài)裝飾器裝飾的變量，改變會引起UI的渲染更新，如果改變的變量不是用于UI更新，只是用于消息傳遞，推薦使用 emitter方式。例子可見不建議借助@StorageLink的雙向同步機(jī)制實(shí)現(xiàn)事件通知。