ScrollView

Компонент, который оборачивает платформенный ScrollView, обеспечивая интеграцию с системой блокировки касаний "responder".

Обратите внимание, что ScrollView должен иметь ограниченную высоту для работы, так как он содержит элементы с неограниченной высотой в ограниченном контейнере (через взаимодействие со скроллингом). Для ограничения высоты ScrollView либо установите высоту представления напрямую (не рекомендуется), либо убедитесь, что все родительские представления имеют ограниченную высоту. Забывание передачи {flex: 1} вниз по стеку представления может привести к ошибкам, которые легко отлаживать с помощью инспектора элементов.

Пока не поддерживает другие связанные компоненты responder, которые могли бы блокировать этот scroll view от того, чтобы стать responder.

<ScrollView> по сравнению с <FlatList> — какой использовать?

ScrollView отображает все свои реактивные дочерние компоненты сразу, но это имеет недостатки с точки зрения производительности.

Представьте, что у вас очень длинный список элементов, которые вы хотите отобразить, возможно, на несколько экранов. Создание JS-компонентов и нативных представлений для всего сразу, большая часть из которых даже не отображается, приведет к медленному отображению и увеличению использования памяти.

Вот где FlatList вступает в игру. FlatList отображает элементы лениво, когда они собираются появиться, и удаляет элементы, которые прокручиваются за пределы экрана, чтобы сэкономить память и время обработки.

FlatList также полезно, если вы хотите отображать разделители между элементами, несколько столбцов, бесконечную прокрутку с загрузкой или любое количество других функций, которые он поддерживает по умолчанию.

Справочник

Свойства

Свойства View

Наследует Свойства View.

StickyHeaderComponent

Реактивный компонент, который будет использоваться для отображения заголовков, которые прилипают к верху, должен использоваться вместе с stickyHeaderIndices. Возможно, вам нужно будет установить этот компонент, если ваш прилипающий заголовок использует пользовательские преобразования, например, когда вы хотите, чтобы у вашего списка был анимируемый и скрываемый заголовок. Если компонент не предоставлен, по умолчанию используется компонент ScrollViewStickyHeader.

alwaysBounceHorizontal

iOS

Если значение true, представление со скроллингом отскакивает по горизонтали при достижении конца, даже если содержимое меньше самого представления со скроллингом.

alwaysBounceVertical

iOS

Если значение true, представление со скроллингом отскакивает по вертикали при достижении конца, даже если содержимое меньше самого представления со скроллингом.

automaticallyAdjustContentInsets

iOS

Управляет тем, автоматически ли iOS корректирует отступ содержимого для представлений со скроллингом, которые размещены под навигационной строкой или панелью вкладок/панелью инструментов.

automaticallyAdjustKeyboardInsets

iOS

Управляет тем, автоматически ли ScrollView корректирует свои contentInset и scrollViewInsets при изменении размера клавиатуры.

automaticallyAdjustsScrollIndicatorInsets

iOS

Управляет тем, автоматически ли iOS корректирует отступы индикатора прокрутки. См. документацию Apple по этому свойству.

bounces

iOS

Если значение true, представление со скроллингом отскакивает при достижении конца содержимого, если содержимое больше представления со скроллингом вдоль оси направления прокрутки. Когда false, отскок отключается, даже если свойства alwaysBounce* имеют значение true.

bouncesZoom

iOS

Если true, жесты могут управлять масштабированием, выходя за пределы минимальных/максимальных значений, и масштабирование анимируется до минимальных/максимальных значений в конце жеста, в противном случае масштабирование не будет превышать пределы.

canCancelContentTouches

iOS

Если false, после начала отслеживания попытка перетащить не будет выполняться, если палец перемещается.

centerContent

iOS

Если true, представление со скроллингом автоматически центрирует содержимое, когда содержимое меньше границ представления со скроллингом; когда содержимое больше, чем границы представления со скроллингом, это свойство не оказывает влияния.

contentContainerStyle

Эти стили будут применены к контейнеру содержимого представления со скроллингом, который оборачивает все дочерние представления. Пример:

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

contentInset

iOS

Величина, на которую содержимое представления со скроллингом смещено от краев представления со скроллингом.

contentInsetAdjustmentBehavior

iOS

Это свойство определяет, как отступы безопасной области используются для изменения области содержимого представления со скроллингом. Доступно на iOS 11 и более поздних версиях.

contentOffset

Используется для ручного задания начального смещения прокрутки.

decelerationRate

Число с плавающей точкой, которое определяет, насколько быстро представление со скроллингом замедляется после того, как пользователь отпустит палец. Вы также можете использовать сокращения "normal" и "fast", которые соответствуют настройкам iOS для UIScrollViewDecelerationRateNormal и UIScrollViewDecelerationRateFast соответственно.

• 'normal' 0.998 на iOS, 0.985 на Android.
• 'fast', 0.99 на iOS, 0.9 на Android.

directionalLockEnabled

iOS

Если значение true, ScrollView будет пытаться заблокировать прокрутку только по вертикали или горизонтали во время перетаскивания.

disableIntervalMomentum

Если значение true, представление со скроллингом останавливается на следующем индексе (относительно положения прокрутки при отпускании) независимо от скорости жеста. Это можно использовать для пагинации, когда страница меньше ширины горизонтального ScrollView или высоты вертикального ScrollView.

disableScrollViewPanResponder

Если значение true, стандартный JS-компонент перетаскивания на ScrollView отключается, и полный контроль над касаниями внутри ScrollView передается его дочерним компонентам. Это особенно полезно, если snapToInterval включен, так как он не следует типичным паттернам касаний. Не используйте это для обычных случаев использования ScrollView без snapToInterval, так как это может привести к неожиданным касаниям во время прокрутки.

endFillColor

Android

Иногда scrollview занимает больше места, чем его заполняет содержимое. В таком случае это свойство заполнит оставшуюся часть scrollview цветом, чтобы избежать установки фона и создания ненужного перерисовывания. Это продвинутая оптимизация, которая не требуется в общем случае.

fadingEdgeLength

Android

Выцветает края содержимого прокрутки.

Если значение больше 0, края с выцветанием будут установлены соответственно текущему направлению и положению прокрутки, указывая, есть ли больше содержимого для отображения.

horizontal

Если true, дочерние элементы представления со скроллингом располагаются по горизонтали в строке вместо вертикального расположения в столбце.

indicatorStyle

iOS

Стиль индикаторов прокрутки.

• 'default' так же, как black.
• 'black', индикатор прокрутки — black. Этот стиль подходит для светлого фона.
• 'white', индикатор прокрутки — white. Этот стиль подходит для тёмного фона.

invertStickyHeaders

Если заголовки sticky должны прикрепляться к нижней части, а не к верхней части ScrollView. Обычно используется с инвертированными ScrollView.

keyboardDismissMode

Определяет, будет ли клавиатура закрываться при перетаскивании.

• 'none', перетаскивания не закрывают клавиатуру.
• 'on-drag', клавиатура закрывается при начале перетаскивания.

Только для iOS

• 'interactive', клавиатура закрывается интерактивно при перетаскивании и перемещается синхронно с касанием, перетаскивание вверх отменяет закрытие. На Android это не поддерживается и будет иметь такое же поведение, как 'none'.

keyboardShouldPersistTaps

Определяет, когда клавиатура должна оставаться видимой после нажатия.

• 'never' нажатие вне области ввода текста, когда клавиатура открыта, закрывает клавиатуру. В этом случае дочерние элементы не получат нажатие.
• 'always', клавиатура не будет автоматически закрываться, и область прокрутки не будет перехватывать нажатия, но дочерние элементы области прокрутки могут перехватывать нажатия.
• 'handled', клавиатура не будет автоматически закрываться, когда нажатие было обработано дочерними элементами области прокрутки (или перехвачено предком).
• false, устарело, используйте 'never' вместо этого
• true, устарело, используйте 'always' вместо этого

maintainVisibleContentPosition

iOS

При установке области прокрутки будет корректировать положение прокрутки таким образом, чтобы первый видимый элемент, который находится на или за minIndexForVisible, не менял положение. Это полезно для списков, загружающих содержимое в обоих направлениях, например, для потока чата, где новые сообщения, поступающие, могут в противном случае привести к скачку позиции прокрутки. Значение 0 является распространённым, но можно использовать и другие значения, например, 1 для пропуска индикаторов загрузки или другого содержимого, положение которого не нужно сохранять.

Необязательное autoscrollToTopThreshold может использоваться для автоматической прокрутки содержимого к началу после внесения корректировок, если пользователь находился в пределах порога верха до внесения корректировок. Это также полезно для приложений типа чата, где вы хотите видеть новые сообщения, прокручивающиеся на место, но не в случае, если пользователь прокрутил вверх и это будет нарушать порядок.

Предупреждение 1: Переупорядочивание элементов в ScrollView с включенным этим параметром, вероятно, приведёт к рывковому и неровному отображению. Его можно исправить, но в настоящее время нет планов это сделать. Пока не переупорядочивайте содержимое ScrollView или списков, использующих эту функцию.

Предупреждение 2: В родном коде используется contentOffset и frame.origin для вычисления видимости. Закрытие, преобразования и другие сложности не будут учитываться при определении того, является ли содержимое «видимым» или нет.

maximumZoomScale

iOS

Максимальный разрешённый масштаб.

minimumZoomScale

iOS

Минимальный разрешённый масштаб.

nestedScrollEnabled

Android

Включает вложенную прокрутку для Android API уровня 21 и выше.

onContentSizeChange

Вызывается при изменении размера содержимого области прокрутки ScrollView.

Функция обработчика получает ширину и высоту содержимого в качестве параметров: (contentWidth, contentHeight)

Реализовано с помощью обработчика onLayout, прикреплённого к контейнеру содержимого, который рендерит этот ScrollView.

onMomentumScrollBegin

Вызывается при начале импульсной прокрутки (прокрутка, которая происходит, когда ScrollView начинает скользить).

onMomentumScrollEnd

Вызывается при окончании импульсной прокрутки (прокрутка, которая происходит, когда ScrollView останавливается).

onScroll

Вызывается не более одного раза за кадр во время прокрутки. Частота событий может контролироваться с помощью свойства scrollEventThrottle. Формат события (все значения — числа):

{
  nativeEvent: {
    contentInset: {bottom, left, right, top},
    contentOffset: {x, y},
    contentSize: {height, width},
    layoutMeasurement: {height, width},
    zoomScale
  }
}

onScrollBeginDrag

Вызывается при начале перетаскивания области прокрутки пользователем.

onScrollEndDrag

Вызывается, когда пользователь прекращает перетаскивание области прокрутки, и она либо останавливается, либо начинает скользить.

onScrollToTop

iOS

Вызывается, когда область прокрутки прокручивается в начало после нажатия на строку состояния.

overScrollMode

Android

Используется для переопределения значения по умолчанию для режима перепрокрутки.

Возможные значения:

• 'auto' — Разрешить перепрокрутку только если содержимое достаточно для значимой прокрутки.
• 'always' — Всегда разрешать перепрокрутку.
• 'never' — Никогда не разрешать перепрокрутку.

pagingEnabled

При значении true область прокрутки останавливается на кратных значениях размера области прокрутки при прокрутке. Это можно использовать для горизонтальной постраничной навигации.

Примечание: Горизонтальная постраничная навигация не поддерживается на Android.

persistentScrollbar

Android

Заставляет полосы прокрутки не становиться прозрачными, когда они не используются.

pinchGestureEnabled

iOS

Если true, ScrollView позволяет использовать жесты щипка для масштабирования.

refreshControl

Компонент RefreshControl, используемый для предоставления функциональности pull-to-refresh для ScrollView. Работает только для вертикальных ScrollView (свойство horizontal должно быть false).

См. RefreshControl.

removeClippedSubviews

Экспериментально: Если true, внеэкранные дочерние элементы (чьё значение overflow равно hidden) удаляются из их родного родительского представления при выходе за экран. Это может улучшить производительность прокрутки длинных списков.

scrollEnabled

Если false, прокрутка невозможна через взаимодействие с касанием.

Обратите внимание, что прокрутку можно выполнить всегда, вызвав scrollTo.

scrollEventThrottle

iOS

Этот параметр управляет частотой срабатывания события прокрутки во время прокрутки (в виде интервала времени в мс). Более низкое значение даёт лучшую точность для кода, отслеживающего положение прокрутки, но может привести к проблемам с производительностью прокрутки из-за объёма информации, передаваемой по мосту. Вы не заметите разницы между значениями от 1 до 16, так как цикл выполнения JS синхронизирован со скоростью обновления экрана. Если вам не нужна точная информация о положении прокрутки, установите это значение выше, чтобы ограничить передачу информации через мост. Значение по умолчанию — 0, что приводит к отправке события прокрутки только один раз при каждой прокрутке.

scrollIndicatorInsets

iOS

Отступ индикаторов прокрутки от краёв области прокрутки. Обычно он должен быть таким же, как contentInset.

scrollPerfTag

Android

Тег, используемый для регистрации производительности прокрутки в этом представлении прокрутки. Заставит события импульса быть включенными (см. sendMomentumEvents). Само по себе это ничего не делает, и вам нужно реализовать пользовательский native FpsListener, чтобы оно было полезным.

scrollToOverflowEnabled

iOS

Когда true, представление прокрутки может быть программно прокручено за пределы размера его содержимого.

scrollsToTop

iOS

Когда true, представление прокрутки прокручивается вверху, когда нажата строка состояния.

showsHorizontalScrollIndicator

Когда true, отображается индикатор горизонтальной прокрутки.

showsVerticalScrollIndicator

Когда true, отображается индикатор вертикальной прокрутки.

snapToAlignment

iOS

Когда snapToInterval установлено, snapToAlignment определит отношение привязки к представлению прокрутки.

Возможные значения:

• 'start' выровняет привязку по левому краю (горизонталь) или верхнему краю (вертикаль).
• 'center' выровняет привязку по центру.
• 'end' выровняет привязку по правому краю (горизонталь) или нижнему краю (вертикаль).

snapToEnd

Используется совместно с snapToOffsets. По умолчанию конец списка учитывается как смещение привязки. Установите snapToEnd в значение false, чтобы отключить это поведение и позволить списку свободно прокручиваться между концом и последним snapToOffsets смещением.

snapToInterval

При установке это заставляет представление прокрутки останавливаться на кратных значениям snapToInterval. Это может использоваться для постраничного просмотра элементов, которые имеют длину меньше, чем у представления прокрутки. Обычно используется в сочетании с snapToAlignment и decelerationRate="fast". Переопределяет менее настраиваемый pagingEnabled параметр.

snapToOffsets

При установке это заставляет представление прокрутки останавливаться на заданных смещениях. Это можно использовать для постраничного просмотра элементов с различными размерами, которые имеют длину меньше, чем у представления прокрутки. Обычно используется в сочетании с decelerationRate="fast". Переопределяет менее настраиваемые pagingEnabled и snapToInterval параметры.

snapToStart

Используется совместно с snapToOffsets. По умолчанию начало списка учитывается как смещение привязки. Установите snapToStart в значение false, чтобы отключить это поведение и позволить списку свободно прокручиваться между началом и первым snapToOffsets смещением.

stickyHeaderHiddenOnScroll

При установке в true, зафиксированный заголовок будет скрыт при прокрутке вниз по списку и будет прикреплен к верху списка при прокрутке вверх.

stickyHeaderIndices

Массив индексов элементов, определяющих, какие элементы прикрепляются к верхней части экрана при прокрутке. Например, передача stickyHeaderIndices={[0]} зафиксирует первый элемент в верхней части представления прокрутки. Вы также можете использовать подобные значения [x,y,z], чтобы закрепить несколько элементов, когда они находятся вверху. Этот параметр не поддерживается в сочетании с horizontal={true}.

zoomScale

iOS

Текущий масштаб содержимого представления прокрутки.

Методы

flashScrollIndicators()

flashScrollIndicators();

Временно отображает индикаторы прокрутки.

scrollTo()

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

Прокручивает до заданного смещения x, y, либо мгновенно, либо с плавной анимацией.

Пример:

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

Примечание: Необычная сигнатура функции связана с тем, что по историческим причинам функция также принимает отдельные аргументы как альтернативу объекту параметров. Это устарело из-за неоднозначности (y перед x), и ЕЁ НЕ СЛЕДУЕТ ИСПОЛЬЗОВАТЬ.

scrollToEnd()

scrollToEnd(([options]: { animated: boolean }));

Если это вертикальная прокрутка, прокручивает до низа. Если это горизонтальная прокрутка, прокручивает вправо.

Используйте scrollToEnd({ animated: true }) для плавной анимированной прокрутки, scrollToEnd({ animated: false }) для мгновенной прокрутки. Если не переданы параметры, animated по умолчанию устанавливается в true.