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 (Object)

  • highlight (Function)
  • unhighlight (Function)
  • updateProps (Function)
    • select (enum('leading', 'trailing'))
    • newProps (Object)

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

Może to poprawić wydajność przewijania w przypadku dużych list. Domyślnie na Androidzie wartość jest ustawiona na true.

Uwaga: Może powodować błędy (brakujące treści) w niektórych sytuacjach — używaj na własne ryzyko.

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 lokalizacji poza 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 lokalizacji poza 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()

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.