[一、基本語法]4@Builder裝飾器：自定義構建函式

为敢技术發表於2024-06-28
UI函式

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

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

說明

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

裝飾器使用說明

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

定義的語法：

@Builder MyBuilderFunction(){ ... }

使用方法：

this.MyBuilderFunction()
  • 允許在自定義元件內定義一個或多個@Builder方法，該方法被認為是該元件的私有、特殊型別的成員函式。
  • 自定義構建函式可以在所屬元件的build方法和其他自定義構建函式中呼叫，但不允許在元件外呼叫。
  • 在自定義函式體中，this指代當前所屬元件，元件的狀態變數可以在自定義構建函式內訪問。建議透過this訪問自定義元件的狀態變數而不是引數傳遞。

全域性自定義構建函式

定義的語法：

@Builder function MyGlobalBuilderFunction(){ ... }

使用方法：

MyGlobalBuilderFunction()
  • 全域性的自定義構建函式可以被整個應用獲取，不允許使用this和bind方法。
  • 如果不涉及元件狀態變化，建議使用全域性的自定義構建方法。

引數傳遞規則

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

  • 引數的型別必須與引數宣告的型別一致，不允許undefined、null和返回undefined、null的表示式。
  • 在自定義構建函式內部，不允許改變引數值。如果需要改變引數值，且同步回撥用點，建議使用@Link。
  • @Builder內UI語法遵循UI語法規則。
  • 只有傳入一個引數，且引數需要直接傳入物件字面量才會按引用傳遞該引數，其餘傳遞方式均為按值傳遞。

按引用傳遞引數

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

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元件中呼叫overBuilder的時候，將this.label引用傳遞給overBuilder
      overBuilder({ paramA1: this.label })
      Button('Click me').onClick(() => {
        // 點選“Click me”後，UI從“Hello”重新整理為“ArkUI”
        this.label = 'ArkUI';
      })
    }
  }
}

按值傳遞引數

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

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

相關文章