FlatList

Nieoficjalne Tłumaczenie Beta

Ta strona została przetłumaczona przez PageTurner AI (beta). Nie jest oficjalnie zatwierdzona przez projekt. Znalazłeś błąd? Zgłoś problem →

Wydajny interfejs do renderowania podstawowych, płaskich list, obsługujący najbardziej przydatne funkcje:

W pełni wieloplatformowy.
Opcjonalny tryb poziomy.
Konfigurowalne callbacki widoczności.
Obsługa nagłówka.
Obsługa stopki.
Obsługa separatorów.
Pull to Refresh (przeciągnij, aby odświeżyć).
Ładowanie podczas przewijania.
Obsługa ScrollToIndex.
Obsługa wielu kolumn.

Jeśli potrzebujesz obsługi sekcji, użyj <SectionList>.

Przykład

TypeScript
JavaScript

Aby renderować wiele kolumn, użyj właściwości numColumns. To podejście zapobiega konfliktom z logiką wysokości elementów, które mogą wystąpić przy układzie flexWrap.

Poniżej znajduje się bardziej złożony przykład z możliwością wyboru.

Przekazując extraData={selectedId} do FlatList, zapewniamy, że sam FlatList zostanie ponownie wyrenderowany przy zmianie stanu. Bez tej właściwości FlatList (jako PureComponent) nie wykryłby potrzeby aktualizacji elementów, ponieważ porównanie właściwości nie wykazałoby różnic.
keyExtractor informuje listę, aby używała id jako kluczy Reacta zamiast domyślnej właściwości key.

TypeScript
JavaScript

Jest to wygodne opakowanie <VirtualizedList>, dlatego dziedziczy jej właściwości (oraz właściwości <ScrollView>) niewymienione tutaj, wraz z następującymi zastrzeżeniami:

Stan wewnętrzny nie jest zachowywany, gdy treść znika z okna renderowania. Przechowuj wszystkie dane w elementach lub zewnętrznych magazynach jak Flux, Redux czy Relay.
Jako PureComponent, nie renderuje się ponownie przy płytko równych props. Upewnij się, że wszystkie zależności funkcji renderItem są przekazywane przez właściwość (np. extraData), która nie jest === po aktualizacjach. Dotyczy to także właściwości data i stanu komponentu nadrzędnego.
Dla oszczędności pamięci i płynności przewijania, treść renderowana jest asynchronicznie poza ekranem. Może to powodować chwilowe puste miejsca przy szybkim przewijaniu. To kompromis dostosowywany do potrzeb aplikacji, nad którym aktywnie pracujemy.
Domyślnie lista używa właściwości key elementów jako kluczy Reacta. Alternatywnie możesz podać własną funkcję keyExtractor.

Dokumentacja

Właściwości

Właściwości VirtualizedList

Dziedziczy właściwości VirtualizedList.

Required
`renderItem`

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

Przyjmuje element z data i renderuje go na liście.

Dostarcza metadane jak index oraz funkcję separators.updateProps, która pozwala modyfikować właściwości separatorów, gdy standardowe highlight/unhighlight (ustawiające highlighted: boolean) są niewystarczające.

Type
function

item (Object): Renderowany element z data.
index (number): Indeks elementu w tablicy data.
separators (Obiekt)
- highlight (Funkcja)
- unhighlight (Funkcja)
- updateProps (Funkcja)
  - select (enum('leading', 'trailing'))
  - newProps (Obiekt)

Przykład użycia:

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>
  )}
/>

Required
`data`

Tablica (lub lista podobna do tablicy) elementów do wyrenderowania. Inne typy danych mogą być użyte poprzez bezpośrednie zastosowanie VirtualizedList.

Type
ArrayLike

`ItemSeparatorComponent`

Renderowany pomiędzy każdym elementem, ale nie na górze ani na dole. Domyślnie dostarczane są właściwości highlighted i leadingItem. renderItem dostarcza separators.highlight/unhighlight, które aktualizują właściwość highlighted, ale możesz także dodać własne właściwości za pomocą separators.updateProps. Może to być komponent Reacta (np. SomeComponent) lub element Reacta (np. <SomeComponent />).

Type
component, function, element

`ListEmptyComponent`

Renderowany, gdy lista jest pusta. Może to być komponent Reacta (np. SomeComponent) lub element Reacta (np. <SomeComponent />).

Type
component, element

`ListFooterComponent`

Renderowany na dole wszystkich elementów. Może to być komponent Reacta (np. SomeComponent) lub element Reacta (np. <SomeComponent />).

Type
component, element

`ListFooterComponentStyle`

Stylizacja wewnętrznego View dla ListFooterComponent.

Type
View Style

`ListHeaderComponent`

Renderowany na górze wszystkich elementów. Może to być komponent Reacta (np. SomeComponent) lub element Reacta (np. <SomeComponent />).

Type
component, element

`ListHeaderComponentStyle`

Stylizacja wewnętrznego View dla ListHeaderComponent.

Type
View Style

`columnWrapperStyle`

Opcjonalny niestandardowy styl dla wielokolumnowych wierszy generowanych przy numColumns > 1.

Type
View Style

`extraData`

Właściwość znacznikowa informująca listę o konieczności ponownego renderowania (ponieważ implementuje PureComponent). Jeśli jakakolwiek funkcja renderItem, Header, Footer itp. zależy od czegokolwiek poza właściwością data, umieść to tutaj i traktuj jako niemutowalne.

Type
any

`getItemLayout`

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

getItemLayout to opcjonalna optymalizacja pozwalająca pominąć pomiar dynamicznej zawartości, jeśli znasz rozmiar (wysokość lub szerokość) elementów z góry. getItemLayout jest wydajne dla elementów o stałym rozmiarze, np.:

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

Dodanie getItemLayout może znacznie zwiększyć wydajność dla list z setkami elementów. Pamiętaj o uwzględnieniu długości separatora (wysokości/szerokości) w obliczeniach offsetu, jeśli określisz ItemSeparatorComponent.

Type
function

`horizontal`

Jeśli true, elementy renderowane są poziomo obok siebie zamiast pionowo.

Type
boolean

`initialNumToRender`

Liczba elementów renderowanych w początowej partii. Powinna wypełniać ekran, ale nie znacznie więcej. Te elementy nigdy nie są odmontowywane (dla poprawy wydajności przewijania na górę).

Type	Default
number	`10`

`initialScrollIndex`

Rozpoczyna renderowanie od initialScrollIndex zamiast pierwszego elementu. Wyłącza optymalizację "przewijania na górę", która utrzymuje pierwsze initialNumToRender elementów stale renderowanymi, i natychmiast renderuje elementy zaczynając od tego początkowego indeksu. Wymaga implementacji getItemLayout.

Type
number

`inverted`

Odwraca kierunek przewijania. Stosuje transformację skali -1.

Type
boolean

`keyExtractor`

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

Funkcja wyciągająca unikalny klucz dla elementu pod określonym indeksem. Domyślnie sprawdza item.key, potem item.id, a na końcu używa indeksu (jak React).

Type
function

`numColumns`

Wiele kolumn może być renderowanych tylko z horizontal={false} i będą one układać się zygzakowato, podobnie jak w układzie flexWrap. Wszystkie elementy powinny mieć tę samą wysokość - układanie w stylu masonry nie jest obsługiwane.

Type
number

`onRefresh`

tsx
() => void;

Jeśli podana, standardowa kontrolka RefreshControl zostanie dodana do funkcjonalności "Pull to Refresh" (przeciągnij, aby odświeżyć). Upewnij się, że poprawnie ustawiłeś właściwość refreshing.

Type
function

`onViewableItemsChanged`

Wywoływana, gdy zmienia się widoczność wierszy, zgodnie z definicją we właściwości viewabilityConfig.

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

`progressViewOffset`

Ustaw tę wartość, gdy potrzebne jest przesunięcie, aby wskaźnik ładowania wyświetlał się poprawnie.

Type
number

`refreshing`

Ustaw na true podczas oczekiwania na nowe dane przy odświeżaniu.

Type
boolean

`removeClippedSubviews`

ostrzeżenie

Użycie tej właściwości może prowadzić do błędów (brakującej treści) w niektórych okolicznościach - używasz na własne ryzyko.

Gdy true, widżety potomne znajdujące się poza ekranem są usuwane z natywnego widoku nadrzędnego. Może to poprawić wydajność przewijania w przypadku dużych list. Domyślnie na Androidzie wartość ta wynosi true.

Type
boolean

`viewabilityConfig`

Zobacz ViewabilityHelper.js dla typu flow i dalszej dokumentacji.

Type
ViewabilityConfig

viewabilityConfig przyjmuje typ ViewabilityConfig - obiekt z następującymi właściwościami:

Property	Type
minimumViewTime	number
viewAreaCoveragePercentThreshold	number
itemVisiblePercentThreshold	number
waitForInteraction	boolean

Wymagane jest przynajmniej jedno z viewAreaCoveragePercentThreshold lub itemVisiblePercentThreshold. Należy to zrobić w constructor, aby uniknąć błędu (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

Minimalny czas (w milisekundach), przez który element musi być fizycznie widoczny, zanim wywołane zostanie callback widoczności. Wysoka wartość oznacza, że przewijanie bez zatrzymania nie oznaczy treści jako widocznej.

viewAreaCoveragePercentThreshold

Procent obszaru widoku, który musi być pokryty, aby częściowo zasłonięty element został uznany za "widoczny" (0-100). Całkowicie widoczne elementy zawsze są uznawane za widoczne. Wartość 0 oznacza, że widoczny pojedynczy piksel wystarczy, a 100 oznacza, że element musi być całkowicie widoczny lub pokrywać cały obszar widoku.

itemVisiblePercentThreshold

Podobne do viewAreaCoveragePercentThreshold, ale uwzględnia procent widoczności elementu zamiast frakcji pokrywanego obszaru.

waitForInteraction

Żaden element nie jest uznawany za widoczny dopóki użytkownik nie przesunie lub nie wywoła recordInteraction po renderowaniu.

`viewabilityConfigCallbackPairs`

Lista par ViewabilityConfig/onViewableItemsChanged. Określony onViewableItemsChanged zostanie wywołany, gdy spełnione zostaną warunki odpowiadającej konfiguracji ViewabilityConfig. Zobacz ViewabilityHelper.js dla typu flow i dalszej dokumentacji.

Type
array of ViewabilityConfigCallbackPair

Metody

`flashScrollIndicators()`

tsx
flashScrollIndicators();

Wyświetla tymczasowo wskaźniki przewijania.

`getNativeScrollRef()`

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

Dostarcza referencję do natywnego komponentu przewijania.

`getScrollResponder()`

tsx
getScrollResponder(): ScrollResponderMixin;

Dostarcza uchwyt do natywnego respondera przewijania.

`getScrollableNode()`

tsx
getScrollableNode(): any;

Dostarcza uchwyt do natywnego węzła przewijania.

`scrollToEnd()`

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

Przewija do końca zawartości. Może działać szarpnięciami bez właściwości getItemLayout.

Parametry:

Name	Type
params	object

Prawidłowe klucze w params:

'animated' (boolean) - Czy lista powinna animować się podczas przewijania. Domyślnie true.

`scrollToIndex()`

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

Przewija do elementu o podanym indeksie, umieszczając go w widocznym obszarze: wartość viewPosition 0 ustawia element u góry, 1 na dole, a 0.5 na środku.

uwaga

Bez podania właściwości getItemLayout nie można przewinąć do pozycji poza aktualnym oknem renderowania.

Parametry:

Name	Type
params Required	object

Prawidłowe klucze w params:

'animated' (boolean) - Czy lista powinna animować się podczas przewijania. Domyślnie true.
'index' (number) - Indeks, do którego przewinąć. Wymagane.
'viewOffset' (number) - Stałe przesunięcie w pikselach od docelowej pozycji.
'viewPosition' (number) - Wartość 0 umieszcza element u góry, 1 na dole, 0.5 na środku.

`scrollToItem()`

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

Wymaga liniowego przeszukania danych - jeśli możliwe, używaj scrollToIndex.

uwaga

Bez podania właściwości getItemLayout nie można przewinąć do pozycji poza aktualnym oknem renderowania.

Parametry:

Name	Type
params Required	object

Prawidłowe klucze w params:

'animated' (boolean) - Czy lista powinna animować się podczas przewijania. Domyślnie true.
'item' (object) - Element, do którego przewinąć. Wymagane.
'viewPosition' (number)

`scrollToOffset()`

Przewija do określonego przesunięcia w pikselach zawartości listy. Sprawdź również scrollToOffset w VirtualizedList.

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

Przewija do określonego przesunięcia w pikselach w zawartości listy.

Parametry:

Name	Type
params Required	object

Prawidłowe klucze w params:

'offset' (number) - Przesunięcie do którego przewinąć. Gdy horizontal jest true, to wartość na osi X, w przeciwnym razie na osi Y. Wymagane.
'animated' (boolean) - Czy lista powinna animować się podczas przewijania. Domyślnie true.

Przykład​

Dokumentacja

Właściwości​

Właściwości VirtualizedList​

Required renderItem​

Required 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​

Metody​

flashScrollIndicators()​

getNativeScrollRef()​

getScrollResponder()​

getScrollableNode()​

scrollToEnd()​

scrollToIndex()​

scrollToItem()​

scrollToOffset()​

Przykład

Właściwości

Właściwości VirtualizedList

Required
`renderItem`

Required
`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`

Metody

`flashScrollIndicators()`

`getNativeScrollRef()`

`getScrollResponder()`

`getScrollableNode()`

`scrollToEnd()`

`scrollToIndex()`

`scrollToItem()`

`scrollToOffset()`