声明式 UI:组件、布局与样式
本篇要点:能用 ArkUI 的组件、布局容器与资源描述一屏界面,并判断一段样式该写成组件、构建函数还是样式扩展。 前置文章:《ArkTS 语言基础:从 TypeScript 到 ArkTS》立住了 ArkTS 的语法与工程结构,这一章开始往屏幕上放东西。
为什么需要它
2026 年 4 月,一个做本地生活的团队把商品页设计稿交给三个人分头实现:手机单列、折叠屏双列、平板左右分栏。三份代码合起来 1400 多行,其中 900 行在调 width、margin、fontSize。品牌色从 #FF6B00 换成 #E8500A 那天,他们改了 37 个文件。
问题不在勤奋。三个人用的都是 ArkUI,只是把声明式 UI 写成了命令式:给每个容器写死尺寸,用 padding 硬凑对齐,颜色直接写十六进制。界面能看,改不动。
声明式 UI(declarative UI)只承诺一件事:你写“界面在某个状态下应该长什么样”,不写“先找到这个节点,再把它改成什么样”。ArkUI 把 build() 里的描述编译成一棵组件树,测量、布局、绘制由框架完成。
命令式里改一个文本要先 findViewById 再 setText;声明式里文本内容就是表达式的一部分,状态一变,描述重新求值。
基线钉一下。截至 2026 年 11 月,HarmonyOS 6.0.0 对应 API 20(2025 年 9 月 25 日转 Release),配套 DevEco Studio 6.0.0(构建号 6.0.0.858),SDK 基于 OpenHarmony Ohos_sdk_public 6.0.0.47。这一章用到的 @ComponentV2 与 V2 装饰器从 API 12 起可用,停在 API 12 的工程能编,但混用约束比现在严。
这一屏还压着一个问题:用户改数量时,谁负责知道数据变了。这一章只把“形状”搭对,数据怎么流进形状留给相关文章。
核心概念
组件树:build() 只描述,不操作
定义:自定义组件就是一个带 @Component 或 @ComponentV2 装饰器的 struct,build() 返回它的界面描述,并且只能有一个根容器。
类比:build() 是菜谱,不是炒菜动作。菜谱写“两克盐”,不等于现在就去拿盐罐。
反例:在 build() 里写 console.log、发网络请求或改状态变量。build() 会被反复执行,副作用跟着执行很多次。要打印,放 aboutToAppear 或事件回调里。
图 2-1 画的是这一屏的组件树,以及布局阶段约束和尺寸的传递方向。
图 2-1 一屏购物车的组件树与约束传递
如图 2-1 所示,CartRow 里的商品名用 layoutWeight(1) 吃掉按钮之外的全部宽度。这个分配不是 Row 猜的:测量阶段 Row 先拿父容器给的宽度减掉两个按钮,剩下的按权重分。
约束:尺寸是谈出来的
定义:父容器在 measure 阶段给每个子组件一组约束(constraint),含最小与最大尺寸;子组件在这组约束内决定自己的尺寸,layout 阶段再由父容器定位置。
这里有两个方向,别记反。约束自上而下,尺寸自下而上。父容器永远不知道子组件想要多大,它只能给范围、收结果。
单位也要分清。默认数值单位是 vp(virtual pixel,虚拟像素),与屏幕密度解耦;字体用 fp(font pixel),会跟随系统字体大小缩放;lpx 以 750 宽的设计稿为基准;百分比相对父容器的内容区。
反例:在 750 宽的设计稿上量到按钮高 88,直接写 .height(88)。750 宽的设计稿是 2 倍图,88 对应 44vp,写成 88 等于把按钮放大一倍;换到平板上,这个写死的值又不再随容器伸缩。
布局容器:先看主轴方向
一排控件是横着放还是竖着放,决定了你该选哪个容器。Row 的主轴是水平,Column 的主轴是垂直,两者都能用 justifyContent 调主轴对齐、alignItems 调交叉轴对齐。
下表是这一屏可能用到的容器,选型时先看第三列。
| 容器 | 排列方式 | 典型用途 | 注意 |
|---|---|---|---|
| Row | 水平单行 | 图标 + 文字、步进器 | 子项总宽超出时被压缩,分配剩余宽度用 layoutWeight |
| Column | 垂直单列 | 卡片内容、表单 | 高度不足时先压可压缩的子项 |
| Stack | 层叠,后写的在上 | 角标、遮罩、加载层 | 子项默认居中,位置靠 alignContent |
| RelativeContainer | 按锚点定位 | 结构复杂但要求扁平的卡片 | 每个子项要设 id,锚点写错不报错,只是位置偏 |
| Flex | 单行或换行 | 标签流式排列 | wrap 与对齐组合多,先用 Row/Column |
| Grid | 行列网格 | 商品九宫格 | 必须配 columnsTemplate / rowsTemplate |
| List | 纵向滚动 | 长列表 | 子项必须是 ListItem,长列表用 LazyForEach 或 Repeat |
表里最容易被忽略的是 RelativeContainer 那一行。它的价值在于把“为了对齐套三层容器”压成一层,代价是每个子项都得有 id,而且锚点关系错了不会有编译错误。
样式与资源:把写死的值抽出去
定义:样式是属性方法,跟在组件后面链式调用;资源是用 $r('app.type.name') 引用的、放在 resources 目录下的值。
$r('app.color.price') 对应 resources/base/element/color.json 里的 price,$r('app.string.title') 对应 string.json,图片走 $r('app.media.icon'),数值走 $r('app.float.gap')。resources/dark/element/color.json 存在时,深色模式自动取深色那一份;zh_CN、en_US 这类限定词目录按语言匹配。
反例:37 个文件里各写一遍 #FF6B00。换色那天你得全局搜索,还得赌没有人写成 #ff6b00。深色模式上线时,白底白字会一起出现。
同类组件的重复样式,用 @Extend(Text) 扩展;只涉及通用属性(padding、margin、背景、圆角)的,用 @Styles。后者能力更窄,只能写通用属性与通用事件。
自定义组件与复用:边界就是状态边界
拆组件不只是为了文件短。一个 struct 一旦独立,它的状态归属就得说清楚:内部状态用 @Local,外部传入的只读值用 @Param,想改数据就抛 @Event 让父组件改。@Param 在子组件里赋值会编译失败,框架不给这条路。
复用则是另一件事。滚动列表里,节点回收由框架管,@Reusable 让组件实例也能回收再用,省下的是构造与初始化开销。API 18 起有面向 V2 的 @ReusableV2,复用时框架会自动重置状态变量、重算 @Computed。
V2 不是性能升级。把能正常跑的 V1 页面改成 V2,帧率不会有可测量的变化;它解决的是嵌套对象改不动、跨层级传参靠字符串 key 硬撑这两件事。混用的边界也要记牢:V1 的 @State、@Prop、@Link 不能和 @ObservedV2 同用,也不能接收被 @ObservedV2 标过的类,混用只允许发生在父子组件之间。
| 手段 | 写法 | 适用 | 限制 |
|---|---|---|---|
| 自定义组件 | @ComponentV2 struct | 有独立状态、生命周期、事件 | 有创建与初始化成本 |
| 构建函数 | @Builder | 纯展示的 UI 片段 | 没有状态与生命周期,按值传参不刷新 |
| 样式扩展 | @Extend(Text) | 同类组件的属性集合 | 只能用于指定组件类型 |
| 通用样式 | @Styles | 通用属性与通用事件 | 不能写组件私有属性 |
| 组件复用 | @Reusable / @ReusableV2 | 滚动中反复创建的同构卡片 | 要处理残留状态 |
动手实践
目标:把这一屏跑起来,看到「合计 33.00」。数量改了合计不动的原因,相关文章处理。
第一步:写数据层
观察能力必须写在类上,这是整段代码的前提。
// 前提:API 20;文件扩展名 .ets;DevEco Studio 6.0.0
import { hilog } from '@kit.PerformanceAnalysisKit';
@ObservedV2
class CartItem {
@Trace name: string = '';
@Trace price: number = 0;
@Trace count: number = 1; // 改这一行,行小计与合计都要动
}
@ObservedV2
class CartModel {
@Trace items: CartItem[] = [];
@Trace coupon: string = '';
}运行结果:编译通过,没有告警。此时 items 是空数组,还没有界面显示它;等第三步把页面接上,这一层才会输出「合计 0.00」。
@ObservedV2 和 @Trace 必须成对出现。只标类不标属性,属性不会进观察集合,改了也不通知。反过来,从网络、从 preferences、从任何序列化路径拿到的对象都是普通对象:哪怕你 as CartItem 转一下类型,编译器信了,运行时也不会带上观察能力。
第二步:写行组件
行组件只负责展示和抛请求,不持有业务数据。
@ComponentV2
struct CartRow {
@Require @Param item: CartItem; // 下行:外部给,只读
@Param @Once compact: boolean = false; // 只初始化一次,此后不同步
@Local pressed: boolean = false; // 内部状态,必须本地初始化
@Event onCountChange: (delta: number) => void = () => {}; // 上行:提需求
build() {
Row() {
Text(this.item.name).layoutWeight(1)
Button('-').onClick(() => this.onCountChange(-1))
Text(`${this.item.count}`)
Button('+').onClick(() => this.onCountChange(1))
}
.backgroundColor(this.pressed ? '#1F000000' : Color.Transparent)
.onTouch((e: TouchEvent) => {
this.pressed = e.type === TouchType.Down;
hilog.info(0x0000, 'Cart', 'row %{public}s pressed=%{public}s',
this.item.name, `${this.pressed}`);
})
}
}运行结果:每行渲染成「商品名 / - / 数量 / +」,商品名占满按钮之外的宽度;按下时该行背景变成 12% 透明度的黑色,日志输出 row 有机菠菜 pressed=true。点「+」只发出回调,数量不变,因为 @Param 是只读的。
这里有两个编译期就拦住你的错误:@Local 写了却从外部传值,编译失败;@Param 在子组件里赋值,同样失败。不用怀疑框架,这就是设计。
第三步:把合计放到页面层
合计跨两层传,用 @Provider / @Consumer 按 key 取,用 @Computed 收口计算。
@ComponentV2
struct CartPage {
@Provider('cart') cart: CartModel = new CartModel();
build() {
Column() {
CartSummary()
CartList()
}
}
}
@ComponentV2
struct CartSummary {
@Consumer('cart') cart: CartModel = new CartModel();
@Computed
get total(): number {
return this.cart.items.reduce((sum: number, it: CartItem) => sum + it.price * it.count, 0);
}
build() {
// 预期输出:12.50 × 2 + 8.00 × 1 → 界面上显示「合计 33.00」
Text(`合计 ${this.total.toFixed(2)}`)
}
}运行结果:商品为 12.50 元两件、8.00 元一件时,底部显示「合计 33.00」。改动任意一件的数量,这一行跟着变。
@Computed 的依赖是在读的时候收集的。getter 里写 if (this.cart.items.length === 0) return 0; 时,空列表那一次一条商品都没读;加进第一件商品后 items 被读过,所以会重算,结果是对的。但如果某个分支把某个 @Trace 字段挡在外面,那个字段变化永远不会触发重算。写条件分支时,回头看一眼每个分支到底读了什么。
@Consumer 还有一条兜底规则:漏配同名 @Provider 时不报错,它会退回本地默认值。页面照常渲染,数据永远不更新。所以别给它的默认值塞一个业务上“看起来正常”的对象,比如预先放一条占位商品——宁可让它显示 0 元,让测试一眼发现,也别让界面假装正常。
第四步:把样式抽成可复用的两种形态
// 全局构建函数与样式扩展:API 20,文件扩展名 .ets
@Extend(Text)
function priceText() {
.fontSize(16)
.fontColor($r('app.color.price'))
.fontWeight(FontWeight.Medium)
}
@Builder
function tagChip(label: string) {
Text(label)
.fontSize(12)
.padding({ left: 6, right: 6, top: 2, bottom: 2 })
.borderRadius(4)
.backgroundColor($r('app.color.tag_bg'))
}
// 调用处
Row({ space: 8 }) {
Text(`¥${this.item.price.toFixed(2)}`).priceText()
tagChip('满减')
}运行结果:价格文本统一为 16fp、品牌色、中等字重;标签统一为 12fp、6vp 内边距、4vp 圆角。改 @Extend 里的 fontSize,所有调用点一起变。
@Builder 的参数是按值传的。调用它的组件整体重建时,片段会跟着重建;但如果只改那个参数、父组件不重建,片段不会自己刷新。要独立刷新,就得写成带状态的自定义组件。
第五步:核对 SDK 基线
# 前提:工程根目录,DevEco Studio 6.0.0
$ grep -n "compatibleSdkVersion" build-profile.json5
# 预期输出
8: "compatibleSdkVersion": "6.0.0(20)"运行结果:输出 "compatibleSdkVersion": "6.0.0(20)"。如果这里还是 5.0.0(12),@ComponentV2 能编,但 @ReusableV2 这类 API 18 才有的能力用不上。
常见误解
很多人以为 build() 只在数据变化时跑一次。 实际上父组件重跑会重建整棵子描述,build() 里放 filter、sort、reduce、长字符串拼接,等于每帧交一次税。算一次用多次的东西,用 @Computed 收口。
以为 @Builder 是轻量版自定义组件。 它没有生命周期、没有独立状态,参数按值传递时不会因参数变化自行刷新。它的定位是“把一段重复的界面描述折起来”,不是组件。
以为 width('100%') 一定撑满屏幕。 百分比相对父容器的内容区:父容器有 padding,或者父容器自己没占满屏幕,结果都不是屏幕宽。想占满剩余空间,用 layoutWeight 比百分比可靠。
小结
build()是描述,不是操作:单根容器、无副作用,副作用放生命周期或事件回调。- 约束自上而下、尺寸自下而上;默认长度单位是 vp,字体是 fp,写死尺寸换设备就错。
- 先确定主轴再选容器;分配剩余空间用
layoutWeight,要扁平化用RelativeContainer。 - 颜色、字号、文案、图片走
$r资源与限定词目录;同类样式用@Extend,UI 片段用@Builder,有状态才拆结构体。 @Reusable与@ReusableV2省的是构造开销,不改变业务逻辑;@ObservedV2必须配@Trace。
相关主题
购物车已经摆好了,但合计为什么会在某些写法下不动,这一章只留了线索:@State 只看第一层,从 JSON 解析出来的对象没有观察能力。相关文章进入[《状态管理:@State 家族与 V2 状态管理》 状态管理](/guide/harmonyos/harmonyos-state-management.html),把 V1 的 @State 家族与 V2 的 @Local/@Param 数据流讲透,再回来解释这条线索。