在鸿蒙Next开发中，ForEach接口用于循环渲染数组类型数据，与容器组件配合使用，可高效构建动态列表等UI元素。以下是ForEach用法的详细总结。
一、键值生成规则
-
系统默认规则：若开发者未定义keyGenerator函数，ArkUI框架使用默认函数
(item: Object, index: number) => { return index + '__' + JSON.stringify(item); }生成键值。 - 自定义规则：通过提供keyGenerator函数来自定义键值生成逻辑。
- 警告与限制：框架会对重复键值发出警告，重复键值可能导致UI更新异常。例如，当不同数组项按规则生成相同键值时，行为可能不符合预期。
二、组件创建规则
1. 首次渲染
- 根据键值生成规则为数据源每个数组项生成唯一键值，并创建相应组件。
- 示例：
@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)
}
}
- 上述代码中，键值生成规则为
item，为数据源数组项依次生成键值one、two和three，并创建对应的ChildItem组件渲染到界面。
2. 非首次渲染
- 检查新生成键值是否在上次渲染中已存在。若不存在，则创建新组件；若存在，则复用对应组件。
- 示例：
@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)
}
}
- 点击修改数组项值后，ForEach遍历新数据源
['one', 'two', 'new three']，键值one和two已存在，复用对应组件，而new three键值不存在，创建新组件。
三、使用场景
1. 数据源不变
- 数据源可直接采用基本数据类型，如使用骨架屏列表渲染展示页面加载状态。
- 示例：
@Entry
@Component
struct ArticleList {
@State simpleList: Array<number> = [1, 2, 3, 4, 5];
build() {
Column() {
ForEach(this.simpleList, (item: number ) => {
ArticleSkeletonView()
.margin({ top: 20 })
}, (item: number) => item.toString())
}
.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)
}
}
2. 数据源数组项发生变化
- 如进行数组插入、删除操作或数组项索引交换，数据源应为对象数组类型，使用对象唯一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)
}
}
3. 数据源数组项子属性变化
- 当数据源为对象数组且仅修改数组项属性值时，需结合
@Observed和@ObjectLink装饰器使用，以使ForEach重新渲染。 - 示例：
@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)
}
}
4. 拖拽排序
- 当ForEach在
List组件下使用且设置onMove事件，每次迭代生成ListItem时，可实现拖拽排序。数据源修改前后要保持数据键值不变，仅顺序变化，以保证落位动画正常执行。 - 示例：
@Entry
@Component
struct ForEachSort {
@State arr: Array<string> = [];
build() {
Row() {
List() {
ForEach(this.arr, (item: string ) => {
ListItem() {
Text(item.toString())
.fontSize(16)
.textAlign(TextAlign.Center)
.size({height: 100, width: "100%"})
}.margin(10)
.borderRadius(10)
.backgroundColor("#FFFFFFFF")
}, (item: string) => item)
.onMove((from:number, to:number) => {
let tmp = this.arr.splice(from, 1);
this.arr.splice(to, 0, tmp[0])
})
}
.width('100%')
.height('100%')
.backgroundColor("#FFDCDCDC")
}
}
aboutToAppear(): void {
for (let i = 0; i < 100; i++) {
this.arr.push(i.toString())
}
}
}
四、使用建议
-
键值选择：对于对象数据类型，建议使用对象唯一ID作为键值。避免在最终键值生成规则中包含数据项索引
index，除非业务必需，因包含index可能导致渲染结果非预期和性能降低。 - 数据类型转换：基本数据类型数组在数据源会变化的场景下，建议转换为具备唯一ID属性的对象数据类型数组，并使用ID属性作为键值生成规则。
-
容器组件使用限制：ForEach在
List、Grid、Swiper、WaterFlow等容器组件内使用时，不要与LazyForEach混用。
五、常见问题
1. 渲染结果非预期
- 若最终键值生成规则包含
index，可能出现渲染结果不符合预期的情况。如在特定示例中，插入新项后渲染结果与期望不符。
2. 渲染性能降低
- 若使用框架默认键值生成规则（包含
index），在数据源变化时可能导致组件大量重新创建，影响性能。例如，插入新数组项时，后面所有数组项对应的组件可能都需重新创建，当数据量较大或组件结构复杂时，性能体验不佳。
掌握ForEach的用法和相关注意事项，有助于在鸿蒙Next开发中高效构建动态UI，提升应用性能和用户体验。
