从 @Component 到 @Builder：深度拆解 ArkTS 声明式 UI 与 @ohos.mediaquery 的协同实战
全文约 3.6k 字，可直接复制到 DevEco Studio 侧边 Markdown 预览，边读边跑代码。
从 @Component 到 @Builder：深度拆解 ArkTS 声明式 UI 与 @ohos.mediaquery 的协同实战
关键词：ArkTS、@Component、@Builder、@Styles、@Extend、MediaQueryKit、响应式、性能、组件复用
1. 前言：为什么“会写组件”≠“写好组件”
HarmonyOS 4.1（API 12）之后，ArkTS 的声明式语法彻底稳定。
很多开发者可以很快写出 Column(){}.width('100%') 这样的“Hello World”级 UI，却在面对以下场景时直接懵圈：
- 设计稿给出 6 种屏幕断点，如何一份代码多端生效？
- 自定义组件嵌套 5 层后，状态管理开始“幽灵刷新”？
- 业务方要求“卡片”外观可换肤，但结构不变，如何优雅抽离？
本文用 一个真实落地的“响应式卡片”组件 作为主线，把 ArkTS 语法糖、组件设计模式、以及 @ohos.mediaquery Kit 的底层机制串起来讲透。
读完你将获得：
- 掌握
@Component、@Builder、@Styles、@Extend四把“手术刀”各自的使用边界； - 理解 轻量级状态管理 与 @Link、@Prop、@Provide、@Consume 在性能上的差异；
- 学会用 MediaQueryKit 在 编译期 完成断点，而非传统“监听窗口尺寸”的卡顿方案；
- 带走一套可移植的 “响应式 + 换肤” 代码模板，直接用于生产。
2. ArkTS 语法再回顾：四把“手术刀”拆解
| 语法/装饰器 | 作用域 | 生成产物 | 典型用途 |
|---|---|---|---|
@Component | struct 顶部 | 一个自定义组件 | 复用 UI + 逻辑 |
@Builder | 函数顶部 | 一段 UI 描述 | 纯 UI 复用，无状态 |
@Styles | 函数顶部 | 样式闭包 | 主题/换肤 |
@Extend | 全局 | 给内置组件“加方法” | 链式调用增强 |
记忆口诀：
Component 是“带电池”的玩具汽车；Builder 是“拼装积木”；Styles 是“喷漆”；Extend 是“外挂氮气”。
3. 需求建模：一张“卡片”的 6 种变体
| 断点 | 屏幕宽 | 卡片列数 | 封面比例 | 文字行数 | 圆角 | 阴影 |
|---|---|---|---|---|---|---|
| xs | <320 | 1 | 16:9 | 2 | 12vp | 无 |
| sm | 320~ | 1 | 4:3 | 3 | 16vp | 低 |
| md | 600~ | 2 | 1:1 | 3 | 20vp | 中 |
| lg | 840~ | 3 | 3:4 | 4 | 24vp | 高 |
| xl | 1080~ | 4 | 9:16 | 5 | 28vp | 高 |
| xxl | 1440~ | 4 | 9:16 | 5 | 32vp | 高 |
注：vp = virtual pixel，与屏幕密度无关。
4. 架构设计：三层解耦
┌------------------------------┐
│ 1. 表现层（Presentation） │ ← 完全无业务，仅 UI
│ - ResponsiveCardComponent │
│ - CardStyles / CardTheme │
└------------------------------┘
┌------------------------------┐
│ 2. 领域层（Domain） │ ← 纯数据模型
│ - CardEntity │
└------------------------------┘
┌------------------------------┐
│ 3. 应用层（Application） │ ← 页面入口，负责组装
│ - HomePage │
└------------------------------┘