1# Declarative UI Description
2
3
4ArkTS declaratively combines and extends components to describe the UI of an application. It also provides basic methods for configuring attributes, events, and child components to help you implement application interaction logic.
5
6
7## Creating a Component
8
9Depending on the builder, you can create components with or without mandatory parameters.
10
11>  **NOTE**
12>
13>  The **new** operator is not required when you create a component.
14
15
16### Without Mandatory Parameters
17
18A struct without mandatory parameters is a component whose API definition has empty parentheses. No parameter needs to be passed to this type of component, for example, the **Divider** component in the following snippet:
19
20
21```ts
22Column() {
23  Text('item 1')
24  Divider()
25  Text('item 2')
26}
27```
28
29
30### With Mandatory Parameters
31
32A struct with mandatory parameters is a component whose API definition expects parameters enclosed in parentheses.
33
34- Set the mandatory parameter **src** of the **Image** component as follows:
35
36  ```ts
37  Image('https://xyz/test.jpg')
38  ```
39
40
41- Set the optional parameter **content** of the **Text** component.
42
43  ```ts
44  // Parameter of the string type
45  Text('test')
46  // Add application resources in $r format, which can be used in multi-language scenarios.
47  Text($r('app.string.title_value'))
48  // No mandatory parameters
49  Text()
50  ```
51
52
53- You can also use variables or expressions to assign values to parameters. The result type returned by an expression must meet the parameter type requirements.
54    For example, to set a variable or expression to construct the **Image** and **Text** components:
55
56    ```ts
57    Image(this.imagePath)
58    Image('https://' + this.imageUrl)
59    Text(`count: ${this.count}`)
60    ```
61
62
63## Configuring Attributes
64
65Use chainable attribute methods to configure the style and other attributes of built-in components. It is recommended that a separate line be used for each attribute method.
66
67
68- Example of configuring the **fontSize** attribute for the **Text** component:
69
70  ```ts
71  Text('test')
72    .fontSize(12)
73  ```
74
75- Example of configuring multiple attributes for the **Image** component:
76
77  ```ts
78  Image('test.jpg')
79    .alt('error.jpg')
80    .width(100)
81    .height(100)
82  ```
83
84- Attribute methods accept expressions and variables as well constant parameters.
85
86  ```ts
87  Text('hello')
88    .fontSize(this.size)
89  Image('test.jpg')
90    .width(this.count % 2 === 0 ? 100 : 200)
91    .height(this.offset + 100)
92  ```
93
94- For built-in components, ArkUI also predefines some enumeration types. These enumeration types can be passed as parameters, as long as they meet the parameter type requirements.
95  Example of configuring the font color and style of the **Text** component:
96
97  ```ts
98  Text('hello')
99    .fontSize(20)
100    .fontColor(Color.Red)
101    .fontWeight(FontWeight.Bold)
102  ```
103
104
105## Handling Events
106
107Use chainable event methods to configure events supported by built-in components. It is recommended that a separate line be used for each event method.
108
109
110- Example of using an arrow function expression to configure the event of a component:
111
112  ```ts
113  Button('Click me')
114    .onClick(() => {
115      this.myText = 'ArkUI';
116    })
117  ```
118
119- Example of using an arrow function expression to configure the event of a component (**() => {...}** must be used to ensure that the function is bound to the component and complies with the ArkTS syntax specifications):
120
121  ```ts
122  Button('add counter')
123    .onClick(() => {
124      this.counter += 2;
125    })
126  ```
127
128- Example of using a component's member function to configure the event of the component, where **this** binding is needed: (This usage is not recommended in ArkTS.)
129
130  ```ts
131  myClickHandler(): void {
132    this.counter += 2;
133  }
134  ...
135  Button('add counter')
136    .onClick(this.myClickHandler.bind(this))
137  ```
138
139- Example of using an arrow function expression for a declaration, where **this** binding is not needed:
140
141  ```ts
142  fn = () => {
143    console.info(`counter: ${this.counter}`)
144    this.counter++
145  }
146  ...
147  Button('add counter')
148    .onClick(this.fn)
149  ```
150
151> **NOTE**
152>
153> In arrow functions, **this** inherits its value from the surrounding (lexical) scope in which they are defined. This means that, in anonymous functions, **this** may present an unclear reference and is therefore not allowed in ArkTS.
154
155
156## Configuring Child Components
157
158For a component with child components, for example, a container component, add the UI descriptions of the child components inside parentheses. The **Column**, **Row**, **Stack**, **Grid**, and **List** components are all container components.
159
160
161- Simple example of configuring child components for the **Column** component:
162
163  ```ts
164  Column() {
165    Text('Hello')
166      .fontSize(100)
167    Divider()
168    Text(this.myText)
169      .fontSize(100)
170      .fontColor(Color.Red)
171  }
172  ```
173
174- Example of nested child components in the **Column** component:.
175
176  ```ts
177  Column() {
178    Row() {
179      Image('test1.jpg')
180        .width(100)
181        .height(100)
182      Button('click +1')
183        .onClick(() => {
184          console.info('+1 clicked!');
185        })
186    }
187  }
188  ```
189