在開發鴻蒙 NEXT 應用時，咱們需要經常創建自定義組件，由于自定義組件內部 UI 結構固定，僅與使用方進行數據傳遞，因此，ArkUI還提供了一種更輕量的 UI 元素復用機制@Builder。

大家好，我是 V 哥，在鴻蒙 NEXT 開發中，@Builder 裝飾器是一種輕量級的 UI 元素復用機制，它允許開發者將重復使用的 UI 元素抽象成一個方法，并在 build() 方法中多次調用，以實現 UI 結構的復用。以下是如何使用 @Builder 裝飾器來優化 UI 組件復用的詳細介紹和案例分析：

自定義構建函數

@Builder 方法可以定義在組件內或全局，用于封裝可復用的 UI 結構。在組件內定義的 @Builder 方法可以通過 this 訪問當前組件的屬性和方法，而全局的 @Builder 方法則不能訪問組件內部的屬性和方法。

組件內 @Builder 方法：

@Entry
@Component
struct BuilderPage {
  build() {
    Column() {
      Row({ space: 50 }) {
        // 復用 UI 結構
        this.compButtonBuilder($r('app.media.icon_edit'), '編輯', () => console.log('編輯'));
        this.compButtonBuilder($r('app.media.icon_send'), '發送', () => console.log('發送'));
      }
    }.width('100%').height('100%').justifyContent(FlexAlign.Center);
  }
  // 定義 UI 結構
  @Builder compButtonBuilder(icon: Resource, text: string, callback: () => void) {
    Button() {
      Row({ space: 10 }) {
        Image(icon).width(25).height(25);
        Text(text).fontColor(Color.White).fontSize(25);
      }
    }.width(120).height(50).onClick(callback);
  }
}

在這個例子中，compButtonBuilder 是一個組件內的 @Builder 方法，它定義了一個按鈕的 UI 結構，并在 build() 方法中被復用 。

全局 @Builder 方法：

@Builder function globalButtonBuilder(icon: Resource, text: string, callback: () => void) {
  Button() {
    Row({ space: 10 }) {
      Image(icon).width(25).height(25);
      Text(text).fontColor(Color.White).fontSize(25);
    }
  }.width(120).height(50).onClick(callback);
}

@Entry
@Component
struct BuilderPage {
  build() {
    Column() {
      Row({ space: 50 }) {
        // 復用 UI 結構
        globalButtonBuilder($r('app.media.icon_edit'), '編輯', () => console.log('編輯'));
        globalButtonBuilder($r('app.media.icon_send'), '發送', () => console.log('發送'));
      }
    }.width('100%').height('100%').justifyContent(FlexAlign.Center);
  }
}

在這個例子中，globalButtonBuilder 是一個全局的 @Builder 方法，它被定義在組件外部，并通過 export 關鍵字導出，使其可以在應用的任何地方被調用 。

參數傳遞規則

@Builder 方法具有兩種參數傳遞機制——按值傳遞和按引用傳遞。當只有一個參數且參數為對象字面量時為按引用傳遞，其余情況均為按值傳遞。按引用傳遞時，若傳遞的參數為狀態變量，則狀態變量的變化會觸發 @Builder 方法內部 UI 的刷新；按值傳遞時則不會。

@BuilderParam 裝飾器

@BuilderParam 裝飾器用于裝飾自定義組件中的屬性，使其可以作為 UI 結構的占位符。在創建組件時，可以通過參數為其傳入具體的內容，類似于 Vue 框架中的 slot。

@Component
struct Container {
  @BuilderParam content: () => void
  build() {
    Column() {
      Text('你好，我是V哥');
      this.content(); // 占位符
      Button('點我一下試試');
    }
  }
}

在這個例子中，content 是一個使用 @BuilderParam 裝飾的屬性，它可以在初始化自定義組件時被賦值，為自定義組件增加特定的功能。

@Builder 在購物車顯示多個商品項的使用

讓我們考慮一個電商應用中的購物車頁面，這個頁面需要顯示多個商品項，每個商品項包括商品圖片、名稱、價格和數量選擇器。我們希望商品項的UI是一致的，但每個商品項的具體內容（圖片、名稱、價格、數量）可能不同。這是一個典型的使用自定義組件的場景，我們可以通過@Builder裝飾器來實現這一點。

步驟 1: 創建自定義組件

首先，我們創建一個名為CartItem的自定義組件，它將顯示單個商品項的詳細信息。

// CartItem.ets
@Component
struct CartItem {
  @Prop商品圖片: Resource;
  @Prop商品名稱: string;
  @Prop商品價格: string;
  @Prop商品數量: number;

  build() {
    Row() {
      Image(this.商品圖片).width(50).height(50);
      Column() {
        Text(this.商品名稱).fontSize(16);
        Text(this.商品價格).fontSize(14).fontColor(Color.Red);
      }
      Stepper() {
        Text(this.商品數量.toString())
      }.min(1).max(10)
    }
    .padding(10).border({ width: 1, color: Color.Grey })
  }
}

在這個組件中，我們使用了@Prop裝飾器來定義屬性，這些屬性將由父組件傳遞。build()方法定義了商品項的UI結構。

步驟 2: 使用自定義組件

接下來，在購物車頁面中使用CartItem組件來顯示商品數據。

// CartPage.ets
@Entry
@Component
struct CartPage {
  @State商品列表: Array<{
    商品圖片: Resource;
    商品名稱: string;
    商品價格: string;
    商品數量: number;
  }> = [
    {
      商品圖片: $r('app.media.product1'),
      商品名稱: '商品名稱1',
      商品價格: '￥100',
      商品數量: 1,
    },
    // 更多商品...
  ];

  build() {
    Column() {
      ForEach(this.商品列表, (item) => {
        CartItem({
          商品圖片: item.商品圖片,
          商品名稱: item.商品名稱,
          商品價格: item.商品價格,
          商品數量: item.商品數量,
        })
      })
    }.padding(10)
  }
}

在CartPage組件中，我們定義了一個狀態變量商品列表來存儲商品數據。在build()方法中，我們使用ForEach循環來遍歷商品數組，并為每個商品創建一個CartItem組件實例，傳遞相應的屬性。

詳細解釋一下

1. 自定義組件的定義：CartItem組件通過@Component裝飾器定義，使其成為一個自定義組件。它接受四個屬性：商品圖片、商品名稱、商品價格和商品數量。

2. UI布局：在CartItem的build()方法中，我們使用Row布局來水平排列商品圖片、名稱、價格和數量選擇器。每個部分都設置了相應的樣式，以確保布局的整潔和一致性。

3. 屬性傳遞：CartItem組件的屬性是通過@Prop裝飾器定義的，這允許父組件CartPage在創建CartItem實例時傳遞這些屬性的值。

4. 數據驅動：CartPage組件的狀態變量商品列表包含了商品數據。使用ForEach循環，我們為每個商品項創建一個CartItem組件實例，并將商品數據作為屬性傳遞給它。

5. 重用性：CartItem組件是可重用的，因為它封裝了商品項的UI和邏輯，可以在購物車頁面之外的其他部分使用，只需傳遞相應的屬性即可。

通過這個案例，我們可以看到如何使用自定義組件和@Builder裝飾器來構建一個具有一致UI結構的電商應用購物車頁面，同時保持代碼的簡潔性和可維護性。

小結一下

使用 @Builder 裝飾器可以有效地復用 UI 結構，減少代碼冗余，并提高開發效率。全局 @Builder 方法適用于整個應用中可復用的 UI 結構，而組件內的 @Builder 方法適用于特定組件內的復用。通過合理使用 @Builder 和 @BuilderParam 裝飾器，開發者可以構建更加模塊化和可維護的鴻蒙應用 UI 組件。輕舟已過萬重山，鴻蒙勢頭不可擋。關注威哥愛編程，一起混進鴻蒙生態。