HarmonyOS NEXT开发（Beta6）自定义组件@LocalBuilder装饰器详解

当开发者使用@Builder做引用数据传递时，会考虑组件的父子关系，使用了bind(this)之后，组件的父子关系和状态管理的父子关系并不一致。为了解决组件的父子关系和状态管理的父子关系保持一致，引入@LocalBuilder装饰器。@LocalBuilder拥有和局部@Builder相同的功能，且比局部@Builder能够更好的确定组件的父子关系和状态管理的父子关系。

说明

从API version 12开始支持。

装饰器使用说明

自定义组件内自定义构建函数

定义的语法：

@LocalBuilder MyBuilderFunction() { ... }

使用方法：

this.MyBuilderFunction()

• 允许在自定义组件内定义一个或多个@LocalBuilder方法，该方法被认为是该组件的私有、特殊类型的成员函数。
• 自定义构建函数可以在所属组件的build方法和其他自定义构建函数中调用，但不允许在组件外调用。
• 在自定义函数体中，this指代当前所属组件，组件的状态变量可以在自定义构建函数内访问。建议通过this访问自定义组件的状态变量而不是参数传递。

限制条件

• @LocalBuilder只能在所属组件内声明，不允许全局声明。

• @LocalBuilder不能被内置装饰器和自定义装饰器使用。

• 自定义组件内的静态方法不能和@LocalBuilder一起使用。

@LocalBuilder和局部@Builder使用区别

@Builder方法引用传参时，为了改变this指向，使用bind(this)后，会导致组件的父子关系和状态管理的父子关系不一致，但是@LocalBuilder是否使用bind(this)，都不会改变组件的父子关系。

参数传递规则

@LocalBuilder函数的参数传递有按值传递和按引用传递两种，均需遵守以下规则：

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

• 在@LocalBuilder修饰的函数内部，不允许改变参数值。

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

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

按引用传递参数

按引用传递参数时，传递的参数可为状态变量，且状态变量的改变会引起@LocalBuilder方法内的UI刷新。

使用场景：

组件Parent内的@LocalBuilder方法在build函数内调用，按键值对写法进行传值，当点击Click me 时，@LocalBuilder内的Text文本内容会随着状态变量内容的改变而改变。

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';
      })
    }
  }
}

按引用传递参数时，如果在@LocalBuilder方法内调用自定义组件，ArkUI提供$$作为按引用传递参数的范式。

使用场景：

组件Parent内的@LocalBuilder方法内调用自定义组件，且按照引用传递参数将值传递到自定义组件，当Parent组件内状态变量值发生变化时，@LocalBuilder方法内的自定义组件HelloComponent的message值也会发生变化。

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';
      })
    }
  }
}

按值传递参数

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

使用场景：

组件Parent将@State修饰的label值按照函数传参方式传递到@LocalBuilder函数内，此时@LocalBuilder函数获取到的值为普通变量值，所以改变@State修饰的label值时，@LocalBuilder函数内的值不会发生改变。

1. @Entry
2. @Component
3. struct Parent {
4. @State label: string = 'Hello';
6. @LocalBuilder
7. citeLocalBuilder(paramA1: string) {
8. Row() {
9. Text(`UseStateVarByValue: ${paramA1} `)
10. }
11. }
13. build() {
14. Column() {
15. this.citeLocalBuilder(this.label);
16. }
17. }
18. }

@LocalBuilder和@Builder区别说明

函数componentBuilder被@Builder修饰时，显示效果是 “Child”，函数componentBuilder被@LocalBuild修饰时，显示效果是“Parent”。

说明：

@Builder componentBuilder()通过this.componentBuilder的形式传给子组件@BuilderParam customBuilderParam，this指向在Child的label，即“Child”。

@LocalBuilder componentBuilder()通过this.componentBuilder的形式传给子组件@BuilderParam customBuilderParam，this指向Parent的label，即“Parent”。

1. @Component
2. struct Child {
3. label: string = `Child`;
4. @BuilderParam customBuilderParam: () => void;
6. build() {
7. Column() {
8. this.customBuilderParam()
9. }
10. }
11. }
13. @Entry
14. @Component
15. struct Parent {
16. label: string = `Parent`;
18. @Builder componentBuilder() {
19. Text(`${this.label}`)
20. }
22. // @LocalBuilder componentBuilder() {
23. // Text(`${this.label}`)
24. // }
26. build() {
27. Column() {
28. Child({ customBuilderParam: this.componentBuilder })
29. }
30. }
31. }

使用场景

@LocalBuilder在@ComponentV2修饰的自定义组件中使用

使用局部的@LocalBuilder在@ComponentV2修饰的自定义组件中调用，修改变量触发UI刷新。

1. @ObservedV2
2. class Info {
3. @Trace name: string = '';
4. @Trace age: number = 0;
5. }
7. @ComponentV2
8. struct ChildPage {
9. @Require @Param childInfo: Info;
10. build() {
11. Column() {
12. Text(`自定义组件 name :${this.childInfo.name}`)
13. .fontSize(20)
14. .fontWeight(FontWeight.Bold)
15. Text(`自定义组件 age :${this.childInfo.age}`)
16. .fontSize(20)
17. .fontWeight(FontWeight.Bold)
18. }
19. }
20. }
22. @Entry
23. @ComponentV2
24. struct ParentPage {
25. info1: Info = { name: "Tom", age: 25 };
26. @Local info2: Info = { name: "Tom", age: 25 };
28. @LocalBuilder
29. privateBuilder() {
30. Column() {
31. Text(`局部LocalBuilder@Builder name :${this.info1.name}`)
32. .fontSize(20)
33. .fontWeight(FontWeight.Bold)
34. Text(`局部LocalBuilder@Builder age :${this.info1.age}`)
35. .fontSize(20)
36. .fontWeight(FontWeight.Bold)
37. }
38. }
40. @LocalBuilder
41. privateBuilderSecond() {
42. Column() {
43. Text(`局部LocalBuilder@Builder name :${this.info2.name}`)
44. .fontSize(20)
45. .fontWeight(FontWeight.Bold)
46. Text(`局部LocalBuilder@Builder age :${this.info2.age}`)
47. .fontSize(20)
48. .fontWeight(FontWeight.Bold)
49. }
50. }
51. build() {
52. Column() {
53. Text(`info1: ${this.info1.name} ${this.info1.age}`) // Text1
54. .fontSize(30)
55. .fontWeight(FontWeight.Bold)
56. this.privateBuilder() // 调用局部@Builder
57. Line()
58. .width('100%')
59. .height(10)
60. .backgroundColor('#000000').margin(10)
61. Text(`info2: ${this.info2.name} ${this.info2.age}`) // Text1
62. .fontSize(30)
63. .fontWeight(FontWeight.Bold)
64. this.privateBuilderSecond() // 调用局部@Builder
65. Line()
66. .width('100%')
67. .height(10)
68. .backgroundColor('#000000').margin(10)
69. Text(`info1: ${this.info1.name} ${this.info1.age}`) // Text1
70. .fontSize(30)
71. .fontWeight(FontWeight.Bold)
72. ChildPage({ childInfo: this.info1}) // 调用自定义组件
73. Line()
74. .width('100%')
75. .height(10)
76. .backgroundColor('#000000').margin(10)
77. Text(`info2: ${this.info2.name} ${this.info2.age}`) // Text2
78. .fontSize(30)
79. .fontWeight(FontWeight.Bold)
80. ChildPage({ childInfo: this.info2}) // 调用自定义组件
81. Line()
82. .width('100%')
83. .height(10)
84. .backgroundColor('#000000').margin(10)
85. Button("change info1&info2")
86. .onClick(() => {
87. this.info1 = { name: "Cat", age: 18} // Text1不会刷新，原因是没有装饰器修饰监听不到值的改变。
88. this.info2 = { name: "Cat", age: 18} // Text2会刷新，原因是有装饰器修饰，可以监听到值的改变。
89. })
90. }
91. }
92. }

最后

小编在之前的鸿蒙系统扫盲中，我明显感觉到一点，那就是许多人参与鸿蒙开发，但是又不知道从哪里下手，有很多小伙伴不知道学习哪些鸿蒙开发技术？不知道需要重点掌握哪些鸿蒙应用开发知识点？而且学习时频繁踩坑，最终浪费大量时间。所以有一份实用的鸿蒙（HarmonyOS NEXT）文档用来跟着学习是非常有必要的。 

GitCode - 全球开发者的开源社区,开源代码托管平台 希望这一份鸿蒙学习文档能够给大家带来帮助