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. 组件复用生命周期
- aboutToAppear()
组件首次创建、即将显示时触发，仅执行一次。 - aboutToReuse(params: Record<string, Object>)
组件被复用时触发，用于接收参数并更新组件状态。- 参数类型：
Record<string, Object>（ArkTS 官方强制类型） - 作用：复用实例时更新数据，替代重建逻辑
- 参数类型：
二、核心使用规则
- 仅支持 @Reusable 组件：系统组件无法使用 reuseId。
- ID 匹配规则：相同
reuseId→ 复用实例；不同reuseId→ 重建实例。 - 组件缓存机制：组件隐藏后实例会被系统缓存，再次显示且ID匹配时直接复用。
- 数据更新：复用时必须在
aboutToReuse中完成数据更新。 - 类型规范：
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_2reuseId变更，组件销毁重建- 输出日志：
【组件创建】aboutToAppear -> type: type_2
4. 再次切换回原ID
- 匹配缓存的
type_1实例，直接复用 - 输出日志：
【组件复用】aboutToReuse -> 旧type: type_2，新type: type_1
总结
reuseId 是 HarmonyOS 官方推荐的组件复用核心方案，通过唯一ID实现组件实例缓存与复用，配合 @Reusable 和 aboutToReuse 可大幅降低 UI 渲染开销。
如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力！
