前面章節介紹瞭如何建立一個自定義元件。該自定義元件內部UI結構固定，僅與使用方進行資料傳遞。ArkUI還提供了一種更輕量的UI元素複用機制@Builder，@Builder所裝飾的函式遵循build()函式語法規則，開發者可以將重複使用的UI元素抽象成一個方法，在build方法裡呼叫。

為了簡化語言，我們將@Builder裝飾的函式也稱為“自定義構建函式”。

說明：

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

裝飾器使用說明

自定義元件內自定義構建函式

定義的語法：

@Builder MyBuilderFunction() { ... }

使用方法：

this.MyBuilderFunction() { ... }

● 允許在自定義元件內定義一個或多個自定義構建函式，該函式被認為是該元件的私有、特殊型別的成員函式。

● 自定義構建函式可以在所屬元件的build方法和其他自定義構建函式中呼叫，但不允許在元件外呼叫。

● 在自定義函式體中，this指代當前所屬元件，元件的狀態變數可以在自定義構建函式內訪問。建議透過this訪問自定義元件的狀態變數而不是引數傳遞。

全域性自定義構建函式

定義的語法：

@Builder function MyGlobalBuilderFunction() { ... }

使用方法：

MyGlobalBuilderFunction()

● 全域性的自定義構建函式可以被整個應用獲取，不允許使用this和bind方法。

● 如果不涉及元件狀態變化，建議使用全域性的自定義構建方法。

引數傳遞規則

自定義構建函式的引數傳遞有按值傳遞和按引用傳遞兩種，均需遵守以下規則：

● 引數的型別必須與引數宣告的型別一致，不允許undefined、null和返回undefined、null的表示式。

● 在@Builder修飾的函式內部，不允許改變引數值。

● @Builder內UI語法遵循 UI語法規則。

按引用傳遞引數

按引用傳遞引數時，傳遞的引數可為狀態變數，且狀態變數的改變會引起@Builder方法內的UI重新整理。ArkUI提供$$作為按引用傳遞引數的正規化。

class ABuilderParam {
  paramA1: string = ''
  paramB1: string = ''
}
@Builder function ABuilder($$ : ABuilderParam) {...}
class ABuilderParam {
  paramA1: string = ''
}
@Builder function ABuilder($$: ABuilderParam) {
  Row() {
    Text(`UseStateVarByReference: ${$$.paramA1} `)
  }
}
@Entry
@Component
struct Parent {
  @State label: string = 'Hello';
  build() {
    Column() {
      // Pass the this.label reference to the ABuilder component when the ABuilder component is called in the Parent component.
      ABuilder({ paramA1: this.label })
      Button('Click me').onClick(() => {
        // After Click me is clicked, the UI text changes from Hello to ArkUI.
        this.label = 'ArkUI';
      })
    }
  }
}

按值傳遞引數

呼叫@Builder裝飾的函式預設按值傳遞。當傳遞的引數為狀態變數時，狀態變數的改變不會引起@Builder方法內的UI重新整理。所以當使用狀態變數的時候，推薦使用按引用傳遞。

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

OpenHarmony自定義構建函式：@Builder裝飾器