• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 声明式UI描述
2<!--Kit: ArkUI-->
3<!--Subsystem: ArkUI-->
4<!--Owner: @sunfei2021-->
5<!--Designer: @sunfei2021-->
6<!--Tester: @sally__-->
7<!--Adviser: @zhang_yixin13-->
8
9ArkTS以声明方式组合和扩展组件来描述应用程序的UI，同时还提供了基本的属性、事件和子组件配置方法，帮助开发者实现应用交互逻辑。
10
11## 创建组件
12
13根据组件构造方法的不同，创建组件包含有参数和无参数两种方式。
14
15>  **说明：**
16>
17>  创建组件不需要使用new关键字。
18
19### 无参数
20
21如果组件接口定义中不包含必选构造参数，则组件后面的“()”不需要配置任何内容。例如：Divider组件不包含构造参数。
22
23```ts
24Column() {
25  Text('item 1')
26  Divider()
27  Text('item 2')
28}
29```
30
31### 有参数
32
33如果组件接口定义包含构造参数，则在组件后的“()”中配置相应参数。
34
35- Image组件的必选参数src。
36
37  ```ts
38  Image('https://xyz/test.jpg')
39  ```
40
41
42- Text组件的非必选参数content。
43
44  ```ts
45  // string类型的参数
46  Text('test')
47  // $r形式引入应用资源，可应用于多语言场景
48  Text($r('app.string.title_value'))
49  // 无参数形式
50  Text()
51  ```
52
53- 变量或表达式可以用于参数赋值，表达式结果类型必须符合参数要求。
54    例如，设置变量或表达式来构造Image和Text组件的参数。
55
56    ```ts
57    Image(this.imagePath)
58    Image('https://' + this.imageUrl)
59    Text(`count: ${this.count}`)
60    ```
61
62
63## 配置属性
64
65属性方法以“.”链式调用配置组件样式和其他属性，建议每个属性方法单独一行。
66
67- 配置Text组件的字体大小。
68
69  ```ts
70  Text('test')
71    .fontSize(12)
72  ```
73
74- 配置组件的多个属性。
75
76  ```ts
77  Image('test.jpg')
78    .alt('error.jpg')
79    .width(100)
80    .height(100)
81  ```
82
83- 除了直接传递常量参数，还可以传递变量或表达式。
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- 对于系统组件，ArkUI还为其属性预定义了一些枚举类型供开发者调用，枚举类型可以作为参数传递，但必须满足参数类型要求。
94  例如，可以按以下方式配置Text组件的颜色和字体样式。
95
96  ```ts
97  Text('hello')
98    .fontSize(20)
99    .fontColor(Color.Red)
100    .fontWeight(FontWeight.Bold)
101  ```
102
103
104## 配置事件
105
106事件方法以“.”链式调用的方式配置系统组件支持的事件，建议每个事件方法单独写一行。
107
108- 使用箭头函数配置组件的事件方法。
109
110  ```ts
111  Button('Click me')
112    .onClick(() => {
113      this.myText = 'ArkUI';
114    })
115  ```
116
117- 使用箭头函数表达式配置组件的事件方法，要求使用“() => {...}”，以确保函数与组件绑定，同时符合ArkTS语法规范。
118
119  ```ts
120  Button('add counter')
121    .onClick(() => {
122      this.counter += 2;
123    })
124  ```
125
126- 使用组件的成员函数配置组件的事件方法，需要bind this。ArkTS语法不建议使用成员函数配合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- 使用声明的箭头函数时可以直接调用，不需要bind this。
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> **说明：**
150>
151> 箭头函数内部的`this`是词法作用域，由上下文确定。匿名函数可能会出现`this`指向不明确的问题，因此在ArkTS中不允许使用。
152
153## 配置子组件
154
155如果组件支持子组件配置，则需在尾随闭包"{...}"中为组件添加子组件的UI描述。Column、Row、Stack、Grid、List等组件都是容器组件。
156
157- 以下是简单的Column组件配置子组件的示例。
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- 容器组件均支持子组件配置，可以实现相对复杂的多级嵌套。
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