【中秋國慶不斷更】OpenHarmony組件內狀態變數使用：@State裝飾器

@State裝飾的變數，或稱為狀態變數，一旦變數擁有了狀態屬性，就和自定義組件的渲染綁定起來。當狀態改變時，UI會發生對應的渲染改變。

在狀態變數相關裝飾器中，@State是最基礎的，使變數擁有狀態屬性的裝飾器，它也是大部分狀態變數的數據源。

說明：

從API version 9開始，該裝飾器支持在ArkTS卡片中使用。

概述

@State裝飾的變數，與聲明式範式中的其他被裝飾變數一樣，是私有的，只能從組件內部訪問，在聲明時必須指定其類型和本地初始化。初始化也可選擇使用命名參數機制從父組件完成初始化。

@State裝飾的變數擁有以下特點：

​ ● @State裝飾的變數與子組件中的@Prop、@Link或@ObjectLink裝飾變數之間建立單向或雙向數據同步。

​ ● @State裝飾的變數生命周期與其所屬自定義組件的生命周期相同。

裝飾器使用規則說明

變數的傳遞/訪問規則說明

圖1 初始化規則圖示

觀察變化和行為表現

並不是狀態變數的所有更改都會引起UI的刷新，只有可以被框架觀察到的修改才會引起UI刷新。該小節去介紹什麼樣的修改才能被觀察到，以及觀察到變化後，框架的是怎麼引起UI刷新的，即框架的行為表現是什麼。

觀察變化

​ ● 當裝飾的數據類型為boolean、string、number類型時，可以觀察到數值的變化。

// for simple type
@State count: number = 0;
// value changing can be observed
this.count = 1;

​ ● 當裝飾的數據類型為class或者Object時，可以觀察到自身的賦值的變化，和其屬性賦值的變化，即Object.keys(observedObject)返回的所有屬性。例子如下。 聲明ClassA和Model類。

  class ClassA {
    public value: string;
  
    constructor(value: string) {
      this.value = value;
    }
  }
  
  class Model {
    public value: string;
    public name: ClassA;
    constructor(value: string, a: ClassA) {
      this.value = value;
      this.name = a;
    }
  }

@State裝飾的類型是Model

// class類型
 @State title: Model = new Model('Hello', new ClassA('World'));

對@State裝飾變數的賦值。

// class類型賦值
this.title = new Model('Hi', new ClassA('ArkUI'));

對@State裝飾變數的屬性賦值。

// class屬性的賦值
this.title.value = 'Hi'

嵌套屬性的賦值觀察不到。

// 嵌套的屬性賦值觀察不到
this.title.name.value = 'ArkUI'

​ ● 當裝飾的對象是array時，可以觀察到數組本身的賦值和添加、刪除、更新數組的變化。例子如下。 聲明ClassA和Model類。

class Model {
  public value: number;
  constructor(value: number) {
    this.value = value;
  }
}

@State裝飾的對象為Model類型數組時。

@State title: Model[] = [new Model(11), new Model(1)]

數組自身的賦值可以觀察到。

this.title = [new Model(2)]

數組項的賦值可以觀察到。

this.title[0] = new Model(2)

刪除數組項可以觀察到。

this.title.pop()

新增數組項可以觀察到。

this.title.push(new Model(12))

​ ● 當裝飾的對象是Date時，可以觀察到Date整體的賦值，同時可通過調用Date的介面setFullYear, setMonth, setDate, setHours, setMinutes, setSeconds, setMilliseconds, setTime, setUTCFullYear, setUTCMonth, setUTCDate, setUTCHours, setUTCMinutes, setUTCSeconds, setUTCMilliseconds 更新Date的屬性。

@Entry
@Component
struct DatePickerExample {
  @State selectedDate: Date = new Date('2021-08-08')

  build() {
    Column() {
      Button('set selectedDate to 2023-07-08')
        .margin(10)
        .onClick(() => {
          this.selectedDate = new Date('2023-07-08')
        })
      Button('increase the year by 1')
        .margin(10)
        .onClick(() => {
          this.selectedDate.setFullYear(this.selectedDate.getFullYear() + 1)
        })
      Button('increase the month by 1')
        .margin(10)
        .onClick(() => {
          this.selectedDate.setMonth(this.selectedDate.getMonth() + 1)
        })
      Button('increase the day by 1')
        .margin(10)
        .onClick(() => {
          this.selectedDate.setDate(this.selectedDate.getDate() + 1)
        })
      DatePicker({
        start: new Date('1970-1-1'),
        end: new Date('2100-1-1'),
        selected: this.selectedDate
      })
    }.width('100%')
  }
}

框架行為

​ ● 當狀態變數被改變時，查詢依賴該狀態變數的組件；

​ ● 執行依賴該狀態變數的組件的更新方法，組件更新渲染；

​ ● 和該狀態變數不相關的組件或者UI描述不會發生重新渲染，從而實現頁面渲染的按需更新。

使用場景

裝飾簡單類型的變數

以下示例為@State裝飾的簡單類型，count被@State裝飾成為狀態變數，count的改變引起Button組件的刷新：

​ ● 當狀態變數count改變時，查詢到只有Button組件關聯了它；

​ ● 執行Button組件的更新方法，實現按需刷新。

@Entry
@Component
struct MyComponent {
  @State count: number = 0;

  build() {
    Button(`click times: ${this.count}`)
      .onClick(() => {
        this.count += 1;
      })
  }
}

裝飾class對象類型的變數

​ ● 自定義組件MyComponent定義了被@State裝飾的狀態變數count和title，其中title的類型為自定義類Model。如果count或title的值發生變化，則查詢MyComponent中使用該狀態變數的UI組件，併進行重新渲染。

​ ● EntryComponent中有多個MyComponent組件實例，第一個MyComponent內部狀態的更改不會影響第二個MyComponent。

class Model {
  public value: string;

  constructor(value: string) {
    this.value = value;
  }
}

@Entry
@Component
struct EntryComponent {
  build() {
    Column() {
      // 此處指定的參數都將在初始渲染時覆蓋本地定義的預設值，並不是所有的參數都需要從父組件初始化
      MyComponent({ count: 1, increaseBy: 2 })
      MyComponent({ title: new Model('Hello, World 2'), count: 7 })
    }
  }
}

@Component
struct MyComponent {
  @State title: Model = new Model('Hello World');
  @State count: number = 0;
  private increaseBy: number = 1;

  build() {
    Column() {
      Text(`${this.title.value}`)
      Button(`Click to change title`).onClick(() => {
        // @State變數的更新將觸發上面的Text組件內容更新
        this.title.value = this.title.value === 'Hello ArkUI' ? 'Hello World' : 'Hello ArkUI';
      })

      Button(`Click to increase count=${this.count}`).onClick(() => {
        // @State變數的更新將觸發該Button組件的內容更新
        this.count += this.increaseBy;
      })
    }
  }
}

從該示例中，我們可以瞭解到@State變數首次渲染的初始化流程：

​ 1. 使用預設的本地初始化：

@State title: Model = new Model('Hello World');
@State count: number = 0;

​ 2. 對於@State來說，命名參數機制傳遞的值並不是必選的，如果沒有命名參數傳值，則使用本地初始化的預設值：

class C1 {
   public count:number;
   public increaseBy:number;
   constructor(count: number, increaseBy:number) {
   this.count = count;
   this.increaseBy = increaseBy;
  }
}
let obj = new C1(1, 2)
MyComponent(obj)

本文由博客一文多發平臺 OpenWrite 發佈！