鸿蒙开发热点系列 · 第 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 混用,一个数据源选一种。
三、接了没效果?先查这四处
- 没加
@Reusable。 文档原话:新重载“需要和 @Reusable/@ReusableV2 配合使用”,否则键值变化的项照样重建。 - 键值没变,界面不刷。 官方 FAQ《LazyForEach 懒加载界面不刷新问题定位》专门讲过:调用 reload 后 keyGenerator 生成的键值没变,界面就不会更新。内容会变的数据,键值里要带上版本号或更新时间,比如
`${item.id}_${item.updatedAt}`。 - 复用后“串数据”。 只有
@State等状态变量在aboutToReuse里被重新赋值才会刷新;点赞高亮、进度这类状态忘了重置,复用出来的卡片就带着上一条的残影。另外,不要在aboutToReuse里改父组件的状态变量,官方说明这类修改不会生效。 - 卡片结构不一致。 复用前后组件结构要保持不变;图文、纯文、视频卡片结构不同,就用不同的
reuseId分组,否则复用过程中仍会创建、销毁子组件。
四、上线前注意
onDataReloaded(reuseImmediately) 和 DataReloadOperation.reuseImmediately 都是 26.0.1 起的接口,而官方版本说明写明:用 Beta 版 DevEco Studio 开发的应用无法上架应用市场。要上架的工程今天能做的是:卡片先加上 @Reusable + reuseId,刷新时键值设计好(没变的内容保持同一个 key,就会直接用原子组件),能增量更新的场景用 onDatasetChange 的增删操作代替整表 reload;等 26.0.1 Release 再把 replaceAll 里那一行换成 onDataReloaded(true)。
参考来源
- 华为开发者联盟:LazyForEach API 参考(onDataReloaded(reuseImmediately)、DataReloadOperation),https://developer.huawei.com/consumer/cn/doc/doccenter-references/api/ts-rendering-control-lazyforeach (2026-11-19 查阅)
- 华为开发者联盟:ArkUI API 变更清单(26.0.1 Beta1,DataChangeListener 新增同名方法),https://developer.huawei.com/consumer/cn/doc/doccenter-release-notes/js-apidiff-arkui-26011 (2026-11-19 查阅)
- 华为开发者联盟:HarmonyOS 26.0.1 版本概览(2026-11-10 发布 Beta1),https://developer.huawei.com/consumer/cn/doc/doccenter-release-notes/overview-2601 (2026-11-19 查阅)
- 华为开发者联盟:@Reusable 装饰器:V1 组件复用,https://developer.huawei.com/consumer/cn/doc/doccenter-capabilities/arkts-reusable (2026-11-19 查阅)
- 华为开发者联盟:LazyForEach 懒加载界面不刷新问题定位,https://developer.huawei.com/consumer/cn/doc/doccenter-dev-faq/arkui-kit-troubleshooting-0013 (2026-11-19 查阅)
- IT之家:华为鸿蒙系统装机量被曝破亿后,HarmonyOS 7 设备占比突破 82%,https://www.ithome.com/1/028/906.htm (2026-11-18)
- IT之家:华为 Mate 90 系列手机推 HarmonyOS 7.0.0.115 升级,https://www.ithome.com/1/029/125.htm (2026-11-19)





































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