• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @Builder
2
3
4The **@Builder** decorated method is used to define the declarative UI description of a component and quickly generate multiple layouts in a custom component. The functionality and syntax of the **@Builder** decorator are the same as those of the [build Function](ts-function-build.md).
5
6
7```ts
8// xxx.ets
9@Entry
10@Component
11struct CompA {
12  size1 : number = 100;
13
14  @Builder SquareText(label: string) {
15    Text(label)
16      .width(1 * this.size1)
17      .height(1 * this.size1)
18  }
19
20  @Builder RowOfSquareTexts(label1: string, label2: string) {
21    Row() {
22      this.SquareText(label1)
23      this.SquareText(label2)
24    }
25    .width(2 * this.size1)
26    .height(1 * this.size1)
27  }
28
29  build() {
30    Column() {
31      Row() {
32        this.SquareText("A")
33        this.SquareText("B")
34        // or as long as tsc is used
35      }
36      .width(2 * this.size1)
37      .height(1 * this.size1)
38      this.RowOfSquareTexts("C", "D")
39    }
40    .width(2 * this.size1)
41    .height(2 * this.size1)
42  }
43}
44```
45## @BuilderParam<sup>8+<sup>
46The **@BuilderParam** decorator is used to modify the function type attributes (for example, `@BuilderParam content: () => any;`) in a custom component. When the custom component is initialized, the attributes modified by the **@BuilderParam** decorator must be assigned values.
47
48### Background
49
50In certain circumstances, you may need to add a specific function, such as a click-to-jump action, to a custom component. However, embedding an event method directly inside of the component will add the function to all places where the component is initialized. This is where the **@BuilderParam** decorator comes into the picture. When initializing a custom component, you can assign a **@Builder** decorated method to the **@BuilderParam** decorated attribute, thereby adding the specific function to the custom component.
51
52### Component Initialization Through Parameters
53When initializing a custom component through parameters, assign a **@Builder** decorated method to the **@BuilderParam** decorated attribute — **content**, and call the value of **content** in the custom component. If no parameter is passed when assigning a value to the **@BuilderParam** decorated attribute (for example, `content: this.specificParam`), define the type of the attribute as a function without a return value (for example, `@BuilderParam content: () => void`). If any parameter is passed when assigning a value to the **@BuilderParam** decorated attribute (for example, `callContent: this.specificParam1("111")`), define the type of the attribute as `any` (for example,`@BuilderParam callContent: any;`).
54
55```ts
56// xxx.ets
57@Component
58struct CustomContainer {
59  header: string = "";
60  @BuilderParam noParam: () => void;
61  @BuilderParam withParam: any;
62  footer: string = "";
63  build() {
64    Column() {
65      Text(this.header)
66        .fontSize(50)
67      this.noParam()
68      this.withParam()
69      Text(this.footer)
70        .fontSize(50)
71    }
72  }
73}
74
75@Entry
76@Component
77struct CustomContainerUser {
78  @Builder specificNoParam() {
79    Column() {
80      Text("noParam").fontSize(50)
81    }
82  }
83  @Builder SpecificWithParam(label: string) {
84    Column() {
85      Text(label).fontSize(50)
86    }
87  }
88
89  build() {
90    Column() {
91      CustomContainer({
92        header: "Header",
93        noParam: this.specificNoParam,
94        withParam: this.SpecificWithParam("WithParam"),
95        footer: "Footer",
96      })
97    }
98  }
99}
100```
101### Component Initialization Through Trailing Closure
102In a custom component, use the **@BuilderParam** decorated attribute to receive a trailing closure. When the custom component is initialized, the component name is followed by a pair of braces ({}) to form a trailing closure (`CustomComponent(){}`). You can consider a trailing closure as a container and add content to it. For example, you can add a component (`{Column(){Text("content")}`) to a trailing closure. The syntax of the closure is the same as that of [build](../ui/ts-function-build.md). In this scenario, the custom component has one and only one **@BuilderParam** decorated attribute.
103
104Example: Add a **\<Column>** component and a click event to the closure, and call the **specificParam** method decorated by **@Builder** in the new **\<Column>** component. After the **\<Column>** component is clicked, the value of the component's `header` attribute will change to `changeHeader`. In addition, when the component is initialized, the content of the trailing closure will be assigned to the `closer` attribute decorated by **@BuilderParam**.
105```ts
106// xxx.ets
107@Component
108struct CustomContainer {
109  header: string = "";
110  @BuilderParam closer: () => void;
111  build() {
112    Column() {
113      Text(this.header)
114        .fontSize(50)
115      this.closer()
116    }
117  }
118}
119@Builder function specificParam(label1: string, label2: string) {
120  Column() {
121    Text(label1)
122      .fontSize(50)
123    Text(label2)
124      .fontSize(50)
125  }
126}
127@Entry
128@Component
129struct CustomContainerUser {
130  @State text: string = "header"
131  build() {
132    Column() {
133      CustomContainer({
134        header: this.text,
135      }){
136        Column(){
137          specificParam("111", "22")
138        }.onClick(()=>{
139          this.text = "changeHeader"
140        })
141      }
142    }
143  }
144}
145```
146