鸿蒙开发笔记-6-装饰器之@Require装饰器，@Reusable装饰器

一、@Require装饰器：强制校验组件构造参数的完整性

基本概念

@Require是ArkTS的参数校验装饰器，用于强制父组件在构造子组件时必须传递指定参数。自API 11开始支持@Prop和@BuilderParam校验，API 12扩展至@State、@Provide和普通变量。

核心特性

• 编译时校验：未传参直接导致编译失败
• 版本兼容：支持元服务开发（API 11+）
• 类型覆盖：支持主流状态管理变量类型
• 默认值支持：可与初始化赋值结合使用

使用示例

@Entry
@Component
struct ParentPage {
  @State config: string = "default";

  build() {
    Column() {
      // 必须传递requiredParam参数
      ChildComponent({ requiredParam: this.config })
    }
  }
}

@Component
struct ChildComponent {
  @Require @Prop requiredParam: string = "fallback";
  
  build() {
    Text(this.requiredParam)
  }
}

典型应用场景

1. 表单组件必填项校验
2. 业务模块间强约束传参
3. 公共组件库开发规范
4. 跨团队协作接口约束

进阶技巧

• 组合校验 ：多个@Require变量联合校验

@Require @Prop userId: string;
@Require @State sessionToken: string;

• 动态参数：配合条件语句使用

build() {
  if(this.needAuth) {
    SecureComponent({ token: this.authToken })
  } else {
    PublicComponent()
  }
}

• 组合校验规则

@Require({
  regular_value: { type: String, defaultValue: 'Hello' },
  state_value: { type: Number, min: 0 }
})
struct ComplexComponent {}

二、@Reusable装饰器：实现组件实例的复用机制以提升性能

设计理念

通过组件实例复用机制减少内存开销，适用于：

• 高频创建/销毁的列表项
• 动态布局的频繁更新
• 大数据量渲染场景

核心机制

• 性能优化：减少DOM节点重建，提升列表/滚动场景性能
• 内存管理：自动缓存组件实例及关联JSView
• 复用策略 ：通过aboutToReuse生命周期回调更新状态
• 缓存池: 维护LRU缓存（默认容量10）
• 缓复用粒度: 组件级复用（含子组件树）

基础用法

// 基础复用组件
@Reusable
@Component
struct CardView {
  @State item: string;

  aboutToReuse(params: { item: string }) {
    this.item = params.item;
  }

  build() {
    Column([Text(this.item)])
      .width('100%')
      .height(100)
  }
}

// 父组件中使用
build() {
  List({
    data: dataSource,
    renderItem: (item) => CardView({ item })
  })
}

性能优化实践

场景1：长列表优化

LazyForEach(dataSource, (item) => {
  ListItem() {
    NewsItem({ article: item })
      .reuseId(item.type)
  }
})

场景2：动态布局切换

@Reusable
@Component
struct AdaptiveLayout {
  @State layoutType: 'grid' | 'list' = 'list';

  aboutToReuse(params) {
    this.layoutType = params.type;
  }

  build() {
    if(this.layoutType === 'grid') {
      GridView()
    } else {
      ListView()
    }
  }
}

场景3：多类型复用（ReuseId）

// 根据图片类型复用不同组件
ListItem({
  moment: moment
})
.reuseId(moment.image ? 'imageCard' : 'textCard')

场景4： 缓存控制

// 设置最大缓存数量
List({
  cachedCount: 10, // 保留最近10个组件实例
  ...
})

场景5： 生命周期管理

@Reusable
@Component
struct ReusableComponent {
  aboutToAppear() {
    console.log('Component is created');
  }

  aboutToReuse(params) {
    console.log('Component is reused with:', params);
  }

  aboutToRecycle() {
    console.log('Component recycled:', this.itemId)
  }
}

三、典型应用场景

1. @Require实战：表单验证组件

@Component
struct FormComponent {
  @Require @Prop label: string;
  @Require @Prop placeholder: string;
  @State value: string;

  build() {
    Row([
      Text(this.label).fontSize(16),
      TextField(this.value)
        .placeholder(this.placeholder)
        .onChange((e) => this.value = e.value)
    ])
  }
}

2. @Reusable实战：万级列表优化方案

@Reusable
@Component
struct NewsItem {
  @State article: NewsData;

  aboutToReuse(params) {
    this.article = params.item;
    Logger.info('Reused:', this.article.id);
  }

  build() {
    Row() {
      Image(this.article.cover)
        .syncLoad(true)
      Text(this.article.title)
    }
  }
}

// 使用端
LazyForEach(dataSource, (item) => {
  ListItem() {
    NewsItem({ item })
      .reuseId(item.type + '_template')
  }
}, (item) => item.id)

• 性能优化数据对比

场景	常规渲染(ms)	复用渲染(ms)	提升幅度
千级列表初始化	1200	320	73%
动态布局切换	450	120	73%
内存占用峰值	82MB	47MB	43%

四、最佳实践指南

1. @Require使用原则

   • 优先在复杂组件中使用
   • 避免过度校验简单组件
   • @Require变量应配合TypeScript接口声明
   • 公共组件库必须使用@Require进行接口约束

2. @Reusable优化策略

   • 对高频创建组件优先使用@Reusable
   • 避免在复用组件内使用动态Builder
   • 合理设置cachedCount平衡内存与性能(建议5-20)
   • 复用组件的reuseId应包含数据类型标识
   • 避免在aboutToReuse中执行耗时操作
   • 复用组件避免直接修改@Link变量
   • 对复杂对象使用深拷贝更新状态
   • 建立组件复用率监控体系（建议>60%）

五、疑难解答

Q1：@Require导致过度传参怎么办？

// 解决方案：合理设计组件层级
@Component
struct SmartComponent {
  @Require @Prop essentialParam: string;
  @State localConfig: LocalConfig = new LocalConfig();
}

Q2：复用组件状态不同步？

aboutToReuse(params) {
  // 必须完整重置状态
  this.data = deepClone(params.data);
  this.resetUIState();
}

Q3：如何选择reuseId策略？

• 简单列表：自动生成
• 混合布局：类型_模板版本
• 差异项：${dataType}_${styleVersion}

六、总结

@Require和@Reusable分别从代码健壮性和运行效率两个维度提升了ArkTS应用的开发质量。在公共组件库中优先采用@Require，对核心页面实施@Reusable优化。 通过合理运用这两种装饰器，开发者可以构建出既稳定又高效的HarmonyOS应用，在复杂的业务场景中实现质量与性能的双重保障。

我是今阳，如果想要进阶和了解更多的干货，欢迎关注微信公众号 "今阳说" 接收我的最新文章