FlatList

用於渲染基本平面列表的高效能介面，支援最便利的功能

完全跨平台。
可選的水平模式。
可配置的可見性回呼。
標頭支援。
頁尾支援。
分隔線支援。
下拉重新整理。
滾動載入。
ScrollToIndex 支援。
多欄支援。

如果您需要區段支援，請使用 <SectionList>。

範例

TypeScript
JavaScript

若要渲染多欄，請使用 numColumns 屬性。使用此方法取代 flexWrap 版面配置可以避免與項目高度邏輯衝突。

下方有更複雜、可選取的範例。

透過將 extraData={selectedId} 傳遞給 FlatList，我們確保當狀態變更時，FlatList 本身會重新渲染。若未設定此屬性，FlatList 將不會知道它需要重新渲染任何項目，因為它是 PureComponent 且屬性比較不會顯示任何變更。
keyExtractor 告知列表使用 id 作為 React 鍵，而不是預設的 key 屬性。

TypeScript
JavaScript

這是 <VirtualizedList> 的便利包裝函式，因此繼承了其屬性（以及 <ScrollView> 的屬性），這些屬性未在此處明確列出，以及以下注意事項

當內容滾出渲染視窗時，內部狀態不會保留。請確保您的所有資料都擷取在項目資料或 Flux、Redux 或 Relay 等外部儲存區中。
這是一個 PureComponent，這表示如果 props 保持淺層相等，它將不會重新渲染。請確保您的 renderItem 函式所依賴的所有項目都作為屬性 (例如 extraData) 傳遞，該屬性在更新後不是 ===，否則您的 UI 可能不會在變更時更新。這包括 data 屬性和父組件狀態。
為了限制記憶體並啟用流暢滾動，內容會異步地在螢幕外渲染。這表示滾動速度可能快於填充率，並且可能會短暫看到空白內容。這是一種權衡，可以調整以適應每個應用程式的需求，我們正在幕後努力改進它。
預設情況下，列表會在每個項目上尋找 key 屬性，並將其用於 React 鍵。或者，您可以提供自訂的 keyExtractor 屬性。

參考

Props

VirtualizedList Props

繼承 VirtualizedList Props。

必要
`renderItem`

tsx
renderItem({
  item: ItemT,
  index: number,
  separators: {
    highlight: () => void;
    unhighlight: () => void;
    updateProps: (select: 'leading' | 'trailing', newProps: any) => void;
  }
}): JSX.Element;

從 data 中取得一個項目，並將其渲染到列表中。

如果您需要，它會提供額外的元資料，例如 index，以及更通用的 separators.updateProps 函式，讓您可以設定任何您想要的屬性，以變更前導分隔線或尾隨分隔線的渲染方式，以防更常見的 highlight 和 unhighlight（設定 highlighted: boolean 屬性）不足以滿足您的用例。

類型
function

item (Object)：正在渲染的 data 中的項目。
index (number)：此項目在 data 陣列中對應的索引。
separators (Object)
- highlight (Function)
- unhighlight (Function)
- updateProps (Function)
  - select (enum('leading', 'trailing'))
  - newProps (Object)

使用範例

tsx
<FlatList
  ItemSeparatorComponent={
    Platform.OS !== 'android' &&
    (({highlighted}) => (
      <View
        style={[style.separator, highlighted && {marginLeft: 0}]}
      />
    ))
  }
  data={[{title: 'Title Text', key: 'item1'}]}
  renderItem={({item, index, separators}) => (
    <TouchableHighlight
      key={item.key}
      onPress={() => this._onPress(item)}
      onShowUnderlay={separators.highlight}
      onHideUnderlay={separators.unhighlight}>
      <View style={{backgroundColor: 'white'}}>
        <Text>{item.title}</Text>
      </View>
    </TouchableHighlight>
  )}
/>

必要
`data`

要渲染的項目陣列（或類似陣列的列表）。其他資料類型可以直接以 VirtualizedList 為目標來使用。

類型
ArrayLike

`ItemSeparatorComponent`

在每個項目之間渲染，但不在頂部或底部渲染。預設情況下，會提供 highlighted 和 leadingItem 屬性。renderItem 提供 separators.highlight/unhighlight，這將更新 highlighted 屬性，但您也可以使用 separators.updateProps 新增自訂屬性。可以是 React 組件（例如 SomeComponent），或 React 元素（例如 <SomeComponent />）。

類型
組件、函式、元素

`ListEmptyComponent`

當列表為空時渲染。可以是 React 組件（例如 SomeComponent），或 React 元素（例如 <SomeComponent />）。

類型
組件、元素

`ListFooterComponent`

在所有項目的底部渲染。可以是 React 組件（例如 SomeComponent），或 React 元素（例如 <SomeComponent />）。

類型
組件、元素

`ListFooterComponentStyle`

ListFooterComponent 內部 View 的樣式。

類型
View 樣式

`ListHeaderComponent`

在所有項目的頂部渲染。可以是 React 組件（例如 SomeComponent），或 React 元素（例如 <SomeComponent />）。

類型
組件、元素

`ListHeaderComponentStyle`

ListHeaderComponent 內部 View 的樣式。

類型
View 樣式

`columnWrapperStyle`

當 numColumns > 1 時產生的多項目列的可選自訂樣式。

類型
View 樣式

`extraData`

用於告知列表重新渲染的標記屬性（因為它實作了 PureComponent）。如果您的任何 renderItem、Header、Footer 等函式依賴於 data 屬性之外的任何項目，請將其放在此處並以不可變的方式處理。

類型
any

`getItemLayout`

tsx
(data, index) => {length: number, offset: number, index: number}

getItemLayout 是一種可選的優化，如果您預先知道項目的大小（高度或寬度），則允許跳過動態內容的測量。例如，如果您有固定大小的項目，getItemLayout 會很有效率

tsx
  getItemLayout={(data, index) => (
    {length: ITEM_HEIGHT, offset: ITEM_HEIGHT * index, index}
  )}

新增 getItemLayout 可以大幅提升數百個項目的列表的效能。如果您指定 ItemSeparatorComponent，請記住在您的偏移計算中包含分隔線長度（高度或寬度）。

類型
function

`horizontal`

如果為 true，則水平並排渲染項目，而不是垂直堆疊。

類型
boolean

`initialNumToRender`

在初始批次中要渲染的項目數量。這應該足以填滿螢幕，但不要太多。請注意，這些項目永遠不會作為視窗化渲染的一部分卸載，以提高滾動到頂部動作的感知效能。

類型	預設
number	`10`

`initialScrollIndex`

從 initialScrollIndex 開始，而不是從頂部開始第一個項目。這會停用「滾動到頂部」的優化，該優化會使前 initialNumToRender 個項目始終渲染，並立即渲染從此初始索引開始的項目。需要實作 getItemLayout。

類型
number

`inverted`

反轉滾動方向。使用 -1 的縮放轉換。

類型
boolean

`keyExtractor`

tsx
(item: ItemT, index: number) => string;

用於為指定索引處的給定項目提取唯一鍵。鍵用於快取，並作為 React 鍵來追蹤項目重新排序。預設提取器會檢查 item.key，然後檢查 item.id，然後退回到使用索引，就像 React 一樣。

類型
function

`numColumns`

只能使用 horizontal={false} 渲染多欄，並且會像 flexWrap 版面配置一樣呈鋸齒狀。項目應全部為相同高度 - 不支援磚牆式版面配置。

類型
number

`onRefresh`

tsx
() => void;

如果提供，將新增標準 RefreshControl 以實現「下拉重新整理」功能。請確保也正確設定 refreshing 屬性。

類型
function

`onViewableItemsChanged`

當列的可見性變更時呼叫，如 viewabilityConfig 屬性所定義。

類型
`(callback: {changed: ViewToken[], viewableItems: ViewToken[]} => void;`

`progressViewOffset`

當需要偏移以正確顯示載入指示器時，請設定此項。

類型
number

`refreshing`

在等待從重新整理取得新資料時，將此項設定為 true。

類型
boolean

`removeClippedSubviews`

這可能會提高大型列表的滾動效能。在 Android 上，預設值為 true。

注意：在某些情況下可能存在錯誤（內容遺失）- 風險自負。

類型
boolean

`viewabilityConfig`

請參閱 ViewabilityHelper.js 以取得流程類型和進一步的文件。

類型
ViewabilityConfig

viewabilityConfig 採用類型 ViewabilityConfig，這是一個具有下列屬性的物件

屬性	類型
minimumViewTime	number
viewAreaCoveragePercentThreshold	number
itemVisiblePercentThreshold	number
waitForInteraction	boolean

viewAreaCoveragePercentThreshold 或 itemVisiblePercentThreshold 至少需要一個。這需要在 constructor 中完成，以避免以下錯誤 (ref)

  Error: Changing viewabilityConfig on the fly is not supported

tsx
constructor (props) {
  super(props)

  this.viewabilityConfig = {
      waitForInteraction: true,
      viewAreaCoveragePercentThreshold: 95
  }
}

tsx
<FlatList
    viewabilityConfig={this.viewabilityConfig}
  ...

minimumViewTime

項目在可見性回呼觸發之前必須實際可見的最短時間（以毫秒為單位）。較高的數字表示在不停止的情況下滾動內容將不會將內容標記為可見。

viewAreaCoveragePercentThreshold

部分遮擋的項目要計為「可見」時，必須覆蓋的視埠百分比，0-100。完全可見的項目始終被視為可見。值 0 表示視埠中的單個像素使項目可見，值 100 表示項目必須完全可見或覆蓋整個視埠才能計為可見。

itemVisiblePercentThreshold

與 viewAreaCoveragePercentThreshold 類似，但考慮的是項目可見的百分比，而不是它覆蓋的可見區域的比例。

waitForInteraction

在使用者滾動或在渲染後呼叫 recordInteraction 之前，任何項目都不會被視為可見。

`viewabilityConfigCallbackPairs`

ViewabilityConfig/onViewableItemsChanged 配對的列表。當滿足其對應 ViewabilityConfig 的條件時，將呼叫特定的 onViewableItemsChanged。請參閱 ViewabilityHelper.js 以取得流程類型和進一步的文件。

類型
ViewabilityConfigCallbackPair 的陣列

方法

`flashScrollIndicators()`

tsx
flashScrollIndicators();

短暫顯示滾動指示器。

`getNativeScrollRef()`

tsx
getNativeScrollRef(): React.ElementRef<typeof ScrollViewComponent>;

提供對底層滾動組件的參考

`getScrollResponder()`

tsx
getScrollResponder(): ScrollResponderMixin;

提供對底層滾動回應器的控制代碼。

`getScrollableNode()`

tsx
getScrollableNode(): any;

提供對底層滾動節點的控制代碼。

`scrollToEnd()`

tsx
scrollToEnd(params?: {animated?: boolean});

滾動到內容的末尾。若沒有 getItemLayout 屬性，可能會不流暢。

參數

名稱	類型
params	object

有效的 params 鍵為

'animated' (boolean) - 列表是否應在滾動時執行動畫。預設值為 true。

`scrollToIndex()`

tsx
scrollToIndex: (params: {
  index: number;
  animated?: boolean;
  viewOffset?: number;
  viewPosition?: number;
});

滾動到指定索引處的項目，使其位於可見區域中，其中 viewPosition 0 將其置於頂部，1 置於底部，0.5 置於中間。

注意：若未指定 getItemLayout 屬性，則無法滾動到渲染視窗外的位置。

參數

名稱	類型
params 必要	object

有效的 params 鍵為

'animated' (boolean) - 列表是否應在滾動時執行動畫。預設值為 true。
'index' (number) - 要滾動到的索引。必要。
'viewOffset' (number) - 用於偏移最終目標位置的固定像素數。
'viewPosition' (number) - 值 0 將索引指定的項目置於頂部，1 置於底部，0.5 置於中間。

`scrollToItem()`

tsx
scrollToItem(params: {
  animated?: ?boolean,
  item: Item,
  viewPosition?: number,
});

需要線性掃描資料 - 如果可能，請改用 scrollToIndex。

注意：若未指定 getItemLayout 屬性，則無法滾動到渲染視窗外的位置。

參數

名稱	類型
params 必要	object

有效的 params 鍵為

'animated' (boolean) - 列表是否應在滾動時執行動畫。預設值為 true。
'item' (object) - 要滾動到的項目。必要。
'viewPosition' (number)

`scrollToOffset()`

tsx
scrollToOffset(params: {
  offset: number;
  animated?: boolean;
});

滾動到列表中特定的內容像素偏移量。

參數

名稱	類型
params 必要	object

有效的 params 鍵為

'offset' (number) - 要滾動到的偏移量。如果 horizontal 為 true，則偏移量為 x 值，在任何其他情況下，偏移量為 y 值。必要。
'animated' (boolean) - 列表是否應在滾動時執行動畫。預設值為 true。

範例​

參考

Props​

VirtualizedList Props​

必要 renderItem​

必要 data​

ItemSeparatorComponent​

ListEmptyComponent​

ListFooterComponent​

ListFooterComponentStyle​

ListHeaderComponent​

ListHeaderComponentStyle​

columnWrapperStyle​

extraData​

getItemLayout​

horizontal​

initialNumToRender​

initialScrollIndex​

inverted​

keyExtractor​

numColumns​

onRefresh​

onViewableItemsChanged​

progressViewOffset​

refreshing​

removeClippedSubviews​

viewabilityConfig​

minimumViewTime​

viewAreaCoveragePercentThreshold​

itemVisiblePercentThreshold​

waitForInteraction​

viewabilityConfigCallbackPairs​

方法​

flashScrollIndicators()​

getNativeScrollRef()​

getScrollResponder()​

getScrollableNode()​

scrollToEnd()​

scrollToIndex()​

scrollToItem()​

scrollToOffset()​

範例

Props

VirtualizedList Props

必要
`renderItem`

必要
`data`

`ItemSeparatorComponent`

`ListEmptyComponent`

`ListFooterComponent`

`ListFooterComponentStyle`

`ListHeaderComponent`

`ListHeaderComponentStyle`

`columnWrapperStyle`

`extraData`

`getItemLayout`

`horizontal`

`initialNumToRender`

`initialScrollIndex`

`inverted`

`keyExtractor`

`numColumns`

`onRefresh`

`onViewableItemsChanged`

`progressViewOffset`

`refreshing`

`removeClippedSubviews`

`viewabilityConfig`

minimumViewTime

viewAreaCoveragePercentThreshold

itemVisiblePercentThreshold

waitForInteraction

`viewabilityConfigCallbackPairs`

方法

`flashScrollIndicators()`

`getNativeScrollRef()`

`getScrollResponder()`

`getScrollableNode()`

`scrollToEnd()`

`scrollToIndex()`

`scrollToItem()`

`scrollToOffset()`