ForEach基于數(shù)組類型數(shù)據(jù)執(zhí)行循環(huán)渲染。說明，從API version 9開始，該接口支持在ArkTS卡片中使用。
一、接口描述

ForEach(arr: any[], itemGenerator: (item: any, index?: number) => void,keyGenerator?: (item: any, index?: number) => string 
)

二、使用限制
ForEach必須在容器組件內(nèi)使用。
生成的子組件應(yīng)當(dāng)是允許包含在ForEach父容器組件中的子組件。
允許子組件生成器函數(shù)中包含if/else條件渲染，同時也允許ForEach包含在if/else條件渲染語句中。
itemGenerator函數(shù)的調(diào)用順序不一定和數(shù)組中的數(shù)據(jù)項相同，在開發(fā)過程中不要假設(shè)itemGenerator和keyGenerator函數(shù)是否執(zhí)行及其執(zhí)行順序。例如，以下示例可能無法正確運行

ForEach(anArray.map((item1, index1) => { return { i: index1 + 1, data: item1 }; }), item => Text(`${item.i}. item.data.label`),item => item.data.id.toString())

三、開發(fā)者的建議
建議開發(fā)者不要假設(shè)項構(gòu)造函數(shù)的執(zhí)行順序。執(zhí)行順序可能不能是數(shù)組中項的排列順序。
不要假設(shè)數(shù)組項是否是初始渲染。ForEach的初始渲染在@Component首次渲染時構(gòu)建所有數(shù)組項。后續(xù)框架版本中可能會將此行為更改為延遲加載模式。
使用 index參數(shù)對UI更新性能有嚴重的負面影響，請盡量避免。
如果項構(gòu)造函數(shù)中使用index參數(shù)，則項索引函數(shù)中也必須使用該參數(shù)。否則，如果項索引函數(shù)未使用index參數(shù)，ForEach在生成實際的鍵值時，框架也會把index考慮進來，默認將index拼接在后面。
四、使用場景
1.簡單ForEach示例
根據(jù)arr數(shù)據(jù)分別創(chuàng)建3個Text和Divide組件。

@Entry
@Component
struct MyComponent {@State arr: number[] = [10, 20, 30];build() {Column({ space: 5 }) {Button('Reverse Array').onClick(() => {this.arr.reverse();})ForEach(this.arr, (item: number) => {Text(`item value: ${item}`).fontSize(18)Divider().strokeWidth(2)}, (item: number) => item.toString())}}
}

2.復(fù)雜ForEach示例

@Component
struct CounterView {label: string;@State count: number = 0;build() {Button(`${this.label}-${this.count} click +1`).width(300).height(40).backgroundColor('#a0ffa0').onClick(() => {this.count++;})}
}@Entry
@Component
struct MainView {@State arr: number[] = Array.from(Array(10).keys()); // [0.,.9]nextUnused: number = this.arr.length;build() {Column() {Button(`push new item`).onClick(() => {this.arr.push(this.nextUnused++)}).width(300).height(40)Button(`pop last item`).onClick(() => {this.arr.pop()}).width(300).height(40)Button(`prepend new item (unshift)`).onClick(() => {this.arr.unshift(this.nextUnused++)}).width(300).height(40)Button(`remove first item (shift)`).onClick(() => {this.arr.shift()}).width(300).height(40)Button(`insert at pos ${Math.floor(this.arr.length / 2)}`).onClick(() => {this.arr.splice(Math.floor(this.arr.length / 2), 0, this.nextUnused++);}).width(300).height(40)Button(`remove at pos ${Math.floor(this.arr.length / 2)}`).onClick(() => {this.arr.splice(Math.floor(this.arr.length / 2), 1);}).width(300).height(40)Button(`set at pos ${Math.floor(this.arr.length / 2)} to ${this.nextUnused}`).onClick(() => {this.arr[Math.floor(this.arr.length / 2)] = this.nextUnused++;}).width(300).height(40)ForEach(this.arr,(item) => {CounterView({ label: item.toString() })},(item) => item.toString())}}

MainView擁有一個@State裝飾的數(shù)字數(shù)組。添加、刪除和替換數(shù)組項是可觀察到的變化事件，當(dāng)這些事件發(fā)生時，MainView內(nèi)的ForEach都會更新。
項目索引函數(shù)為每個數(shù)組項創(chuàng)建唯一且持久的鍵值，ArkUI框架通過此鍵值確定數(shù)組中的項是否有變化，只要鍵值相同，數(shù)組項的值就假定不變，但其索引位置可能會更改。此機制的運行前提是不同的數(shù)組項不能有相同的鍵值。
使用計算出的ID，框架可以對添加、刪除和保留的數(shù)組項加以區(qū)分：
（1）框架將刪除已刪除數(shù)組項的UI組件。
（2）框架僅對新添加的數(shù)組項執(zhí)行項構(gòu)造函數(shù)。
（3）框架不會為保留的數(shù)組項執(zhí)行項構(gòu)造函數(shù)。如果數(shù)組中的項索引已更改，框架將僅根據(jù)新順序移動其UI組件，但不會更新該UI組件。
建議使用項目索引函數(shù)，但這是可選的。生成的ID必須是唯一的，這意味著不能為數(shù)組中的不同項計算出相同的ID。即使兩個數(shù)組項具有相同的值，其ID也必須不同。
如果數(shù)組項值更改，則ID必須更改。
示例：如前所述，id生成函數(shù)是可選的。以下是不帶項索引函數(shù)的ForEach：
ForEach(this.arr,
(item) => {
CounterView({ label: item.toString() })
}
)
如果沒有提供項ID函數(shù)，則框架會嘗試在更新ForEach時智能檢測數(shù)組更改。但是，它可能會刪除子組件，并為在數(shù)組中移動（索引被更改）的數(shù)組項重新執(zhí)行項構(gòu)造函數(shù)。在上面的示例中，這將更改應(yīng)用程序針對CounterView counter狀態(tài)的行為。創(chuàng)建新的CounterView實例時，counter的值將初始化為0。
3.使用@ObjectLink的ForEach示例
當(dāng)需要保留重復(fù)子組件的狀態(tài)時，@ObjectLink可將狀態(tài)在組件樹中向父組件推送。

let NextID: number = 0;@Observed
class MyCounter {public id: number;public c: number;constructor(c: number) {this.id = NextID++;this.c = c;}
}@Component
struct CounterView {@ObjectLink counter: MyCounter;label: string = 'CounterView';build() {Button(`CounterView [${this.label}] this.counter.c=${this.counter.c} +1`).width(200).height(50).onClick(() => {this.counter.c += 1;})}
}@Entry
@Component
struct MainView {@State firstIndex: number = 0;@State counters: Array<MyCounter> = [new MyCounter(0), new MyCounter(0), new MyCounter(0),new MyCounter(0), new MyCounter(0)];build() {Column() {ForEach(this.counters.slice(this.firstIndex, this.firstIndex + 3),(item) => {CounterView({ label: `Counter item #${item.id}`, counter: item })},(item) => item.id.toString())Button(`Counters: shift up`).width(200).height(50).onClick(() => {this.firstIndex = Math.min(this.firstIndex + 1, this.counters.length - 3);})Button(`counters: shift down`).width(200).height(50).onClick(() => {this.firstIndex = Math.max(0, this.firstIndex - 1);})}}
}

當(dāng)增加firstIndex的值時，Mainview內(nèi)的ForEach將更新，并刪除與項ID firstIndex-1關(guān)聯(lián)的CounterView子組件。對于ID為firstindex + 3的數(shù)組項，將創(chuàng)建新的CounterView子組件實例。由于CounterView子組件的狀態(tài)變量counter值由父組件Mainview維護，故重建CounterView子組件實例不會重建狀態(tài)變量counter值。
說明，違反上述數(shù)組項ID規(guī)則是最常見的應(yīng)用開發(fā)錯誤，尤其是在Array場景下，因為執(zhí)行過程中很容易添加重復(fù)的數(shù)字。
4.ForEach的嵌套使用
允許將ForEach嵌套在同一組件中的另一個ForEach中，但更推薦將組件拆分為兩個，每個構(gòu)造函數(shù)只包含一個ForEach。下面為ForEach嵌套使用反例。

class Month {year: number;month: number;days: number[];constructor(year: number, month: number, days: number[]) {this.year = year;this.month = month;this.days = days;}
}
@Component
struct CalendarExample {// 模擬6個月@State calendar : Month[] = [new Month(2020, 1, [...Array(31).keys()]),new Month(2020, 2, [...Array(28).keys()]),new Month(2020, 3, [...Array(31).keys()]),new Month(2020, 4, [...Array(30).keys()]),new Month(2020, 5, [...Array(31).keys()]),new Month(2020, 6, [...Array(30).keys()])]build() {Column() {Button() {Text('next month')}.onClick(() => {this.calendar.shift()this.calendar.push(new Month(year: 2020, month: 7, days: [...Array(31).keys()]))})ForEach(this.calendar,(item: Month) => {ForEach(item.days,(day : number) => {// 構(gòu)建日期塊},(day : number) => day.toString())// 內(nèi)部ForEach},(item: Month) => (item.year * 12 + item.month).toString() // 字段與年和月一起使用，作為月份的唯一ID。)// 外部ForEach}}
}

以上示例存在兩個問題：
（1）代碼可讀性差。
（2）對于上述的年月份數(shù)據(jù)的數(shù)組結(jié)構(gòu)形式，由于框架無法觀察到針對該數(shù)組中Month數(shù)據(jù)結(jié)構(gòu)的改變（比如day數(shù)組變化），從而內(nèi)層的ForEach無法刷新日期顯示。
建議應(yīng)用設(shè)計時將Calendar拆分為Year、Month和Day子組件。定義一個“Day”模型類，以保存有關(guān)day的信息，并用@Observed裝飾此類。DayView組件利用ObjectLink裝飾變量以綁定day數(shù)據(jù)。對MonthView和Month模型類執(zhí)行同樣的操作。
5.ForEach中使用可選index參數(shù)示例
可以在構(gòu)造函數(shù)和ID生成函數(shù)中使用可選的index參數(shù)。

@Entry
@Component
struct ForEachWithIndex {@State arr: number[] = [4, 3, 1, 5];build() {Column() {ForEach(this.arr,(it, indx) => {Text(`Item: ${indx} - ${it}`)},(it, indx) => {return `${indx} - ${it}`})}}
}

必須正確構(gòu)造ID生成函數(shù)。當(dāng)在項構(gòu)造函數(shù)中使用index參數(shù)時，ID生成函數(shù)也必須使用index參數(shù)，以生成唯一ID和給定源數(shù)組項的ID。當(dāng)數(shù)組項在數(shù)組中的索引位置發(fā)生變化時，其ID會發(fā)生變化。
此示例還說明了index參數(shù)會造成顯著性能下降。即使項在源數(shù)組中移動而不做修改，因為索引發(fā)生改變，依賴該數(shù)組項的UI仍然需要重新渲染。例如，使用索引排序時，數(shù)組只需要將ForEach未修改的子UI節(jié)點移動到正確的位置，這對于框架來說是一個輕量級操作。而使用索引時，所有子UI節(jié)點都需要重新構(gòu)建，這操作負擔(dān)要重得多。

?