一、前置思考

企业级鸿蒙应用的UI开发，迟早会碰到一个分水岭：当业务模块超过20个，复用最多的不是页面而是组件。按钮变体、输入框样式、卡片布局、弹窗交互——如果每个开发者在不同页面中重新写一遍Row/Column/Text组合，维护成本呈指数级增长。

传统的原生开发（Android View、iOS UIKit）解决这个问题的方案是自定义View/UIView子类化。但在声明式UI框架（ArkUI）中不存在"子类化UI组件"的概念，取而代之的是**@ComponentV2 + @Builder/@BuilderParam + 属性透传 + 自定义Modifier**的组件化体系。

这篇博客聚焦以下高阶问题：

• 如何封装一个可被任意页面复用、可传参、可组合的企业级组件库？
• 属性透传（attribute pass-through）在ArkUI中有哪些隐藏陷阱？
• @BuilderParam 插槽机制如何实现"骨架固定 + 内容自定义"？
• FreezeWhenInActive 和生命周期精准管控在复杂组件中的作用？

二、核心原理

2.1 ArkUI组件化模型

ArkUI的组件化不是基于类继承，而是基于组合 + 声明：

┌────────────────────────────────────┐
│        @Entry Page                 │
│  ┌──────────────────────────────┐  │
│  │   @ComponentV2 CardComponent  │  │
│  │  ┌─────────────────────────┐  │  │
│  │  │ @BuilderParam slot      │  │  │
│  │  │  (注入内容)              │  │  │
│  │  └─────────────────────────┘  │  │
│  │  @Param title                 │  │
│  │  @Param icon                  │  │
│  └──────────────────────────────┘  │
└────────────────────────────────────┘

• @ComponentV2：声明可复用组件，拥有独立的@Local状态
• @Param：接受父组件传入的参数（单向或双向）
• @BuilderParam：接受父组件注入的UI片段（插槽）
• @Event：子组件向父组件传递事件

2.2 属性透传机制

属性透传是指将父组件设置的属性自动传递给子组件内部的根节点。ArkUI中仅部分内置组件支持属性透传（如Button的.onClick会透传给内部的Text），但自定义@ComponentV2需要手动透传。

核心手段：

• @Param 接收属性值 → 手动绑定到子节点
• 自定义Modifier（attributeModifier）统一管理样式
• 通过接口约束组件的可配置项

2.3 @BuilderParam 插槽设计

@BuilderParam 是ArkUI实现"骨架+内容分离"的核心机制：

@ComponentV2
struct Card {
  @Param title: string = '';
  @BuilderParam content: () => void = this.defaultContent; // 默认内容

  @Builder
  defaultContent() {
    Text('默认内容')
  }

  build() {
    Column() {
      Text(this.title)
      this.content()  // 注入的UI片段在此渲染
    }
  }
}

// 使用方：
Card({ title: '标题' }) {
  Text('自定义内容') // → 注入到 @BuilderParam content
}

2.4 生命周期精准管控

V2组件的关键生命周期：

钩子	触发时机	适用场景
aboutToAppear	组件即将挂载	初始化数据、请求网络
aboutToDisappear	组件即将卸载	取消订阅、释放Timer
onDidBuild	首次build完成	获取组件尺寸、执行入场动画
aboutToReuse	复用池取出	重置@Local状态
FreezeWhenInActive	组件冻结/解冻	减少非可见组件开销

三、源码/API深度解析

3.1 @ComponentV2关键API

@ComponentV2
struct MyComponent {
  @Local privateState: number = 0;        // 组件内部状态
  @Param @Once title: string = '';        // 仅首次接收
  @Param title: string = '';              // 持续同步（默认）
  @Event onAction: () => void = () => {}; // 事件回调
  @Provider('theme') theme: string = '';  // 跨层级提供
  @Consumer('theme') themeColor: string = ''; // 跨层级消费
  @BuilderParam content: () => void = this.emptyContent;
  @Computed get computed() { ... }        // 计算属性
}

3.2 自定义Modifier

ArkUI提供了attributeModifier用于批量管理样式：

class CardStyle implements AttributeModifier<ColumnAttribute> {
  applyNormalAttribute(instance: ColumnAttribute): void {
    instance.backgroundColor('#1E1E2E')
      .borderRadius(12)
      .padding(16)
      .margin({ bottom: 8 });
  }
}

// 使用：
Column().attributeModifier(new CardStyle())

3.3 FreezeWhenInActive冻结优化

在LazyForEach列表场景中，对非可见item设置FreezeWhenInActive(true)可显著减少内存和CPU开销：

@ComponentV2
struct ListItemCard {
  @Param item: DataItem = new DataItem();
  @Local frozen: boolean = true;

  build() {
    FreezeWhenInActive({ isFrozen: this.frozen }) {
      Column() {
        // 复杂UI
      }
    }
  }
}

四、企业级实战落地

本Demo实现以下核心场景：

组件	演示能力	备注
SmartCard	@Param属性透传 + @BuilderParam插槽	多态卡片骨架
GradientButton	自定义Modifier + @Event回调	5种预设样式
ProgressRing	Canvas自定义绘制 + @Computed	环形进度条
FormGroup	组合组件 + 属性透传链	表单组
LazyListCard	FreezeWhenInActive冻结	长列表性能

使用方式：

• 左侧切换Tab查看不同组件
• 每个组件展示完整的接口定义、使用示例和渲染效果

五、问题排查与性能优化

坑点	现象	根因	解决
属性透传丢失	父组件设置的fontSize子组件不生效	@ComponentV2不像内置组件有隐式透传	显式声明@Param接收
@BuilderParam不更新	父组件状态变但插槽内容不变	@BuilderParam默认仅首次渲染	检查是否缺少尾随闭包
自定义Modifier不响应	修改样式类属性后UI不刷新	Modifier不是@ObservedV2	改用@Local + 直接绑定
FreezeWhenInActive导致数据丢失	解冻后@Local被重置	V2生命周期未正确处理	在aboutToReuse中恢复状态

六、高阶总结与最佳实践

• 接口优先：先用interface定义组件的配置项，再实现，保证调用方类型安全
• 插槽设计：一个组件最多3个@BuilderParam（header/content/footer），避免过度设计
• 属性透传链长度≤3：超过3层透传就应使用@Provider/@Consumer
• Modifier vs @Param：样式类属性（颜色/尺寸）用自定义Modifier；业务数据用@Param
• 冻结策略：列表类组件优先使用FreezeWhenInActive；非列表场景不必
• 生命周期：aboutToDisappear中必须取消所有Timer/订阅，否则内存泄漏

---

对应Demo文件：entry/src/main/ets/pages/ComponentLibraryDemo.ets
可在首页点击「组件库 Demo」入口进入查看完整可运行代码。