harmony 鸿蒙Declarative UI Description

2023-06-24
浏览 (694)

Declarative UI Description

ArkTS 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.

Creating a Component

Depending on the builder, you can create components with or without mandatory parameters.

NOTE

The new operator is not required when you create a component.

Without Mandatory Parameters

A 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:

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

With Mandatory Parameters

A struct with mandatory parameters is a component whose API definition expects parameters enclosed in parentheses.

Set the mandatory parameter src of the <Image> component as follows:

  Image('https://xyz/test.jpg')

Set the optional parameter content of the <Text> component.

  // Parameter of the string type
  Text('test')
  // Add application resources in $r format, which can be used in multi-language scenarios.
  Text($r('app.string.title_value'))
  // No mandatory parameters
  Text()

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. For example, to set a variable or expression to construct the <Image> and <Text> components:
```
Image(this.imagePath)
Image('https://' + this.imageUrl)
Text(`count: ${this.count}`)
```

Configuring Attributes

Use 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.

Example of configuring the fontSize attribute for the <Text> component:

  Text('test')
    .fontSize(12)

Example of configuring multiple attributes for the <Image> component:

  Image('test.jpg')
    .alt('error.jpg')    
    .width(100)    
    .height(100)

Attribute methods accept expressions and variables as well constant parameters.

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

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. Example of configuring the font color and style of the <Text> component:

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

Handling Events

Use chainable event methods to configure events supported by built-in components. It is recommended that a separate line be used for each event method.

Example of using a lambda expression to configure the event of a component:

  Button('Click me')
    .onClick(() => {
      this.myText = 'ArkUI';
    })

Example of using an anonymous 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):

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

Example of using a component’s member function to configure the event of the component:

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

Configuring Child Components

For 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.

Simple example of configuring child components for the <Column> component:

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

Example of nesting multiple child components in the <Column> component:.

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