FlatList

基本的なフラットリストを描画するための高パフォーマンスなインターフェースで、最も便利な機能をサポートしています。

完全なクロスプラットフォーム。
オプションの水平モード。
設定可能なビューアビリティコールバック。
ヘッダーのサポート。
フッターのサポート。
セパレーターのサポート。
Pull to Refresh (引っ張って更新)。
スクロールローディング。
ScrollToIndex のサポート。
複数カラムのサポート。

セクションのサポートが必要な場合は、<SectionList> を使用してください。

使用例

TypeScript
JavaScript

複数カラムを描画するには、numColumns prop を使用します。flexWrap レイアウトの代わりこのアプローチを使用すると、アイテムの高さのロジックとの競合を防ぐことができます。

以下は、より複雑で選択可能な例です。

FlatList に extraData={selectedId} を渡すことで、state が変更されたときに FlatList 自体が再描画されるようにします。この prop を設定しないと、FlatList は PureComponent であり、prop の比較では変更が示されないため、アイテムを再描画する必要があることを知りません。
keyExtractor は、デフォルトの key プロパティの代わりに、React のキーとして id を使用するようにリストに指示します。

TypeScript
JavaScript

これは <VirtualizedList> の便利なラッパーであり、そのため、ここに明示的にリストされていない prop（および <ScrollView> の prop）を継承しますが、以下の注意点があります。

コンテンツがレンダーウィンドウの外にスクロールされると、内部の状態は保持されません。すべてのデータが項目データまたはFlux、Redux、Relayのような外部ストアにキャプチャされていることを確認してください。
これは PureComponent であり、props が浅い比較で等しいままであれば再描画されません。renderItem 関数が依存するものはすべて、更新後に === とならない prop（例：extraData）として渡すようにしてください。そうしないと、変更時に UI が更新されない可能性があります。これには data prop と親コンポーネントの state が含まれます。
メモリを制限し、スムーズなスクロールを可能にするために、コンテンツは画面外で非同期に描画されます。これは、フィルレートよりも速くスクロールすると、一時的に空白のコンテンツが表示される可能性があることを意味します。これは各アプリケーションのニーズに合わせて調整できるトレードオフであり、私たちは舞台裏でこれを改善するために取り組んでいます。
デフォルトでは、リストは各項目の 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 prop を設定する) がユースケースに不十分な場合に、先行セパレーターまたは後続セパレーターのいずれかの描画を変更するために必要な prop を設定できます。

型
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 props が提供されます。renderItem は highlighted prop を更新する separators.highlight/unhighlight を提供しますが、separators.updateProps を使ってカスタム prop を追加することもできます。React コンポーネント (例: SomeComponent) または React 要素 (例: <SomeComponent />) を指定できます。

型
component, function, element

`ListEmptyComponent`

リストが空のときにレンダリングされます。Reactコンポーネント（例：SomeComponent）またはReact要素（例：<SomeComponent />）を指定できます。

型
component, element

`ListFooterComponent`

すべてのアイテムの一番下に描画されます。React コンポーネント (例: SomeComponent) または React 要素 (例: <SomeComponent />) を指定できます。

型
component, element

`ListFooterComponentStyle`

ListFooterComponent の内部 View のスタイル。

型
View Style

`ListHeaderComponent`

すべてのアイテムの一番上に描画されます。React コンポーネント (例: SomeComponent) または React 要素 (例: <SomeComponent />) を指定できます。

型
component, element

`ListHeaderComponentStyle`

ListHeaderComponent の内部 View のスタイル。

型
View Style

`columnWrapperStyle`

numColumns > 1 のときに生成される複数アイテムの行に対するオプションのカスタムスタイル。

型
View Style

`extraData`

リストに再描画を指示するためのマーカープロパティ（PureComponent を実装しているため）。renderItem、Header、Footerなどの関数が data prop 以外の何かに依存している場合は、それをここに設定し、不変 (immutable) として扱います。

型
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;

提供された場合、「Pull to Refresh」機能のために標準の RefreshControl が追加されます。refreshing prop も正しく設定するようにしてください。

型
function

`onViewableItemsChanged`

viewabilityConfig プロップで定義された行の可視性が変更されたときに呼び出されます。

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

`progressViewOffset`

ローディングインジケーターを正しく表示するためにオフセットが必要な場合に設定します。

型
number

`refreshing`

更新による新しいデータを待っている間、これをtrueに設定します。

型
boolean

`removeClippedSubviews`

これにより、大きなリストのスクロールパフォーマンスが向上する可能性があります。Android ではデフォルト値は true です。

注意：一部の状況でバグ（コンテンツの欠落）が発生する可能性があります - 自己責任で使用してください。

型
boolean

`viewabilityConfig`

flow 型と詳細なドキュメントについては、ViewabilityHelper.js を参照してください。

型
ViewabilityConfig

viewabilityConfig は、次のプロパティを持つオブジェクトである ViewabilityConfig 型を取ります。

プロパティ	型
minimumViewTime	number
viewAreaCoveragePercentThreshold	number
itemVisiblePercentThreshold	number
waitForInteraction	boolean

viewAreaCoveragePercentThreshold または itemVisiblePercentThreshold の少なくとも1つが必要です。これは、次のエラーを避けるために constructor で行う必要があります (参照)。

  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 は、ビューポート内の 1 ピクセルでアイテムが表示可能になることを意味し、値 100 は、アイテムが完全に表示されているか、ビューポート全体をカバーしている場合に表示可能とカウントされることを意味します。

itemVisiblePercentThreshold

viewAreaCoveragePercentThreshold と似ていますが、表示領域をカバーする割合ではなく、アイテムが表示されている割合を考慮します。

waitForInteraction

ユーザーがスクロールするか、描画後に recordInteraction が呼び出されるまで、何も表示可能とは見なされません。

`viewabilityConfigCallbackPairs`

ViewabilityConfig/onViewableItemsChanged のペアのリスト。対応する ViewabilityConfig の条件が満たされると、特定の onViewableItemsChanged が呼び出されます。flow 型と詳細なドキュメントについては、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 prop がないと、カクカクすることがあります。

パラメータ

名前	型
params	object

有効な params のキーは以下の通りです

'animated' (boolean) - スクロール中にリストがアニメーションを実行するかどうか。デフォルトは true です。

`scrollToIndex()`

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

指定されたインデックスのアイテムにスクロールし、viewPosition 0 が一番上、1 が一番下、0.5 が中央になるように表示領域に配置します。

注意：getItemLayout prop を指定しないと、描画ウィンドウ外の場所にスクロールすることはできません。

パラメータ

名前	型
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 prop を指定しないと、描画ウィンドウ外の場所にスクロールすることはできません。

パラメータ

名前	型
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()`