ArkUI提供了一種更輕量的UI元素進制@Builder，可用于自定義組件build()方法中，達到復(fù)用的效果。

裝飾器使用說明

自定義組件內(nèi)自定義構(gòu)建函數(shù)

定義：

@Builder MyBuilderFunction(){ ... }

使用

this.MyBuilderFunction()

• 允許在自定義組件內(nèi)定義一個或多個@Builder方法，該方法被認為是該組件的私有、特殊類型的成員函數(shù)。
• 自定義構(gòu)建函數(shù)可以在所屬組件的build方法和其他自定義構(gòu)建函數(shù)中調(diào)用，但不允許在組件外調(diào)用。
• 在自定義函數(shù)體中，this指代當(dāng)前所屬組件，組件的狀態(tài)變量可以在自定義構(gòu)建函數(shù)內(nèi)訪問。建議通過this訪問自定義組件的狀態(tài)變量而不是參數(shù)傳遞。

全局自定義構(gòu)建函數(shù)

定義：

@Builder function MyGlobalBuilderFunction(){ ... }

使用：

MyGlobalBuilderFunction()

• 全局的自定義構(gòu)建函數(shù)可以被整個應(yīng)用獲取，不允許使用this和bind方法。
• 如果不涉及組件狀態(tài)變化，建議使用全局的自定義構(gòu)建方法。

參數(shù)傳遞規(guī)則

自定義構(gòu)建函數(shù)的參數(shù)傳遞有 按值傳遞 和 按引用傳遞 兩種，均需遵守以下規(guī)則：

• 參數(shù)的類型必須與參數(shù)聲明的類型一致，不允許undefined、null和返回undefined、null的表達式。
• 在自定義構(gòu)建函數(shù)內(nèi)部，不允許改變參數(shù)值。如果需要改變參數(shù)值，且同步回調(diào)用點，建議使用@Link。
• @Builder內(nèi)UI語法遵循UI語法規(guī)則。
• 只有傳入一個參數(shù)，且參數(shù)需要直接傳入對象字面量才會按引用傳遞該參數(shù)，其余傳遞方式均為按值傳遞。

按引用傳遞參數(shù)

按引用傳遞參數(shù)時，傳遞的參數(shù)可為狀態(tài)變量，且狀態(tài)變量的改變會引起@Builder方法內(nèi)的UI刷新。ArkUI提供$$作為按引用傳遞參數(shù)的范式。

overBuilder( $$ : { paramA1: string, paramB1 : string } );

@Builder function overBuilder($$: { paramA1: string }) {
  Row() {
    Text(`UseStateVarByReference: ${$$.paramA1} `)
  }
}
@Entry
@Component
struct Parent {
  @State label: string = 'Hello';
  build() {
    Column() {
      // 在Parent組件中調(diào)用ABuilder的時候，將this.label引用傳遞給ABuilder
      overBuilder({ paramA1: this.label })
      Button('Click me').onClick(() => {
        // 點擊“Click me”后，UI從“Hello”刷新為“ArkUI”
        this.label = 'ArkUI';
      })
    }
  }
}

按值傳遞參數(shù)

調(diào)用@Builder裝飾的函數(shù)默認按值傳遞。當(dāng)傳遞的參數(shù)為狀態(tài)變量時，狀態(tài)變量的改變不會引起@Builder方法內(nèi)的UI刷新。所以當(dāng)使用狀態(tài)變量的時候，推薦使用按引用傳遞。

@Builder function overBuilder(paramA1: string) {
  Row() {
    Text(`UseStateVarByValue: ${paramA1} `)
  }
}
@Entry
@Component
struct Parent {
  @State label: string = 'Hello';
  build() {
    Column() {
      overBuilder(this.label)
    }
  }
}