OpenHarmony装饰指定自定义组件：@BuilderParam装饰器_鸿蒙系统

当开发者创建了自定义组件，并想对该组件添加特定功能时，例如在自定义组件中添加一个点击跳转操作。若直接在组件内嵌入事件方法，将会导致所有引入该自定义组件的地方均增加了该功能。为解决此问题，arkui引入了@builderparam装饰器，@builderparam用来装饰指向@builder方法的变量，开发者可在初始化自定义组件时对此属性进行赋值，为自定义组件增加特定的功能。该装饰器用于声明任意ui描述的一个元素，类似slot占位符。

说明：

从api version 9开始，该装饰器支持在arkts卡片中使用。

装饰器使用说明

初始化@builderparam装饰的方法

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

● 使用所属自定义组件的自定义构建函数或者全局的自定义构建函数，在本地初始化@builderparam。

@builder function globalbuilder0() {}

@component
struct child {
  @builder donothingbuilder() {};

  @builderparam abuilder0: () => void = this.donothingbuilder;
  @builderparam abuilder1: () => void = globalbuilder0;
  build(){}
}

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

@component
struct child {
  @builder componentbuilder() {
    text(`parent builder `)
  }

  @builderparam abuilder0: () => void = this.componentbuilder;

  build() {
    column() {
      this.abuilder0()
    }
  }
}

@entry
@component
struct parent {
  @builder componentbuilder() {
    text(`parent builder `)
  }

  build() {
    column() {
      child({ abuilder0: this.componentbuilder })
    }
  }
}

● 需注意this指向正确。

以下示例中，parent组件在调用this.componentbuilder()时，this.label指向其所属组件，即“parent”。@builder componentbuilder()传给子组件@builderparam abuilder0，在child组件中调用this.abuilder0()时，this.label指向在child的label，即“child”。对于@builderparam abuilder1，在将this.componentbuilder传给abuilder1时，调用bind绑定了this，因此其this.label指向parent的label。

说明：

开发者谨慎使用bind改变函数调用的上下文，可能会使this指向混乱。

@component
struct child {
  @builder componentbuilder() {
    text(`child builder `)
  }

  label: string = `child`
  @builderparam abuilder0: () => void = this.componentbuilder;
  @builderparam abuilder1: () => void = this.componentbuilder;

  build() {
    column() {
      this.abuilder0()
      this.abuilder1()
    }
  }
}

@entry
@component
struct parent {
  label: string = `parent`

  @builder componentbuilder() {
    text(`${this.label}`)
  }

  build() {
    column() {
      this.componentbuilder()
      child({ abuilder0: this.componentbuilder, abuilder1: this.componentbuilder })
    }
  }
}

使用场景

参数初始化组件

@builderparam装饰的方法可以是有参数和无参数的两种形式，需与指向的@builder方法类型匹配。@builderparam装饰的方法类型需要和@builder方法类型一致。

class globalbuilderparam {
  label: string = ""
}

@builder function globalbuilder1($$ : globalbuilderparam) {
  text($$.label)
    .width(400)
    .height(50)
    .backgroundcolor(color.blue)
}

@component
struct child {
  @builder componentbuilder() {
    text(`child builder `)
  }

  label: string = 'child'
  // 无参数类，指向的componentbuilder也是无参数类型
  @builderparam abuilder0: () => void = this.componentbuilder;
  // 有参数类型，指向的globalbuilder1也是有参数类型的方法
  @builderparam abuilder1: ($$ : globalbuilderparam) => void = this.componentbuilder;

  build() {
    column() {
      this.abuilder0()
      this.abuilder1({label: 'global builder label' } )
    }
  }
}

@entry
@component
struct parent {
  label: string = 'parent'

  @builder componentbuilder() {
    text(`${this.label}`)
  }

  build() {
    column() {
      this.componentbuilder()
      child({ abuilder0: this.componentbuilder, abuilder1: globalbuilder1 })
    }
  }
}

尾随闭包初始化组件

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

说明：

此场景下自定义组件内有且仅有一个使用@builderparam装饰的属性。

开发者可以将尾随闭包内的内容看做@builder装饰的函数传给@builderparam。示例如下：

// xxx.ets
class customcontainerparam {
  header: string = '';
}
@component
struct customcontainer {
  @builder componentcloser() {
    text(`custom closer `)
  }

  @prop header: string = '';
  @builderparam closer: () => void = this.componentcloser;

  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';
  param: customcontainerparam = {
    header: this.text
  };

  build() {
    column() {
      // 创建customcontainer，在创建customcontainer时，通过其后紧跟一个大括号“{}”形成尾随闭包
      // 作为传递给子组件customcontainer @builderparam closer: () => void的参数
      customcontainer(this.param) {
        column() {
          specificparam('testa', 'testb')
        }.backgroundcolor(color.yellow)
        .onclick(() => {
          this.text = 'changeheader';
        })
      }
    }
  }
}