【高心星出品】
文章目錄
- V2裝飾器@param的使用
- 概念
- 使用方法
- 案例
V2裝飾器@param的使用
概念
在鴻蒙ArkTS開發中，@Param裝飾器是組件間狀態管理的重要工具，主要用于父子組件間的單向數據傳遞，這一點與V1中的@prop類似。
- @Param裝飾的變量支持本地初始化，但不允許在組件內部直接修改。
- 被@Param裝飾的變量能夠在初始化自定義組件時從外部傳入，當數據源也是狀態變量時，數據源的修改會同步給@Param。
- @Param可以接受任意類型的數據源，包括普通變量、狀態變量、常量、函數返回值等。
- @Param裝飾的變量變化時，會刷新該變量關聯的組件。
- @Param支持對基本類型（如number、boolean、string、Object、class）、內嵌類型（如Array、Set、Map、Date），以及null、undefined和聯合類型進行觀測。
- 對于復雜類型如類對象，@Param會接受數據源的引用。在組件內可以修改類對象中的屬性，該修改會同步到數據源。
- @Param的觀測能力僅限于被裝飾的變量本身。詳見觀察變化。
使用方法
- 數據流向
單向同步（父組件 → 子組件），僅支持父組件數據源變化觸發子組件更新。 - 適用條件 1
- 僅限@ComponentV2裝飾的組件（API version 12+）。
- 子組件禁止直接修改@Param裝飾的變量（需通過@Once或事件觸發父組件修改）。
- 支持類型
基本類型（number/boolean/string等）、對象、數組、Date/Map/Set等內嵌類型，以及null/undefined和聯合類型。
| @Param變量裝飾器 | 說明 |
|---|---|
| 裝飾器參數 | 無。 |
| 能否本地修改 | 否。若需要修改值，可使用@Param搭配@Once修改子組件的本地值。或通過@Event裝飾器，修改@Param數據源的值。 |
| 同步類型 | 由父到子單向同步。 |
| 允許裝飾的變量類型 | Object、class、string、number、boolean、enum等基本類型以及Array、Date、Map、Set等內嵌類型。支持null、undefined以及聯合類型。 |
| 被裝飾變量的初始值 | 允許本地初始化，若不在本地初始化，則需要和@Require裝飾器一起使用，要求必須從外部傳入初始化。 |
| 傳遞規則 | 說明 |
|---|---|
| 從父組件初始化 | @Param裝飾的變量允許本地初始化，若無本地初始化則必須從外部傳入初始化。當同時存在本地初始值與外部傳入值時，優先使用外部傳入值進行初始化。 |
| 初始化子組件 | @Param裝飾的變量可以初始化子組件中@Param裝飾的變量。 |
| 同步 | @Param可以和父組件傳入的狀態變量數據源（即@Local或@Param裝飾的變量）進行同步，當數據源發生變化時，會將修改同步給子組件的@Param。 |
案例
子組件中有一個按鈕展示@param裝飾的count，但是不能更新本地的count，父組件中有一個按鈕展示@local裝飾的count，并且與子組件的count綁定，形成單向通信效果。點擊父組件按鈕會更新父子兩者的組件顯示數據。@require配合@param會強制要求父組件初始化子組件數據。
@ComponentV2
struct child {// 強制父組件傳參@Require @Param count:number// 父組件可以傳參也可以不傳參// @Param count: number = 10build() {Column() {Button('child count: ' + this.count).width('60%').onClick(() => {// 這里會報錯，因為@param裝飾的數據不能自己更新，需要讓父組件更新 同步進來// this.count+=1})}.width('100%').padding(20)}
}@Entry
@ComponentV2
struct Parampage {@Local count: number = 10;build() {Column({ space: 20 }) {Button('page count: ' + this.count).width('60%').onClick(() => {this.count += 1})// child count與 父組件count單向綁定child({ count: this.count })}.height('100%').width('100%')}
}
同步數據為數組的時候，子組件中可以修改數組元素，不能初始化整個數組，這里的修改會形成雙向同步關系，下面案例里面點擊兩個按鈕數據會同時變化。
@ComponentV2
struct child2 {@Require @Param arr:number[]build() {Column() {Button('child count: ' + this.arr[0]).width('60%').onClick(() => {// 不可以修改整個數組，但是可以修改數組元素 形成雙向同步this.arr[0]+=1})}.width('100%').padding(20)}
}@Entry
@ComponentV2
struct Parampage1 {@Local arr:number[]=[1,2,3]build() {Column({ space: 20 }) {Button('page count: ' + this.arr[0]).width('60%').onClick(() => {this.arr[0]+=1})// child arr與 父組件arr單向綁定child2({arr:this.arr })}.height('100%').width('100%')}
}
如果單向同步的數據是復雜的結構info類，在子組件中@param裝飾的數據可以進行修改其屬性并且會同步給父組件形成局部雙向通信，
在下面案例中點擊子組件按鈕的時候in的count值已經發生了修改，父組件中的count也會修改，只不過@param和@local沒有觀察到，當先點擊子組件按鈕再點擊父組件按鈕的時候就會觀察到兩者顯示10–12–14 .
class info{count:numberconstructor(count:number) {this.count=count}
}@ComponentV2
struct child2 {@Require @Param in:info=new info(10)build() {Column() {Button('child count: ' + this.in.count).width('60%').onClick(() => {// param不允許本地修改// this.in=new info(11)// 允許修改對象的屬性 并且會同步到父組件 形成有限制的雙向同步this.in.count+=1})}.width('100%').padding(20)}
}@Entry
@ComponentV2
struct Parampage1 {@Local in:info=new info(10)build() {Column({ space: 20 }) {Button('page count: ' + this.in.count).width('60%').onClick(() => {this.in=new info(this.in.count+1)})// child count與 父組件count單向綁定child2({ in: this.in })}.height('100%').width('100%')}
}
