LocalBuilder装饰器

【中工开发者】根据HarmonyOS官方文档

定义语法

@LocalBuilder
MyBuilderFunction() { ... }

使用方法

this.MyBuilderFunction()

特点

允许在自定义组件内定义一个或多个 @LocalBuilder 方法。
该方法被认为是组件的私有、特殊类型的成员函数。
自定义构建函数可以在所属组件的 build 方法和其他自定义构建函数中调用，但不允许在组件外调用。
在自定义函数体中，this 指代当前所属组件，组件的状态变量可以在自定义构建函数内访问。
限制条件
@LocalBuilder 只能在所属组件内声明，不允许全局声明。
@LocalBuilder 不能被内置装饰器和自定义装饰器使用。
自定义组件内的静态方法不能和 @LocalBuilder 一起使用。

参数传递规则

按值传递

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

按引用传递

只有传入一个参数，且参数需要直接传入对象字面量才会按引用传递该参数，其余传递方式均为按值传递。按引用传递参数时，传递的参数可为状态变量，且状态变量的改变会引起 @LocalBuilder 方法内的 UI 刷新。

使用场景

场景一：组件内状态变量的按引用传递

class ReferenceType {
  paramString: string = '';
}

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

  @LocalBuilder
  citeLocalBuilder(params: ReferenceType) {
    Row() {
      Text(`UseStateVarByReference: ${params.paramString} `)
    }
  };

  build() {
    Column() {
      this.citeLocalBuilder({ paramString: this.variableValue });
      Button('Click me').onClick(() => {
        this.variableValue = 'Hi World';
      })
    }
  }
}

当点击按钮时，variableValue 的值从 'Hello World' 变为 'Hi World'，citeLocalBuilder 方法内的 Text 组件会随之更新。

场景二：子组件调用父组件的 @LocalBuilder 函数

class ReferenceType {
  paramString: string = '';
}

@Component
struct HelloComponent {
  @Prop message: string;

  build() {
    Row() {
      Text(`HelloComponent===${this.message}`);
    }
  }
}

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

  @LocalBuilder
  citeLocalBuilder($$: ReferenceType) {
    Row() {
      Column() {
        Text(`citeLocalBuilder===${$$.paramString}`);
        HelloComponent({ message: $$.paramString });
      }
    }
  }

  build() {
    Column() {
      this.citeLocalBuilder({ paramString: this.variableValue });
      Button('Click me').onClick(() => {
        this.variableValue = 'Hi World';
      })
    }
  }
}

当 variableValue 的值发生变化时，citeLocalBuilder 方法内的 Text 组件和 HelloComponent 组件都会随之更新。

场景三：子组件引用父组件的 @LocalBuilder 函数

class LayoutSize {
  size: number = 0;
}

@Entry
@Component
struct Parent {
  label: string = 'parent';
  @State layoutSize: LayoutSize = { size: 0 };

  @LocalBuilder
  // @Builder
  componentBuilder($$: LayoutSize) {
    Text(`${'this :'+this.label}`);
    Text(`${'size :'+$$.size}`);
  }

  build() {
    Column() {
      Child({ contentBuilder: this.componentBuilder });
    }
  }
}

@Component
struct Child {
  label: string = 'child';
  @BuilderParam contentBuilder: ((layoutSize: LayoutSize) => void);
  @State layoutSize: LayoutSize = { size: 0 };

  build() {
    Column() {
      this.contentBuilder({ size: this.layoutSize.size });
      Button("add child size").onClick(() => {
        this.layoutSize.size += 1;
      })
    }
  }
}

子组件 Child 调用父组件 Parent 的 @LocalBuilder 方法 componentBuilder。由于 @LocalBuilder 绑定在父组件上，状态变量的变化不会引发 componentBuilder 方法内的 UI 刷新。

场景四：按值传递参数

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

  @LocalBuilder
  citeLocalBuilder(paramA1: string) {
    Row() {
      Text(`UseStateVarByValue: ${paramA1} `)
    }
  }

  build() {
    Column() {
      this.citeLocalBuilder(this.label);
    }
  }
}

citeLocalBuilder 方法获取到的是普通变量值，因此改变 @State 修饰的 label 值时，citeLocalBuilder 方法内的值不会发生改变。

总结

@LocalBuilder 是一个强大的装饰器，允许在自定义组件内定义私有的构建函数。它支持按值传递和按引用传递参数，但在使用时需要注意 this 的指向和状态变量的刷新机制。通过合理使用 @LocalBuilder，可以提高组件的复用性和可维护性。