当前位置：首页 > news >正文

声明式UI语法

news 2025/6/25 14:40:16

一、ArkTS的基本组成

@Entry  // 装饰器
@Component  // 装饰器
struct  Hello {  // 自定义组件@State myText: string = 'World';build() {  // UI描述Column() {  // 系统组件Text('Hello ${this.myText}').fontSize(50)Divider()Button('Click me').onClick(() => {  // 事件方法this.myText = 'ArkUI'}).height(50)  // 属性描述.width(100).margin({top: 20})}}
}

装饰器：用于装饰类、结构、方法以及变量，并赋予其特殊的含义。如上述示例中@Entry、@Component和@State都是装饰器，@Component表示自定义组件，@Entry表示该自定义组件为入口组件，@State表示组件中的状态变量，状态变量变化会触发UI刷新。
UI描述：以声明式的方式来描述UI的结构，例如build()方法中的代码块。
自定义组件：可复用的UI单元，可组合其他组件，如上述被@Component装饰的struct Hello。
系统组件：ArkUI框架中默认内置的基础和容器组件，可直接被开发者调用，比如示例中的Column、Text、Divider、Button。
属性方法：组件可以通过链式调用配置多项属性，如fontSize()、width()、height()、backgroundColor()等。
事件方法：组件可以通过链式调用设置多个事件的响应逻辑，如跟随在Button后面的onClick()。
系统组件、属性方法、事件方法具体使用可参考基于ArkTS的声明式开发范式。

二、声明式UI描述

ArkTS以声明方式组合和扩展组件来描述应用程序的UI，同时还提供了基本的属性、事件和子组件配置方法，帮助开发者实现应用交互逻辑。

1、创建组件

根据组件构造方法的不同，创建组件包含有参数（如果组件的接口定义包含构造参数，则在组件后面的“()”需要配置相应参数）和无参数（如果组件的接口定义没有包含必选构造参数，则组件后面的“()”不需要配置任何内容）两种方式。

// 无参数
Column() {Text('item 1')Divider()Text('item 2')
}// 有参数
Image('https://xyz/test.jpg')// string类型的参数
Text('test')
// $r形式引入应用资源，可应用于多语言场景
Text($r('app.string.title_value'))
// 无参数形式
Text()

2、配置属性

属性方法以“.”链式调用的方式配置系统组件的样式和其他属性，建议每个属性方法单独写一行。

// 配置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)

3、配置事件

事件方法以“.”链式调用的方式配置系统组件支持的事件，建议每个事件方法单独写一行。

// 使用箭头函数配置组件的事件方法。
Button('Click me').onClick(() => {this.myText = 'ArkUI';})// 使用组件的成员函数配置组件的事件方法，需要bind this。ArkTS语法不推荐使用成员函数配合bind this去配置组件的事件方法。
myClickHandler(): void {this.counter += 2;
}
...
Button('add counter').onClick(this.myClickHandler.bind(this))// 使用声明的箭头函数，可以直接调用，不需要bind this。
fn = () => {console.info(`counter: ${this.counter}`)this.counter++
}
...
Button('add counter').onClick(this.fn)

4、配置子组件

如果组件支持子组件配置，则需在尾随闭包"{...}"中为组件添加子组件的UI描述。Column、Row、Stack、Grid、List等组件都是容器组件。

// 容器组件均支持子组件配置，可以实现相对复杂的多级嵌套。
Column() {Row() {Image('test1.jpg').width(100).height(100)Button('click +1').onClick(() => {console.info('+1 clicked!');})}
}

三、创建自定义组件

在ArkUI中，UI显示的内容均为组件，由框架直接提供的称为系统组件，由开发者定义的称为自定义组件。

自定义组件具有以下特点：

可组合：允许开发者组合使用系统组件、及其属性和方法。
可重用：自定义组件可以被其他组件重用，并作为不同的实例在不同的父组件或容器中使用。
数据驱动UI更新：通过状态变量的改变，来驱动UI的刷新。

1、自定义组件的基本结构

a、struct：自定义组件基于struct实现，struct + 自定义组件名 + {...}的组合构成自定义组件，不能有继承关系。对于struct的实例化，可以省略new。自定义组件名、类名、函数名不能和系统组件名相同。

b、@Component：@Component装饰器仅能装饰struct关键字声明的数据结构。struct被@Component装饰后具备组件化的能力，需要实现build方法描述UI，一个struct只能被一个@Component装饰。@Component可以接受一个可选的bool类型参数。

@Component
struct MyComponent {
}

c、build()函数：build()函数用于定义自定义组件的声明式UI描述，自定义组件必须定义build()函数。

@Component
struct MyComponent {build() {}
}

d、@Entry：@Entry装饰的自定义组件将作为UI页面的入口。在单个UI页面中，最多可以使用@Entry装饰一个自定义组件。

@Entry
@Component
struct MyComponent {
}

命名路由跳转选项：

名称	类型	必填	说明
routeName	string	否	表示作为命名路由页面的名字。
storage	LocalStorage	否	页面级的UI状态存储。
useSharedStorage12+	boolean	否	是否使用LocalStorage.getShared()接口返回的LocalStorage实例对象，默认值false。

@Entry({ routeName : 'myPage' })
@Component
struct MyComponent {
}

e、@Reusable：@Reusable装饰的自定义组件具备可复用能力

@Reusable
@Component
struct MyComponent {
}

2、成员函数/变量

成员函数约束：自定义组件的成员函数为私有的，且不建议声明成静态函数。

成员变量约束：自定义组件的成员变量为私有的，且不建议声明成静态变量；自定义组件的成员变量本地初始化有些是可选的，有些是必选的。具体是否需要本地初始化，是否需要从父组件通过参数传递初始化子组件的成员变量，请参考状态管理。

3、自定义组件参数规定

@Component
struct MyComponent {private countDownFrom: number = 0;private color: Color = Color.Blue;build() {}
}@Entry
@Component
struct ParentComponent {private someColor: Color = Color.Pink;build() {Column() {// 创建MyComponent实例，并将创建MyComponent成员变量countDownFrom初始化为10，将成员变量color初始化为this.someColorMyComponent({ countDownFrom: 10, color: this.someColor })}}
}

下面的示例代码将父组件中的函数传递给子组件，并在子组件中调用。

@Entry
@Component
struct Parent {@State cnt: number = 0submit: () => void = () => {this.cnt++;}build() {Column() {Text(`${this.cnt}`)Son({ submitArrow: this.submit })}}
}@Component
struct Son {submitArrow?: () => voidbuild() {Row() {Button('add').width(80).onClick(() => {if (this.submitArrow) {this.submitArrow()}})}.justifyContent(FlexAlign.SpaceBetween).height(56)}
}

4、build函数

所有声明在build()函数的语句，我们统称为UI描述，UI描述需要遵循以下规则：

a、@Entry装饰的自定义组件，其build()函数下的根节点唯一且必要，且必须为容器组件，其中ForEach禁止作为根节点；@Component装饰的自定义组件，其build()函数下的根节点唯一且必要，可以为非容器组件，其中ForEach禁止作为根节点。

b、不允许声明本地变量

c、不允许在UI描述里直接使用console.info，但允许在方法或者函数里使用

d、不允许创建本地的作用域

e、不允许调用没有用@Builder装饰的方法，允许系统组件的参数是TS方法的返回值

f、不允许使用switch语法，如果需要使用条件判断，请使用if

g、不允许使用表达式

h、不允许直接改变状态变量

在ArkUI状态管理中，状态驱动UI更新。所以，不能在自定义组件的build()或@Builder方法里直接改变状态变量，这可能会造成循环渲染的风险。

5、自定义组件通用样式

自定义组件通过“.”链式调用的形式设置通用样式。

@Component
struct MyComponent2 {build() {Button(`Hello World`)}
}@Entry
@Component
struct MyComponent {build() {Row() {MyComponent2().width(200).height(300).backgroundColor(Color.Red)}}
}

四、页面和自定义组件的生命周期

1、页面生命周期

即被@Entry装饰的组件生命周期，提供以下生命周期接口：

onPageShow：页面每次显示时触发一次，包括路由过程、应用进入前台等场景。
onPageHide：页面每次隐藏时触发一次，包括路由过程、应用进入后台等场景。
onBackPress：当用户点击返回按钮时触发。

2、组件生命周期

即一般用@Component装饰的自定义组件的生命周期，提供以下生命周期接口：

aboutToAppear：组件即将出现时回调该接口，具体时机为在创建自定义组件的新实例后，在执行其build()函数之前执行。
onDidBuild：组件build()函数执行完成之后回调该接口，不建议在onDidBuild函数中更改状态变量、使用animateTo等功能，这可能会导致不稳定的UI表现。
aboutToDisappear：aboutToDisappear函数在自定义组件析构销毁之前执行。不允许在aboutToDisappear函数中改变状态变量，特别是@Link变量的修改可能会导致应用程序行为不稳定。

3、自定义组件的创建和渲染流程

a、自定义组件的创建：自定义组件的实例由ArkUI框架创建

b、初始化自定义组件的成员变量：通过本地默认值或者构造方法传递参数来初始化自定义组件的成员变量，初始化顺序为成员变量的定义顺序

c、如果开发者定义了aboutToAppear，则执行aboutToAppear方法

d、在首次渲染的时候，执行build方法渲染系统组件，如果子组件为自定义组件，则创建自定义组件的实例。在首次渲染的过程中，框架会记录状态变量和组件的映射关系，当状态变量改变时，驱动其相关的组件刷新

e、如果开发者定义了onDidBuild，则执行onDidBuild方法

4、自定义组件重新渲染

当事件句柄被触发（比如设置了点击事件，即触发点击事件）改变了状态变量时，或者LocalStorage / AppStorage中的属性更改，并导致绑定的状态变量更改其值时：

a、框架观察到了变化，将启动重新渲染。

b、根据框架持有的两个map，框架可以知道该状态变量管理了哪些UI组件，以及这些UI组件对应的更新函数。执行这些UI组件的更新函数，实现最小化更新。

5、自定义组件删除

如果if组件的分支改变，或者ForEach循环渲染中数组的个数改变，组件将被删除：

a、在删除组件之前，将调用其aboutToDisappear生命周期函数，标记着该节点将要被销毁。ArkUI的节点删除机制是：后端节点直接从组件树上摘下，后端节点被销毁，对前端节点解引用，前端节点已经没有引用时，将被JS虚拟机垃圾回收。

b、自定义组件和它的变量将被删除，如果其有同步的变量，比如@Link、@Prop、@StorageLink，将从同步源上取消注册。

不建议在生命周期aboutToDisappear内使用async await，如果在生命周期的aboutToDisappear使用异步操作（Promise或者回调方法），自定义组件将被保留在Promise的闭包中，直到回调方法被执行完，这个行为阻止了自定义组件的垃圾回收。

展示生命周期被调用的实例：

// Index.ets
import { router } from '@kit.ArkUI';@Entry
@Component
struct MyComponent {@State showChild: boolean = true;@State btnColor:string = "#FF007DFF";// 只有被@Entry装饰的组件才可以调用页面的生命周期onPageShow() {console.info('Index onPageShow');}// 只有被@Entry装饰的组件才可以调用页面的生命周期onPageHide() {console.info('Index onPageHide');}// 只有被@Entry装饰的组件才可以调用页面的生命周期onBackPress() {console.info('Index onBackPress');this.btnColor ="#FFEE0606";return true // 返回true表示页面自己处理返回逻辑，不进行页面路由；返回false表示使用默认的路由返回逻辑，不设置返回值按照false处理}// 组件生命周期aboutToAppear() {console.info('MyComponent aboutToAppear');}// 组件生命周期onDidBuild() {console.info('MyComponent onDidBuild');}// 组件生命周期aboutToDisappear() {console.info('MyComponent aboutToDisappear');}build() {Column() {// this.showChild为true，创建Child子组件，执行Child aboutToAppearif (this.showChild) {Child()}// this.showChild为false，删除Child子组件，执行Child aboutToDisappearButton('delete Child').margin(20).backgroundColor(this.btnColor).onClick(() => {this.showChild = false;})// push到page页面，执行onPageHideButton('push to next page').onClick(() => {router.pushUrl({ url: 'pages/page' });})}}
}@Component
struct Child {@State title: string = 'Hello World';// 组件生命周期aboutToDisappear() {console.info('[lifeCycle] Child aboutToDisappear')}// 组件生命周期onDidBuild() {console.info('[lifeCycle] Child onDidBuild');}// 组件生命周期aboutToAppear() {console.info('[lifeCycle] Child aboutToAppear')}build() {Text(this.title).fontSize(50).margin(20).onClick(() => {this.title = 'Hello ArkUI';})}
}

// page.ets
@Entry
@Component
struct page {@State textColor: Color = Color.Black;@State num: number = 0;onPageShow() {this.num = 5;}onPageHide() {console.log("page onPageHide");}onBackPress() { // 不设置返回值按照false处理this.textColor = Color.Grey;this.num = 0;}aboutToAppear() {this.textColor = Color.Blue;}build() {Column() {Text(`num 的值为：${this.num}`).fontSize(30).fontWeight(FontWeight.Bold).fontColor(this.textColor).margin(20).onClick(() => {this.num += 5;})}.width('100%')}
}

6、自定义组件监听页面生命周期

// Index.ets
import { uiObserver, router, UIObserver } from '@kit.ArkUI';@Entry
@Component
struct Index {listener: (info: uiObserver.RouterPageInfo) => void = (info: uiObserver.RouterPageInfo) => {let routerInfo: uiObserver.RouterPageInfo | undefined = this.queryRouterPageInfo();if (info.pageId == routerInfo?.pageId) {if (info.state == uiObserver.RouterPageState.ON_PAGE_SHOW) {console.log(`Index onPageShow`);} else if (info.state == uiObserver.RouterPageState.ON_PAGE_HIDE) {console.log(`Index onPageHide`);}}}aboutToAppear(): void {let uiObserver: UIObserver = this.getUIContext().getUIObserver();uiObserver.on('routerPageUpdate', this.listener);}aboutToDisappear(): void {let uiObserver: UIObserver = this.getUIContext().getUIObserver();uiObserver.off('routerPageUpdate', this.listener);}build() {Column() {Text(`this page is ${this.queryRouterPageInfo()?.pageId}`).fontSize(25)Button("push self").onClick(() => {router.pushUrl({url: 'pages/Index'})})Column() {SubComponent()}}}
}
@Component
struct SubComponent {listener: (info: uiObserver.RouterPageInfo) => void = (info: uiObserver.RouterPageInfo) => {let routerInfo: uiObserver.RouterPageInfo | undefined = this.queryRouterPageInfo();if (info.pageId == routerInfo?.pageId) {if (info.state == uiObserver.RouterPageState.ON_PAGE_SHOW) {console.log(`SubComponent onPageShow`);} else if (info.state == uiObserver.RouterPageState.ON_PAGE_HIDE) {console.log(`SubComponent onPageHide`);}}}aboutToAppear(): void {let uiObserver: UIObserver = this.getUIContext().getUIObserver();uiObserver.on('routerPageUpdate', this.listener);}aboutToDisappear(): void {let uiObserver: UIObserver = this.getUIContext().getUIObserver();uiObserver.off('routerPageUpdate', this.listener);}build() {Column() {Text(`SubComponent`)}}
}

五、if...else...条件渲染

1、使用规则

支持if、else和else if语句。
if、else if后跟随的条件语句可以使用状态变量或者常规变量(状态变量：值的改变可以实时渲染UI，常规变量：值的改变不会实时渲染UI)。
允许在容器组件内使用，通过条件渲染语句构建不同的子组件。
条件渲染语句在涉及到组件的父子关系时是“透明”的，当父组件和子组件之间存在一个或多个if语句时，必须遵守父组件关于子组件使用的规则。
每个分支内部的构建函数必须遵循构建函数的规则，并创建一个或多个组件。无法创建组件的空构建函数会产生语法错误。
某些容器组件限制子组件的类型或数量，将条件渲染语句用于这些组件内时，这些限制将同样应用于条件渲染语句内创建的组件。

2、更新机制

当if、else if后跟随的状态判断中使用的状态变量值变化时，条件渲染语句会进行更新，更新步骤如下：

评估if和else if的状态判断条件，如果分支没有变化，无需执行以下步骤。如果分支有变化，则执行2、3步骤：
删除此前构建的所有子组件。
执行新分支的构造函数，将获取到的组件添加到if父容器中。如果缺少适用的else分支，则不构建任何内容。

条件可以包括Typescript表达式。对于构造函数中的表达式，此类表达式不得更改应用程序状态。

@Entry
@Component
struct ViewA {@State count: number = 0;build() {Column() {Text(`count=${this.count}`)if (this.count > 0) {Text(`count is positive`).fontColor(Color.Green)}Button('increase count').onClick(() => {this.count++;})Button('decrease count').onClick(() => {this.count--;})}}
}

六、循环渲染

在ForEach循环渲染过程中，系统会为每个数组元素生成一个唯一且持久的键值，用于标识对应的组件。当这个键值变化时，ArkUI框架将视为该数组元素已被替换或修改，并会基于新的键值创建一个新的组件。

ForEach提供了一个名为keyGenerator的参数，这是一个函数，开发者可以通过它自定义键值的生成规则。如果开发者没有定义keyGenerator函数，则ArkUI框架会使用默认的键值生成函数，即(item: Object, index: number) => { return index + '__' + JSON.stringify(item); }。

ArkUI框架对于ForEach的键值生成有一套特定的判断规则，这主要与itemGenerator函数的第二个参数index以及keyGenerator函数的第二个参数index有关，具体的键值生成规则判断逻辑如下图所示。

1、创建规则

在确定键值生成规则后，ForEach的第二个参数itemGenerator函数会根据键值生成规则为数据源的每个数组项创建组件。

组件的创建包括两种情况：

a、 ForEach首次渲染（在ForEach首次渲染时，会根据前述键值生成规则为数据源的每个数组项生成唯一键值，并创建相应的组件）；

b、ForEach非首次渲染（在ForEach组件进行非首次渲染时，它会检查新生成的键值是否在上次渲染中已经存在。如果键值不存在，则会创建一个新的组件；如果键值存在，则不会创建新的组件，而是直接渲染该键值所对应的组件）。

2、使用场景

ForEach组件在开发过程中的主要应用场景包括：数据源不变（在数据源保持不变的场景中，数据源可以直接采用基本数据类型）、数据源数组项发生变化（在数据源数组项发生变化的场景下，例如进行数组插入、删除操作或者数组项索引位置发生交换时，数据源应为对象数组类型，并使用对象的唯一ID作为最终键值）、数据源数组项子属性发生变化（当数据源的数组项为对象数据类型，并且只修改某个数组项的属性值时，由于数据源为复杂数据类型，ArkUI框架无法监听到@State装饰器修饰的数据源数组项的属性变化，从而无法触发ForEach的重新渲染。为实现ForEach重新渲染，需要结合@Observed和@ObjectLink装饰器使用）。

3、使用建议

a、尽量避免在最终的键值生成规则中包含数据项索引index，以防止出现渲染结果非预期和渲染性能降低。如果业务确实需要使用index，例如列表需要通过index进行条件渲染，开发者需要接受ForEach在改变数据源后重新创建组件所带来的性能损耗；

b、为满足键值的唯一性，对于对象数据类型，建议使用对象数据中的唯一id作为键值；

c、基本数据类型的数据项没有唯一ID属性。如果使用基本数据类型本身作为键值，必须确保数组项无重复。因此，对于数据源会发生变化的场景，建议将基本数据类型数组转化为具备唯一ID属性的对象数据类型数组，再使用ID属性作为键值生成规则。