如何在鴻蒙 NEXT 中使用 @Builder 裝飾器最佳化 UI 元件的複用？

威哥爱编程發表於2024-10-16
鴻蒙UI元件

在開發鴻蒙 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 元件。輕舟已過萬重山，鴻蒙勢頭不可擋。關注威哥愛程式設計，一起混進鴻蒙生態。

相關文章