鸿蒙UI开发快速入门 —— part04: 组件的UI逻辑复用

1、为什么要复用？

从鸿蒙UI开发快速入门 —— part02: 组件开发文章中我们学习到，build()函数是我们构建用户UI界面的入口函数，在该函数中完成UI样式定义以及事件定义。

实际的项目开发中，一个组件的UI可能是相对比较复杂的（代码量比较多），如果把所有的UI描述代码都写在build()函数中，那维护起来真的会让人崩溃。

因此，合理的将build()函数中的逻辑抽离一部分到其他函数，那代码将变得更易理解，更易维护。

2、哪些可以复用？

在实际的UI开发中，一般可被复用的分为两个类型：1）组件的组合结构；2）组件的特定样式；

• 组件的组合结构

组件的组合结构比较容易理解，类似于HTML中的DOM树结构，它表示的是组件的层级包含关系。

针对组件的组合结构，鸿蒙提供了有两个复用方式，分别是：@Builder装饰器、@BuilderParam装饰器。

• 组件的特定样式

组件的样式复用也是字面意思，即：将公用的一些样式定义抽离出来，多个组件使用同一套样式。鸿蒙也提供了两个复用方式，分别是：@Styles装饰器、@Extend装饰器。

下面将展开说明这几个装饰器的使用。

3、 @Builder装饰器

先上demo，下面的overBuilder()展示了使用方式。

@Entry
@Component
struct Parent {
  @State label: string = 'Hello';

  // overBuilder方法被@Builder装饰器装饰
  @Builder overBuilder(paramA1: string) {
    Row() {
      Text(`UseStateVarByValue: ${paramA1} `)
    }
  }

  build() {
    Column() {
      // 这里调用了装饰器方法
      this.overBuilder(this.label)
      // 可以在基础上继续定义UI
      Text(`build().... `)
    }
  }
}

@Builder所装饰的函数遵循build()函数语法规则，开发者可以将重复使用的UI元素抽象成一个方法，在build方法里调用。@Builder装饰的函数也称为“自定义构建函数”。

使用方法如下：

1）定义@Builder函数，语法如下：

@Builder MyBuilderFunction(){ ... }

2）使用该方法，语法如下：

this.MyBuilderFunction()

需要注意一下几点：

• 允许在自定义组件内定义一个或多个@Builder方法，该方法被认为是该组件的私有、特殊类型的成员函数。

• 自定义构建函数可以在所属组件的build方法和其他自定义构建函数中调用，但不允许在组件外调用。

• 在自定义函数体中，this指代当前所属组件，组件的状态变量可以在自定义构建函数内访问。建议通过this访问自定义组件的状态变量而不是参数传递。

和普通函数一样，自定义构建函数还允许传递参数。自定义构建函数的参数传递有按值传递和按引用传递两种，均需遵守以下规则：

• 参数的类型必须与参数声明的类型一致，不允许undefined、null和返回undefined、null的表达式。

• 在自定义构建函数内部，不允许改变参数值。如果需要改变参数值，且同步回调用点，建议使用@Link。

• @Builder内UI语法遵循UI语法规则。

• 只有传入一个参数，且参数需要直接传入对象字面量才会按引用传递该参数，其余传递方式均为按值传递。

按值传递参数示例

调用@Builder装饰的函数默认按值传递。当传递的参数为状态变量时，状态变量的改变不会引起@Builder方法内的UI刷新。所以当使用状态变量的时候，推荐使用按引用传递。

@Entry
@Component
struct Parent {
  @State label: string = 'Hello';

  @Builder function overBuilder(paramA1: string) {
    Row() {
      Text(`UseStateVarByValue: ${paramA1} `)
    }
  }

  build() {
    Column() {
      this.overBuilder(this.label)
    }
  }
}

按引用传递参数示例

按引用传递参数时，传递的参数可为状态变量，且状态变量的改变会引起@Builder方法内的UI刷新。ArkUI提供$$作为按引用传递参数的范式。

@Entry
@Component
struct Parent {
  @State label: string = 'Hello';

  @Builder function overBuilder($$: { paramA1: string, paramB1 : string  }) {
    Row() {
      Text(`UseStateVarByReference: ${$$.paramA1} ${$$.paramB1}`)
    }
  }

  build() {  
    Column() {
      // 在Parent组件中调用overBuilder的时候，将this.label引用传递给overBuilder
      this.overBuilder({ paramA1: this.label })
      Button('Click me').onClick(() => {
        // 点击“Click me”后，UI从“Hello”刷新为“ArkUI”
        this.label = 'ArkUI';
      })
    }
  }
}

4、 @BuilderParam装饰器

除了组件内写死的UI逻辑,组件还可以支持外部传入自定义的构建逻辑。

@BuilderParam用来装饰指向@Builder方法的变量，开发者可在初始化自定义组件时对此属性进行赋值，为自定义组件增加特定的功能。该装饰器用于声明任意UI描述的一个元素，类似slot占位符。

@BuilderParam装饰的方法只能被自定义构建函数（@Builder装饰的方法）初始化。

@BuilderParam的初始化分为三种：1）组件内本地初始化（默认值）；2）组件的上层调用方构造函数中传入新的构建函数；3）尾随闭包初始化。

• 本地初始化，demo如下（customBuilderParam）：

@Component
struct Child {
  @Builder doNothingBuilder() {};

  // 使用自定义组件的自定义构建函数初始化@BuilderParam
  @BuilderParam customBuilderParam: () => void = this.doNothingBuilder;

  build(){}
}

• 用父组件自定义构建函数初始化子组件@BuilderParam装饰的方法。

@Component
struct Child {
  // 使用父组件@Builder装饰的方法初始化子组件@BuilderParam
  @BuilderParam customBuilderParam: () => void;

  build() {
    Column() {
      this.customBuilderParam()
    }
  }
}

@Entry
@Component
struct Parent {
  @Builder componentBuilder() {
    Text(`Parent builder `)
  }

  build() {
    Column() {
      Child({ customBuilderParam: this.componentBuilder })
    }
  }
}

• 尾随闭包初始化组件

在自定义组件中使用@BuilderParam装饰的属性时也可通过尾随闭包进行初始化。在初始化自定义组件时，组件后紧跟一个大括号“{}”形成尾随闭包场景。

开发者可以将尾随闭包内的内容看做@Builder装饰的函数传给@BuilderParam。

示例如下：

// xxx.ets
@Component
struct CustomContainer {
  @Prop header: string;
  // 使用父组件的尾随闭包{}(@Builder装饰的方法)初始化子组件@BuilderParam
  @BuilderParam closer: () => void

  build() {
    Column() {
      Text(this.header)
        .fontSize(30)
      this.closer()
    }
  }
}

@Builder function specificParam(label1: string, label2: string) {
  Column() {
    Text(label1)
      .fontSize(30)
    Text(label2)
      .fontSize(30)
  }
}

@Entry
@Component
struct CustomContainerUser {
  @State text: string = 'header';

  build() {
    Column() {
      // 创建CustomContainer，在创建CustomContainer时，通过其后紧跟一个大括号“{}”形成尾随闭包
      // 作为传递给子组件CustomContainer @BuilderParam closer: () => void的参数
      CustomContainer({ header: this.text }) {
        Column() {
          specificParam('testA', 'testB')
        }.backgroundColor(Color.Yellow)
        .onClick(() => {
          this.text = 'changeHeader';
        })
      }
    }
  }
}

预览图如下：

5、总结

至此，我们已经简单了解了使用@Builder装饰器和@BuilderParam装饰器来实现UI组合关系的复用，以及如何复用父组件传入的自定义@Builder函数。

接下来，我们将学习如何使用@Styles和@Extend装饰器复用组件的特定样式，请关注 “鸿蒙UI开发快速入门 —— part05”；