• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Declarative UI Development Guidelines
2
3## Overview
4
5| Task         | Description                                      | Related Resources                                    |
6| ----------- | ---------------------------------------- | ---------------------------------------- |
7| Set up the development environment.     | Understand the project structure of the declarative UI.<br>Learn the resource categories and how to access resources.             | [OpenHarmony Project Overview](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-project-overview-0000001218440650)<br>[Resource Categories and Access](../quick-start/resource-categories-and-access.md)|
8| Learn ArkTS.  | As its name implies, ArkTS is a superset of TypeScript. It is the preferred, primary programming language for application development in OpenHarmony.| [Learning ArkTS](../quick-start/arkts-get-started.md)|
9| Develop a page.       | Select an appropriate layout based on the use case.<br>Add built-in components and set the component style based on the page content to present.<br>Update and diversify the page content.| [Creating a Page](#creating-a-page)<br>          [Common Layout Development](ui-ts-layout-linear.md)<br>          [Common Components](ui-ts-components-intro.md)<br>[Setting the Component Style](#setting-the-component-styles)<br>[Updating Page Content](#updating-page-content)|
10| (Optional) Diversify the page content.  | Leverage the drawing and animation features to effectively increase user engagement.                                  | [Drawing Components](../reference/arkui-ts/ts-drawing-components-circle.md)<br>[Canvas Components](../reference/arkui-ts/ts-components-canvas-canvas.md)<br>[Animation](../reference/arkui-ts/ts-animatorproperty.md)|
11| (Optional) Implement page redirection.| Use page routing to implement redirection between pages.                      | [Page Routing](../reference/apis/js-apis-router.md)|
12| (Optional) Improve performance.   | Learn how you can improve your implementation, thereby avoiding possible performance drop.                    | [Recommendations for Improving Performance](ui-ts-performance-improvement-recommendation.md)|
13
14## Creating a Page
15
16Select a layout to create a page and add basic built-in components to the page. In this example, the [flex layout](ui-ts-layout-flex.md) is used, and the **\<Text>** component is centered horizontally and vertically on the page.
17
18   ```ts
19    // xxx.ets
20    @Entry
21    @Component
22    struct MyComponent {
23      build() {
24        Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
25          Text('Hello')
26        }
27        .width('100%')
28        .height('100%')
29      }
30    }
31   ```
32
33## Setting the Component Style
34
35If a built-in component does not have attribute methods set, it takes the default style. To change the style of a component and thereby how it looks on the UI, modify the settings of styles, including component-specific styles and [universal styles](../reference/arkui-ts/ts-universal-attributes-size.md).
36
371. Change the display content of the **\<Text>** component to **Tomato** by modifying its constructor parameters.
382. Set the **fontSize** attribute to **26** and the **fontWeight** attribute to **500**.
39
40   ```ts
41    // xxx.ets
42    @Entry
43    @Component
44    struct MyComponent {
45      build() {
46        Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
47          Text('Tomato')
48            .fontSize(26)
49            .fontWeight(500)
50        }
51        .width('100%')
52        .height('100%')
53      }
54    }
55   ```
56
57   ![en-us_image_0000001168888224](figures/en-us_image_0000001168888224.png)
58
59## Updating Page Content
60
61You can update page content by updating component status. Below is a simple example.
62
63> **NOTE**
64>
65> Before updating the status of a component, initialize its member variables. The member variables of a custom component can be initialized in either of the following methods: [local initialization](../quick-start/arkts-restrictions-and-extensions.md#initialization-rules-and-restrictions-of-custom-components-member-variables) or [initialization using constructor parameters](../quick-start/arkts-restrictions-and-extensions.md#initialization-rules-and-restrictions-of-custom-components-member-variables). Select the appropriate method based on the decorator used by the variable.
66
67**Example**
68
69```ts
70// xxx.ets
71@Entry
72@Component
73struct ParentComp {
74  @State isCountDown: boolean = true
75
76  build() {
77    Column() {
78      Text(this.isCountDown ? 'Count Down' : 'Stopwatch').fontSize(20).margin(20)
79      if (this.isCountDown) {
80        // The image resources are stored in the media directory.
81        Image($r("app.media.countdown")).width(120).height(120)
82        TimerComponent({ counter: 10, changePerSec: -1, showInColor: Color.Red })
83      } else {
84        // The image resources are stored in the media directory.
85        Image($r("app.media.stopwatch")).width(120).height(120)
86        TimerComponent({ counter: 0, changePerSec: +1, showInColor: Color.Black })
87      }
88      Button(this.isCountDown ? 'Switch to Stopwatch' : 'Switch to Count Down')
89        .onClick(() => {
90          this.isCountDown = !this.isCountDown
91        })
92    }.width('100%')
93  }
94}
95
96// Custom timer/countdown component.
97@Component
98struct TimerComponent {
99  @State counter: number = 0
100  private changePerSec: number = -1
101  private showInColor: Color = Color.Black
102  private timerId: number = -1
103
104  build() {
105    Text(`${this.counter}sec`)
106      .fontColor(this.showInColor)
107      .fontSize(20)
108      .margin(20)
109  }
110
111  aboutToAppear() {
112    this.timerId = setInterval(() => {
113      this.counter += this.changePerSec
114    }, 1000)
115  }
116
117  aboutToDisappear() {
118    if (this.timerId > 0) {
119      clearTimeout(this.timerId)
120      this.timerId = -1
121    }
122  }
123}
124```
125
126![component](figures/component.gif)
127
128**Initial creation and rendering:**
129
1301. Create the parent component **ParentComp**.
131
1322. Locally initialize the state variable **isCountDown** of **ParentComp**.
133
1343. Execute the **build** function of **ParentComp**.
135
1364. Create a **\<Column>** component.
137   1. Create a **\<Text>** component, set the text content, and add the **\<Text>** component instance to the **\<Column>** component.
138   2. With the **if** statement, create a component under the **true** condition.
139       1. Create an **\<Image>** component and set the image source address.
140       2. Create a **TimerComponent** using the given constructor.
141   3. Create a **\<Button>** component and set the corresponding content.
142
143**Status update:**
144
145When the user clicks a button:
146
1471. The value of the **isCountDown** state variable of **ParentComp** is changed to **false**.
148
1492. The **build** function of **ParentComp** is executed.
150
1513. The **\<Column>** component is reused and reinitialized.
152
1534. The child components of **\<Column>** reuse and reinitialize the objects in the memory.
154   1. The **\<Text>** component is reused after being re-initialized using the new text content.
155   2. With the **if** statement, the components under the **false** condition are used.
156       1. The component instances created under the **true** condition are destroyed.
157       2. Components under the **false** condition are created.
158   3. The **\<Button>** component is reused with the new image source.
159