ForEach接口基于数组类型数据来进行循环渲染,需要与容器组件配合使用,且接口返回的组件应当是允许包含在ForEach父容器组件中的子组件。例如,ListItem组件要求ForEach的父容器组件必须为 List组件 。
说明:
从API version 9开始,该接口支持在ArkTS卡片中使用。
接口描述
ForEach(arr: Array,itemGenerator: (item: any, index: number) => void,keyGenerator?: (item: any, index: number) => string
)
以下是参数的详细说明:
参数名 | 参数类型 | 是否必填 | 参数描述 |
---|---|---|---|
arr | Array | 是 | 数据源,为Array 类型的数组。说明: - 可以设置为空数组,此时不会创建子组件。 - 可以设置返回值为数组类型的函数,例如 arr.slice(1, 3) ,但设置的函数不应改变包括数组本身在内的任何状态变量,例如不应使用Array.splice() ,Array.sort() 或Array.reverse() 这些会改变原数组的函数。 |
itemGenerator | (item: any, index: number) => void | 是 | 组件生成函数。 - 为数组中的每个元素创建对应的组件。 - item 参数:arr 数组中的数据项。- index 参数(可选):arr 数组中的数据项索引。说明: - 组件的类型必须是 ForEach 的父容器所允许的。例如,ListItem 组件要求ForEach 的父容器组件必须为List 组件。 |
keyGenerator | (item: any, index: number) => string | 否 | 键值生成函数。 - 为数据源 arr 的每个数组项生成唯一且持久的键值。函数返回值为开发者自定义的键值生成规则。- item 参数:arr 数组中的数据项。- index 参数(可选):arr 数组中的数据项索引。说明: - 如果函数缺省,框架默认的键值生成函数为 (item: T, index: number) => { return index + '__' + JSON.stringify(item); } - 键值生成函数不应改变任何组件状态。 |
说明:
ForEach
的itemGenerator
函数可以包含if/else
条件渲染逻辑。另外,也可以在if/else
条件渲染语句中使用ForEach
组件。- 在初始化渲染时,
ForEach
会加载数据源的所有数据,并为每个数据项创建对应的组件,然后将其挂载到渲染树上。如果数据源非常大或有特定的性能需求,建议使用LazyForEach
组件。
键值生成规则
在ForEach
循环渲染过程中,系统会为每个数组元素生成一个唯一且持久的键值,用于标识对应的组件。当这个键值变化时,ArkUI框架将视为该数组元素已被替换或修改,并会基于新的键值创建一个新的组件。
ForEach
提供了一个名为keyGenerator
的参数,这是一个函数,开发者可以通过它自定义键值的生成规则。如果开发者没有定义keyGenerator
函数,则ArkUI框架会使用默认的键值生成函数,即(item: any, index: number) => { return index + '__' + JSON.stringify(item); }
。
ArkUI框架对于ForEach
的键值生成有一套特定的判断规则,这主要与itemGenerator
函数的第二个参数index
以及keyGenerator
函数的第二个参数index
有关,具体的键值生成规则判断逻辑如下图所示。
图1 ForEach键值生成规则
说明:
ArkUI框架会对重复的键值发出警告。在UI更新的场景下,如果出现重复的键值,框架可能无法正常工作。
组件创建规则
在确定键值生成规则后,ForEach的第二个参数itemGenerator
函数会根据键值生成规则为数据源的每个数组项创建组件。组件的创建包括两种情况: ForEach首次渲染 和 ForEach非首次渲染 。
首次渲染
在ForEach首次渲染时,会根据前述键值生成规则为数据源的每个数组项生成唯一键值,并创建相应的组件。
@Entry
@Component
struct Parent {@State simpleList: Array<string> = ['one', 'two', 'three'];build() {Row() {Column() {ForEach(this.simpleList, (item: string) => {ChildItem({ item: item })}, (item: string) => item)}.width('100%').height('100%')}.height('100%').backgroundColor(0xF1F3F5)}
}@Component
struct ChildItem {@Prop item: string;build() {Text(this.item).fontSize(50)}
}
运行效果如下图所示。
图2 ForEach数据源不存在相同值案例首次渲染运行效果图
在上述代码中,键值生成规则是keyGenerator
函数的返回值item
。在ForEach渲染循环时,为数据源数组项依次生成键值one
、two
和three
,并创建对应的ChildItem
组件渲染到界面上。
当不同数组项按照键值生成规则生成的键值相同时,框架的行为是未定义的。例如,在以下代码中,ForEach渲染相同的数据项two
时,只创建了一个ChildItem
组件,而没有创建多个具有相同键值的组件。
@Entry
@Component
struct Parent {@State simpleList: Array<string> = ['one', 'two', 'two', 'three'];build() {Row() {Column() {ForEach(this.simpleList, (item: string) => {ChildItem({ item: item })}, (item: string) => item)}.width('100%').height('100%')}.height('100%').backgroundColor(0xF1F3F5)}
}@Component
struct ChildItem {@Prop item: string;build() {Text(this.item).fontSize(50)}
}
运行效果如下图所示。
图3 ForEach数据源存在相同值案例首次渲染运行效果图
在该示例中,最终键值生成规则为item
。当ForEach遍历数据源simpleList
,遍历到索引为1的two
时,按照最终键值生成规则生成键值为two
的组件并进行标记。当遍历到索引为2的two
时,按照最终键值生成规则当前项的键值也为two
,此时不再创建新的组件。
非首次渲染
在ForEach组件进行非首次渲染时,它会检查新生成的键值是否在上次渲染中已经存在。如果键值不存在,则会创建一个新的组件;如果键值存在,则不会创建新的组件,而是直接渲染该键值所对应的组件。例如,在以下的代码示例中,通过点击事件修改了数组的第三项值为"new three",这将触发ForEach组件进行非首次渲染。
@Entry
@Component
struct Parent {@State simpleList: Array<string> = ['one', 'two', 'three'];build() {Row() {Column() {Text('点击修改第3个数组项的值').fontSize(24).fontColor(Color.Red).onClick(() => {this.simpleList[2] = 'new three';})ForEach(this.simpleList, (item: string) => {ChildItem({ item: item }).margin({ top: 20 })}, (item: string) => item)}.justifyContent(FlexAlign.Center).width('100%').height('100%')}.height('100%').backgroundColor(0xF1F3F5)}
}@Component
struct ChildItem {@Prop item: string;build() {Text(this.item).fontSize(30)}
}
运行效果如下图所示。
图4 ForEach非首次渲染案例运行效果图
从本例可以看出@State
能够监听到简单数据类型数组数据源 simpleList
数组项的变化。
- 当
simpleList
数组项发生变化时,会触发ForEach
进行重新渲染。 ForEach
遍历新的数据源['one', 'two', 'new three']
,并生成对应的键值one
、two
和new three
。- 其中,键值
one
和two
在上次渲染中已经存在,所以ForEach
复用了对应的组件并进行了渲染。对于第三个数组项 “new three”,由于其通过键值生成规则item
生成的键值new three
在上次渲染中不存在,因此ForEach
为该数组项创建了一个新的组件。
使用场景
ForEach组件在开发过程中的主要应用场景包括: 数据源不变 、 数据源数组项发生变化 (如插入、删除操作)、 数据源数组项子属性变化 。
数据源不变
在数据源保持不变的场景中,数据源可以直接采用基本数据类型。例如,在页面加载状态时,可以使用骨架屏列表进行渲染展示。
@Entry
@Component
struct ArticleList {@State simpleList: Array<number> = [1, 2, 3, 4, 5];build() {Column() {ForEach(this.simpleList, (item: string) => {ArticleSkeletonView().margin({ top: 20 })}, (item: string) => item)}.padding(20).width('100%').height('100%')}
}@Builder
function textArea(width: number | Resource | string = '100%', height: number | Resource | string = '100%') {Row().width(width).height(height).backgroundColor('#FFF2F3F4')
}@Component
struct ArticleSkeletonView {build() {Row() {Column() {textArea(80, 80)}.margin({ right: 20 })Column() {textArea('60%', 20)textArea('50%', 20)}.alignItems(HorizontalAlign.Start).justifyContent(FlexAlign.SpaceAround).height('100%')}.padding(20).borderRadius(12).backgroundColor('#FFECECEC').height(120).width('100%').justifyContent(FlexAlign.SpaceBetween)}
}
运行效果如下图所示。
图5 骨架屏运行效果图
在本示例中,采用数据项item作为键值生成规则,由于数据源simpleList的数组项各不相同,因此能够保证键值的唯一性。
数据源数组项发生变化
在数据源数组项发生变化的场景下,例如进行数组插入、删除操作或者数组项索引位置发生交换时,数据源应为对象数组类型,并使用对象的唯一ID作为最终键值。例如,当在页面上通过手势上滑加载下一页数据时,会在数据源数组尾部新增新获取的数据项,从而使得数据源数组长度增大。
class Article {id: string;title: string;brief: string;constructor(id: string, title: string, brief: string) {this.id = id;this.title = title;this.brief = brief;}
}@Entry
@Component
struct ArticleListView {@State isListReachEnd: boolean = false;@State articleList: Array<Article> = [new Article('001', '第1篇文章', '文章简介内容'),new Article('002', '第2篇文章', '文章简介内容'),new Article('003', '第3篇文章', '文章简介内容'),new Article('004', '第4篇文章', '文章简介内容'),new Article('005', '第5篇文章', '文章简介内容'),new Article('006', '第6篇文章', '文章简介内容')]loadMoreArticles() {this.articleList.push(new Article('007', '加载的新文章', '文章简介内容'));}build() {Column({ space: 5 }) {List() {ForEach(this.articleList, (item: Article) => {ListItem() {ArticleCard({ article: item }).margin({ top: 20 })}}, (item: Article) => item.id)}.onReachEnd(() => {this.isListReachEnd = true;}).parallelGesture(PanGesture({ direction: PanDirection.Up, distance: 80 }).onActionStart(() => {if (this.isListReachEnd) {this.loadMoreArticles();this.isListReachEnd = false;}})).padding(20).scrollBar(BarState.Off)}.width('100%').height('100%').backgroundColor(0xF1F3F5)}
}@Component
struct ArticleCard {@Prop article: Article;build() {Row() {Image($r('app.media.icon')).width(80).height(80).margin({ right: 20 })Column() {Text(this.article.title).fontSize(20).margin({ bottom: 8 })Text(this.article.brief).fontSize(16).fontColor(Color.Gray).margin({ bottom: 8 })}.alignItems(HorizontalAlign.Start).width('80%').height('100%')}.padding(20).borderRadius(12).backgroundColor('#FFECECEC').height(120).width('100%').justifyContent(FlexAlign.SpaceBetween)}
}
初始运行效果(左图)和手势上滑加载后效果(右图)如下图所示。
图6 数据源数组项变化案例运行效果图
在本示例中,ArticleCard
组件作为ArticleListView
组件的子组件,通过@Prop
装饰器接收一个Article
对象,用于渲染文章卡片。
- 当列表滚动到底部时,如果手势滑动距离超过指定的80,将触发
loadMoreArticle()
函数。此函数会在articleList
数据源的尾部添加一个新的数据项,从而增加数据源的长度。 - 数据源被
@State
装饰器修饰,ArkUI框架能够感知到数据源长度的变化,并触发ForEach
进行重新渲染。
数据源数组项子属性变化
当数据源的数组项为对象数据类型,并且只修改某个数组项的属性值时,由于数据源为复杂数据类型,ArkUI框架无法监听到@State
装饰器修饰的数据源数组项的属性变化,从而无法触发ForEach
的重新渲染。为实现ForEach
重新渲染,需要结合@Observed
和@ObjectLink
装饰器使用。例如,在文章列表卡片上点击“点赞”按钮,从而修改文章的点赞数量。
@Observed
class Article {id: string;title: string;brief: string;isLiked: boolean;likesCount: number;constructor(id: string, title: string, brief: string, isLiked: boolean, likesCount: number) {this.id = id;this.title = title;this.brief = brief;this.isLiked = isLiked;this.likesCount = likesCount;}
}@Entry
@Component
struct ArticleListView {@State articleList: Array<Article> = [new Article('001', '第0篇文章', '文章简介内容', false, 100),new Article('002', '第1篇文章', '文章简介内容', false, 100),new Article('003', '第2篇文章', '文章简介内容', false, 100),new Article('004', '第4篇文章', '文章简介内容', false, 100),new Article('005', '第5篇文章', '文章简介内容', false, 100),new Article('006', '第6篇文章', '文章简介内容', false, 100),];build() {List() {ForEach(this.articleList, (item: Article) => {ListItem() {ArticleCard({article: item}).margin({ top: 20 })}}, (item: Article) => item.id)}.padding(20).scrollBar(BarState.Off).backgroundColor(0xF1F3F5)}
}@Component
struct ArticleCard {@ObjectLink article: Article;handleLiked() {this.article.isLiked = !this.article.isLiked;this.article.likesCount = this.article.isLiked ? this.article.likesCount + 1 : this.article.likesCount - 1;}build() {Row() {Image($r('app.media.icon')).width(80).height(80).margin({ right: 20 })Column() {Text(this.article.title).fontSize(20).margin({ bottom: 8 })Text(this.article.brief).fontSize(16).fontColor(Color.Gray).margin({ bottom: 8 })Row() {Image(this.article.isLiked ? $r('app.media.iconLiked') : $r('app.media.iconUnLiked')).width(24).height(24).margin({ right: 8 })Text(this.article.likesCount.toString()).fontSize(16)}.onClick(() => this.handleLiked()).justifyContent(FlexAlign.Center)}.alignItems(HorizontalAlign.Start).width('80%').height('100%')}.padding(20).borderRadius(12).backgroundColor('#FFECECEC').height(120).width('100%').justifyContent(FlexAlign.SpaceBetween)}
}
上述代码的初始运行效果(左图)和点击第1个文章卡片上的点赞图标后的运行效果(右图)如下图所示。
图7 数据源数组项子属性变化案例运行效果图
在本示例中,Article
类被@Observed
装饰器修饰。父组件ArticleListView
传入Article
对象实例给子组件ArticleCard
,子组件使用@ObjectLink
装饰器接收该实例。
- 当点击第1个文章卡片上的点赞图标时,会触发
ArticleCard
组件的handleLiked
函数。该函数修改第1个卡片对应组件里article
实例的isLiked
和likesCount
属性值。 - 由于子组件
ArticleCard
中的article
使用了@ObjectLink
装饰器,父子组件共享同一份article
数据。因此,父组件中articleList
的第1个数组项的isLiked
和likedCounts
数值也会同步修改。 - 当父组件监听到数据源数组项属性值变化时,会触发
ForEach
重新渲染。 - 在此处,
ForEach
键值生成规则为数组项的id
属性值。当ForEach
遍历新数据源时,数组项的id
均没有变化,不会新建组件。 - 渲染第1个数组项对应的
ArticleCard
组件时,读取到的isLiked
和likesCount
为修改后的新值。
使用建议
- 尽量避免在最终的键值生成规则中包含数据项索引
index
,以防止出现渲染结果非预期和渲染性能降低。如果业务确实需要使用index
,例如列表需要通过index
进行条件渲染,开发者需要接受ForEach
在改变数据源后重新创建组件所带来的性能损耗。 - 为满足键值的唯一性,对于对象数据类型,建议使用对象数据中的唯一
id
作为键值。 - 基本数据类型的数据项没有唯一
ID
属性。如果使用基本数据类型本身作为键值,必须确保数组项无重复。因此,对于数据源会发生变化的场景,建议将基本数据类型数组转化为具备唯一ID
属性的对象数据类型数组,再使用ID
属性作为键值生成规则。
不推荐案例
开发者在使用ForEach的过程中,若对于键值生成规则的理解不够充分,可能会出现错误的使用方式。错误使用一方面会导致功能层面问题,例如 渲染结果非预期 ,另一方面会导致性能层面问题,例如 渲染性能降低。
渲染结果非预期
在本示例中,通过设置ForEach
的第三个参数KeyGenerator
函数,自定义键值生成规则为数据源的索引index
的字符串类型值。当点击父组件Parent
中“在第1项后插入新项”文本组件后,界面会出现非预期的结果。
@Entry
@Component
struct Parent {@State simpleList: Array<string> = ['one', 'two', 'three'];build() {Column() {Button() {Text('在第1项后插入新项').fontSize(30)}.onClick(() => {this.simpleList.splice(1, 0, 'new item');})ForEach(this.simpleList, (item: string) => {ChildItem({ item: item })}, (item: string, index: number) => index.toString())}.justifyContent(FlexAlign.Center).width('100%').height('100%').backgroundColor(0xF1F3F5)}
}@Component
struct ChildItem {@Prop item: string;build() {Text(this.item).fontSize(30)}
}
上述代码的初始渲染效果(左图)和点击“在第1项后插入新项”文本组件后的渲染效果(右图)如下图所示。
图8 渲染结果非预期运行效果图
ForEach
在首次渲染时,创建的键值依次为"0"、“1”、“2”。
插入新项后,数据源simpleList
变为['one', 'new item', 'two', 'three']
,框架监听到@State
装饰的数据源长度变化触发ForEach
重新渲染。
ForEach
依次遍历新数据源,遍历数据项"one"时生成键值"0",存在相同键值,因此不创建新组件。继续遍历数据项"new item"时生成键值"1",存在相同键值,因此不创建新组件。继续遍历数据项"two"生成键值"2",存在相同键值,因此不创建新组件。最后遍历数据项"three"时生成键值"3",不存在相同键值,创建内容为"three"的新组件并渲染。
从以上可以看出,当最终键值生成规则包含index
时,期望的界面渲染结果为['one', 'new item', 'two', 'three']
,而实际的渲染结果为['one', 'two', 'three', 'three']
,渲染结果不符合开发者预期。因此,开发者在使用ForEach
时应尽量避免最终键值生成规则中包含index
。
渲染性能降低
在本示例中,ForEach
的第三个参数KeyGenerator
函数处于缺省状态。根据上述 键值生成规则 ,此例使用框架默认的键值生成规则,即最终键值为字符串index + '__' + JSON.stringify(item)
。当点击“在第1项后插入新项”文本组件后,ForEach
将需要为第2个数组项以及其后的所有项重新创建组件。
@Entry
@Component
struct Parent {@State simpleList: Array<string> = ['one', 'two', 'three'];build() {Column() {Button() {Text('在第1项后插入新项').fontSize(30)}.onClick(() => {this.simpleList.splice(1, 0, 'new item');console.log(`[onClick]: simpleList is ${JSON.stringify(this.simpleList)}`);})ForEach(this.simpleList, (item: string) => {ChildItem({ item: item })})}.justifyContent(FlexAlign.Center).width('100%').height('100%').backgroundColor(0xF1F3F5)}
}@Component
struct ChildItem {@Prop item: string;aboutToAppear() {console.log(`[aboutToAppear]: item is ${this.item}`);}build() {Text(this.item).fontSize(50)}
}
以上代码的初始渲染效果(左图)和点击"在第1项后插入新项"文本组件后的渲染效果(右图)如下所示。
图9 渲染性能降低案例运行效果图
点击“在第1项后插入新项”文本组件后,IDE的日志打印结果如下所示。
图10 渲染性能降低案例日志打印图
插入新项后,ForEach
为new item
、 two
、 three
三个数组项创建了对应的组件ChildItem
,并执行了组件的 aboutToAppear()
生命周期函数。这是因为:
- 在
ForEach
首次渲染时,创建的键值依次为0__one
、1__two
、2__three
。 - 插入新项后,数据源
simpleList
变为['one', 'new item', 'two', 'three']
,ArkUI框架监听到@State
装饰的数据源长度变化触发ForEach
重新渲染。 ForEach
依次遍历新数据源,遍历数据项one
时生成键值0__one
,键值已存在,因此不创建新组件。继续遍历数据项new item
时生成键值1__new item
,不存在相同键值,创建内容为new item
的新组件并渲染。继续遍历数据项two
生成键值2__two
,不存在相同键值,创建内容为two
的新组件并渲染。最后遍历数据项three
时生成键值3__three
,不存在相同键值,创建内容为three
的新组件并渲染。
尽管此示例中界面渲染的结果符合预期,但每次插入一条新数组项时,ForEach
都会为从该数组项起后面的所有数组项全部重新创建组件。当数据源数据量较大或组件结构复杂时,由于组件无法得到复用,将导致性能体验不佳。因此,除非必要,否则不推荐将第三个参数KeyGenerator
函数处于缺省状态,以及在键值生成规则中包含数据项索引index
。
为了能让大家更好的学习鸿蒙(HarmonyOS NEXT)开发技术,这边特意整理了《鸿蒙开发学习手册》(共计890页),希望对大家有所帮助:https://qr21.cn/FV7h05
《鸿蒙开发学习手册》:
如何快速入门:https://qr21.cn/FV7h05
- 基本概念
- 构建第一个ArkTS应用
- ……
开发基础知识:https://qr21.cn/FV7h05
- 应用基础知识
- 配置文件
- 应用数据管理
- 应用安全管理
- 应用隐私保护
- 三方应用调用管控机制
- 资源分类与访问
- 学习ArkTS语言
- ……
![](ht
tps://img-blog.csdnimg.cn/img_convert/c02d1bcf9201e3d3d8baf3b812f8e370.webp?x-oss-process=image/format,png)
基于ArkTS 开发:https://qr21.cn/FV7h05
- Ability开发
- UI开发
- 公共事件与通知
- 窗口管理
- 媒体
- 安全
- 网络与链接
- 电话服务
- 数据管理
- 后台任务(Background Task)管理
- 设备管理
- 设备使用信息统计
- DFX
- 国际化开发
- 折叠屏系列
- ……
鸿蒙开发面试真题(含参考答案):https://qr18.cn/F781PH
鸿蒙开发面试大盘集篇(共计319页):https://qr18.cn/F781PH
1.项目开发必备面试题
2.性能优化方向
3.架构方向
4.鸿蒙开发系统底层方向
5.鸿蒙音视频开发方向
6.鸿蒙车载开发方向
7.鸿蒙南向开发方向