Versión: 0.77

FlatList

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

Una interfaz performante para renderizar listas planas básicas, que incluye las funcionalidades más útiles:

Totalmente multiplataforma.
Modo horizontal opcional.
Callbacks de visibilidad configurables.
Soporte para cabeceras.
Soporte para pies de página.
Soporte para separadores.
Pull to Refresh (arrastrar para actualizar).
Carga al hacer scroll.
Soporte para ScrollToIndex.
Soporte para múltiples columnas.

Si necesitas soporte para secciones, usa <SectionList>.

Ejemplo

TypeScript
JavaScript

Para renderizar múltiples columnas, usa la prop numColumns. Este enfoque previene conflictos con la lógica de altura de elementos comparado con un layout flexWrap.

Ejemplo más complejo con selección a continuación.

Al pasar extraData={selectedId} a FlatList aseguramos que el propio FlatList se rerenderice cuando cambie el estado. Sin esta prop, FlatList no sabría que debe rerenderizar elementos porque es un PureComponent y la comparación de props no mostraría cambios.
keyExtractor indica a la lista que use los ids como claves de React en lugar de la propiedad key por defecto.

TypeScript
JavaScript

Este componente es un wrapper conveniente alrededor de <VirtualizedList>, por lo que hereda sus props (y las de <ScrollView>) que no se listan explícitamente aquí, con las siguientes advertencias:

El estado interno no se preserva cuando el contenido sale de la ventana de renderizado. Asegúrate de capturar todos los datos en los elementos o almacenes externos como Flux, Redux o Relay.
Es un PureComponent, lo que significa que no se rerenderizará si los props permanecen superficialmente iguales. Asegúrate que todo lo que depende tu función renderItem se pase como prop (ej. extraData) que no sea === tras actualizaciones, o tu UI podría no actualizarse. Esto incluye la prop data y el estado del componente padre.
Para optimizar memoria y permitir scroll fluido, el contenido se renderiza asíncronamente fuera de pantalla. Esto puede causar que al hacer scroll muy rápido aparezca contenido vacío momentáneamente. Es una compensación ajustable por aplicación, y estamos trabajando en mejoras internas.
Por defecto, la lista busca una prop key en cada elemento para usarla como clave de React. Alternativamente, puedes proveer una prop personalizada keyExtractor.

Referencia

Props

Props de VirtualizedList

Hereda Props de VirtualizedList.

Required
`renderItem`

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

Toma un elemento de data y lo renderiza en la lista.

Provee metadatos adicionales como index si se necesitan, y una función más genérica separators.updateProps que permite establecer cualquier prop para modificar el renderizado de separadores iniciales o finales, útil cuando highlight/unhighlight (que establecen la prop highlighted: boolean) son insuficientes.

Type
function

item (Object): Elemento de data siendo renderizado.
index (number): Índice correspondiente a este elemento en el array data.
separators (Object)
- highlight (Function)
- unhighlight (Function)
- updateProps (Function)
  - select (enum('leading', 'trailing'))
  - newProps (Object)

Ejemplo de uso:

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

Required
`data`

Un array (o lista similar a un array) de elementos para renderizar. Pueden usarse otros tipos de datos dirigiendo directamente a VirtualizedList.

Type
ArrayLike

`ItemSeparatorComponent`

Renderizado entre cada elemento, pero no al inicio ni al final. Por defecto, se proporcionan las props highlighted y leadingItem. renderItem ofrece separators.highlight/unhighlight que actualizan la prop highlighted, pero también puedes añadir props personalizadas con separators.updateProps. Puede ser un Componente de React (ej. SomeComponent) o un elemento React (ej. <SomeComponent />).

Type
component, function, element

`ListEmptyComponent`

Renderizado cuando la lista está vacía. Puede ser un Componente de React (ej. SomeComponent) o un elemento React (ej. <SomeComponent />).

Type
component, element

`ListFooterComponent`

Renderizado al final de todos los elementos. Puede ser un Componente de React (ej. SomeComponent) o un elemento React (ej. <SomeComponent />).

Type
component, element

`ListFooterComponentStyle`

Estilo para la View interna de ListFooterComponent.

Type
View Style

`ListHeaderComponent`

Renderizado al inicio de todos los elementos. Puede ser un Componente de React (ej. SomeComponent) o un elemento React (ej. <SomeComponent />).

Type
component, element

`ListHeaderComponentStyle`

Estilo para la View interna de ListHeaderComponent.

Type
View Style

`columnWrapperStyle`

Estilo personalizado opcional para filas multi-elemento generadas cuando numColumns > 1.

Type
View Style

`extraData`

Propiedad marcadora para indicar a la lista que vuelva a renderizar (dado que implementa PureComponent). Si tus funciones renderItem, Header, Footer, etc. dependen de algo externo a la prop data, inclúyelo aquí y trátalo como inmutable.

Type
any

`getItemLayout`

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

getItemLayout es una optimización opcional que permite omitir la medición de contenido dinámico si conoces el tamaño (altura o ancho) de los elementos de antemano. getItemLayout es eficiente si tienes elementos de tamaño fijo, por ejemplo:

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

Añadir getItemLayout puede ser un gran impulso de rendimiento para listas de varios cientos de elementos. Recuerda incluir la longitud del separador (altura o ancho) en tu cálculo de offset si especificas ItemSeparatorComponent.

Type
function

`horizontal`

Si es true, renderiza los elementos horizontalmente uno al lado del otro, en lugar de apilados verticalmente.

Type
boolean

`initialNumToRender`

Cantidad de elementos a renderizar en el lote inicial. Debe ser suficiente para llenar la pantalla pero no mucho más. Nota que estos elementos nunca se desmontarán como parte del renderizado por ventanas para mejorar el rendimiento percibido de acciones de scroll al inicio.

Type	Default
number	`10`

`initialScrollIndex`

En lugar de comenzar al inicio con el primer elemento, comienza en initialScrollIndex. Esto desactiva la optimización de "scroll al inicio" que mantiene siempre renderizados los primeros initialNumToRender elementos, y renderiza inmediatamente los elementos a partir de este índice inicial. Requiere que se implemente getItemLayout.

Type
number

`inverted`

Invierte la dirección de desplazamiento. Utiliza transformaciones de escala de -1.

Type
boolean

`keyExtractor`

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

Usado para extraer una clave única para un elemento dado en el índice especificado. La clave se usa para caché y como clave React para rastrear reordenamientos. El extractor por defecto verifica item.key, luego item.id, y finalmente recurre al índice, como hace React.

Type
function

`numColumns`

La renderización de múltiples columnas solo es posible con horizontal={false} y tendrá un patrón en zig-zag similar al diseño flexWrap. Todos los elementos deben tener la misma altura; no se admiten diseños tipo mampostería.

Type
number

`onRefresh`

tsx
() => void;

Si se proporciona, se añadirá un RefreshControl estándar para la funcionalidad de "Pull to Refresh". Asegúrate de configurar correctamente también la prop refreshing.

Type
function

`onViewableItemsChanged`

Se llama cuando cambia la visibilidad de las filas, según lo definido por la prop viewabilityConfig.

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

`progressViewOffset`

Configura esto cuando se necesite un desplazamiento para que el indicador de carga se muestre correctamente.

Type
number

`refreshing`

Establécelo en true mientras esperas nuevos datos durante una actualización.

Type
boolean

`removeClippedSubviews`

Puede mejorar el rendimiento del desplazamiento en listas grandes. En Android el valor predeterminado es true.

Nota: Puede tener errores (contenido faltante) en ciertas circunstancias; úsalo bajo tu propio riesgo.

Type
boolean

`viewabilityConfig`

Consulta ViewabilityHelper.js para ver el tipo de flujo y documentación adicional.

Type
ViewabilityConfig

viewabilityConfig recibe un tipo ViewabilityConfig: un objeto con las siguientes propiedades.

Property	Type
minimumViewTime	number
viewAreaCoveragePercentThreshold	number
itemVisiblePercentThreshold	number
waitForInteraction	boolean

Se requiere al menos uno de estos umbrales: viewAreaCoveragePercentThreshold o itemVisiblePercentThreshold. Esto debe hacerse en el constructor para evitar el siguiente error (ref):

  Error: Changing viewabilityConfig on the fly is not supported

tsx
constructor (props) {
  super(props)

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

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

minimumViewTime

Tiempo mínimo (en milisegundos) que un elemento debe ser visible físicamente antes de activar el callback de visibilidad. Un valor alto significa que al desplazarse rápidamente sin detenerse, el contenido no se marcará como visible.

viewAreaCoveragePercentThreshold

Porcentaje del viewport que debe cubrirse para que un elemento parcialmente ocluido cuente como "visible" (0-100). Los elementos completamente visibles siempre se consideran visibles. Un valor de 0 significa que un solo píxel visible hace que el elemento sea visible, mientras que un valor de 100 requiere que el elemento esté completamente visible o cubra todo el viewport.

itemVisiblePercentThreshold

Similar a viewAreaCoveragePercentThreshold, pero considera el porcentaje visible del elemento, no la fracción del área visible que cubre.

waitForInteraction

Nada se considera visible hasta que el usuario se desplaza o se llama a recordInteraction después de la renderización.

`viewabilityConfigCallbackPairs`

Lista de pares ViewabilityConfig/onViewableItemsChanged. Se llamará al onViewableItemsChanged específico cuando se cumplan las condiciones de su ViewabilityConfig correspondiente. Consulta ViewabilityHelper.js para el tipo de flujo y documentación adicional.

Type
array of ViewabilityConfigCallbackPair

Métodos

`flashScrollIndicators()`

tsx
flashScrollIndicators();

Muestra momentáneamente los indicadores de desplazamiento.

`getNativeScrollRef()`

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

Proporciona una referencia al componente de desplazamiento subyacente.

`getScrollResponder()`

tsx
getScrollResponder(): ScrollResponderMixin;

Proporciona un manejador al respondedor de desplazamiento subyacente.

`getScrollableNode()`

tsx
getScrollableNode(): any;

Proporciona un manejador al nodo de desplazamiento subyacente.

`scrollToEnd()`

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

Desplaza al final del contenido. Puede tener problemas de rendimiento sin la prop getItemLayout.

Parámetros:

Name	Type
params	object

Las claves válidas para params son:

'animated' (boolean) - Si la lista debe realizar una animación al desplazarse. Por defecto true.

`scrollToIndex()`

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

Desplaza la lista hasta el elemento en el índice especificado, posicionándolo en el área visible donde viewPosition 0 lo coloca en la parte superior, 1 en la inferior y 0.5 centrado en el medio.

Nota: No se puede desplazar a ubicaciones fuera de la ventana de renderizado sin especificar la prop getItemLayout.

Parámetros:

Name	Type
params Required	object

Las claves válidas para params son:

'animated' (boolean) - Si la lista debe realizar una animación al desplazarse. Por defecto true.
'index' (number) - El índice al que desplazarse. Requerido.
'viewOffset' (number) - Número fijo de píxeles para compensar la posición objetivo final.
'viewPosition' (number) - Valor 0 coloca el elemento en la parte superior, 1 en la inferior y 0.5 centrado.

`scrollToItem()`

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

Requiere escaneo lineal de datos - usa scrollToIndex cuando sea posible.

Nota: No se puede desplazar a ubicaciones fuera de la ventana de renderizado sin especificar la prop getItemLayout.

Parámetros:

Name	Type
params Required	object

Las claves válidas para params son:

'animated' (boolean) - Si la lista debe realizar una animación al desplazarse. Por defecto true.
'item' (object) - Elemento al que desplazarse. Requerido.
'viewPosition' (number)

`scrollToOffset()`

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

Desplaza la lista hasta un desplazamiento (offset) específico en píxeles.

Parámetros:

Name	Type
params Required	object

Las claves válidas para params son:

'offset' (number) - Desplazamiento objetivo. Cuando horizontal es verdadero, el desplazamiento es el valor x; en otros casos, el valor y. Requerido.
'animated' (boolean) - Si la lista debe realizar una animación al desplazarse. Por defecto true.

Ejemplo​

Referencia

Props​

Props de VirtualizedList​

Required renderItem​

Required data​

ItemSeparatorComponent​

ListEmptyComponent​

ListFooterComponent​

ListFooterComponentStyle​

ListHeaderComponent​

ListHeaderComponentStyle​

columnWrapperStyle​

extraData​

getItemLayout​

horizontal​

initialNumToRender​

initialScrollIndex​

inverted​

keyExtractor​

numColumns​

onRefresh​

onViewableItemsChanged​

progressViewOffset​

refreshing​

removeClippedSubviews​

viewabilityConfig​

minimumViewTime​

viewAreaCoveragePercentThreshold​

itemVisiblePercentThreshold​

waitForInteraction​

viewabilityConfigCallbackPairs​

Métodos​

flashScrollIndicators()​

getNativeScrollRef()​

getScrollResponder()​

getScrollableNode()​

scrollToEnd()​

scrollToIndex()​

scrollToItem()​

scrollToOffset()​

Ejemplo

Props

Props de VirtualizedList

Required
`renderItem`

Required
`data`

`ItemSeparatorComponent`

`ListEmptyComponent`

`ListFooterComponent`

`ListFooterComponentStyle`

`ListHeaderComponent`

`ListHeaderComponentStyle`

`columnWrapperStyle`

`extraData`

`getItemLayout`

`horizontal`

`initialNumToRender`

`initialScrollIndex`

`inverted`

`keyExtractor`

`numColumns`

`onRefresh`

`onViewableItemsChanged`

`progressViewOffset`

`refreshing`

`removeClippedSubviews`

`viewabilityConfig`

minimumViewTime

viewAreaCoveragePercentThreshold

itemVisiblePercentThreshold

waitForInteraction

`viewabilityConfigCallbackPairs`

Métodos

`flashScrollIndicators()`

`getNativeScrollRef()`

`getScrollResponder()`

`getScrollableNode()`

`scrollToEnd()`

`scrollToIndex()`

`scrollToItem()`

`scrollToOffset()`