Skip to content

声明式 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」。数量改了合计不动的原因,相关文章处理。

第一步:写数据层 ​

观察能力必须写在类上,这是整段代码的前提。

ts
// 前提: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 转一下类型,编译器信了,运行时也不会带上观察能力。

第二步:写行组件 ​

行组件只负责展示和抛请求,不持有业务数据。

ts
@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 收口计算。

ts
@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 元,让测试一眼发现,也别让界面假装正常。

第四步:把样式抽成可复用的两种形态 ​

ts
// 全局构建函数与样式扩展: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 基线 ​

bash
# 前提:工程根目录,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 数据流讲透,再回来解释这条线索。