VirtualizedList

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 →

Podstawowa implementacja dla wygodniejszych komponentów <FlatList> i <SectionList>, które są również lepiej udokumentowane. Ogólnie rzecz biorąc, powinieneś używać tej klasy tylko wtedy, gdy potrzebujesz większej elastyczności niż ta, którą zapewnia FlatList, np. do pracy z niezmiennymi danymi zamiast zwykłych tablic.

Wirtualizacja znacząco poprawia zużycie pamięci i wydajność dużych list poprzez utrzymywanie ograniczonego okna renderowania aktywnych elementów i zastępowanie elementów poza tym oknem odpowiednio dopasowaną pustą przestrzenią. Okno dostosowuje się do zachowania podczas przewijania, a elementy są renderowane przyrostowo z niskim priorytetem (po zakończeniu interakcji), jeśli znajdują się daleko od widocznego obszaru, lub z wysokim priorytetem w przeciwnym razie, aby zminimalizować ryzyko pojawienia się pustego miejsca.

Przykład

TypeScript

JavaScript

---

Kilka zastrzeżeń:

• 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.

• Jest to PureComponent, co oznacza, że nie zostanie ponownie wyrenderowany, jeśli props są płytko równe. Upewnij się, że wszystko, od czego zależy twoja funkcja renderItem, jest przekazywane jako właściwość (np. extraData), która nie jest === po aktualizacjach, w przeciwnym razie interfejs użytkownika może nie zaktualizować się przy zmianach. Dotyczy to również 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 ScrollView

Dziedziczy właściwości ScrollView.

---

data

Nieprzezroczysty typ danych przekazywany do getItem i getItemCount w celu pobrania elementów.

Type
any

---

Required

getItem

tsx

(data: any, index: number) => any;

Ogólna funkcja dostępu do wyciągania elementu z dowolnego rodzaju danych.

Type
function

---

Required

getItemCount

tsx

(data: any) => number;

Określa liczbę elementów w danych.

Type
function

---

Required

renderItem

tsx

(info: any) => ?React.Element<any>

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

Type
function

---

CellRendererComponent

CellRendererComponent pozwala dostosować sposób opakowywania komórek renderowanych przez renderItem/ListItemComponent po umieszczeniu w podstawowym ScrollView. Ten komponent musi akceptować procedury obsługi zdarzeń, które informują VirtualizedList o zmianach w komórce.

Type
React.ComponentType<CellRendererProps>

---

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

---

ListItemComponent

Każdy element danych jest renderowany przy użyciu tego elementu. Może to być klasa komponentu React lub funkcja renderująca.

Type
component, function

---

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	Required
ViewStyleProp	No

---

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

---

debug

debug włącza dodatkowe logowanie i nakładki wizualne pomagające w debugowaniu użycia i implementacji, ale kosztem znaczącego spadku wydajności.

Type
boolean

---

disableVirtualization

Przestarzałe. Wirtualizacja zapewnia znaczące optymalizacje wydajności i zużycia pamięci, ale całkowicie odmontowuje instancje Reacta znajdujące się poza oknem renderowania. Powinieneś wyłączać tę funkcję tylko w celach debugowania.

Type
boolean

---

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: any,
  index: number,
) => {length: number, offset: number, index: number}

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: any, 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

---

maxToRenderPerBatch

Maksymalna liczba elementów renderowanych w każdej przyrostowej partii. Im więcej renderowanych na raz, tym lepszy współczynnik wypełnienia, ale responsywność może ucierpieć, ponieważ renderowanie treści może zakłócać reagowanie na dotknięcia przycisków lub inne interakcje.

Type
number

---

onEndReached

Wywoływana raz, gdy pozycja przewijania znajdzie się w odległości onEndReachedThreshold od logicznego końca listy.

Type
(info: {distanceFromEnd: number}) => void

---

onEndReachedThreshold

Odległość (w jednostkach widocznej długości listy) końca listy od końca treści, która spowoduje wywołanie onEndReached. Na przykład wartość 0.5 wywoła onEndReached, gdy koniec treści będzie w połowie widocznej długości listy.

Type	Default
number	2

---

onRefresh

tsx

() => void;

Jeśli podana, standardowy RefreshControl zostanie dodany w celu zapewnienia funkcjonalności "Pull to Refresh". Upewnij się, że właściwość refreshing jest poprawnie ustawiona.

Type
function

---

onScrollToIndexFailed

tsx

(info: {
  index: number,
  highestMeasuredFrameIndex: number,
  averageItemLength: number,
}) => void;

Używana do obsługi błędów podczas przewijania do indeksu, który nie został jeszcze zmierzony. Zalecaną akcją jest obliczenie własnego przesunięcia i wywołanie scrollTo do niego, lub przewinięcie tak daleko jak to możliwe i ponowienie próby po wyrenderowaniu większej liczby elementów.

Type
function

---

onStartReached

Wywoływana jednorazowo, gdy pozycja przewijania znajdzie się w odległości onStartReachedThreshold od logicznego początku listy.

Type
(info: {distanceFromStart: number}) => void

---

onStartReachedThreshold

Odległość od początku (w jednostkach widocznej długości listy), na której krawędź listy musi się znaleźć względem początku zawartości, aby wywołać callback onStartReached. Wartość 0.5 spowoduje wywołanie onStartReached, gdy początek zawartości znajdzie się w połowie widocznej długości listy.

Type	Default
number	2

---

onViewableItemsChanged

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

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

---

persistentScrollbar

Type
bool

---

progressViewOffset

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

Type
number

---

refreshControl

Niestandardowy element kontroli odświeżania. Po ustawieniu zastępuje domyślny komponent <RefreshControl>. Właściwości onRefresh i refreshing są wówczas ignorowane. Działa tylko dla pionowego VirtualizedList.

Type
element

---

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

---

renderScrollComponent

tsx

(props: object) => element;

Renderuje niestandardowy komponent do przewijania, np. ze stylizowanym inaczej RefreshControl.

Type
function

---

viewabilityConfig

Zobacz ViewabilityHelper.js dla typu flow i dalszej dokumentacji.

Type
ViewabilityConfig

---

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

---

updateCellsBatchingPeriod

Czas pomiędzy partiami renderowania elementów o niskim priorytecie (np. tych daleko poza ekranem). Podobny kompromis między szybkością wypełniania a responsywnością jak w maxToRenderPerBatch.

Type
number

---

windowSize

Określa maksymalną liczbę elementów renderowanych poza widocznym obszarem, w jednostkach długości widocznych. Jeśli lista wypełnia ekran, windowSize={21} (domyślnie) spowoduje renderowanie widocznego obszaru plus do 10 ekranów powyżej i poniżej. Zmniejszenie tej liczby ograniczy zużycie pamięci i może poprawić wydajność, ale zwiększy ryzyko pojawiania się pustych obszarów przy szybkim przewijaniu.

Type
number

Metody

flashScrollIndicators()

tsx

flashScrollIndicators();

---

getScrollableNode()

tsx

getScrollableNode(): any;

---

getScrollRef()

Zwraca referencję do podstawowego komponentu przewijania.

tsx

getScrollRef():
  | React.ElementRef<typeof ScrollView>
  | React.ElementRef<typeof View>
  | null;

---

getScrollResponder()

tsx

getScrollResponder () => ScrollResponderMixin | null;

Zapewnia uchwyt do natywnego responder'a przewijania. Uwaga: this._scrollRef może nie być ScrollView, więc należy sprawdzić, czy odpowiada na getScrollResponder przed wywołaniem.

---

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) - Określa, czy lista ma animować przewijanie. Domyślnie true.

---

scrollToIndex()

tsx

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

Poprawne params składają się z:

• 'index' (number) - Wymagane.

• 'animated' (boolean) - Opcjonalne.

• 'viewOffset' (number) - Opcjonalne.

• 'viewPosition' (number) - Opcjonalne.

---

scrollToItem()

tsx

scrollToItem(params: {
  item: ItemT;
  animated?: boolean;
  viewOffset?: number;
  viewPosition?: number;
);

Poprawne params składają się z:

• 'item' (Item) - Wymagane.

• 'animated' (boolean) - Opcjonalne.

• 'viewOffset' (number) - Opcjonalne.

• 'viewPosition' (number) - Opcjonalne.

---

scrollToOffset()

tsx

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

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

Parametr offset określa przesunięcie, do którego nastąpi przewinięcie. Gdy horizontal ma wartość true, offset to wartość x, w przeciwnym przypadku to wartość y.

Parametr animated (domyślnie true) określa, czy lista ma animować przewijanie.