HarmonyOS6 组件复用 reuseId 官方使用文档

Ne0inhk

— 5 min read
HarmonyOS6 组件复用 reuseId 官方使用文档

文章目录

本文档基于 HarmonyOS 官方 reuseId 通用属性规范编写，配套可直接运行、无语法报错的完整示例，适用于 API 12+ 稳定版 DevEco Studio，严格遵循 ArkTS 语法检查规则。

reuseId 是 HarmonyOS ArkUI 提供的组件复用标识通用属性，用于为 @Reusable 可复用组件设置唯一复用ID。
系统会根据 reuseId 匹配组件实例：相同ID直接复用缓存实例，不同ID则重建实例，大幅减少组件创建/销毁开销，提升页面渲染性能与流畅度。

配合组件复用生命周期 aboutToReuse，可实现复用时的数据更新，是长列表、动态组件切换、频繁显隐组件场景的核心性能优化方案。

一、核心 API 定义

1. reuseId 通用属性

reuseId(id:string):T
  • 作用：为可复用组件绑定唯一复用标识，控制实例复用逻辑
  • 参数：id - 字符串类型，自定义唯一标识
  • 返回值：组件自身实例，支持链式调用

2. 核心装饰器

@Reusable：标记组件为可复用组件，使用 reuseId 的必备前提。

3. 组件复用生命周期

  1. aboutToAppear()
    组件首次创建、即将显示时触发，仅执行一次。
  2. aboutToReuse(params: Record<string, Object>)
    组件被复用时触发，用于接收参数并更新组件状态。
    • 参数类型：Record<string, Object>（ArkTS 官方强制类型）
    • 作用：复用实例时更新数据，替代重建逻辑

二、核心使用规则

  1. 仅支持 @Reusable 组件：系统组件无法使用 reuseId。
  2. ID 匹配规则：相同 reuseId → 复用实例；不同 reuseId → 重建实例。
  3. 组件缓存机制：组件隐藏后实例会被系统缓存，再次显示且ID匹配时直接复用。
  4. 数据更新：复用时必须在 aboutToReuse 中完成数据更新。
  5. 类型规范：aboutToReuse 参数必须使用 Record<string, Object>，符合 ArkTS 严格语法。

三、完整可运行示例代码

// xxx.ets@Entry@Component struct ReuseIdFullDemo {@State isShow:boolean=true;@State currentTypeId:string='type_1';build(){Column({ space:20}){Text("组件复用 reuseId 完整示例").fontSize(22).fontWeight(FontWeight.Bold).margin({ top:30});Button("显示/隐藏组件").onClick(()=>{this.isShow =!this.isShow;}).width(260);Button("切换复用ID: "+this.currentTypeId).onClick(()=>{this.currentTypeId =this.currentTypeId ==='type_1'?'type_2':'type_1';}).width(260);if(this.isShow){ReusableItem({ typeText:this.currentTypeId }).reuseId(this.currentTypeId)}}.width('100%').height('100%').justifyContent(FlexAlign.Start).padding(20).backgroundColor('#f8f8f8');}}// ==============================================// 可复用组件（完全符合官方类型定义）// ==============================================@Reusable@Component struct ReusableItem { typeText:string='';@State count:number=0;aboutToAppear(){console.info(`【组件创建】aboutToAppear -> type: ${this.typeText}`);}// 官方要求的固定类型：Record<string, Object>aboutToReuse(params: Record<string, Object>){// 安全取值，完全符合类型检查const newType = params.typeText asstring;console.info(`【组件复用】aboutToReuse -> 旧type: ${this.typeText}，新type: ${newType}`);// 更新数据this.typeText = newType;this.count++;}build(){Row(){Text(`当前类型：${this.typeText}`).fontSize(20).fontWeight(FontWeight.Medium);Text(`复用次数：${this.count}`).fontSize(18).margin({ left:20}).fontColor(Color.Blue);}.width('90%').height(60).backgroundColor('#ffffff').justifyContent(FlexAlign.Center).borderRadius(12).margin({ top:20});}}

运行效果如图：


点击按钮 显示/隐藏组件 如下图

四、示例执行流程与日志说明

1. 页面初始化

  • switch = true，渲染 ReusableItem 组件
  • reuseId = type_1，组件首次创建
  • 输出日志：【组件创建】aboutToAppear -> type: type_1

2. 点击「显示/隐藏组件」

  • 第一次点击：组件隐藏，实例被系统缓存
  • 第二次点击：组件重新显示，匹配缓存ID，直接复用实例
  • 输出日志：【组件复用】aboutToReuse -> 旧type: type_1，新type: type_1
  • 复用次数 +1

3. 点击「切换复用ID」

  • currentTypeId 切换为 type_2
  • reuseId 变更，组件销毁重建
  • 输出日志：【组件创建】aboutToAppear -> type: type_2

4. 再次切换回原ID

  • 匹配缓存的 type_1 实例，直接复用
  • 输出日志：【组件复用】aboutToReuse -> 旧type: type_2，新type: type_1

总结

reuseId 是 HarmonyOS 官方推荐的组件复用核心方案，通过唯一ID实现组件实例缓存与复用，配合 @Reusable 和 aboutToReuse 可大幅降低 UI 渲染开销。

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力！
Could not load content