文档开发者中心
我的

下拉刷新一下,整屏卡片全重建?HarmonyOS 7 让 LazyForEach 在 reload 时“就地复用”旧组件

浏览9发布于7 小时前未知归属地

鸿蒙开发热点系列 · 第 17 篇 | 基于 HarmonyOS 7(API 26.0.0 / 26.0.1 Beta1)

11 月 16 日,鸿蒙装机量突破 1 亿台;HarmonyOS 7(API 26.0.0)设备占比已到 82.21%,这几天 7.0.0.115 版本还在陆续推送。用户越多,信息流 App 越躲不开一个老问题:下拉刷新,新数据整批替换,列表“顿”一下甚至白一下。原因很直接——新数据的键值全变了,LazyForEach 只能把屏幕上的子组件销毁、再一个个新建。11 月 10 日发布的 26.0.1 Beta1 给 DataChangeListener 加了一个同名重载 onDataReloaded(reuseImmediately: boolean):reload 时允许把旧子组件回收后立刻复用成新子组件。这篇只讲两件事:怎么接,以及接了却没效果的几个坑。

一、reload 时到底发生了什么

官方 LazyForEach 文档对老接口的描述是:onDataReloaded() 通知组件重新加载所有数据,键值没有变化的数据项使用原先的子组件,键值发生变化的会重建子组件。下拉刷新拿到的是一批全新 id,于是几乎每一项都要重建。

新重载把行为分成三种情况(摘自同一文档):

配置 键值未变的项 键值变化的项
reuseImmediately = true + @Reusable/@ReusableV2 用原子组件 优先用复用池;池里没有,就把 LazyForEach 的旧子组件回收、复用为新子组件;都没有才新建
reuseImmediately = true,未用 @Reusable 用原子组件 重建(等于没开)
reuseImmediately = false 用原子组件 复用池里有可用组件才复用,否则新建

关键就在第一行:以前 reload 时屏幕上的旧卡片要等走完销毁流程才谈得上复用,现在同一次更新里就能把它们“翻新”成新卡片,省掉的是一整屏的组件创建开销。

二、实战模板:下拉刷新 + 就地复用

收起
自动换行
深色代码主题
复制
class NewsItem {
  id: string;
  title: string;
  summary: string;

  constructor(id: string, title: string, summary: string) {
    this.id = id;
    this.title = title;
    this.summary = summary;
  }
}

class FeedSource implements IDataSource {
  private list: NewsItem[] = [];
  private listeners: DataChangeListener[] = [];

  totalCount(): number {
    return this.list.length;
  }

  getData(index: number): NewsItem {
    return this.list[index];
  }

  registerDataChangeListener(listener: DataChangeListener): void {
    if (this.listeners.indexOf(listener) < 0) {
      this.listeners.push(listener);
    }
  }

  unregisterDataChangeListener(listener: DataChangeListener): void {
    const pos = this.listeners.indexOf(listener);
    if (pos >= 0) {
      this.listeners.splice(pos, 1);
    }
  }

  // 下拉刷新:整批替换数据
  replaceAll(newList: NewsItem[]): void {
    this.list = newList;
    this.listeners.forEach((listener: DataChangeListener) => {
      listener.onDataReloaded(true); // 26.0.1:允许 reload 过程中复用旧子组件
    });
  }
}

@Reusable
@Component
struct NewsCard {
  @State item: NewsItem = new NewsItem('', '', '');

  // 复用时把新数据灌进来;所有展示用的状态都要在这里重置
  aboutToReuse(params: Record<string, ESObject>): void {
    this.item = params.item as NewsItem;
  }

  build() {
    Column({ space: 6 }) {
      Text(this.item.title).fontSize(17).fontWeight(FontWeight.Medium)
      Text(this.item.summary).fontSize(14).fontColor('#666').maxLines(2)
    }
    .alignItems(HorizontalAlign.Start)
    .padding(12)
    .width('100%')
  }
}

@Entry
@Component
struct FeedPage {
  @State refreshing: boolean = false;
  private source: FeedSource = new FeedSource();
  private batch: number = 0;

  aboutToAppear(): void {
    this.source.replaceAll(this.mockBatch());
  }

  // 演示用:实际项目里来自接口
  private mockBatch(): NewsItem[] {
    this.batch++;
    const arr: NewsItem[] = [];
    for (let i = 0; i < 30; i++) {
      arr.push(new NewsItem(`${this.batch}-${i}`, `第 ${this.batch} 批 · 新闻 ${i}`, '摘要内容……'));
    }
    return arr;
  }

  build() {
    Refresh({ refreshing: $$this.refreshing }) {
      List() {
        LazyForEach(this.source, (item: NewsItem) => {
          ListItem() {
            NewsCard({ item: item }).reuseId('news')
          }
        }, (item: NewsItem) => item.id)
      }
      .cachedCount(4)
    }
    .onRefreshing(() => {
      this.source.replaceAll(this.mockBatch());
      this.refreshing = false;
    })
  }
}

如果你的数据源统一走 onDatasetChange 批量通知,也可以用 DataReloadOperation 的新字段,效果相同:

收起
自动换行
深色代码主题
复制
listener.onDatasetChange([{ type: DataOperationType.RELOAD, reuseImmediately: true }]);

文档写明:onDatasetChange 里一旦含有 RELOAD 操作,同批其余操作全部失效,框架自己用 keyGenerator 比对键值;reuseImmediately 默认 false。另外 onDataReloaded 不能和 onDatasetChange 混用,一个数据源选一种。

三、接了没效果?先查这四处

  1. 没加 @Reusable。 文档原话:新重载“需要和 @Reusable/@ReusableV2 配合使用”,否则键值变化的项照样重建。
  2. 键值没变,界面不刷。 官方 FAQ《LazyForEach 懒加载界面不刷新问题定位》专门讲过:调用 reload 后 keyGenerator 生成的键值没变,界面就不会更新。内容会变的数据,键值里要带上版本号或更新时间,比如 `${item.id}_${item.updatedAt}`。
  3. 复用后“串数据”。 只有 @State 等状态变量在 aboutToReuse 里被重新赋值才会刷新;点赞高亮、进度这类状态忘了重置,复用出来的卡片就带着上一条的残影。另外,不要在 aboutToReuse 里改父组件的状态变量,官方说明这类修改不会生效。
  4. 卡片结构不一致。 复用前后组件结构要保持不变;图文、纯文、视频卡片结构不同,就用不同的 reuseId 分组,否则复用过程中仍会创建、销毁子组件。

四、上线前注意

onDataReloaded(reuseImmediately) 和 DataReloadOperation.reuseImmediately 都是 26.0.1 起的接口,而官方版本说明写明:用 Beta 版 DevEco Studio 开发的应用无法上架应用市场。要上架的工程今天能做的是:卡片先加上 @Reusable + reuseId,刷新时键值设计好(没变的内容保持同一个 key,就会直接用原子组件),能增量更新的场景用 onDatasetChange 的增删操作代替整表 reload;等 26.0.1 Release 再把 replaceAll 里那一行换成 onDataReloaded(true)。

参考来源

  1. 华为开发者联盟:LazyForEach API 参考(onDataReloaded(reuseImmediately)、DataReloadOperation),https://developer.huawei.com/consumer/cn/doc/doccenter-references/api/ts-rendering-control-lazyforeach (2026-11-19 查阅)
  2. 华为开发者联盟:ArkUI API 变更清单(26.0.1 Beta1,DataChangeListener 新增同名方法),https://developer.huawei.com/consumer/cn/doc/doccenter-release-notes/js-apidiff-arkui-26011 (2026-11-19 查阅)
  3. 华为开发者联盟:HarmonyOS 26.0.1 版本概览(2026-11-10 发布 Beta1),https://developer.huawei.com/consumer/cn/doc/doccenter-release-notes/overview-2601 (2026-11-19 查阅)
  4. 华为开发者联盟:@Reusable 装饰器:V1 组件复用,https://developer.huawei.com/consumer/cn/doc/doccenter-capabilities/arkts-reusable (2026-11-19 查阅)
  5. 华为开发者联盟:LazyForEach 懒加载界面不刷新问题定位,https://developer.huawei.com/consumer/cn/doc/doccenter-dev-faq/arkui-kit-troubleshooting-0013 (2026-11-19 查阅)
  6. IT之家:华为鸿蒙系统装机量被曝破亿后,HarmonyOS 7 设备占比突破 82%,https://www.ithome.com/1/028/906.htm (2026-11-18)
  7. IT之家:华为 Mate 90 系列手机推 HarmonyOS 7.0.0.115 升级,https://www.ithome.com/1/029/125.htm (2026-11-19)
收藏
0
回复
3
分享
全部评论
authorIcon
优秀滴俊哥

四个坑总结得很到位,尤其是aboutToReuse里要重置点赞高亮这类状态、不同结构卡片分reuseId这两点,之前复用串数据就是栽在这;先加@Reusable打底、等26.0.1正式版再切onDataReloaded(true)的节奏也很稳。

回复于2 小时前未知归属地
authorIcon
匿名用户
感谢分享,学习
回复于2 小时前四川
authorIcon
lovoyd
学习一下
回复于6 小时前广西
写评论
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。
发表
我要写文章
目录 收起
一、reload 时到底发生了什么
二、实战模板:下拉刷新 + 就地复用
三、接了没效果?先查这四处
四、上线前注意
参考来源
了解社区公约,与您携手共创和谐专业的开发者社区。