企业官网建设流程全解析

搞鸿蒙 NEXT 开发这段时间，最让我血压拉满的报错倒不是编译失败，而是运行时界面纹丝不动。明明数组里加了数据，LazyForEach 列表跟没看见一样；明明把某条记录删了，界面上那行字还稳稳待着；甚至有的 item 内容改了，UI 却还是老样子。网上搜“LazyForeach没有刷新”能翻出一堆帖子，但大多只给结论不给排查思路，新手照着抄也未必能解决自己那片代码的问题。

这篇文章我把 LazyForEach 不刷新的问题从头到尾拆一遍：先分类辩症状，再讲清通知链路和 keyGenerator 的配合逻辑，然后给出一条完整的定位排查链路，最后针对不同场景给出修复方案，顺带把 @Reusable 复用残留、@Observed 深层监听这类“假不刷新”的坑也一起处理掉。内容基于我在某智慧阅读项目里做书籍列表筛选、批量删除、备注编辑这几块功能的实战记录，代码用 ArkTS 写，版本基于 HarmonyOS NEXT 5.0 附近的 API 12。

1. 先给“不刷新”做分类：症状不同，根因完全不同

“LazyForEach 不刷新”这句话太笼统了，不同表现背后是根本不同的机制问题。我建议先按现象分成四类，再逐类定位。

1.1 整个列表对数据变化完全无感

这是最常见的一类。你调用了一个接口，返回了新的数据数组，把 this.bookList 重新赋值了，页面却没有任何变化。有些情况下连列表长度都不变，有些时候新增了 20 条数据，UI 还是原来的 10 条。

这类问题的核心原因十有八九出在数据源对象没有触发通知机制。LazyForEach 的数据来自一个实现了 IDataSource 接口的类，它不像 @State 那样有深层响应式能力，它依赖你手动调用 notifyDataChange、notifyDataAdd、notifyDataDelete 这组方法告诉框架“数据变了”。很多人把数组换成新的，却没有在任何地方调用这些方法，LazyForEach 自然认为数据没变。

1.2 数据变少了，界面却还留着旧行

这类现象我排查了最久。删除一条记录后，列表还在显示那条记录，点删除按钮也没反应。用日志打印数据源，发现数组里确实已经没有这条数据了，但 UI 上那一行就是不走。

这种问题通常和 keyGenerator 的返回值有关。LazyForEach 是根据 key 识别 item 的，如果 key 生成得不稳定，或者干脆用了数组下标，那删除数据后框架比对 key，剩下的项看起来“还是原来的项”，于是复用了旧组件，旧的 UI 状态被沿用了。

1.3 单条记录内容改了，整行都不刷新

这个更隐蔽。列表本身在新增、删除时都能正常刷新，但修改某条记录的某个字段后，那一条 item 不更新。比如你改了某本书的备注，界面上备注文字还是旧的。

这类问题的根因通常是：LazyForEach 的 itemGenerator 里用了普通对象，而对象的属性变化没有通过 @Observed 包装，组件本身也没有被 @ObjectLink 观察。ArkUI 的响应式系统不会因为一个普通对象的属性变化就重新渲染对应组件。

1.4 顺序变了，item 和数据显示错乱

做拖拽排序或者接口返回顺序变化时，会出现数据顺序已经变了，但界面 item 顺序不对、内容张冠李戴的情况。这往往是 keyGenerator 使用了内容字段，而内容字段本身参与排序、重复率又高，导致框架在做 diff 时匹配到了错误的旧组件。

这四类症状混合出现也很常见。建议按“数组增删”和“字段变化”两条线分别排查，前者重点关注 IDataSource 通知方法，后者重点关注 @Observed 和 @ObjectLink。下面先讲清楚 LazyForEach 的刷新机制，这个机制弄懂了，排查方向自然就清晰了。

2. 从源码理解刷新链路：IDataSource 通知与 keyGenerator 是怎么配合的

不少人把 LazyForEach 当成 ForEach 的“性能优化版”来用，认为只要把数组换成数据源、键值生成器补上就完事了。这种理解不能说全错，但漏掉了最关键的部分：LazyForEach 的数据刷新不是自动的，也不是全量 diff 的，它是“按通知增量更新”的。

2.1 一次数据变化在框架内部经历了什么

一个标准的数据变更链路是这样的：

1. 你的业务代码修改了数据源中的真实数据，比如往数组里插入了一条记录。
2. 业务代码调用 dataSource 的 notifyDataAdd(index) 方法，通知框架“在第 index 位置新增了一条数据”。
3. 框架收到通知后，在 index 位置调用 itemGenerator，生成新的组件。
4. 如果该位置邻近的 item 还在可视区域内，框架可能也会复用旧组件并调用 keyGenerator 重新计算 key，用于 diff。
5. 框架把新生成的组件插入到对应位置，完成 UI 更新。

这中间任何一步断了，UI 都不会正确刷新。尤其要注意第 2 步，很多人改了数据但没有调用 notify 方法，那后续步骤根本不会被触发。

2.2 keyGenerator 的职责不是“给个 key 就行”

keyGenerator 的作用是：当数据变化时，让框架能识别“哪个 item 是新的，哪个 item 是旧的”。它直接决定了 LazyForEach 的复用和更新行为。

如果你用数组下标做 key：

(key: string, index: number) => index.toString()

那么删除第一条数据后，原来第二条数据的 key 变成了“0”，框架会认为这个位置上的 item 没有变化，直接复用旧组件。但旧组件里显示的还是原来第一条数据的内容，于是你看到的就是“删除后界面还在显示旧内容”。

正确做法是用数据的唯一标识：

(key: string) => key

但这里也有细节：如果数据本身没有唯一 id，只是用 title 做 key，而列表里恰好有两条同名的书，那 diff 也会出问题。所以数据模型设计阶段就应保证 id 唯一且稳定，不要用参与展示的字段做 key。

2.3 一个完整可用的 IDataSource 实现长什么样

HarmonyOS NEXT 的 LazyForEach 要求传入一个实现 IDataSource 接口的对象，接口包含 5 个方法：

interface IDataSource { totalCount(): number; getData(index: number): any; registerDataChangeListener(listener: DataChangeListener): void; unregisterDataChangeListener(listener: DataChangeListener): void; onDataChange(index: number): void; notifyDataAdd(index: number): void; notifyDataDelete(index: number): void; notifyDataChange(index: number): void; notifyDataMove(fromIndex: number, toIndex: number): void; notifyDataReload(): void; }

实际开发中，很多人只实现了前 5 个方法，后面的 notify 系列方法全都没写，或者写了个空实现。这样 LazyForEach 确实能显示数据，但永远无法增量刷新。我给你一个可以直接抄的模板，代码如下：

import { IDataSource, DataChangeListener } from '@kit.ArkUI'; export class BookDataSource implements IDataSource { private data: Book[]; private listeners: DataChangeListener[] = []; constructor(data: Book[]) { this.data = data; } totalCount(): number { return this.data.length; } getData(index: number): Book { return this.data[index]; } registerDataChangeListener(listener: DataChangeListener): void { this.listeners.push(listener); } unregisterDataChangeListener(listener: DataChangeListener): void { const i = this.listeners.indexOf(listener); if (i !== -1) { this.listeners.splice(i, 1); } } onDataChange(index: number): void { this.listeners.forEach((l) => l.onDataChange(index)); } notifyDataAdd(index: number): void { this.listeners.forEach((l) => l.onDataAdd(index)); } notifyDataDelete(index: number): void { this.listeners.forEach((l) => l.onDataDelete(index)); } notifyDataChange(index: number): void { this.listeners.forEach((l) => l.onDataChange(index)); } notifyDataMove(fromIndex: number, toIndex: number): void { this.listeners.forEach((l) => l.onDataMove(fromIndex, toIndex)); } notifyDataReload(): void { this.listeners.forEach((l) => l.onDataReload()); } addBook(item: Book, index?: number): void { if (index === undefined) { this.data.push(item); this.notifyDataAdd(this.data.length - 1); } else { this.data.splice(index, 0, item); this.notifyDataAdd(index); } } deleteBook(index: number): void { if (index < 0 || index >= this.data.length) { return; } this.data.splice(index, 1); this.notifyDataDelete(index); } updateBook(index: number, item: Book): void { if (index < 0 || index >= this.data.length) { return; } this.data[index] = item; this.notifyDataChange(index); } }

这里有一个容易忽略的点：IDataSource 接口在较新版本的 SDK 中把 notify 系列方法作为接口必选成员，有些早期示例代码里写的是在类里额外定义这些方法。不管哪种写法，核心思路都是同一套：数据有任何变化，就同步对应用 index 通知框架。

2.4 为什么 notify 传的 index 错了，界面会“刷新错位”

notifyDataDelete(index) 传的 index 必须和数组 splice 删除的位置一致。很多人删除数据后，用indexOf(id)去查下标，这本身没问题。但如果你用 async/await 接口请求，请求完成后数组已经变了，再用旧 id 去 indexOf，拿到的 index 可能已经不是当初那条记录的位置了。这类“错位”问题调试起来非常抓狂，因为数据看起来是对的，就是 UI 串行。

3. 一条实用的定位链路：从现象到根因的排查流程

我在排查“LazyForEach 不刷新”时，不会一上来改代码，而是按下面这条链路走一遍，大部分问题都能在 15 分钟内定位到根因。这条链路是基于我在实际项目中排查多个列表页问题的经验，适合大多数场景。

3.1 第一步：确认“数据确实变了，但界面没变”

这一步看起来废话，但真的能过滤掉一半问题。先用 console.info 把数据源的 totalCount 和相关字段打出来，确认数据已经变化。如果数据本身就没变，那不是 UI 的问题，而是数据层的问题。

console.info('当前数据量: ' + this.bookDataSource.totalCount()); console.info('第三条数据: ' + JSON.stringify(this.bookDataSource.getData(3)));

3.2 第二步：检查 keyGenerator 是否稳定且唯一

打开你的 LazyForEach 代码，看 keyGenerator 的返回值。

LazyForEach(this.bookDataSource, (item: Book) => { BookItem({ book: item }) }, (key: string) => key)

如果这个写法用了item.id，说明 key 本身是稳定的。如果看到(key: string, index: number) => index.toString()，那问题几乎可以确定在这一步。把 key 改成基于唯一 id 的写法，再测一次。

3.3 第三步：在数据源方法里打日志，看 notify 是否被调用

在 BookDataSource 的 notifyDataAdd、notifyDataDelete、notifyDataChange 方法入口各加一行日志。如果你触发了业务操作，日志却没打出来，说明业务代码根本没调用这些方法。

最典型的情况是：你在 ViewModel 里直接 new 了一个新的 BookDataSource，然后把它赋给 @State 变量，但根本没有调用任何 notify 方法。LazyForEach 不刷新就是必然结果。

3.4 第四步：区分“数组引用替换”和“数据源 notify”两种刷新方式

这是最后一个排查点，也是最常见的混淆点。

第一种方式，你有一个 @State bookDataSource: BookDataSource，修改数据时新建一个 BookDataSource 并整体赋值。这种方式需要保证新实例的 registerDataChangeListener 被重新调用，否则监听器丢失，也不刷新。

第二种方式是保持同一个 BookDataSource 实例，修改其内部数组后调用 notify 系列方法。这种方式更稳定，也是我在项目中最终采用的方案。

排查到这里，基本能确定根因。接下来按场景对症下药。

4. 修复实践：整体替换、局部增删、单条修改三种场景的改造

下面这三个场景是我在项目里真实遇到过的，每一种我都给出了完整改造方案。注意场景之间可能叠加，比如先做整体替换，再做单条修改，需要把方案组合起来。

4.1 场景 A：接口返回新数据，整体替换列表

很多列表页的逻辑是：下拉刷新时请求接口，拿到新数据后整体替换列表。我最初的做法是：

this.bookDataSource = new BookDataSource(newBooks);

结果列表不刷新。原因写在 3.4 里：LazyForEach 已经注册的数据监听器挂在旧实例上，新实例虽然被赋值，但它的 registerDataChangeListener 还没有被框架调用，或者调用了但旧监听器的“之前状态”还在，UI 就认为没有变化。

改造方案是给 BookDataSource 增加一个 reload 方法，复用同一个实例：

reload(newBooks: Book[]): void { this.data = newBooks; this.notifyDataReload(); }

调用处：

this.bookDataSource.reload(newBooks);

notifyDataReload 会让 LazyForEach 重新计算全部 item 的 key，并重新生成可视区内的组件，逻辑最简单，也不容易出错。缺点是如果列表很长，性能理论上不如增量更新，但实测在几百条的列表上差别不大。

4.2 场景 B：删除某条记录，界面倒着数都留着旧行

这个场景就是典型的“删不掉”问题。我在排查时发现，即使调用 notifyDataDelete，旧行也可能不消失。原因有三个，按概率从高到低排列：

第一个原因是 keyGenerator 用了 index，框架匹配 key 时认为其他 item 没变，导致位置错乱且旧 UI 残留。解决方法是把 key 改为 item.id。

第二个原因是删除时传入的 index 不对。有个很典型的错误写法：在异步回调里拿到了一个旧数组的 index，去数据源里删除，此时数据源已经被其他操作改动，index 错位。解决方法是删除事件携带 id，在删除方法里用当前数组查找：

deleteBookById(id: string): void { const index = this.data.findIndex((item) => item.id === id); if (index >= 0) { this.data.splice(index, 1); this.notifyDataDelete(index); } }

第三个原因是删除方法里先调用了 notifyDataReload，又调用了 notifyDataDelete，两次通知打架，导致 UI 状态混乱。改法很简单：只保留一种通知方式。

4.3 场景 C：修改单条记录的字段，整行不刷新

这个问题的完整链路是：LazyForEach 调用 itemGenerator 生成 BookItem 子组件，BookItem 内部显示 book.title、book.remark 等字段。如果你修改了 book 对象的 remark 属性，但 book 不是 @Observed 类，BookItem 也没有用 @ObjectLink 绑定，那么 UI 不会感知这次修改。

选择一：用 @Observed + @ObjectLink 改造。给 Book 类加 @Observed，BookItem 组件里用 @ObjectLink 接收，修改属性后 UI 自动刷新。

@Observed export class Book { id: string = ''; title: string = ''; remark: string = ''; constructor(id: string, title: string, remark: string) { this.id = id; this.title = title; this.remark = remark; } }

@Component export struct BookItem { @ObjectLink book: Book; build() { Row() { Column() { Text(this.book.title) Text(this.book.remark) } } } }

选择二：如果数据结构比较简单，不值得大动干戈，可以直接替换整个对象，让 key 变化，从而触发重建：

updateBookRemark(id: string, newRemark: string): void { const index = this.data.findIndex((item) => item.id === id); if (index >= 0) { const newBook = new Book(id, this.data[index].title, newRemark); this.data[index] = newBook; this.notifyDataChange(index); } }

注意：替换整个对象时，key 必须仍基于 id，而不是基于 remark，否则 key 变了，框架会当作新增而不是更新。这里容易产生新的坑。

5. 那些“假不刷新”的隐藏坑：@Reusable 复用、层级嵌套、动效残留

有些时候，数据源、keyGenerator、notify 方法全部正确，界面上依然出现“不刷新”的观感。我在这部分整理了几种隐藏较深的诱因，它们经常被误判为 LazyForEach 的 bug。

5.1 @Reusable 组件复用导致旧内容残留

给列表项加了 @Reusable 之后，item 组件会被复用。复用在提高性能的同时引入了一个新问题：组件被复用时，@State 状态可能残留上一次的内容。如果你的 item 内部用 @State 保存了某些临时状态（比如展开标记、选中状态），而复用后没有重置，就会看到“内容已经变了但 UI 停留在旧状态”。

标准的解决方式是在子组件里实现 onReused 回调：

@Reusable @Component export struct BookItem { @State isExpanded: boolean = false; book: Book | null = null; aboutToReuse(params: Record<string, Object>): void { this.book = params.book as Book; this.isExpanded = false; } build() { // ... } }

注意 aboutToReuse 在组件复用之前触发，适合做状态重置。如果你没有写这个方法，那么复用的组件携带旧状态非常正常，这不是 LazyForEach 的锅。

5.2 @Observed 只监听第一层，嵌套对象属性变化不会触发刷新

@Observed 能监听的属性是有深度的限制的。如果 Book 类里有一个 EditorInfo 对象，EditorInfo 内部有个 name 字段，你直接修改 book.editor.name，@Observed 并不会帮你触发 UI 更新。

遇到过的情况是这样：列表项的子组件里展示的是一本书的编辑者信息，接口返回后我直接改了book.editor.name，UI 不刷新。排查了半天才发现 editor 对象本身没有被 @Observed 标记。

解决方案有两种：要么把 EditorInfo 也标记 @Observed，要么在修改嵌套字段后，对整条数据进行拷贝替换并调用 notifyDataChange。考虑到 ArkUI 的 @Observed 在某些版本中对嵌套深度支持有限，我更推荐第二种，代码更可控，也更容易排查。

5.3 itemGenerator 内部条件分支导致渲染结果没变

有时候数据本身变了，notify 也调了，但 itemGenerator 里写了复杂的条件分支，数据变化后仍然走了同一个分支，所以界面上看起来没有任何变化。

这类问题不是刷新机制的问题，而是呈现逻辑的问题。排查时可以在 itemGenerator 里加日志，打印实际进入的分支和 key 值。如果日志显示分支走了新逻辑，但界面没变，再去查组件内部是否绑定了正确的数据字段。

5.4 动效打断、动画残留制造“视觉不刷新”

靠一种比较少见的场景：删除 list item 时，组件先执行了退场动画，但因为动画被打断或者 withAnimation 使用不当，视觉上 item 一直停在半透明状态，看起来“界面没刷新”。

这种问题已经完全脱离 LazyForEach 本身了，但在表象上非常迷惑。如果你发现数据、key、notify 全部正常，可以检查是否在删除操作外面包了 withAnimation，尝试去掉动画再验证。

6. 几个能真正减少返工的操作习惯

这段内容是我在模拟项目 X 的列表功能开发过程中积累下来的实操习惯，不是理论推演。每一项都对应过真实的问题，照着做能显著减少“LazyForEach 不刷新”这类问题的产生。

第一，把 IDataSource 的 notify 调用集中到数据层，不要散落在页面里。我在项目里做了一个约定：所有页面组件禁止直接操作数据源内部数组，只能通过 BookDataSource 暴露的 addBook、deleteBookById、reload 方法操作。这样想漏调 notify 都难，排查时也只需要看一个文件。

第二，给 keyGenerator 写单元测试级别的验证。我可以分享一个笨办法：开发调试阶段，在 keyGenerator 里加日志，输出每次生成的 key。然后执行增删改操作，观察 key 是否唯一、是否稳定。如果日志里出现了重复 key，问题很大概率出在 key 上。

第三，处理异步刷新时，一定要把 id 带到回调里，不要在回调里使用闭包捕获的旧数组 index。这个坑我至少踩了三次，每次都是“看起来逻辑没问题，但 UI 就是不对”，最后定位全是 index 错位。

第四，优先用 notifyDataReload。很多开发者刚接触 LazyForEach 时认为增量通知更优雅，非要写 notifyDataAdd、notifyDataDelete。实际上，如果列表只有几十到几百条，整体 reload 的代码简单得多，可维护性也更高。只有列表达到成千上万条且性能瓶颈明显时，才有必要精细到增量通知。

第五，利用 DevEco Studio 的 ArkUI Inspector 检查实际组件树。当页面出现“不刷新”的观感时，通过 Inspector 看组件树上到底渲染了哪些节点、每个节点绑定的数据是什么，很多时候一眼就能看出是 key 复用还是数据层的问题。这一步比反复读代码高效得多。

做完这轮排查和重构，我在项目里的列表刷新问题基本清零。这个功能后续如果要扩展到底层分页加载，我会在 BookDataSource 里增加一个 hasMore 字段，让分页逻辑和数据源通知走同一条链路，避免再次出现“加载更多后列表不刷新”的返工。