一、我们要做什么
1.1 背景与目标
传统移动端 UI 开发多采用命令式（imperative）方式：开发者手动查询控件引用、监听事件、再显式调用 setText/setVisibility 等方法更新界面。这种方式在界面复杂、状态分散时极易出现「状态与视图不一致」「遗漏更新」「回调地狱」等问题。ArkUI 作为鸿蒙官方推荐的下一代 UI 框架，采用声明式（declarative）开发范式，主张「用数据描述 UI，让框架负责渲染」。本篇文章的目标是带领读者从零搭建一个完整的声明式购物车页面，并理解其背后的状态管理新特性。
我们要完成的核心任务包括：使用 ArkTS 定义一个购物车的商品列表与选中状态模型；通过 @State 持有页面级可变状态；通过 @Prop 实现父向子的单向数据流；通过 @Link 实现父子双向同步；通过 @Provide/@Consume 跨多层组件直接共享状态而无需逐层透传；通过 @Builder 抽取可复用的 UI 片段；将商品卡片、数量步进器封装为独立自定义组件实现复用。最终交付一份可直接运行的 ArkTS 源码与一套可复用的工程化思路。
1.2 声明式 UI 开发需求表
下表梳理了本示例需要覆盖的需求、对应技术点与预期表现，作为后续设计与验收的基线。每一项需求都对应一个具体的装饰器或 API，确保技术选型与业务目标一一对齐，避免「为了用特性而用特性」：
| 编号 | 需求描述 | 使用特性 | 预期效果 |
|---|---|---|---|
| R1 | 页面展示商品列表 | @State 数组状态 | 数据变化自动重渲染列表 |
| R2 | 点击商品切换选中 | @State + 条件渲染 | 选中态高亮且无手动刷新 |
| R3 | 子组件展示商品名 | @Prop 单项传递 | 父改子随，子改父不动 |
| R4 | 子组件修改数量 | @Link 双向绑定 | 父子数量始终同步 |
| R5 | 跨层显示购物车总数 | @Provide/@Consume | 深层组件无需透传参数 |
| R6 | 复用卡片底部操作区 | @Builder | 多处调用同一构建函数 |
| R7 | 封装可复用组件 | struct 自定义组件 | 列表项、步进器独立复用 |
1.3 预期效果
最终页面将呈现一个商品列表，每个商品卡片包含名称、价格、选中框与数量步进器。用户点击选中框时卡片高亮，视觉上立即反馈选中状态；点击加减按钮时数量与底部购物车汇总实时变化，顶部标题栏的「已选 N 种 / 共 M 件」同步刷新；整个过程无需任何手动 findViewById 或 notify，所有更新由状态驱动自动完成，界面与数据始终保持一致。这种「所改即所见」的体验，正是声明式开发最直观的价值，也是它能在复杂业务中保持低维护成本的根本原因。
1.4 我们面临的挑战
挑战一：状态归属不清。多组件需要共享同一份数据时，若用 props 层层透传，组件耦合度高、重构困难，一旦出现中间层漏传就会导致数据断层，且排查困难。挑战二：双向同步易错。命令式开发中父子互相持有引用并互调方法，循环更新难以排查，且容易出现「父改了子不知道、子改了父没存」的不一致。挑战三：UI 复用粒度粗。相同布局散落多处，修改需同步多处，极易产生遗漏与样式漂移，后期维护成本随页面数线性增长。挑战四：性能不可控。全量重绘在大列表下卡顿，命令式下需要开发者手动判断哪些控件该更新，心智负担重且容易漏判。ArkUI 的装饰器体系与最小更新算法正是为解决上述四类问题而生。
1.5 命令式与声明式的直观对比
在命令式代码里，增加一件商品需要「找到列表容器 → 创建行视图 → 设置文本 → 插入到指定位置 → 刷新适配器」五步；而在声明式里，只需 this.products = [...this.products, newItem]，框架自动算出差异并增量更新。声明式把「过程」交给框架，开发者只描述「终态」，这正是 ArkUI 提升生产力的根本来源。理解这一点，就能明白为什么状态装饰器是 ArkUI 的第一公民，而非可有可无的语法糖；也能解释为何很多从命令式转来的开发者最初会「不习惯」——因为他们习惯了自己掌控每一步，而声明式要求他们把控制权让渡给状态与框架。
1.6 开发环境与项目准备
要运行本文示例，需要安装 DevEco Studio 5.0 及以上版本，并创建「Empty Ability」模板的 ArkTS 工程，SDK 选择 HarmonyOS NEXT（API 12+）。页面文件通常位于 entry/src/main/ets/pages/ 目录，组件与模型可按需拆分到 ets/components/、ets/model/。本文所有代码均为标准 ArkTS，无需额外依赖，可直接粘贴到 Index.ets 中预览。建议在真机或模拟器上运行以观察真实的最小更新行为，因为预览器对部分装饰器的刷新表现与真机基本一致，但真机更能反映性能差异。
1.7 本文结构导览
全文共八节：第一节明确目标与需求，第二节设计数据模型与契约，第三节做核心方案选型对比，第四节给出完整可运行代码，第五节深入框架原理，第六节汇总常见坑点，第七节用字符画呈现运行效果，第八节给出扩展方向。建议按顺序阅读，尤其不要跳过第三节的选型理由——它决定了你能否在真实项目里正确选用装饰器，避免「刷新不生效」这类高频问题。
1.8 验收标准与成功指标
完成上述目标后，如何判断实现合格？建议设定可量化验收点：首屏标题栏应显示「已选 1 种 / 共 1 件」；点击未选商品选中框，种类数 +1 且边框变蓝；点击 + 数量与总件数同步 +1 且小计正确；数量减到 1 后 - 不再生效；删除商品后列表与汇总同步收缩。五点全过即说明状态流与 UI 联动正确，可作为提测准出条件。把这些口径写成清单，既能在联调时逐项核对，也能作为 Code Review 的验收门槛，确保「状态驱动」不只是口号，而是可度量的工程质量。
1.9 数据流设计三原则
在动手前，我们立下三条贯穿全文的原则：第一，单一数据源——每个状态只有一个权威来源，派生数据由来源计算得出；第二，单向流动——数据从祖先流向后代，回写通过 @Link 显式声明，不偷偷改父；第三，最小刷新——状态只通知真正依赖它的节点。这三条原则让复杂页面的状态始终保持可预测，是声明式开发区别于混乱命令式代码的分水岭，也是后文所有选型的最终判据。新人只要守住这三条，绝大多数状态归属问题都能在写代码前想清楚，而不是上线后靠排查。
1.10 项目结构与技术栈
为让示例可落地，我们约定工程结构：pages/ShoppingPage.ets 放主页面，components/ 放可复用组件，model/CartModel.ets 放数据层。技术栈为 ArkTS + ArkUI（API 12+），开发工具 DevEco Studio 5.x。这种分层让「状态归状态、UI 归 UI、数据归数据」，配合装饰器体系，天然契合声明式开发。本章确立的目标与挑战，正是后续章节要逐一拆解解决的问题，也为团队提供了可复制的脚手架模板，让新人能照着搭出第一个状态驱动页面。
二、数据模型设计
2.1 为什么先定义数据模型
声明式开发的信条是「UI 是 state 的函数」：UI = f(state)。因此动手写界面之前，必须先明确状态的形状（shape）与契约。良好的数据模型能让我们在编译期就发现字段错误，并让状态装饰器正确建立依赖追踪。数据模型也是团队沟通的「接口文档」，前端、后端、测试都能基于它对齐理解，减少联调期的字段歧义与空值异常。先把数据想清楚，UI 往往自然浮现，这正是声明式相比命令式「先画界面再填数据」的反转之处。
2.2 状态模型定义
我们以购物车场景为例，定义两个核心接口。Product 描述单个商品：包含唯一标识 id、名称 name、单价 price、当前数量 count 以及是否选中 selected。CartSummary 描述购物车汇总信息：商品种类数 kinds 与总件数 total。二者共同构成页面的「单一数据源」，所有 UI 都是这两个结构的投影，任何界面变化都能在数据中找到唯一对应的状态变更，杜绝了「界面显示对、数据存错」的割裂。
interface Product {
id: number
name: string
price: number
count: number
selected: boolean
}
interface CartSummary {
kinds: number
total: number
}
2.3 UI 数据契约
UI 数据契约强调「视图只读取、不拥有」状态。父组件持有 Product[] 这一 @State 数组，子组件 ProductCard 通过 @Prop 接收单个 Product 的快照用于展示，通过 @Link 接收与该数组元素的双向绑定用于修改数量。顶层 CartPage 通过 @Provide 暴露 summary，任意深层子组件用 @Consume 消费，形成「可观察状态 → UI 纯函数」的清晰边界，任何写操作都经由状态层而非视图层，避免分散修改带来的不一致。这样的边界让组件成为「状态的纯投影」，可预测、可测试。
2.4 状态分类约定
我们约定：可变且影响渲染的字段必须加状态装饰器；纯展示的常量（如文案、图标名）不加装饰器以减少追踪开销；数组尽量整体替换或配合 ForEach 的 key 以保证最小更新；跨组件共享的派生数据（如 summary）集中计算、避免各组件各自重复聚合。以上约定将在第四节代码实现中严格执行，也是后期可维护性的关键。遵守约定后，状态变更路径可预测，调试时只需关注状态而非散落的视图更新调用，问题定位时间显著下降。
2.5 可观察性的边界
需要特别理解：普通 interface/字面量对象的赋值默认不会被深度追踪。若把 Product 定义为 class 并用 @Observed 装饰，其子字段变化才能被 @ObjectLink 捕获。本文列表用 @State 数组整体替换即可触发更新，故采用 interface 即可；但在「对象内部属性频繁变更」的场景，应当升级为 @Observed 方案，这是数据建模时的一项重要权衡。过早引入 @Observed 会增加复杂度，过晚引入则会出现「改了属性 UI 不动」的诡异 bug，需结合变更频率判断，通常「整体替换够用就不上 @Observed」。
2.6 示例数据与初始化
为便于演示，我们在 @State products 中预置两条数据：一条默认选中（selected: true），一条未选中。这样首屏即可看到选中态差异与汇总计算的正确性。aboutToAppear 中调用 refreshSummary 完成首次聚合，保证进入页面时标题栏数字准确。示例数据应尽量覆盖边界：选中/未选中、数量为 1、数量大于 1，以便在后续交互中验证步进器下限与汇总累加逻辑。对于需要异步加载的数据，推荐先以空数组 + loading=true 进入加载态，数据返回后再整体替换引用。
2.7 不可变性与状态更新
声明式框架普遍偏好「不可变更新」：与其修改数组元素再手动通知，不如返回新数组 this.products = this.products.map(...)。虽然 ArkUI 的 @Link 支持就地写回数组元素，但在跨组件、跨页面场景，整体替换更不易出错，也更容易与 AppStorage、持久化方案对接。本文为降低初学门槛使用了 @Link 就地写回，生产环境可根据团队规范在「就地」与「不可变」之间权衡，但务必保持统一风格，避免混用导致认知混乱。把「不可变」作为契约写进团队规范，可从根本消除一大批隐蔽的刷新 bug。
2.8 与后端接口对齐
真实项目中 Product 通常来自接口。建议定义独立的「网络模型」与「UI 模型」：网络层返回 ApiProduct（含服务端字段），在仓库层映射为本文 Product 后再交给 @State。这样当接口字段变更时，只需改映射函数，UI 与状态装饰器不受影响，避免后端契约波动直接冲击视图层，是分层架构下的稳妥做法。契约先行，能把状态管理从「运行时排错」前移到「编译期预防」，把 Bug 消灭在敲下回车之前，让前后端协作更顺畅。
2.9 类型安全的收益与契约校验
ArkTS 相比普通 JS 强化了类型检查：装饰器只能修饰被允许的类型，@Link 必须与父状态类型兼容，@Prop 的传值会被类型系统校验。这意味着在编译期就能发现「把一个字符串传给数字状态」这类错误，而不是在运行时诡异崩溃。类型安全是把购物车从 demo 推向生产级应用的基石，也是我们坚持用 interface 而非 any 的根本原因。把接口当作 UI 与数据的「契约」，还能让前后端基于同一份字段定义对齐，减少联调期的口径分歧，把 Bug 消灭在敲下回车之前，让状态管理从运行时排错前移到编译期预防。
三、核心设计决策
3.1 声明式 vs 命令式
在选型阶段，我们首先对比两种范式。声明式以「描述终态」为核心，框架通过差异比对（diff）执行最小更新；命令式以「描述过程」为核心，开发者自己编排每一步 UI 变更。对于状态密集、交互频繁的购物类页面，声明式显著降低心智负担，也更利于组件复用与测试。下表从多个维度量化了二者差异，帮助团队在架构评审时统一认知，减少「要不要上 ArkUI」的争论。
| 维度 | 命令式 | 声明式（ArkUI） |
|---|---|---|
| 心智模型 | 操作控件过程 | 描述数据终态 |
| 状态同步 | 手动调用更新 | 自动响应式刷新 |
| 复用方式 | 继承/模板复制 | 组件+Builder 组合 |
| 跨层状态 | 逐层透传或全局单例 | @Provide/@Consume |
| 可维护性 | 随规模下降 | 随规模稳定 |
| 性能控制 | 人工判断更新点 | 框架最小更新 |
3.2 状态装饰器适用场景对比
不同装饰器解决不同范围的状态问题，选错会导致刷新失效或副作用。核心对比见下表，它也是团队内部 Code Review 时判断「该用哪个装饰器」的速查表，建议沉淀为规范文档，让新成员照表填空即可少踩坑：
| 装饰器 | 数据流向 | 作用范围 | 典型场景 | 注意点 |
|---|---|---|---|---|
@State | 私有可变 | 组件内 | 页面主状态 | 仅本地，子组件看不到 |
@Prop | 父→子单向 | 子组件 | 展示型传参 | 子改不影响父 |
@Link | 父子双向 | 子组件 | 表单/计数器 | 必须与父 @State 绑定 |
@Provide | 祖先→后代 | 跨层 | 主题/用户/购物车 | 配合 @Consume |
@Consume | 后代→祖先 | 跨层 | 深层读全局 | 无需逐层传参 |
@Observed/@ObjectLink | 嵌套对象 | 深层字段 | 对象内部属性 | 用于 class 实例 |
3.3 选型理由
本示例最终选型为：@State 持有商品数组（R1/R2），@Prop 传展示快照（R3），@Link 做数量双向（R4），@Provide/@Consume 做购物车汇总（R5），@Builder 抽卡片底部（R6），struct 封装卡片与步进器（R7）。理由有三：其一，单向 @Prop 保证展示稳定，避免子组件误改父数据；其二，@Link 在需要回写时比事件回调更简洁且不易遗漏；其三，@Provide/@Consume 消除了「prop drilling」，使深层标题栏零成本订阅全局状态，重构时无需改动中间组件。这三点共同保证了「数据流单向可追、写回点集中可控」。
3.4 为什么不全部用 @State + 事件
一种朴素做法是：所有状态放顶层 @State，子组件通过事件回调通知父组件修改。这在简单页面可行，但会强制每个中间组件都声明并转发回调，形成「回调透传」；而 @Link/@Consume 让子组件直接读写目标状态，省去中转，代码更短、耦合更低。因此本文在「需要回写」处优先使用双向装饰器，而非一律走事件，这是工程成熟度的体现。当然，若写回伴随复杂业务校验（如库存校验、价格计算），则仍建议回调上抛、在父层统一处理，做到「简单同步用装饰器，复杂业务用事件」。
3.5 常见反模式
反模式一：用 @State 在子组件里拷贝父数据后自行修改，导致父子永远不同步——应改用 @Link。反模式二：深层组件层层 @Prop 透传同一全局状态——应改用 @Provide/@Consume。反模式三：在 build 内做随机数或网络请求，造成每次刷新结果不一致——副作用应移出 build。反模式四：用数组下标作 ForEach 的 key，重排后状态串台。识别这些反模式，能让代码从「能跑」走向「跑得好、改得动」，避免技术债在迭代中悄悄累积。
3.6 装饰器组合建议
实际页面常需组合使用：顶层 @State 持有主数据，@Provide 暴露聚合态；列表项用 @Prop 收快照、@Link 收可写字段；深层只读标题用 @Consume。记住「能单向不双向、能局部不跨层」，可显著降低意外刷新与调试成本。该选型表应作为团队规范沉淀，减少重复决策，也让 Code Review 有统一标尺，新人能照此快速上手，老代码逐步收敛到声明式。
3.7 决策 Checklist
落地新功能时，可用一张清单快速决策：这个状态有几个组件需要写它？只有一个 → @State；只有子组件读 → @Prop；子组件也要写回 → @Link；跨多层都要用 → @Provide/@Consume；只是纯展示片段 → @Builder；带独立交互 → @Component。照此对照，绝大多数状态归属问题都能秒级定位，避免后期返工，也方便 Code Review 时统一评判标准，让团队对「该用哪个装饰器」有共同语言。
3.8 迁移建议
对仍习惯命令式的团队，迁移时不要一次性重写，而是先挑一个叶子页面试点：用 @State 承接数据、@Prop 展示、@Link 回写，跑通后再推广到跨层主题用 @Provide/@Consume。每一步都以「刷新范围是否最小、依赖是否单向」为标尺，老代码逐步收敛到声明式，风险可控、收益可见。当团队形成统一选型语言，状态相关的线上故障会显著下降，维护成本随规模保持平稳而非线性上升，这正是声明式范式的长期价值。
3.9 性能与可读性的权衡
装饰器选择并非越「强」越好：@Link 比 @Prop 能力更强，但滥用 @Link 会让子组件获得改父的能力，破坏单向流的清晰度。原则是「刚好够用」——能用 @Prop 就别用 @Link，能用局部 @State 就别提升。这样在可读性与性能之间取得平衡，也让后续维护者一眼看懂每个状态的边界与归属，降低协作摩擦，避免技术债在迭代中悄悄累积。
四、完整代码实现
本节给出完整可运行的 ArkTS 代码。所有状态装饰器与构建函数均围绕第二节的数据模型落地，代码块只展示核心逻辑，每个片段都控制在 50 行以内，避免堆砌重复内容。本节共 5 个代码块，覆盖父子 @Prop/@Link 通信、跨层 @Provide/@Consume，以及 @Builder 与自定义组件的封装。
4.1 数据模型与顶层页面（@State + @Provide）
顶层 CartPage 用 @State 持有商品数组，用 @Provide 暴露购物车汇总；aboutToAppear 中计算初始汇总，refreshSummary 在每次状态变化后重算并写回 @Provide，驱动深层标题栏刷新。ForEach 的第三个参数是 key 生成函数，返回稳定唯一的主键字符串，这是列表高性能更新的前提。
// 数据模型
interface Product {
id: number
name: string
price: number
count: number
selected: boolean
}
interface CartSummary {
kinds: number
total: number
}
// 顶层购物车页面
@Entry
@Component
struct CartPage {
@State products: Product[] = [
{ id: 1, name: '鸿蒙开发板', price: 299, count: 1, selected: true },
{ id: 2, name: 'Type-C 线缆', price: 29, count: 2, selected: false }
]
@Provide summary: CartSummary = { kinds: 0, total: 0 }
aboutToAppear(): void {
this.refreshSummary()
}
refreshSummary(): void {
const kinds = this.products.filter(p => p.selected).length
const total = this.products.reduce((s, p) => s + (p.selected ? p.count : 0), 0)
this.summary = { kinds, total }
}
build() {
Column() {
CartHeader()
ForEach(this.products, (p: Product) => {
ProductCard({ product: p, onChanged: () => this.refreshSummary() })
}, (p: Product) => p.id.toString())
}.padding(16)
}
}
4.2 商品卡片：@Prop 展示 + @Link 双向数量
ProductCard 用 @Prop product 接收展示快照（父改子随、子改父不动），用 @Link count 双向绑定数量（子改直接写回父数组元素）；选中态用本地 @State selected 管理并通过 onChanged 回调通知父重算汇总。这里把「选中」留在本地、把「数量」交给 @Link，体现了「局部态本地管、共享态双向绑」的清晰边界，也让卡片自身对选中样式有完全控制权。
@Component
struct ProductCard {
@Prop product: Product // 单向展示快照
@Link count: number // 双向绑定数量
@State selected: boolean = false
onChanged: () => void = () => {}
build() {
Row() {
Checkbox({ name: 'sel', group: 'g' })
.select(this.selected)
.onChange(v => { this.selected = v; this.onChanged() })
Text(this.product.name).fontSize(16)
Stepper({ value: this.count, onChange: v => { this.count = v; this.onChanged() } })
}.border({ width: 1, color: this.selected ? '#007DFF' : '#ddd' })
}
}
4.3 跨层购物车汇总（@Provide / @Consume）
顶层已在 CartPage 用 @Provide summary 暴露，深层 CartHeader 直接用 @Consume summary 消费，无需逐层传参。这种跨层订阅让标题栏与页面状态解耦，中间任意层级组件都不必感知购物车数据，极大降低了重构时的连锁改动风险，是大型应用状态组织的推荐做法。注意 @Consume 的变量名必须与 @Provide 完全一致，否则会拿到默认值而非实时状态。
// 顶层已在 CartPage 用 @Provide summary 暴露
// 深层标题栏直接消费，无需逐层传参
@Component
struct CartHeader {
@Consume summary: CartSummary
build() {
Row() {
Text('我的购物车').fontSize(20).fontWeight(FontWeight.Bold)
Text(`已选 ${this.summary.kinds} 种 / 共 ${this.summary.total} 件`)
.fontColor('#007DFF').margin({ left: 12 })
}
}
}
4.4 Builder 自定义构建与组件封装
@Builder 抽取卡片底部操作区 CardFooter，可被多张卡片复用；Stepper 作为独立自定义组件封装加减逻辑，通过 @Link value 与父数量双向同步。两者共同体现了声明式下「UI 片段复用」与「逻辑组件化」的最佳实践，也让「展示」与「交互」职责分明，便于单独测试与样式调整。CardFooter 虽在示例里被预留调用位置，但其形态已是跨卡片复用的标准写法。
// @Builder 抽取卡片底部操作区，多处复用
@Builder
function CardFooter(price: number, count: number) {
Row() {
Text(`单价 ¥${price}`).fontColor('#999')
Text(`小计 ¥${price * count}`).fontColor('#ff5000').margin({ left: 16 })
}.margin({ top: 8 })
}
// 数量步进器自定义组件
@Component
struct Stepper {
@Link value: number
onChange: (v: number) => void = () => {}
build() {
Row() {
Button('-').onClick(() => { if (this.value > 1) { this.value--; this.onChange(this.value) } })
Text(this.value.toString()).margin(8)
Button('+').onClick(() => { this.value++; this.onChange(this.value) })
}
}
}
4.5 组合与状态联动说明
在 CartPage 的 ForEach 中，我们为每个 Product 创建 ProductCard 并传入 product（快照）与 count: this.products[idx].count（通过 @Link 双向绑定到数组元素）。当用户在步进器中加减时，@Link 直接写回数组元素，products 状态变更触发 ForEach 重渲染；同时 onChanged 回调 recompute summary 并写回 @Provide，深层 CartHeader 经 @Consume 自动刷新。整条链路「零手动 setText」，充分验证了声明式状态驱动的有效性，也说明正确拆分状态归属后，交互逻辑可以非常薄。
4.6 工程化封装建议
在实际工程中，建议把 Product、CartSummary 抽到独立 model/cart.ts；把 ProductCard、Stepper、CartHeader 拆到 components/ 目录；把 refreshSummary 的计算逻辑抽为纯函数 computeSummary(products) 便于单元测试；并将 @Builder 卡片底部放入公共 builders.ts 供多页面复用。这样的目录划分让状态层、视图层、构建层各司其职，规模扩大后依旧清晰可维护。此外，建议为关键装饰器用法补充注释与示例，降低新人上手成本，并把本文的选型表纳入团队规范，做到「状态归属有据可依」。
4.7 样式与主题抽离
为让示例更接近生产，可把颜色、间距抽到 theme.ets 的常量：PRIMARY='#007DFF'、BORDER_NORMAL='#ddd'、PRICE_RED='#ff5000'。组件内引用常量而非硬编码，配合 @Provide 还可实现「换肤」：把主题对象也用 @Provide 暴露，深层组件 @Consume 后随主题切换整体刷新。这样状态管理与样式管理统一在同一套响应式体系下，维护成本最低，也避免各处魔法字符串导致的样式不一致与暗色模式缺失，让主题切换成为声明式能力的自然延伸。
4.8 调试与测试建议
定位「刷新不生效」时，先确认状态是否真的被 set：在赋值处打日志；再确认组件是否真的读取了该状态（依赖是否建立）；最后确认 key 是否稳定。DevEco Studio 的 ArkUI 预览器可实时反映状态变化，结合断点能快速锁定是「状态没变」还是「依赖没建立」。把 computeSummary 抽成纯函数后，可用最简单断言覆盖「全选/全不选/部分选」三种汇总结果，无需启动 UI——声明式让状态层可测，是它利于工程化的隐性收益，应尽早建立这一习惯。
4.9 代码组织与导入
推荐目录：ets/model/cart.ts（接口与纯函数）、ets/components/ProductCard.ets、Stepper.ets、CartHeader.ets、ets/builders/CardFooter.ets。各组件用 export 导出，Index.ets 中 import 组装。拆分后单文件更短、职责更单一，也方便单元复用与跨页面搬运。注意 @Builder 全局函数需放在组件外，组件内私有构建函数可用成员 @Builder 装饰，二者作用域不同，全局函数可被任意组件调用，成员函数仅本组件可用。良好的目录划分让状态层、视图层、构建层各司其职。
4.10 状态提升的边界
「提升」指把状态从子组件移到共同祖先以便共享，但并非越高越好：状态提升过高会让本不相关的兄弟组件因共享祖先状态而被迫重渲染。判断边界的经验是——只提升到「所有需要该状态的组件的最小公共祖先」。购物车列表提升到 CartPage 即可；主题因几乎全树都需要，才提升到根并用 @Provide 跨层下发。这条经验直接决定刷新范围与性能上限，是写大页面时必须反复掂量的点。
4.11 错误处理与边界
真实购物车要做边界保护：步进器最小值 1、最大值可设库存上限；价格应做四舍五入与货币格式化；空列表需渲染「购物车为空」占位。这些边界都应落在状态层或纯函数里，保证 UI 只负责投影。把校验前置到状态写入处，能避免非法数据流入 UI 造成崩溃或显示异常，也便于集中测试边界逻辑，提升健壮性，让异常分支有清晰的可渲染形态。
4.12 单元测试示例
把 computeSummary(products) 抽成纯函数后，可编写轻量断言：输入两件全选商品期望 {kinds:2,total:5}；输入一件未选期望 {kinds:0,total:0}；输入混合期望仅累加选中项。这类测试不依赖 UI，运行快、稳定，能在 CI 中守护汇总逻辑。状态层可测是声明式相比命令式的重要工程优势，应尽早建立这一习惯，把验证从「点开模拟器手点」升级为「提交即跑测试」。
4.13 事件与状态的分离
注意代码中「事件回调」（如 onChanged）与「状态」（count、summary）是分开传递的：状态用 @Link 做结构化回写，事件用函数做通知。二者职责不同——@Link 负责数据同步，回调负责副作用（如埋点、持久化）。把副作用收敛到回调而非散落在组件各处，可以让状态逻辑保持纯净、易于推理，也便于后期接入统一的日志与监控体系，避免业务逻辑与视图逻辑纠缠。
4.14 组合优于继承
ArkUI 的组件复用靠「组合」而非「继承」：CartPage 组合 CartHeader、ProductCard、Stepper，每个组件自包含、可单独替换。这种风格让 UI 像搭积木，新增一种卡片只需新增一个 @Component 并放入 ForEach，不影响既有结构。组合带来的另一个好处是测试隔离——Stepper 可以脱离页面单独渲染与验证，进一步提升工程质量，也是组件库得以长期演进的底层纪律与最佳实践。
五、深度技术原理
5.1 UI 描述与渲染分离
ArkUI 将「UI 描述」与「渲染」解耦。build() 函数返回的是一颗 UI 描述树（轻量声明），框架在内部将其转译为真正的渲染节点。状态变化时，框架不会销毁重建整棵视图树，而是基于描述树做差异化比对，只更新变化的节点，从而实现高性能局部刷新，这也是声明式相比命令式在复杂页面更具优势的根源。开发者写的是「声明」，框架负责「落实」，二者职责清晰、互不侵入，这让「写起来简单」与「跑起来高效」得以兼得。
5.2 状态装饰器与依赖追踪
每个被装饰的状态变量在初始化时会被框架建立「可观察包装」。组件 build() 执行过程中读取了某状态变量，框架就记录「该组件依赖此状态」。当状态 set 赋值触发时，框架沿依赖表找到所有相关组件，标记为「脏（dirty）」，加入更新队列。这就是声明式「数据变→UI 变」的底层机制，开发者无需手动维护依赖关系，框架在编译与运行期为每个组件自动织入追踪逻辑，把最容易出错的「依赖登记」交给机器完成，从而避免了人为遗漏。
5.3 UI 更新脏检查（Dirty Check）
框架采用「标记-刷新」而非每帧全量遍历。状态写入即标记，下一帧只处理被标记的组件，执行其 build() 重新生成描述并 diff。对比命令式「开发者自己判断哪些控件要改」，脏检查把「判断成本」从人转移到框架，既防遗漏又避免无谓重绘，是性能与正确性的双重保障。理解脏检查后，就能解释「为什么有时改了数据 UI 没动」——往往是因为赋值未触发可观察包装的 set，例如直接改了对象内部未被追踪的字段，而未产生新引用。
5.4 最小更新与 ForEach 的 key
ForEach 通过 key 函数在数据数组与 UI 节点间建立稳定映射。数据增删时，框架依据 key 复用已有节点而非重建，仅对变化项做最小更新。key 必须具备稳定性与唯一性，推荐使用业务主键（如 product.id），避免使用数组下标——下标在数据重排时会错位，导致组件错误地复用旧状态，引发难以排查的显示 bug。这一条是声明式列表开发的铁律，务必在 Code Review 中重点检查，也是高性能长列表的基石。
5.5 @Link 与 @Prop 的本质区别
@Prop 在子组件创建时拷贝父值，形成独立副本，父变子随、子变父不动，适合纯展示。@Link 则持有对父状态的「引用指针」，读写都作用在父状态上，实现双向同步，适合表单、计数器等需要回写的场景。二者不可混用，误用 @Prop 做双向会导致子改父不生效，误用 @Link 接收非状态变量则会编译报错。选择时记住一句话：「只展示用 Prop，要回写用 Link」，可覆盖九成以上的组件通信需求，剩余边缘场景再考虑 @ObjectLink。
5.6 @Provide / @Consume 的跨层机制
@Provide 在祖先组件注册一个带名字的可观察状态，@Consume 在任意后代中以同名消费。框架内部维护一条「提供链」，后代无需逐级 props 透传即可订阅。该机制特别适合主题、登录用户、购物车这类全局或准全局状态，显著降低组件耦合，是大型应用中避免「prop drilling」的首选方案。与事件上抛相比，它更轻量、更不易遗漏，但也更适合「读多写少」的共享状态；若写操作频繁且需副作用，仍建议配合回调或 @Watch 统一处理，做到能力与分析清晰。
5.7 更新批处理与时序
一次用户操作可能连续触发多个状态变更（如改数量同时改选中态）。ArkUI 不会每次赋值都立即重绘，而是把同一渲染周期内的变更合并，最后统一做脏检查与差分提交。这让「连续改多个状态」与「改一个状态」的性能开销接近，开发者无需手动 batch，可以把代码写得自然而不必过度优化，把精力放在真正影响帧率的热路径上，做到好钢用在刀刃上。
5.8 订阅的注册与注销
组件创建时，框架为其读取的状态注册订阅；组件销毁（如从 List 移除、页面跳转）时，相关订阅被自动清理，避免悬空引用与内存泄漏。这也是 ArkUI 相对手写监听更安全的体现：你不必手动 unsubscribe。但需注意，若把状态提升到过长的生命周期（如 AppStorage），要警惕其订阅范围过广带来的无关刷新，平衡好共享与性能，避免「为了省事把什么都丢进全局」的反模式。
5.9 与主流框架的理念对照
ArkUI 的装饰器体系与 React 的 useState/useContext、Vue 的 ref/provide-inject 思路相通：@State 近似 useState，@Prop 近似 props，@Link 近似受控/v-model，@Provide/@Consume 近似 Context/provide。不同在于 ArkUI 在编译期织入依赖追踪，粒度到组件级最小更新，无需手写依赖数组。理解这种映射，能帮前端开发者快速建立心智模型，把既有经验平移到鸿蒙，也便于跨端团队统一状态管理语言，降低协作摩擦，让成熟的前端思想在鸿蒙落地。
5.10 常见误区与原理对应
误区一：「状态变了 UI 不动」→ 多为引用未变（见 5.4）。误区二：「改一个值整页闪」→ 多为状态提升过高或组件粒度过大（见 4.10）。误区三：「@Prop 回写不生效」→ @Prop 是单向拷贝，需用 @Link。把现象映射到原理，多数问题都能快速定位，而不必在论坛里盲目发帖求助，把调试时间从小时级降到分钟级，显著提升交付效率与信心。
六、常见问题解答
Q1：@State 修饰的数组 push 后视图没更新？
A：直接 this.arr.push(x) 可能因引用未变而未被追踪。推荐用整体替换：this.arr = [...this.arr, x]，或配合 ForEach 的 key 使用可观察对象 @Observed 类。若必须原地修改，应先取出副本修改再整体赋值，确保触发可观察包装的 set。
Q2：@Prop 和 @Link 怎么选？
A：子组件只展示、不改父数据用 @Prop；子组件需要回写并同步父数据用 @Link。@Link 必须绑定父组件的 @State/@Link/@StorageLink 变量，且类型需严格一致，否则编译报错。牢记「展示用 Prop，回写用 Link」，可覆盖绝大多数通信需求。
Q3：@Provide/@Consume 必须同名吗？
A：是的，二者通过变量名（或别名）配对。@Consume 变量名需与祖先 @Provide 完全一致才能正确订阅，否则取到的是默认值而非实时状态，调试时容易误判为「框架 bug」，务必先核对变量名，再排查其他可能。
Q4：为什么推荐 ForEach 而非普通循环？
A：ForEach 提供 key 映射，能复用节点实现最小更新；普通循环无法建立稳定映射，易触发全量重建，列表长时性能差，且重排会错乱状态。大数据集应进一步使用 LazyForEach + DataChangeListener 做按需加载，把内存占用从 O(n) 降到视口附近常数级。
Q5：@Builder 和普通函数有何不同？
A：@Builder 标记的函数内可直接使用 ArkUI 组件语法并被多处复用，且能访问组件作用域；普通函数不能返回 UI 描述，因此构建可复用 UI 片段必须用 @Builder，否则编译器会报类型错误，无法作为组件树的一部分参与渲染与状态依赖追踪。
Q6：@ObjectLink 何时用？
A：当状态是 class 实例且需观察其「内部属性」变化时，用 @Observed 装饰类、@ObjectLink 装饰子组件字段，才能追踪嵌套属性变更，弥补 @State 仅追踪顶层赋值的不足，适合复杂领域模型与深层字段联动的场景，是精细刷新的关键手段。
Q7：@Builder 能传组件作为参数吗？
A：可以。@Builder 支持用 @BuilderParam 接收另一个构建函数作为参数，实现「插槽」式复用，例如把卡片头部作为 header 构建函数传入，让同一卡片适配不同业务，是比硬编码更灵活的复用方式，也让组件骨架与差异内容解耦。
Q8：组件很多时性能会下降吗？
A：不会显著下降。ArkUI 按组件粒度做脏检查与最小更新，未被标记脏的组件不重渲染。只要避免在大列表里滥用全局状态、保证 key 稳定，千级组件也能保持流畅；超长列表再配合 LazyForEach 即可应对，性能与组件数量没有线性关系。
Q9：@Watch 有什么用，和依赖追踪是什么关系？
A：@Watch 用于监听某个被装饰状态的变化并触发副作用（如埋点、持久化），它建立在框架已有的依赖追踪之上，是对「状态变更」的主动响应。注意副作用应放在 @Watch 或事件回调里，而不是 build 中，避免每次重渲染都重复执行，保持状态逻辑纯净可测，也让可观测性能力随业务需要灵活接入。
Q10：状态更新会卡顿吗？
A：框架做了脏检查与差分更新，只刷新受影响节点。但要避免在大列表里放过多 @State、避免 build 中做重计算，派生数据（如总价）应在状态变化时计算而非每次 build 重算。必要时用 LazyForEach 懒加载，把内存与计算开销都压到最低，从而在高密度列表下依然保持顺滑的刷新体验。
七、运行效果
下面用字符画展示组件树与状态流向。左侧为组件层级，右侧为状态装饰器链路，箭头表示数据流方向。通过它可直观看到「状态写回 → 脏标记 → 自动刷新」的完整闭环，理解声明式是如何把刷新逻辑从开发者手里收归框架的。
运行时交互：点击选中框 → 卡片边框变蓝、汇总种类 +1；点击 + → 数量 +1、小计与顶部总件数同步 +1；点击 - → 数量不小于 1、总件数同步减少。全程无手动刷新调用，证明状态驱动生效，界面与数据始终保持一致。还可验证组合场景：先全选两件商品，再把开发板数量加到 5，观察总件数实时累加；随后取消一件选中，种类数与总件数立即回退但另一件数量不变——这证明 @Link 局部写回与 @Provide/@Consume 聚合刷新互不干扰，状态边界划分正确。
除基本交互外，还可验证组合场景以确认边界：先全选两件商品，再把开发板数量加到 5，观察总件数实时累加，小计同步变化；随后取消一件选中，种类数与总件数立即回退但另一件数量不变——这证明 @Link 局部写回与 @Provide/@Consume 聚合刷新互不干扰，状态边界划分正确。再尝试把某商品数量减到 1 后继续点减，验证下限保护生效、不出现负数。此类组合交互是检验声明式正确性的有效手段，建议在提测前作为手动用例固化下来，确保每一次状态流转都可被观测、可被自动化测试覆盖，把体验优势转化为可验证的质量基线。
八、扩展方向
其一，引入 AppStorage/LocalStorage 实现跨页面全局状态持久化，让购物车在多页面间共享；其二，对大列表使用 LazyForEach 加 DataChangeListener 做按需加载与回收，提升超长列表性能；其三，用 @Watch 监听状态变化执行副作用（如埋点、校验），把业务逻辑与视图解耦；其四，将 CartSummary 计算逻辑抽为纯函数便于单元测试，提升代码可信度；其五，结合 Navigation 与路由参数做页面间状态传递；其六，用 PersistentStorage 把购物车落盘，重启后自动恢复。
此外，可引入轻量状态管理库统一管理多页面共享态；或结合 Worker 把重计算移出 UI 线程，保持刷新顺滑。无论走哪条扩展路径，核心都是「状态单一可信源 + 装饰器驱动 UI」这一范式，切勿退回命令式手动刷新。掌握本文范式后，这些扩展都只是水到渠成的自然演进，而非推倒重来，能让声明式的优势在团队内持续复用、不断演进。
此外，可引入轻量状态管理库统一管理多页面共享态；或结合 Worker 把重计算移出 UI 线程，保持刷新顺滑。无论走哪条扩展路径，核心都是「状态单一可信源 + 装饰器驱动 UI」这一范式，切勿退回命令式手动刷新。掌握本文范式后，这些扩展都只是水到渠成的自然演进，而非推倒重来。把声明式的优势在团队内持续复用、不断演进，才是工程化的最终目标，也是本文学以致用的真正落脚点，值得在新项目中一以贯之。
转载自 CSDN-专业IT技术社区
原文链接：https://blog.csdn.net/2502_92709686/article/details/162796775
