• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 the 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 a lambda 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 anonymous function expression to configure the event of a component (**bind** must be used to ensure that the current components are referenced by **this **in the function body):
120
121  ```ts
122  Button('add counter')
123    .onClick(function(){
124      this.counter += 2;
125    }.bind(this))
126  ```
127
128- Example of using a component's member function to configure the event of the component:
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
140## Configuring Child Components
141
142For a component that supports 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.
143
144
145- Simple example of configuring child components for the **\<Column>** component:
146
147  ```ts
148  Column() {
149    Text('Hello')
150      .fontSize(100)
151    Divider()
152    Text(this.myText)
153      .fontSize(100)
154      .fontColor(Color.Red)
155  }
156  ```
157
158- Example of nesting multiple child components in the **\<Column>** component:.
159
160  ```ts
161  Column() {
162    Row() {
163      Image('test1.jpg')
164        .width(100)
165        .height(100)
166      Button('click +1')
167        .onClick(() => {
168          console.info('+1 clicked!');
169        })
170    }
171  }
172  ```
173