• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Declarative UI Description
2<!--Kit: ArkUI-->
3<!--Subsystem: ArkUI-->
4<!--Owner: @sunfei2021-->
5<!--Designer: @sunfei2021-->
6<!--Tester: @sally__-->
7<!--Adviser: @zhang_yixin13-->
8
9ArkTS describes an application's UI by combining and extending components in a declarative manner. It also provides basic methods for configuring attributes, events, and child components to help you implement application interaction logic.
10
11## Creating a Component
12
13You can create a component with or without parameters, depending on the component's constructor.
14
15>  **NOTE**
16>
17>  The **new** keyword is not required for component instantiation.
18
19### Without Parameters
20
21If a component's API definition does not include mandatory constructor parameters, leave the parentheses empty. For example, the **Divider** component requires no parameters.
22
23```ts
24Column() {
25  Text('item 1')
26  Divider()
27  Text('item 2')
28}
29```
30
31### With Parameters
32
33If a component's API definition includes constructor parameters, configure the required parameters in the parentheses.
34
35- **Image** component with a mandatory **src** parameter:
36
37  ```ts
38  Image('https://xyz/test.jpg')
39  ```
40
41
42- **Text** component with an optional **content** parameter:
43
44  ```ts
45  // Parameter of the string type
46  Text('test')
47  // Reference application resources using $r, applicable to multi-language scenarios.
48  Text($r('app.string.title_value'))
49  // Parameter-free form
50  Text()
51  ```
52
53- Variables or expressions can be used for parameter assignment, with types matching the parameter requirements.
54    For example, set variables or expressions to construct parameters for **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
65Configure styles and other attributes using chained method calls, one per line recommended.
66
67- Set the font size for the **Text** component:
68
69  ```ts
70  Text('test')
71    .fontSize(12)
72  ```
73
74- Set multiple attributes for the **Image** component:
75
76  ```ts
77  Image('test.jpg')
78    .alt('error.jpg')
79    .width(100)
80    .height(100)
81  ```
82
83- Attribute methods accept expressions and variables as well constant parameters.<br>Use expressions and variables:
84
85  ```ts
86  Text('hello')
87    .fontSize(this.size)
88  Image('test.jpg')
89    .width(this.count % 2 === 0 ? 100 : 200)
90    .height(this.offset + 100)
91  ```
92
93- For built-in components, ArkUI also predefines some enumeration types for their attributes. Enumeration types can be passed as parameters but must meet the parameter type requirements.
94  Set the font color and style for the **Text** component:
95
96  ```ts
97  Text('hello')
98    .fontSize(20)
99    .fontColor(Color.Red)
100    .fontWeight(FontWeight.Bold)
101  ```
102
103
104## Configuring Events
105
106Configure built-in component events using chained method calls, one per line recommended.
107
108- Use the arrow function syntax for event configuration:
109
110  ```ts
111  Button('Click me')
112    .onClick(() => {
113      this.myText = 'ArkUI';
114    })
115  ```
116
117- Use the arrow function expression syntax for event configuration, requiring the use of "() => {...}" to ensure that the function is bound to the component and complies with ArkTS syntax specifications:
118
119  ```ts
120  Button('add counter')
121    .onClick(() => {
122      this.counter += 2;
123    })
124  ```
125
126- (Not recommended in ArkTS) Use a member function for event configuration, which requires explicit **bind(this)**:
127
128  ```ts
129  myClickHandler(): void {
130    this.counter += 2;
131  }
132  // ...
133  Button('add counter')
134    .onClick(this.myClickHandler.bind(this))
135  ```
136
137- Use a pre-declared arrow function for event configuration, where binding **this** is not needed:
138
139  ```ts
140  fn = () => {
141    console.info(`counter: ${this.counter}`)
142    this.counter++
143  }
144  // ...
145  Button('add counter')
146    .onClick(this.fn)
147  ```
148
149> **NOTE**
150>
151> 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.
152
153## Configuring Child Components
154
155For a component with child components, for example, a container component, add the UI descriptions of the child components within trailing closures {...}. The **Column**, **Row**, **Stack**, **Grid**, and **List** components are all container components.
156
157- Configure child components for the **Column** component:
158
159  ```ts
160  Column() {
161    Text('Hello')
162      .fontSize(100)
163    Divider()
164    Text(this.myText)
165      .fontSize(100)
166      .fontColor(Color.Red)
167  }
168  ```
169
170- Configure nested child components in the **Column** component:.
171
172  ```ts
173  Column() {
174    Row() {
175      Image('test1.jpg')
176        .width(100)
177        .height(100)
178      Button('click +1')
179        .onClick(() => {
180          console.info('+1 clicked!');
181        })
182    }
183  }
184  ```
185