FlatList

Высокопроизводительный интерфейс для отрисовки простых, плоских списков, поддерживающий самые удобные функции:

• Полностью кроссплатформенный.
• Необязательный горизонтальный режим.
• Настраиваемые колбэки видимости.
• Поддержка заголовка.
• Поддержка подвала.
• Поддержка разделителей.
• Перетаскивание для обновления.
• Загрузка при прокрутке.
• Поддержка ScrollToIndex.
• Поддержка нескольких столбцов.

Если вам нужна поддержка разделов, используйте <SectionList>.

Для отрисовки нескольких столбцов используйте свойство numColumns. Использование этого подхода вместо flexWrap макета может предотвратить конфликты с логикой высоты элементов.

Более сложный, пример с выбором, ниже.

• Передав extraData={selectedId} свойству FlatList, мы гарантируем, что FlatList будет перерисовываться при изменении состояния. Без этого свойства FlatList не будет знать, что ему нужно перерисовать какие-либо элементы, потому что он является PureComponent, и сравнение свойств не покажет никаких изменений.
• keyExtractor сообщает списку использовать id в качестве ключей React вместо стандартного свойства key.

Это обертка над <VirtualizedList>, и поэтому она наследует её свойства (а также свойства <ScrollView>), которые не указаны здесь, наряду со следующими замечаниями:

• Внутреннее состояние не сохраняется, когда содержимое прокручивается за пределы области отрисовки. Убедитесь, что все ваши данные хранятся в данных элементов или во внешних хранилищах, таких как Flux, Redux или Relay.
• Это PureComponent, что означает, что он не будет перерисовываться, если props останутся одинаковыми после поверхностного сравнения. Убедитесь, что всё, от чего зависит ваша функция renderItem, передаётся как свойство (например, extraData), которое не === после обновлений, иначе ваш пользовательский интерфейс может не обновиться при изменениях. Это включает свойство data и состояние родительского компонента.
• Для ограничения памяти и плавной прокрутки содержимое рендерится асинхронно вне экрана. Это означает, что можно прокручивать быстрее, чем скорость заполнения, и временно видеть пустое содержимое. Это компромисс, который можно настроить в соответствии с потребностями каждого приложения, и мы работаем над его улучшением.
• По умолчанию список ищет свойство key на каждом элементе и использует его в качестве ключа React. В качестве альтернативы вы можете предоставить свойство keyExtractor.

Справочник

Свойства

Свойства ScrollView

Наследует Свойства ScrollView, если он не вложен в другой FlatList с той же ориентацией.

Обязательное

renderItem

renderItem({ item, index, separators });

Принимает элемент из data и отрисовывает его в список.

Предоставляет дополнительную метаданные, такие как index, если вам это нужно, а также более общую функцию separators.updateProps, которая позволяет задавать любые необходимые свойства для изменения отрисовки ведущего разделителя или хвостового разделителя в случае, если более распространённые highlight и unhighlight (которые устанавливают свойство highlighted: boolean) недостаточны для вашего случая.

• item (Объект): Элемент из data для отрисовки.
• index (число): Индекс, соответствующий этому элементу в массиве data.
• separators (Объект)
  • highlight (Функция)
  • unhighlight (Функция)
  • updateProps (Функция)
    • select (перечисление('leading', 'trailing'))
    • newProps (Объект)

Пример использования:

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

Обязательное

data

Для простоты данные представляют собой обычный массив. Если вы хотите использовать что-то другое, например, неизменяемый список, используйте базовый VirtualizedList напрямую.

ItemSeparatorComponent

Отрисовывается между каждым элементом, но не вверху и внизу. По умолчанию предоставляются свойства highlighted и leadingItem. renderItem предоставляет separators.highlight/unhighlight, которые обновят свойство highlighted, но вы также можете добавить пользовательские свойства с помощью separators.updateProps.

ListEmptyComponent

Отрисовывается, когда список пуст. Может быть компонентом React (например, SomeComponent) или элементом React (например, <SomeComponent />).

ListFooterComponent

Отрисовывается внизу всех элементов. Может быть компонентом React (например, SomeComponent) или элементом React (например, <SomeComponent />).

ListFooterComponentStyle

Стиль для внутреннего View для ListFooterComponent.

ListHeaderComponent

Отрисовывается вверху всех элементов. Может быть компонентом React (например, SomeComponent) или элементом React (например, <SomeComponent />).

ListHeaderComponentStyle

Стиль для внутреннего View для ListHeaderComponent.

columnWrapperStyle

Необязательный пользовательский стиль для строк с несколькими элементами, сгенерированных при использовании numColumns > 1.

extraData

Маркерное свойство для уведомления списка о необходимости перерисовки (поскольку он реализует PureComponent). Если какие-либо из ваших функций renderItem, заголовок, подвал и т. д. зависят от чего-либо, кроме свойства data, поместите это сюда и обращайтесь с этим неизменяемо.

getItemLayout

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

getItemLayout — необязательная оптимизация, которая позволяет пропустить измерение динамического содержимого, если вы знаете размер (высоту или ширину) элементов заранее. getItemLayout эффективна, если у вас элементы с фиксированным размером, например:

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

Добавление getItemLayout может значительно повысить производительность для списков с сотнями элементов. Не забудьте включить длину разделителя (высоту или ширину) в свой расчёт смещения, если вы указываете ItemSeparatorComponent.

horizontal

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

initialNumToRender

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

initialScrollIndex

Вместо начала с первого элемента вверху, начать с initialScrollIndex. Это отключает оптимизацию «прокрутки к началу», которая держит первые initialNumToRender элементов всегда отрисованными и сразу же отрисовывает элементы, начиная с этого начального индекса. Требует реализации getItemLayout.

inverted

Изменяет направление прокрутки. Использует преобразования масштаба -1.

keyExtractor

(item: object, index: number) => string;

Используется для извлечения уникального ключа для заданного элемента в указанном индексе. Ключ используется для кэширования и как ключ React для отслеживания переупорядочивания элементов. По умолчанию извлекатель проверяет item.key, затем item.id, а затем возвращается к использованию индекса, как и React.

numColumns

Несколько столбцов могут быть отрисованы только с horizontal={false} и будут изгибаться, как в макете flexWrap . Все элементы должны иметь одинаковую высоту — макеты с выравниванием по высоте не поддерживаются.

onEndReached

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

Вызывается один раз, когда позиция прокрутки находится в пределах onEndReachedThreshold от отрисованного содержимого.

onEndReachedThreshold

Насколько близко к концу (в единицах видимой длины списка) должен быть нижний край списка от конца содержимого, чтобы вызвать колбэк onEndReached. Таким образом, значение 0,5 вызовет onEndReached , когда конец содержимого находится в пределах половины видимой длины списка.

onRefresh

() => void

Если предоставлено, стандартное RefreshControl будет добавлено для функциональности "Перетаскивание для обновления". Убедитесь, что свойство refreshing также установлено правильно.

onViewableItemsChanged

Вызывается при изменении видимости строк, как определено свойством viewabilityConfig.

progressViewOffset

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

refreshing

Установите это значение в true во время ожидания новых данных после обновления.

removeClippedSubviews

Это может улучшить производительность прокрутки для больших списков. По умолчанию на Android значение равно true.

Примечание: в некоторых случаях могут быть ошибки (отсутствующие данные) — используйте на свой страх и риск.

viewabilityConfig

См. ViewabilityHelper.js для типа потока и дополнительной документации.

viewabilityConfig принимает тип ViewabilityConfig и объект со следующими свойствами

Необходимо указать хотя бы одно из viewAreaCoveragePercentThreshold или itemVisiblePercentThreshold. Это необходимо сделать в constructor, чтобы избежать следующей ошибки (ссылка):

  Error: Changing viewabilityConfig on the fly is not supported

constructor (props) {
  super(props)

  this.viewabilityConfig = {
      waitForInteraction: true,
      viewAreaCoveragePercentThreshold: 95
  }
}

<FlatList
    viewabilityConfig={this.viewabilityConfig}
  ...

minimumViewTime

Минимальное количество времени (в миллисекундах), в течение которого элемент должен быть физически виден, прежде чем будет вызван обратный вызов viewability. Большое значение означает, что прокрутка содержимого без остановки не будет отмечать содержимое как видимое.

viewAreaCoveragePercentThreshold

Процент области просмотра, который должен быть покрыт частично скрытым элементом, чтобы считать его «видимым», от 0 до 100. Полностью видимые элементы всегда считаются видимыми. Значение 0 означает, что один пиксель в области просмотра делает элемент видимым, а значение 100 означает, что элемент должен быть полностью виден или занимать всю область просмотра, чтобы считаться видимым.

itemVisiblePercentThreshold

Аналогично viewAreaCoveragePercentThreshold, но учитывает процент элемента, который виден, а не долю покрываемой им области просмотра.

waitForInteraction

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

viewabilityConfigCallbackPairs

Список пар ViewabilityConfig/onViewableItemsChanged. Конкретный onViewableItemsChanged будет вызван, когда условия соответствующего ViewabilityConfig будут выполнены. См. ViewabilityHelper.js для типа потока и дополнительной документации.

Методы

flashScrollIndicators()

flashScrollIndicators();

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

getNativeScrollRef()

getNativeScrollRef();

Предоставляет ссылку на базовый компонент прокрутки.

getScrollResponder()

getScrollResponder();

Предоставляет обработчик базового обработчика прокрутки.

getScrollableNode()

getScrollableNode();

Предоставляет обработчик базового узла прокрутки.

recordInteraction()

recordInteraction();

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

scrollToEnd()

scrollToEnd(params);

Прокрутка до конца содержимого. Может быть нестабильной без свойства getItemLayout.

Параметры:

Допустимые ключи params:

• 'animated' (булево) — выполнить ли анимацию при прокрутке. По умолчанию true.

scrollToIndex()

scrollToIndex(params);

Прокрутка к элементу со значением указанного индекса таким образом, что он располагается в области просмотра так, что viewPosition 0 размещает его вверху, 1 — внизу, а 0,5 — посередине.

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

Параметры:

Допустимые ключи params:

• 'animated' (булево) — выполнить ли анимацию при прокрутке. По умолчанию true.
• 'index' (число) — индекс элемента для прокрутки. Обязательный.
• 'viewOffset' (число) — фиксированное количество пикселей для смещения конечной целевой позиции.
• 'viewPosition' (число) — значение 0 размещает элемент, указанный индексом, вверху, 1 — внизу, а 0.5 — посередине.

scrollToItem()

scrollToItem(params);

Требует линейного сканирования данных — используйте scrollToIndex вместо этого, если это возможно.

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

Параметры:

Допустимые ключи params:

• 'animated' (булево) — выполнить ли анимацию при прокрутке. По умолчанию true.
• 'item' (объект) — элемент для прокрутки. Обязательный.
• 'viewPosition' (число)

scrollToOffset()

scrollToOffset(params);

Прокрутка к определенному смещению пикселей содержимого в списке.

Параметры:

Допустимые ключи params:

• 'offset' (число) — смещение для прокрутки. В случае, если horizontal имеет значение true, смещение — это значение x, в противном случае — y. Обязательный.
• 'animated' (булево) — выполнить ли анимацию при прокрутке. По умолчанию true.