基本 UI 描述

声明式 UI 通过装饰器@Component 和@Entry 装饰 struct 关键字声明的数据结构，构成一个自定义组件。自定义组件中提供了一个 build 函数，开发者需在该函数内以链式调用的方式进行基本的 UI 描述，UI 描述的方法请参考UI 描述规范。

基本概念

• struct：自定义组件可以基于 struct 实现，不能有继承关系，对于 struct 的实例化，可以省略 new。

• 装饰器：装饰器给被装饰的对象赋予某一种能力，其不仅可以装饰类或结构体，还可以装饰类的属性。多个装饰器可以叠加到目标元素上，定义在同一行中或者分开多行，推荐分开多行定义。

  @Entry
  @Component
  struct MyComponent {
  }
  

• build 函数：自定义组件必须定义 build 函数，并且禁止自定义构造函数。build 函数满足 Builder 构造器接口定义，用于定义组件的声明式 UI 描述。

  interface Builder {
    build: () => void;
  }
  

• @Component：装饰 struct，结构体在装饰后具有基于组件的能力，需要实现 build 方法来创建 UI。

• @Entry： 装饰 struct，组件被装饰后作为页面的入口，页面加载时将被渲染显示。

• @Preview：装饰 struct， 用@Preview 装饰的自定义组件可以在 DevEco Studio 的预览器上进行实时预览，加载页面时，将创建并显示@Preview 装饰的自定义组件。

  说明： 在单个源文件中，最多可以使用 10 个@Preview 装饰自定义组件

• 链式调用：以 "." 链式调用的方式配置 UI 组件的属性方法、事件方法等。

UI 描述规范

无参数构造配置

如果组件的接口定义中不包含必选构造参数，组件后面的“()”中不需要配置任何内容。例如，Divider 组件不包含构造参数：

Column() {
    Text('item 1')
    Divider()
    Text('item 2')
}

必选参数构造配置

如果组件的接口定义中包含必选构造参数，则在组件后面的“()”中必须配置相应参数，参数可以使用常量进行赋值。

例如：

• Image 组件的必选参数 src：

  Image("https://xyz/test.jpg");
  

• Text 组件的必选参数 content：

  Text("test");
  

变量或表达式也可以用于参数赋值，其中表达式返回的结果类型必须满足参数类型要求，变量的定义详见页面级变量的状态管理与应用级变量的状态管理。例如，设置变量或表达式来构造 Image 和 Text 组件的参数：

Image(this.imagePath);
Image("https://" + this.imageUrl);
Text(`count: ${this.count}`);

属性配置

使用属性方法配置组件的属性，属性方法紧随组件，并用"."运算符连接。

• 配置 Text 组件的字体大小属性：

  Text("test").fontSize(12);
  

• 使用"."运算符进行链式调用并同时配置组件的多个属性，如下所示：

  Image("test.jpg").alt("error.jpg").width(100).height(100);
  

• 除了直接传递常量参数外，还可以传递变量或表达式，如下所示：

  Text("hello").fontSize(this.size);
  Image("test.jpg")
    .width(this.count % 2 === 0 ? 100 : 200)
    .height(this.offset + 100);
  

• 对于系统内置组件，框架还为其属性预定义了一些枚举类型供开发人员调用，枚举类型可以作为参数传递，且必须满足参数类型要求。例如，可以按以下方式配置 Text 组件的颜色和字体属性：

Text("hello").fontSize(20).fontColor(Color.Red).fontWeight(FontWeight.Bold);

事件配置

通过事件方法可以配置组件支持的事件，事件方法紧随组件，并用"."运算符连接。

• 使用 lambda 表达式配置组件的事件方法：

  Button("add counter").onClick(() => {
    this.counter += 2;
  });
  

• 使用匿名函数表达式配置组件的事件方法，要求使用 bind，以确保函数体中的 this 引用包含的组件：

  Button("add counter").onClick(
    function () {
      this.counter += 2;
    }.bind(this)
  );
  

• 使用组件的成员函数配置组件的事件方法：

  myClickHandler(): void {
    this.counter += 2
  }
  
  ...
  
  Button('add counter')
    .onClick(this.myClickHandler)
  

子组件配置

对于支持子组件配置的组件，例如容器组件，在"{ ... }"里为组件添加子组件的 UI 描述。Column、Row、Stack、Grid、List 等组件都是容器组件。

• 以下是简单的 Column 示例：

  Column() {
      Text('Hello')
          .fontSize(100)
      Divider()
      Text(this.myText)
          .fontSize(100)
          .fontColor(Color.Red)
  }
  

• 容器组件之间也可以互相嵌套，实现相对复杂的多级嵌套效果：

  Column() {
    Row() {
      Image('test1.jpg')
        .width(100)
        .height(100)
      Button('click +1')
        .onClick(() => {
          console.info('+1 clicked!')
        })
    }
  
    Divider()
    Row() {
      Image('test2.jpg')
        .width(100)
        .height(100)
      Button('click +2')
        .onClick(() => {
          console.info('+2 clicked!')
        })
    }
  
    Divider()
    Row() {
      Image('test3.jpg')
        .width(100)
        .height(100)
      Button('click +3')
        .onClick(() => {
          console.info('+3 clicked!')
        })
    }
  }