ScrollView

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 →

Komponent opakowujący natywny ScrollView platformy, zapewniający integrację z systemem "responderów" blokujących dotyk.

Pamiętaj, że ScrollView musi mieć ograniczoną wysokość, aby działać poprawnie, ponieważ zawiera dzieci o nieograniczonej wysokości w ograniczonym kontenerze (poprzez interakcję przewijania). Aby ograniczyć wysokość ScrollView, możesz bezpośrednio ustawić wysokość widoku (niezalecane) lub upewnić się, że wszystkie widoki nadrzędne mają ograniczoną wysokość. Zapomnienie o przekazaniu {flex: 1} w dół hierarchii widoków może prowadzić do błędów, które inspektor elementów pozwala szybko zdebugować.

Nie obsługuje jeszcze blokowania innych responderów, które uniemożliwiałyby temu ScrollView zostanie responderem.

<ScrollView> kontra <FlatList> - którego użyć?

ScrollView renderuje wszystkie swoje komponenty potomne jednocześnie, co ma negatywny wpływ na wydajność.

Wyobraź sobie, że masz bardzo długą listę elementów do wyświetlenia, być może zawierającą treść o rozmiarze kilku ekranów. Tworzenie komponentów JS i natywnych widoków dla wszystkich elementów na raz, z których wiele może nigdy nie zostać wyświetlonych, przyczyni się do wolnego renderowania i zwiększonego zużycia pamięci.

Tutaj wkracza FlatList. FlatList renderuje elementy leniwie, gdy mają się pojawić na ekranie, i usuwa elementy, które przewiną się poza ekran, aby oszczędzać pamięć i czas procesora.

FlatList jest również przydatny, jeśli chcesz renderować separatory między elementami, wiele kolumn, nieskończone ładowanie podczas przewijania lub wiele innych funkcji, które obsługuje od ręki.

Przykład

---

Dokumentacja

Właściwości

Właściwości widoku

Dziedziczy właściwości widoku.

---

StickyHeaderComponent

Komponent React używany do renderowania przyklejonych nagłówków, powinien być używany razem z stickyHeaderIndices. Może być potrzebny, jeśli twój przyklejony nagłówek używa niestandardowych transformacji, na przykład gdy chcesz, aby lista miała animowany i chowalny nagłówek. Jeśli komponent nie został podany, zostanie użyty domyślny komponent ScrollViewStickyHeader.

Type
component, element

---

alwaysBounceHorizontal

iOS

Gdy true, przewijany widok odbija się poziomo po osiągnięciu końca, nawet jeśli zawartość jest mniejsza niż sam przewijany widok.

Type	Default
bool	true when horizontal={true} false otherwise

---

alwaysBounceVertical

iOS

Gdy true, ScrollView odbija się pionowo po osiągnięciu końca, nawet jeśli zawartość jest mniejsza niż sam ScrollView.

Type	Default
bool	false when horizontal={true} true otherwise

---

automaticallyAdjustContentInsets

iOS

Kontroluje, czy iOS powinien automatycznie dostosowywać wcięcie zawartości dla ScrollView umieszczonych pod paskiem nawigacyjnym lub zakładkami/paskiem narzędzi.

Type	Default
bool	true

---

automaticallyAdjustKeyboardInsets

iOS

Kontroluje, czy ScrollView powinien automatycznie dostosowywać swoje contentInset i scrollViewInsets gdy klawiatura zmienia rozmiar.

Type	Default
bool	false

---

automaticallyAdjustsScrollIndicatorInsets

iOS

Kontroluje, czy iOS powinien automatycznie dostosowywać wcięcia wskaźnika przewijania. Zobacz dokumentację Apple dotyczącą tej właściwości.

Type	Default
bool	true

---

bounces

iOS

Gdy true, ScrollView odbija się po osiągnięciu końca zawartości, jeśli zawartość jest większa niż ScrollView wzdłuż osi przewijania. Gdy false, wyłącza wszystkie odbicia, nawet jeśli właściwości alwaysBounce* są ustawione na true.

Type	Default
bool	true

---

bouncesZoom

iOS

Gdy true, gesty mogą przekroczyć min/max skalowania, a powiększenie animuje do wartości min/max po zakończeniu gestu; w przeciwnym razie powiększenie nie przekroczy limitów.

Type	Default
bool	true

---

canCancelContentTouches

iOS

Gdy false, po rozpoczęciu śledzenia, nie spróbuje przeciągać, jeśli dotyk się przesunie.

Type	Default
bool	true

---

centerContent

iOS

Gdy true, ScrollView automatycznie wyśrodkowuje zawartość, gdy jest ona mniejsza niż granice ScrollView; gdy zawartość jest większa, ta właściwość nie ma efektu.

Type	Default
bool	false

---

contentContainerStyle

Te style zostaną zastosowane do kontenera zawartości ScrollView, który opakowuje wszystkie widoki potomne. Przykład:

return (
  <ScrollView contentContainerStyle={styles.contentContainer}>
  </ScrollView>
);
...
const styles = StyleSheet.create({
  contentContainer: {
    paddingVertical: 20
  }
});

Type
View Style

---

contentInset

iOS

Wielkość wcięcia zawartości ScrollView od krawędzi ScrollView.

Type	Default
object: {top: number, left: number, bottom: number, right: number}	{top: 0, left: 0, bottom: 0, right: 0}

---

contentInsetAdjustmentBehavior

iOS

Ta właściwość określa, jak wcięcia bezpiecznego obszaru są używane do modyfikacji obszaru zawartości ScrollView. Dostępne od iOS 11 i nowszych.

Type	Default
enum('automatic', 'scrollableAxes', 'never', 'always')	'never'

---

contentOffset

Służy do ręcznego ustawienia początkowego przesunięcia przewijania.

Type	Default
Point	{x: 0, y: 0}

---

decelerationRate

Liczba zmiennoprzecinkowa określająca szybkość wyhamowywania przewijania po zwolnieniu palca. Można użyć skrótów tekstowych: "normal" i "fast", które odpowiadają ustawieniom iOS dla UIScrollViewDecelerationRateNormal i UIScrollViewDecelerationRateFast.

• 'normal': 0.998 w iOS, 0.985 w Androidzie.

• 'fast': 0.99 w iOS, 0.9 w Androidzie.

Type	Default
enum('fast', 'normal'), number	'normal'

---

directionalLockEnabled

iOS

Gdy true, ScrollView próbuje blokować przewijanie tylko w pionie lub poziomie podczas przeciągania.

Type	Default
bool	false

---

disableIntervalMomentum

Gdy true, przewijanie zatrzyma się na następnym indeksie (względem pozycji przy zwolnieniu) niezależnie od prędkości gestu. Przydatne przy paginacji, gdy strona jest mniejsza niż szerokość poziomego ScrollView lub wysokość pionowego.

Type	Default
bool	false

---

disableScrollViewPanResponder

Gdy true, wyłącza domyślny mechanizm reagowania na gesty w JS, pozostawiając pełną kontrolę nad dotknięciami komponentom potomnym. Szczególnie przydatne z snapToInterval, ponieważ nie stosuje typowych wzorców dotknięć. Nie używaj bez snapToInterval, bo może powodować nieoczekiwane zachowania.

Type	Default
bool	false

---

endFillColor

Android

Gdy ScrollView zajmuje więcej miejsca niż jego zawartość, ta właściwość wypełnia pozostały obszar kolorem, unikając ustawiania tła i niepotrzebnego przemalowywania. Zaawansowana optymalizacja, zwykle niepotrzebna.

Type
color

---

fadingEdgeLength

Android

Wygasza krawędzie przewijanej treści.

Wartość większa niż 0 ustawia efekt wygaszania zgodnie z kierunkiem przewijania, wskazując dodatkową treść.

Type	Default
number object: {start: number, end: number}	0

---

horizontal

Gdy true, elementy potomne są ułożone poziomo w rzędzie zamiast pionowo w kolumnie.

Type	Default
bool	false

---

indicatorStyle

iOS

Styl wskaźników przewijania.

• 'default' to samo co black.

• 'black', wskaźnik przewijania jest black. Dobry na jasnym tle.

• 'white', wskaźnik przewijania jest white. Dobry na ciemnym tle.

Type	Default
enum('default', 'black', 'white')	'default'

---

invertStickyHeaders

Gdy true, przyklejone nagłówki trzymają się dołu zamiast góry ScrollView. Zwykle używane z odwróconymi ScrollView.

Type	Default
bool	false

---

keyboardDismissMode

Określa, czy klawiatura ma być chowana w odpowiedzi na przeciąganie.

• 'none': przeciąganie nie chowa klawiatury.

• 'on-drag': klawiatura chowa się przy rozpoczęciu przeciągania.

Tylko iOS

• 'interactive': klawiatura chowana jest interaktywnie z przeciąganiem, ruch synchronizowany z palcem. Przeciągnięcie w górę anuluje chowanie. Android nieobsługiwane - zachowanie jak 'none'.

Type	Default
enum('none', 'on-drag') Android enum('none', 'on-drag', 'interactive') iOS	'none'

---

keyboardShouldPersistTaps

Określa, kiedy klawiatura powinna pozostać widoczna po dotknięciu.

• 'never': dotknięcie poza polem tekstowym chowa klawiaturę. Dzieci nie otrzymają dotknięcia.

• 'always': klawiatura nie chowa się automatycznie, a ScrollView nie przechwytuje dotknięć (ale dzieci mogą).

• 'handled': klawiatura nie chowa się automatycznie, gdy dotknięcie obsłużyły dzieci ScrollView (lub przodek).

• false, przestarzałe, użyj 'never'

• true, przestarzałe, użyj 'always'

Type	Default
enum('always', 'never', 'handled', false, true)	'never'

---

maintainVisibleContentPosition

Po ustawieniu, widok przewijania automatycznie dostosuje pozycję przewijania tak, aby pierwsze widoczne dziecko na poziomie minIndexForVisible lub dalsze nie zmieniało swojej pozycji. Jest to przydatne w listach ładowanych dwukierunkowo (np. wątek czatu), gdzie nowe wiadomości mogłyby powodować skoki pozycji przewijania. Wartość 0 jest najczęstsza, ale można użyć innych wartości (np. 1) by pominąć animacje ładowania lub inne elementy, które nie powinny utrzymywać pozycji.

Opcjonalny parametr autoscrollToTopThreshold może wymusić automatyczne przewinięcie do góry po dostosowaniu, jeśli użytkownik znajdował się w pobliżu progu przed zmianą. Przydatne w aplikacjach typu czat, gdzie chcemy widzieć nowe wiadomości pojawiające się na dole, ale nie gdy użytkownik już przewinął w górę i takie przewijanie byłoby uciążliwe.

Uwaga 1: Zmiana kolejności elementów w widoku przewijania z aktywną tą funkcją prawdopodobnie spowoduje nienaturalne skoki. Można to naprawić, ale obecnie nie ma takich planów. Na razie nie zmieniaj kolejności treści w ScrollView ani listach używających tej funkcji.

Uwaga 2: Mechanizm wykorzystuje contentOffset i frame.origin w kodzie natywnym do określenia widoczności. Nie uwzględnia przesłaniania, transformacji ani innych złożonych czynników przy ocenie "widoczności" treści.

Type
object: {minIndexForVisible: number, autoscrollToTopThreshold: number}

---

maximumZoomScale

iOS

Maksymalna dozwolona skala powiększenia.

Type	Default
number	1.0

---

minimumZoomScale

iOS

Minimalna dozwolona skala powiększenia.

Type	Default
number	1.0

---

nestedScrollEnabled

Android

Włącza zagnieżdżone przewijanie dla Androida (poziom API 21+).

Type	Default
bool	false

---

onContentSizeChange

Wywoływane gdy zmienia się rozmiar przewijalnej zawartości ScrollView.

Funkcja obsługi otrzymuje dwa parametry: szerokość i wysokość zawartości (contentWidth, contentHeight).

Zaimplementowane przy użyciu procedury onLayout dołączonej do kontenera zawartości renderowanego przez ScrollView.

Type
function

---

onMomentumScrollBegin

Wywoływane przy rozpoczęciu przewijania z rozpędu (gdy ScrollView zaczyna płynnie sunąć).

Type
function

---

onMomentumScrollEnd

Wywoływane przy zakończeniu przewijania z rozpędu (gdy ScrollView kończy płynnie sunąć).

Type
function

---

onScroll

Wywoływane maksymalnie raz na klatkę podczas przewijania. Struktura zdarzenia (wszystkie nieokreślone typy to liczby):

js

{
  nativeEvent: {
    contentInset: {bottom, left, right, top},
    contentOffset: {x, y},
    contentSize: {height, width},
    layoutMeasurement: {height, width},
    velocity: {x, y},
    responderIgnoreScroll: boolean,
    zoomScale,
    // iOS only
    targetContentOffset: {x, y}
  }
}

Type
function

---

onScrollBeginDrag

Wywoływane gdy użytkownik rozpoczyna przeciąganie widoku przewijania.

Type
function

---

onScrollEndDrag

Wywoływane gdy użytkownik kończy przeciąganie i przewijanie zatrzymuje się lub zaczyna płynnie sunąć.

Type
function

---

onScrollToTop

iOS

Wywoływane gdy przewijanie dotrze do góry po dotknięciu paska statusu.

Type
function

---

overScrollMode

Android

Służy do nadpisania domyślnego trybu przewijania poza krawędzie (overScroll).

Dopuszczalne wartości:

• 'auto' - Pozwala na przewijanie poza krawędzie tylko gdy zawartość jest wystarczająco duża do sensownego przewijania.

• 'always' - Zawsze pozwala na przewijanie poza krawędzie.

• 'never' - Nigdy nie pozwala na przewijanie poza krawędzie.

Type	Default
enum('auto', 'always', 'never')	'auto'

---

pagingEnabled

Gdy true, przewijanie zatrzymuje się na wielokrotnościach rozmiaru widoku przewijania. Może być używane do paginacji poziomej.

Type	Default
bool	false

---

persistentScrollbar

Android

Zapobiega przezroczystości pasków przewijania gdy nie są używane.

Type	Default
bool	false

---

pinchGestureEnabled

iOS

Gdy true, ScrollView umożliwia powiększanie gestem szczypania.

Type	Default
bool	true

---

refreshControl

Komponent RefreshControl zapewniający funkcję "pull-to-refresh". Działa tylko dla pionowych ScrollView (horizontal musi być false).

Patrz RefreshControl.

Type
element

---

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

---

scrollEnabled

Gdy false, blokuje przewijanie przez interakcję dotykową.

Pamiętaj, że widok zawsze można przewinąć, wywołując scrollTo.

Type	Default
bool	true

---

scrollEventThrottle

Ogranicza częstotliwość wysyłania zdarzeń przewijania podczas scrollowania, określoną jako interwał czasowy w ms. Może to być przydatne, gdy w odpowiedzi na przewijanie wykonywana jest kosztowna operacja. Wartości ≤ 16 wyłączają ograniczanie, niezależnie od częstotliwości odświeżania urządzenia.

Type	Default
number	0

---

scrollIndicatorInsets

iOS

Wielkość, o jaką wskaźniki przewijania są wsunięte od krawędzi widoku przewijania. Powinna być zwykle ustawiona na taką samą wartość jak contentInset.

Type	Default
object: {top: number, left: number, bottom: number, right: number}	{top: 0, left: 0, bottom: 0, right: 0}

---

scrollPerfTag

Android

Tag używany do logowania wydajności przewijania w tym widoku. Wymusi włączenie zdarzeń momentum (patrz sendMomentumEvents). Domyślnie nie robi nic - aby był użyteczny, potrzebujesz własnej implementacji natywnego FpsListener.

Type
string

---

scrollToOverflowEnabled

iOS

Gdy true, widok przewijania może być programowo przewijany poza rozmiar swojej zawartości.

Type	Default
bool	false

---

scrollsToTop

iOS

Gdy true, widok przewijania będzie przewijał się do góry po dotknięciu paska stanu.

Type	Default
bool	true

---

showsHorizontalScrollIndicator

Gdy true, pokazuje poziomy wskaźnik przewijania.

Type	Default
bool	true

---

showsVerticalScrollIndicator

Gdy true, pokazuje pionowy wskaźnik przewijania.

Type	Default
bool	true

---

snapToAlignment

Gdy ustawiono snapToInterval, snapToAlignment definiuje relację przyciągania do widoku przewijania.

Dopuszczalne wartości:

• 'start' wyrówna przyciąganie do lewej (poziomo) lub góry (pionowo).

• 'center' wyrówna przyciąganie do środka.

• 'end' wyrówna przyciąganie do prawej (poziomo) lub dołu (pionowo).

Type	Default
enum('start', 'center', 'end')	'start'

---

snapToEnd

Używaj razem z snapToOffsets. Domyślnie koniec listy liczy się jako offset przyciągania. Ustaw snapToEnd na false, aby wyłączyć to zachowanie i umożliwić swobodne przewijanie między końcem listy a ostatnim offsetem snapToOffsets.

Type	Default
bool	true

---

snapToInterval

Po ustawieniu powoduje, że widok przewijania zatrzymuje się na wielokrotnościach wartości snapToInterval. Może być używane do paginacji przez elementy potomne o długościach mniejszych niż widok przewijania. Zwykle używane z snapToAlignment i decelerationRate="fast". Nadpisuje mniej konfigurowalną właściwość pagingEnabled.

Type
number

---

snapToOffsets

Po ustawieniu powoduje, że widok przewijania zatrzymuje się na zdefiniowanych offsetach. Może być używane do paginacji przez elementy potomne o różnych rozmiarach mniejszych niż widok przewijania. Zwykle używane z decelerationRate="fast". Nadpisuje właściwości pagingEnabled i snapToInterval.

Type
array of number

---

snapToStart

Używaj razem z snapToOffsets. Domyślnie początek listy liczy się jako offset przyciągania. Ustaw snapToStart na false, aby wyłączyć to zachowanie i umożliwić swobodne przewijanie między początkiem listy a pierwszym offsetem snapToOffsets.

Type	Default
bool	true

---

stickyHeaderHiddenOnScroll

Gdy ustawione na true, przyklejony nagłówek będzie ukrywany podczas przewijania listy w dół i dokowany na górze podczas przewijania w górę.

Type	Default
bool	false

---

stickyHeaderIndices

Tablica indeksów elementów potomnych określająca, które elementy są dokowane do góry ekranu podczas przewijania. Np. stickyHeaderIndices={[0]} spowoduje, że pierwszy element potomny będzie przymocowany do góry widoku. Można użyć [x,y,z] do przyklejenia wielu elementów. Nieobsługiwane z horizontal={true}.

Type
array of number

---

zoomScale

iOS

Bieżąca skala zawartości widoku przewijania.

Type	Default
number	1.0

---

Metody

flashScrollIndicators()

tsx

flashScrollIndicators();

Wyświetla tymczasowo wskaźniki przewijania.

---

scrollTo()

tsx

scrollTo(
  options?: {x?: number, y?: number, animated?: boolean} | number,
  deprecatedX?: number,
  deprecatedAnimated?: boolean,
);

Przewija do podanego przesunięcia x, y - natychmiast lub z płynną animacją.

Przykład:

scrollTo({x: 0, y: 0, animated: true})

uwaga

Dziwna sygnatura funkcji wynika z historycznych powodów - jako alternatywę dla obiektu opcji można podawać osobne argumenty. To podejście jest przestarzałe z powodu niejednoznaczności (kolejność y przed x) i NIE POWINNO BYĆ UŻYWANE.

---

scrollToEnd()

tsx

scrollToEnd(options?: {animated?: boolean});

W przypadku pionowego ScrollView przewija do dołu. W przypadku poziomego ScrollView przewija do prawej krawędzi.

Użyj scrollToEnd({animated: true}) do płynnego przewijania z animacją, scrollToEnd({animated: false}) do natychmiastowego przewijania. Jeśli nie przekazano opcji, domyślnie używana jest wartość animated ustawiona na true.