企业官网建设流程全解析

做鸿蒙应用列表优化的时候，我踩过最深的坑就是：滚动一快，页面就开始卡。尤其是那种数据列表、信息流、商品卡片混排的页面，上下滑动稍微频繁一点，帧率直接往下掉，用户体验一下子就拉垮了。后来我把项目从手动创建子组件改成复用组件，核心就靠@Reusable装饰器加上reuseId这个属性，列表的流畅度才真正稳住。

这篇文章我就围绕reuseId展开，把它背后那套“复用池”机制、接入步骤、容易翻车的地方一次性讲透。适合正好在做 HarmonyOS 应用、被长列表卡顿困扰的开发同学。不管你是新手还是已经在用 LazyForEach 的老手，只要列表里渲染的是自定义组件，这篇文章就能帮你省下不少排查性能问题的时间。

1. 组件复用机制：先把卡顿的根源讲清楚

1.1 列表滚动卡顿到底卡在哪

很多同学一提到列表优化，第一反应是“图片缓存”“减少渲染节点”，但真正让列表在滚动时掉帧的元凶，往往是组件对象的频繁创建和销毁。

想想看，List组件配合LazyForEach使用时，本质上是一个“按需渲染”的机制：滚到哪，渲染到哪；划出屏幕，组件就销毁。听起来很省内存对吧？但问题在于，滚动是一个高频操作，每秒钟可能有十几个组件被创建、十几个组件被销毁。每一次创建组件都要走一遍构造、初始化、布局、绘制流程，高频重复这种操作，主线程根本忙不过来。

我见过不少项目，列表项里面塞了图片、文本、按钮、进度条、甚至视频播放器，一个卡片的组件树几十个节点起步。每滚动一小段距离，这些节点全部推倒重来，卡顿几乎是必然的。

这里要强调一下，LazyForEach本身解决的是“只渲染可见区域”的问题，它并不负责“组件复用”。如果你在子组件里打了日志，会看到屏幕外的组件确实被销毁了，滑回来又重新创建，日志哗哗地刷。这个行为就是性能瓶颈所在。

1.2 复用与缓存的本质区别

很多人在做列表优化的时候，会先想到“缓存数据”“缓存图片”，但组件复用和这些是完全不同层面的事情。

数据缓存解决的是“网络请求慢、I/O 重复读”的问题，而组件复用解决的是“UI 对象重复创建”的问题。你可以把数据缓存理解成“把菜提前做好放冰箱”，组件复用则是“连锅碗瓢盆都留在厨房里，下一道菜直接换食材下锅”。

在 ArkUI 的机制里，@Reusable标记的组件在滑出屏幕时不会马上销毁，而是被丢进一个“复用池”；等它再次需要出现在屏幕内时，框架直接从池里捞出来，用新数据把旧内容“洗一遍”再展示。这样一来，省掉了组件构造、布局计算里最耗时的那部分过程，滚动自然就顺了。

reuseId在这个机制里的角色，就是给复用池做“分区”的标签。同一个池子里的组件才能互相复用，不同reuseId的组件保持独立，各归各的池子。这个概念后面会详细展开，你现在只需要记住一句话：reuseId决定了组件从哪里取、往哪里还。

1.3 什么时候该用组件复用，什么时候别硬上

组件复用不是银弹，我见过有同学在页面只有五六个组件的场景里强行加@Reusable，结果代码复杂了，收益却几乎为零。按照我的经验，出现以下情况才真正需要考虑复用：

• 列表数据量超过一屏，且单条数据渲染的组件层级较深。
• 滚动时能明显感知掉帧，或者用性能工具看到帧率曲线出现“深坑”。
• 列表项内部有图片加载、复杂布局、条件渲染等耗时操作。
• 用户在列表上的操作是高频的，比如快速滑动、反复进出页面。

反过来，如果列表很短、数据量很小、页面本身就不怎么滚动，那你加了复用反而要处理“状态残留”“数据重置”这些问题，属于给自己找事。先判断痛点是否真实存在，再决定要不要动刀。

2. reuseId 的核心用法与设计细节

2.1 三步接入：从零到一加上复用能力

把一个普通列表项改成可复用组件，流程非常固定，总结下来就是三步。

第一步，在子组件上加上@Reusable装饰器。这个装饰器是复用能力的总开关，不加它，下面所有操作都不会生效。写法很简单：

@Reusable @Component export struct FeedCard { @Prop title: string; @Prop cover: string; aboutToReuse(params: Record<string, Object>) { this.title = params.title as string; this.cover = params.cover as string; } }

第二步，在列表渲染的时候，给组件实例设置reuseId。这个属性用来标记当前组件属于哪一个复用池：

LazyForEach(this.dataSource, (item: FeedItem) => { FeedCard({ title: item.title, cover: item.cover }) .reuseId('feed_card') }, (item: FeedItem) => item.id)

第三步，在组件里实现aboutToReuse回调。这个回调会在组件从复用池里被拿出来、重新放到屏幕上的时候触发。你要在这里把组件里的所有数据替换成新数据。

这样三步走完，复用就已经生效了。这里面最容易漏的其实是第三步，因为很多组件在可见时依赖父组件传参更新状态，但复用的组件不会重新走构造函数，它拿到的还是上一次的数据，必须靠aboutToReuse手动刷新。

2.2 reuseId 的命名与生成规则

reuseId本质上就是一个字符串标识，但它并不是随便写写就完事的。命名规则直接影响到复用的命中率和内存布局。

最推荐的用法是“按组件的视觉样式和结构类型来命名”，而不是“按数据内容来命名”。比如你的信息流里有三种卡片：纯文本卡片、图文卡片、视频卡片，那reuseId就应该是text_card、image_card、video_card，而不是card_1、card_2、card_3。

这里有一个非常重要的点：reuseId相同，意味着 ArkUI 认为这些组件“长一个样”，可以互相替换。如果你把结构差异很大的两种组件塞进同一个reuseId，那么在aboutToReuse里就得做大量的状态重置，甚至需要手写分支逻辑去隐藏、显示不同的子树，代码会变得非常难维护。

还有一种常见误区是把reuseId拼上数据的唯一标识，比如：

.reuseId('feed_card_' + item.id)

这样写的话，每个 item 都有自己的独立池子，组件根本不可能互相复用，相当于给每个数据项都开了一个专属缓存，复用池的意义完全丧失。要记住，reuseId描述的是“哪一类组件”，而不是“哪一个组件”。

2.3 复杂场景：同容器多种复用类型怎么设计

实际项目里，列表往往不是单一卡片的简单重复，而是多种卡片混合排列。有的同学会问：这种情况下该怎么设置reuseId？是一个列表统一用一个，还是每种卡片各用一个？

答案是各用各的。reuseId的设计初衷就是支持同一个LazyForEach里混排多种组件类型。举一个我经手过的项目例子：首页信息流里有三种卡片，数据源通过type字段区分。最常见的错误写法是把它们都塞进同一个组件里，然后靠if分支渲染不同内容：

LazyForEach(this.dataSource, (item: FeedItem) => { CommonCard({ item: item }) .reuseId('common_card') }, (item: FeedItem) => item.id)

这样做不是不行，但CommonCard内部会同时持有三套卡片的 UI 节点，每次复用都要走大量条件判断，状态重置逻辑也变得复杂。更优雅的做法是拆成三个独立组件，分别用不同的reuseId：

LazyForEach(this.dataSource, (item: FeedItem) => { if (item.type === 'text') { TextCard({ item: item }).reuseId('text_card') } else if (item.type === 'image') { ImageCard({ item: item }).reuseId('image_card') } else { VideoCard({ item: item }).reuseId('video_card') } }, (item: FeedItem) => item.id)

这样每个组件只维护自己那一套状态，复用池各自独立，互不干扰。从性能角度讲，组件内部节点越少，复用时需要重置的状态越少，效率就越高。

2.4 生命周期回调：什么时机该做什么事

可复用组件比普通组件多了两个生命周期回调：aboutToReuse和aboutToRecycle。这两个回调是复用时最核心的“交接仪式”。

aboutToReuse前面已经介绍过，它接收一个Record<string, Object>类型的参数。这个参数是你在.reuseId()之外通过.reuseId()的兄弟方法传进来的吗？不是。实际上，aboutToReuse的params参数来源于父组件的reuseId配置之外，ArkUI 会在复用时把当时创建组件时传入的参数打包好再传进来。

举个例子，你在列表里这样写：

FeedCard({ title: item.title, cover: item.cover }) .reuseId('feed_card')

当组件被复用时，框架会把title和cover的当前值通过params传进aboutToReuse。所以你在aboutToReuse里要做的事，就是把老数据全部覆盖成新数据。

aboutToRecycle则是在组件被回收进复用池之前触发。这个回调适合做一些释放性操作，比如取消网络请求、清空图片加载、暂停视频播放、释放定时器等。

我在实践中特别推荐一个习惯：进入aboutToRecycle时把组件的状态“恢复出厂设置”，也就是说让组件回到一个默认的初始状态。这样即使aboutToReuse漏掉了某个字段，组件显示出来的也只是空白或默认内容，而不是上一个 Item 的残留数据。

3. 实操过程：从普通列表到可复用列表

3.1 初始代码与性能问题表现

我先展示一下大多数项目里最初的写法，你看一眼就知道为什么卡。

数据源用LazyForEach管理，子组件FeedCard是一个普通的@Component：

@Component export struct FeedCard { @Prop title: string; @Prop cover: string; @Prop author: string; build() { Column({ space: 8 }) { Text(this.author) .fontSize(14) .fontColor('#999999') Text(this.title) .fontSize(18) .fontWeight(FontWeight.Bold) Image(this.cover) .width('100%') .height(200) .objectFit(ImageFit.Cover) } .padding(16) .backgroundColor(Color.White) .borderRadius(12) } }

这个组件本身没有问题，问题出在它没有被复用。我在真机上跑了一个 500 条数据的列表，每张卡片高度大约 220vp，使用性能工具抓帧率曲线，快速滚动时能看到明显的掉帧，部分时段帧率掉到 40 帧以下。

为了确认问题来源，我在FeedCard的构造函数里加了日志：

aboutToAppear() { console.info('FeedCard created'); }

快速滑动列表，日志刷屏速度非常快，说明组件在不断地被创建和销毁。这就是卡顿的直接证据。

3.2 改造步骤与完整示例

改造过程并不复杂，按前面说的三步来。

先给FeedCard加上@Reusable，并实现aboutToReuse：

@Reusable @Component export struct FeedCard { @Prop title: string; @Prop cover: string; @Prop author: string; aboutToReuse(params: Record<string, Object>) { this.title = params.title as string; this.cover = params.cover as string; this.author = params.author as string; } build() { Column({ space: 8 }) { Text(this.author) .fontSize(14) .fontColor('#999999') Text(this.title) .fontSize(18) .fontWeight(FontWeight.Bold) Image(this.cover) .width('100%') .height(200) .objectFit(ImageFit.Cover) } .padding(16) .backgroundColor(Color.White) .borderRadius(12) } }

然后在列表页面里，给组件设置reuseId：

LazyForEach(this.dataSource, (item: FeedItem) => { FeedCard({ title: item.title, cover: item.cover, author: item.author }) .reuseId('feed_card') }, (item: FeedItem) => item.id)

这里补充一个细节：如果FeedCard内部有@State类型的本地状态，在aboutToReuse里也必须手动重置。比如卡片内部有一个“点赞状态”，复用后的新数据可能是未点赞状态，但组件从复用池里拿出来时还保留着上次的已点赞状态，不重置就会显示错误。

3.3 状态重置：最容易翻车的环节

用组件复用之后，我遇到的第一个大坑就是“脏数据”。

表现非常典型：滑到第 10 条数据，显示的却是第 3 条数据的作者头像；或者图片区域闪了一下旧图，然后才变成新图。这些问题的根源，都是复用时没有把组件的所有状态重置干净。

这里我总结了一套自查清单，每次写完复用组件都会过一遍：

• @Prop、@State、@Link等所有响应式属性是否都在aboutToReuse里重新赋值。
• 内部通过if控制显隐的节点，是否可能因为旧状态而显示出来。比如某张卡片有“VIP 标识”，复用它时旧数据是 VIP，新数据不是，if分支是没办法自动感知参数变化的，必须在aboutToReuse里先把 VIP 标识状态置为 false。
• 子组件的构造函数参数变化时，是否依赖@Prop的自动同步。复用的组件不会再走构造函数，所以这种自动同步不会发生，必须手动赋值。
• 图片这种异步加载资源，是否会出现旧图闪烁。我的习惯是在aboutToReuse里先把图片地址置为空字符串或占位图，再赋新值，视觉上不会闪旧图。
• 是否注册了事件监听、定时器、动画播放。这些要在aboutToRecycle里统一清理，避免复用时还带着上一次的监听状态。

这几个点只要有一个没处理干净，界面上就会出现难以察觉但真实存在的显示错乱。

3.4 结合 cachedCount 让复用更顺畅

组件复用的另一个好搭档是cachedCount。这个属性控制的是列表前后额外缓存的组件数量。默认情况下，列表只渲染可视区域，加上cachedCount之后，可视区域外会多预留一些组件，滑过来的时候就不用临时创建了。

它们的关系可以这样理解：cachedCount负责“提前准备”，reuseId负责“加速切换”。

我通常会在列表组件上这样设置：

List({ space: 12 }) { LazyForEach(this.dataSource, (item: FeedItem) => { FeedCard({ ... }) .reuseId('feed_card') }, (item: FeedItem) => item.id) } .cachedCount(5)

这个 5 不是固定的，需要根据卡片高度和列表高度来调。卡片越高，一屏能容纳的数量越少，cachedCount就可以相对设小；卡片越矮，预留多一些。

但注意，cachedCount不是越大越好。设得太大会增加内存占用，尤其卡片内部有图片时，额外缓存的组件会持有图片资源，内存压力会明显上升。一般从 3 到 8 之间来回调，找到体感和内存的平衡点。

4. 常见问题与排查技巧实录

4.1 复用后 UI 显示脏数据

前面提到过，脏数据是复用最典型的问题。但具体到排查，我建议先打日志确认组件是不是真的被复用了。在aboutToReuse里打一行日志，看看滑回可见区域时日志是否触发。

如果触发了但 UI 还是不对，基本可以断定是重置不完整。我的排查思路是“从外到内”：先看组件根节点绑定的数据对不对，再看内部各个子节点对应的状态有没有更新到位，最后看图片、视频这类异步资源是不是没有重置。

这里有一个效率很高的排查技巧：把所有@State和@Prop变量在aboutToReuse里全部打印出来，然后手动对比滑入的这条数据和 UI 展示的数据。如果数据对不上，就是参数传错了；如果数据对得上而 UI 不对，那就是某个if分支没有被正确触发，需要手动把分支条件的状态重置掉。

4.2 复用没生效，怎么验证

加了@Reusable和reuseId之后，性能没有明显提升，先别急着怀疑方案，大概率是你没验证到自己预期的东西。

验证复用以否，最可靠的方法是在aboutToReuse和构造方法里各打一条日志：

aboutToAppear() { console.info('FeedCard created'); } aboutToReuse(params: Record<string, Object>) { console.info('FeedCard reused'); }

快速滑动列表，如果日志里created出现的频率明显降低，而reused持续出现，说明复用已经生效了。如果created还是很频繁，说明复用池没有命中，这时候检查两个地方：

一是@Reusable装饰器是否在目标组件上。很多人会顺手加到父组件上，那就完全没作用。

二是reuseId是否设置在组件实例上。reuseId是组件属性，要跟随LazyForEach里的组件实例写，漏掉它，ArkUI 就把组件当普通组件处理，该销毁销毁、该创建创建，复用池根本进不去。

还有一个容易被忽略的原因：LazyForEach的 key 生成器不稳定。key 必须保证唯一且稳定，如果每次生成 key 的逻辑都变，比如用了Math.random()，那列表会认为数据一直在变化，反复触发创建，复用也无从谈起。

4.3 嵌套滚动与复用冲突

如果你的列表项内部还嵌了可滚动组件，比如卡内有横向滑动条，那情况会更复杂一点。

我碰到过一个真实案例：列表卡片里套了一个横向滚动的Scroll，加完复用之后，横向滚动条经常出现在组件时就已经被滚动到了中间位置。原因是组件被回收进复用池时，Scroll的偏移量没有被重置。

解决方案是在aboutToRecycle里把Scroll的偏移量归零，或者给Scroll加一个受控的偏移参数，在aboutToReuse时赋值。

这里我的建议是，列表项内部尽量不要嵌套滚动组件。嵌套滚动手势冲突、状态重置、事件分发都要额外处理，性能收益会被复杂度和隐患抵消掉。如果确实需要横向滑动，优先考虑Swiper或者通过offset位移实现，而不是嵌套一层Scroll。

4.4 内存与性能的平衡：复用池不是越大越好

看到这里，有的同学可能会想：既然复用这么好，那我干脆把所有列表项都做成可复用组件，把cachedCount调到最大，是不是就能彻底告别卡顿？

实际操作下来，不是这样的。

复用池本身会占用内存，池子里每个组件都持有着自己的 UI 节点树和资源引用。如果你一个页面里有太多种类的reuseId，每个类型的池子都保留几个组件，加起来内存占用就不小了。图片组件尤其明显，一张高清图可能几 MB 内存，复用池里多存几个，内存直接告急。

我一般会把同屏可见的卡片类型控制在 3 到 4 种以内。如果业务上确实有七八种卡片，优先考虑把结构相近的合并成一个组件，内部用少量if分支处理差异，而不是重新定义一种reuseId。

另外，aboutToRecycle里释放图片资源也很重要。我通常在组件回收时把Image的src置为空，这样图片对象能够被及时回收，而不是一直挂在复用池里占用内存。这个操作会影响一点点复用时的刷新速度，但比起内存暴涨的风险，完全值得。

4.5 踩坑后的通用排查表

最后给你整理一份排查表，遇到问题直接对着查，很多时候能省下一两个小时。

你在项目里遇到的大部分复用问题，基本都能从这张表里找到答案。如果症状不在表里，建议先把组件里所有的日志都打开，从aboutToRecycle开始跟踪整个生命周期，看看哪个环节的状态和你预期不一致，问题就能定位出来。

说回reuseId本身，它不是一个需要花里胡哨设计的 API，反而是越朴素越好用。关键就三条：按类型分类、保证状态重置完整、控制复用池数量。把这三点做扎实，你会明显感觉到列表滚动时那种“跟手”的顺滑感。我自己在几个项目里反复使用的体会是，组件复用的收益不仅仅是帧率的提升，更重要的是它逼着你把组件之间的数据边界梳理清楚，写出来的代码反而更规范了。