@Prop裝飾器：父子單向同步

概述

@Prop裝飾的變量和父組件建立單向的同步關(guān)系：

• @Prop變量允許在本地修改，但修改后的變化不會同步回父組件。
• 當(dāng)父組件中的數(shù)據(jù)源更改時(shí)，與之相關(guān)的@Prop裝飾的變量都會自動(dòng)更新。如果子組件已經(jīng)在本地修改了@Prop裝飾的相關(guān)變量值，而在父組件中對應(yīng)的@State裝飾的變量被修改后，子組件本地修改的@Prop裝飾的相關(guān)變量值將被覆蓋。

限制條件

@Prop裝飾器不能在@Entry裝飾的自定義組件中使用。

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

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

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

觀察變化

@Prop裝飾的數(shù)據(jù)可以觀察到以下變化。

• 當(dāng)裝飾的類型是允許的類型，即string、number、boolean、enum類型都可以觀察到的賦值變化；

  // 簡單類型
  @Prop count: number;
  // 賦值的變化可以被觀察到
  this.count = 1;

對于@State和@Prop的同步場景：

• 使用父組件中@State變量的值初始化子組件中的@Prop變量。當(dāng)@State變量變化時(shí)，該變量值也會同步更新至@Prop變量。
• @Prop裝飾的變量的修改不會影響其數(shù)據(jù)源@State裝飾變量的值。
• 除了@State，數(shù)據(jù)源也可以用@Link或@Prop裝飾，對@Prop的同步機(jī)制是相同的。
• 數(shù)據(jù)源和@Prop變量的類型需要相同。

框架行為

要理解@Prop變量值初始化和更新機(jī)制，有必要了解父組件和擁有@Prop變量的子組件初始渲染和更新流程。

1. 初始渲染：
   1. 執(zhí)行父組件的build()函數(shù)將創(chuàng)建子組件的新實(shí)例，將數(shù)據(jù)源傳遞給子組件；
   2. 初始化子組件@Prop裝飾的變量。
2. 更新：
   1. 子組件@Prop更新時(shí)，更新僅停留在當(dāng)前子組件，不會同步回父組件；
   2. 當(dāng)父組件的數(shù)據(jù)源更新時(shí)，子組件的@Prop裝飾的變量將被來自父組件的數(shù)據(jù)源重置，所有@Prop裝飾的本地的修改將被父組件的更新覆蓋。

使用場景

父組件@State到子組件@Prop簡單數(shù)據(jù)類型同步

父組件@State數(shù)組項(xiàng)到子組件@Prop簡單數(shù)據(jù)類型同步

從父組件中的@State類對象屬性到@Prop簡單類型的同步

如果圖書館有一本圖書和兩位用戶，每位用戶都可以將圖書標(biāo)記為已讀，此標(biāo)記行為不會影響其它讀者用戶。從代碼角度講，對@Prop圖書對象的本地更改不會同步給圖書館組件中的@State圖書對象。

class Book {
  public title: string;
  public pages: number;
  public readIt: boolean = false;

  constructor(title: string, pages: number) {
    this.title = title;
    this.pages = pages;
  }
}

@Component
struct ReaderComp {
  @Prop title: string;
  @Prop readIt: boolean;

  build() {
    Row() {
      Text(this.title)
      Text(`... ${this.readIt ? 'I have read' : 'I have not read it'}`)
        .onClick(() => this.readIt = true)
    }
  }
}

@Entry
@Component
struct Library {
  @State book: Book = new Book('100 secrets of C++', 765);

  build() {
    Column() {
      ReaderComp({ title: this.book.title, readIt: this.book.readIt })
      ReaderComp({ title: this.book.title, readIt: this.book.readIt })
    }
  }
}

@Prop本地初始化不和父組件同步

為了支持@Component裝飾的組件復(fù)用場景，@Prop支持本地初始化，這樣可以讓@Prop是否與父組件建立同步關(guān)系變得可選。當(dāng)且僅當(dāng)@Prop有本地初始化時(shí)，從父組件向子組件傳遞@Prop的數(shù)據(jù)源才是可選的。

下面的示例中，子組件包含兩個(gè)@Prop變量：

• @Prop customCounter沒有本地初始化，所以需要父組件提供數(shù)據(jù)源去初始化@Prop，并當(dāng)父組件的數(shù)據(jù)源變化時(shí)，@Prop也將被更新；
• @Prop customCounter2有本地初始化，在這種情況下，@Prop依舊允許但非強(qiáng)制父組件同步數(shù)據(jù)源給@Prop。

  @Component
  struct MyComponent {
    @Prop customCounter: number;
    @Prop customCounter2: number = 5;
  
    build() {
      Column() {
        Row() {
          Text(`From Main: ${this.customCounter}`).fontColor('#ff6b6565').margin({ left: -110, top: 12 })
        }
  
        Row() {
          Button('Click to change locally !')
            .width(288)
            .height(40)
            .margin({ left: 30, top: 12 })
            .fontColor('#FFFFFF，90%')
            .onClick(() => {
              this.customCounter2++
            })
        }
  
        Row() {
          Text(`Custom Local: ${this.customCounter2}`).fontColor('#ff6b6565').margin({ left: -110, top: 12 })
        }
      }
    }
  }
  
  @Entry
  @Component
  struct MainProgram {
    @State mainCounter: number = 10;
  
    build() {
      Column() {
        Row() {
          Column() {
            // customCounter必須從父組件初始化，因?yàn)镸yComponent的customCounter成員變量缺少本地初始化；此處，customCounter2可以不做初始化。
            MyComponent({ customCounter: this.mainCounter })
            // customCounter2也可以從父組件初始化，父組件初始化的值會覆蓋子組件customCounter2的本地初始化的值
            MyComponent({ customCounter: this.mainCounter, customCounter2: this.mainCounter })
          }
        }
  
        Row() {
          Column() {
            Button('Click to change number')
              .width(288)
              .height(40)
              .margin({ left: 30, top: 12 })
              .fontColor('#FFFFFF，90%')
              .onClick(() => {
                this.mainCounter++
              })
          }
        }
      }
    }
  }