FlatList¶

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

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

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

Пример¶

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

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

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

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

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

• Это PureComponent, что означает, что он не будет перерисовываться, если props остаются неглубоко равными. Убедитесь, что все, от чего зависит функция renderItem, передается в качестве пропса (например, extraData), который не становится === после обновления, иначе ваш пользовательский интерфейс может не обновляться при изменениях. Это относится к пропсу data и состоянию родительского компонента.

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

• По умолчанию список ищет свойство key у каждого элемента и использует его для ключа React. В качестве альтернативы вы можете предоставить собственный пропс keyExtractor.

Пропсы¶

Пропсы ScrollView¶

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

renderItem (обязательно)¶

1
2
3
4
5
6
7
8
9

renderItem({
  item: ItemT,
  index: number,
  separators: {
    highlight: () => void;
    unhighlight: () => void;
    updateProps: (select: 'leading' | 'trailing', newProps: any) => void;
  }
}): JSX.Element;

Берет элемент из data и отображает его в списке.

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

<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. Может быть React Component (например, SomeComponent) или React элемент (например, <SomeComponent />).

ListEmptyComponent¶

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

ListFooterComponent¶

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

ListFooterComponentStyle¶

Стилизация для внутреннего представления для ListFooterComponent.

ListHeaderComponent¶

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

ListHeaderComponentStyle¶

Стилизация для внутреннего представления для ListHeaderComponent.

columnWrapperStyle¶

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

extraData¶

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

getItemLayout¶

1

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

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

1
2
3

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

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

horizontal¶

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

initialNumToRender¶

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

initialScrollIndex¶

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

inverted¶

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

keyExtractor¶

1

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

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

numColumns¶

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

onEndReached¶

1

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

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

onEndReachedThreshold¶

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

onRefresh¶

1

() => void;

Если указано, будет добавлен стандартный RefreshControl для функциональности "Pull to Refresh". Не забудьте также правильно установить параметр refreshing.

onViewableItemsChanged¶

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

progressViewOffset¶

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

refreshing¶

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

removeClippedSubviews¶

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

viewabilityConfig¶

Тип потока и дальнейшую документацию смотрите в ViewabilityHelper.js.

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

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

1

Error: Changing viewabilityConfig on the fly is not supported

1
2
3
4
5
6
7
8

constructor (props) {
  super(props)

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

1
2
3
4

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

minimumViewTime¶

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

viewAreaCoveragePercentThreshold¶

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

itemVisiblePercentThreshold¶

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

waitForInteraction¶

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

viewabilityConfigCallbackPairs¶

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

Методы¶

flashScrollIndicators()¶

1

flashScrollIndicators();

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

getNativeScrollRef()¶

1

getNativeScrollRef(): React.ElementRef<typeof ScrollViewComponent>;

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

getScrollResponder()¶

1

getScrollResponder(): ScrollResponderMixin;

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

getScrollableNode()¶

1

getScrollableNode(): any;

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

scrollToEnd()¶

1

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

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

Параметры:

Допустимыми ключами params являются:

• 'animated' (boolean) — Должен ли список делать анимацию при прокрутке. По умолчанию имеет значение true.

scrollToIndex()¶

1
2
3
4
5
6

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

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

Параметры:

Допустимыми ключами params являются:

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

scrollToItem()¶

1
2
3
4
5

scrollToItem(params: {
  animated?: ?boolean,
  item: Item,
  viewPosition?: number,
});

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

Параметры:

Допустимыми ключами params являются:

• 'animated' (boolean) — Должен ли список делать анимацию при прокрутке. По умолчанию true.
• 'item' (объект) — Элемент для прокрутки. Требуется.
• 'viewPosition' (число)

scrollToOffset()¶

1
2
3
4

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

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

Параметры:

Допустимыми ключами params являются:

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

Комментарии