• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# \@Builder: Custom Builder Function
2
3
4After a custom component is created, its internal UI structure is fixed and allows only data passing with its caller. ArkUI also provides a more lightweight mechanism for reusing UI elements: \@Builder. An \@Builder decorated function is a special function that serves similar purpose as the build function. The \@Builder function body follows the same syntax rules as the **build** function. You can abstract reusable UI elements into a method and call the method in **build**.
5
6
7To simplify language, here we refer to an \@Builder decorated function also as a custom builder function.
8
9
10> **NOTE**
11>
12> Since API version 9, this decorator is supported in ArkTS widgets.
13
14
15## Rules of Use
16
17
18### Custom Builder Function
19
20Syntax:
21
22
23```ts
24@Builder myBuilderFunction({ ... })
25```
26
27Usage:
28
29
30```ts
31this.myBuilderFunction({ ... })
32```
33
34- Defining one or more custom builder (\@Builder decorated) functions inside a custom component is allowed. Such a custom builder function can be considered as a private, special type of member functions of that component.
35
36- The custom builder function can be called from the owning component's** build** or another custom builder (within that custom component) function only.
37
38- Inside the custom builder function body, **this** refers to the owning component. Component state variables are accessible from within the custom builder function implementation. Using the custom components' state variables is recommended over parameter passing.
39
40
41### Global Custom Builder Function
42
43Syntax:
44
45
46```ts
47@Builder function MyGlobalBuilderFunction({ ... })
48```
49
50Usage:
51
52
53```ts
54MyGlobalBuilderFunction()
55```
56
57
58- A global custom builder function is accessible from the entire application. **this** and the **bind** method are not allowed.
59
60- Use of a global custom builder function is recommended if no own state is required.
61
62
63## Parameter Passing Rules
64
65There are two types of parameter passing for custom builder functions: [by-value parameter passing](#by-value-parameter-passing) and [by-reference parameter passing](#by-reference-parameter-passing). Both of them must comply with the following rules:
66
67- The parameter type must be the same as the declared parameter type. The **undefined** or **null** constants as well as expressions evaluating to these values are not allowed.
68
69- All parameters are immutable inside the custom builder function. If mutability and synchronization of the mutation is required, the custom builder should be replaced by a custom component with a [@Link](arkts-link.md) decorated variable.
70
71- The \@Builder function body follows the same [syntax rules](arkts-create-custom-components.md#build-function) as the **build** function.
72
73
74### By-Reference Parameter Passing
75
76In by-reference parameter passing, the passed parameters can be state variables, and the change of these state variables causes the UI re-rendering in the \@Builder method. ArkUI provides $$ as a paradigm for by-reference parameter passing.
77
78
79```ts
80ABuilder( $$ : { paramA1: string, paramB1 : string } );
81```
82
83
84
85```ts
86@Builder function ABuilder($$: { paramA1: string }) {
87  Row() {
88    Text(`UseStateVarByReference: ${$$.paramA1} `)
89  }
90}
91@Entry
92@Component
93struct Parent {
94  @State label: string = 'Hello';
95  build() {
96    Column() {
97      // Pass the this.label reference to the ABuilder component when the ABuilder component is called in the Parent component.
98      ABuilder({ paramA1: this.label })
99      Button('Click me').onClick(() => {
100        // After Click me is clicked, the UI text changes from Hello to ArkUI.
101        this.label = 'ArkUI';
102      })
103    }
104  }
105}
106```
107
108
109### By-Value Parameter Passing
110
111By default, parameters in the \@Builder decorated functions are passed by value. When the passed parameter is a state variable, the change of the state variable does not cause the UI re-rendering in the \@Builder method. Therefore, when using state variables, you are advised to use [by-reference parameter passing](#by-reference-parameter-passing).
112
113
114```ts
115@Builder function ABuilder(paramA1: string) {
116  Row() {
117    Text(`UseStateVarByValue: ${paramA1} `)
118  }
119}
120@Entry
121@Component
122struct Parent {
123  label: string = 'Hello';
124  build() {
125    Column() {
126      ABuilder(this.label)
127    }
128  }
129}
130```
131