鴻蒙 NEXT 開(kāi)發(fā)：使用 @Builder 裝飾器優(yōu)化 UI 組件復(fù)用

在開(kāi)發(fā)鴻蒙 NEXT 應(yīng)用時(shí)，咱們需要經(jīng)常創(chuàng)建自定義組件，由于自定義組件內(nèi)部 UI 結(jié)構(gòu)固定，僅與使用方進(jìn)行數(shù)據(jù)傳遞，因此，ArkUI還提供了一種更輕量的 UI 元素復(fù)用機(jī)制@Builder。

大家好，我是 V 哥，在鴻蒙 NEXT 開(kāi)發(fā)中，@Builder 裝飾器是一種輕量級(jí)的 UI 元素復(fù)用機(jī)制，它允許開(kāi)發(fā)者將重復(fù)使用的 UI 元素抽象成一個(gè)方法，并在 build() 方法中多次調(diào)用，以實(shí)現(xiàn) UI 結(jié)構(gòu)的復(fù)用。以下是如何使用 @Builder 裝飾器來(lái)優(yōu)化 UI 組件復(fù)用的詳細(xì)介紹和案例分析：

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

@Builder 方法可以定義在組件內(nèi)或全局，用于封裝可復(fù)用的 UI 結(jié)構(gòu)。在組件內(nèi)定義的 @Builder 方法可以通過(guò) this 訪問(wèn)當(dāng)前組件的屬性和方法，而全局的 @Builder 方法則不能訪問(wèn)組件內(nèi)部的屬性和方法。

組件內(nèi) @Builder 方法：

@Entry
@Component
struct BuilderPage {
  build() {
    Column() {
      Row({ space: 50 }) {
        // 復(fù)用 UI 結(jié)構(gòu)
        this.compButtonBuilder($r('app.media.icon_edit'), '編輯', () => console.log('編輯'));
        this.compButtonBuilder($r('app.media.icon_send'), '發(fā)送', () => console.log('發(fā)送'));
      }
    }.width('100%').height('100%').justifyContent(FlexAlign.Center);
  }
  // 定義 UI 結(jié)構(gòu)
  @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);
  }
}

在這個(gè)例子中，compButtonBuilder 是一個(gè)組件內(nèi)的 @Builder 方法，它定義了一個(gè)按鈕的 UI 結(jié)構(gòu)，并在 build() 方法中被復(fù)用 。

全局 @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 }) {
        // 復(fù)用 UI 結(jié)構(gòu)
        globalButtonBuilder($r('app.media.icon_edit'), '編輯', () => console.log('編輯'));
        globalButtonBuilder($r('app.media.icon_send'), '發(fā)送', () => console.log('發(fā)送'));
      }
    }.width('100%').height('100%').justifyContent(FlexAlign.Center);
  }
}

在這個(gè)例子中，globalButtonBuilder 是一個(gè)全局的 @Builder 方法，它被定義在組件外部，并通過(guò) export 關(guān)鍵字導(dǎo)出，使其可以在應(yīng)用的任何地方被調(diào)用 。

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

@Builder 方法具有兩種參數(shù)傳遞機(jī)制——按值傳遞和按引用傳遞。當(dāng)只有一個(gè)參數(shù)且參數(shù)為對(duì)象字面量時(shí)為按引用傳遞，其余情況均為按值傳遞。按引用傳遞時(shí)，若傳遞的參數(shù)為狀態(tài)變量，則狀態(tài)變量的變化會(huì)觸發(fā) @Builder 方法內(nèi)部 UI 的刷新；按值傳遞時(shí)則不會(huì)。

@BuilderParam 裝飾器

@BuilderParam 裝飾器用于裝飾自定義組件中的屬性，使其可以作為 UI 結(jié)構(gòu)的占位符。在創(chuàng)建組件時(shí)，可以通過(guò)參數(shù)為其傳入具體的內(nèi)容，類似于 Vue 框架中的 slot。

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

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

@Builder 在購(gòu)物車(chē)顯示多個(gè)商品項(xiàng)的使用

讓我們考慮一個(gè)電商應(yīng)用中的購(gòu)物車(chē)頁(yè)面，這個(gè)頁(yè)面需要顯示多個(gè)商品項(xiàng)，每個(gè)商品項(xiàng)包括商品圖片、名稱、價(jià)格和數(shù)量選擇器。我們希望商品項(xiàng)的UI是一致的，但每個(gè)商品項(xiàng)的具體內(nèi)容（圖片、名稱、價(jià)格、數(shù)量）可能不同。這是一個(gè)典型的使用自定義組件的場(chǎng)景，我們可以通過(guò)@Builder裝飾器來(lái)實(shí)現(xiàn)這一點(diǎn)。

步驟 1: 創(chuàng)建自定義組件

首先，我們創(chuàng)建一個(gè)名為CartItem的自定義組件，它將顯示單個(gè)商品項(xiàng)的詳細(xì)信息。

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


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

在這個(gè)組件中，我們使用了@Prop裝飾器來(lái)定義屬性，這些屬性將由父組件傳遞。build()方法定義了商品項(xiàng)的UI結(jié)構(gòu)。

步驟 2: 使用自定義組件

接下來(lái)，在購(gòu)物車(chē)頁(yè)面中使用CartItem組件來(lái)顯示商品數(shù)據(jù)。

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


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

在CartPage組件中，我們定義了一個(gè)狀態(tài)變量商品列表來(lái)存儲(chǔ)商品數(shù)據(jù)。在build()方法中，我們使用ForEach循環(huán)來(lái)遍歷商品數(shù)組，并為每個(gè)商品創(chuàng)建一個(gè)CartItem組件實(shí)例，傳遞相應(yīng)的屬性。

詳細(xì)解釋一下

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

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

1. 屬性傳遞：CartItem組件的屬性是通過(guò)@Prop裝飾器定義的，這允許父組件CartPage在創(chuàng)建CartItem實(shí)例時(shí)傳遞這些屬性的值。

1. 數(shù)據(jù)驅(qū)動(dòng)：CartPage組件的狀態(tài)變量商品列表包含了商品數(shù)據(jù)。使用ForEach循環(huán)，我們?yōu)槊總€(gè)商品項(xiàng)創(chuàng)建一個(gè)CartItem組件實(shí)例，并將商品數(shù)據(jù)作為屬性傳遞給它。

1. 重用性：CartItem組件是可重用的，因?yàn)樗庋b了商品項(xiàng)的UI和邏輯，可以在購(gòu)物車(chē)頁(yè)面之外的其他部分使用，只需傳遞相應(yīng)的屬性即可。

通過(guò)這個(gè)案例，我們可以看到如何使用自定義組件和@Builder裝飾器來(lái)構(gòu)建一個(gè)具有一致UI結(jié)構(gòu)的電商應(yīng)用購(gòu)物車(chē)頁(yè)面，同時(shí)保持代碼的簡(jiǎn)潔性和可維護(hù)性。

小結(jié)一下

使用 @Builder 裝飾器可以有效地復(fù)用 UI 結(jié)構(gòu)，減少代碼冗余，并提高開(kāi)發(fā)效率。全局 @Builder 方法適用于整個(gè)應(yīng)用中可復(fù)用的 UI 結(jié)構(gòu)，而組件內(nèi)的 @Builder 方法適用于特定組件內(nèi)的復(fù)用。通過(guò)合理使用 @Builder 和 @BuilderParam 裝飾器，開(kāi)發(fā)者可以構(gòu)建更加模塊化和可維護(hù)的鴻蒙應(yīng)用 UI 組件。輕舟已過(guò)萬(wàn)重山，鴻蒙勢(shì)頭不可擋。關(guān)注威哥愛(ài)編程，一起混進(jìn)鴻蒙生態(tài)。