VirtualizedList

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 →

Implementación base para los componentes más convenientes <FlatList> y <SectionList>, que también están mejor documentados. En general, solo deberías usar esto si necesitas más flexibilidad de la que ofrece FlatList, por ejemplo para trabajar con datos inmutables en lugar de arrays simples.

La virtualización mejora masivamente el consumo de memoria y rendimiento en listas grandes manteniendo una ventana de renderizado finita de elementos activos, reemplazando los elementos fuera de esta ventana con espacios en blanco de tamaño adecuado. La ventana se adapta al comportamiento de scroll, y los elementos se renderizan incrementalmente con baja prioridad (tras interacciones en curso) si están lejos del área visible, o con alta prioridad para minimizar la posibilidad de ver espacios vacíos.

Ejemplo

TypeScript

JavaScript

---

Algunas 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.

• Este es un PureComponent, lo que significa que no se volverá a renderizar si las props son superficialmente iguales. Asegúrate de que todo lo que depende tu función renderItem se pase como prop (ej. extraData) que no sea === tras actualizaciones, de lo contrario tu UI podría no actualizarse con los cambios. 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 ScrollView

Hereda las props de ScrollView.

---

data

Tipo de datos opaco pasado a getItem y getItemCount para recuperar elementos.

Type
any

---

Required

getItem

tsx

(data: any, index: number) => any;

Un accesor genérico para extraer un elemento de cualquier blob de datos.

Type
function

---

Required

getItemCount

tsx

(data: any) => number;

Determina cuántos elementos hay en el blob de datos.

Type
function

---

Required

renderItem

tsx

(info: any) => ?React.Element<any>

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

Type
function

---

CellRendererComponent

CellRendererComponent permite personalizar cómo se envuelven las celdas renderizadas por renderItem/ListItemComponent al colocarse en el ScrollView subyacente. Este componente debe aceptar manejadores de eventos que notifiquen a VirtualizedList sobre cambios dentro de la celda.

Type
React.ComponentType<CellRendererProps>

---

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

---

ListItemComponent

Cada elemento de datos se renderiza usando este elemento. Puede ser una Clase de Componente React o una función de renderizado.

Type
component, function

---

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	Required
ViewStyleProp	No

---

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

---

debug

debug activará registro extra y superposiciones visuales para ayudar en depuración de uso e implementación, pero con un impacto significativo de rendimiento.

Type
boolean

---

🗑️ disableVirtualization

Obsoleto

La virtualización proporciona optimizaciones significativas de rendimiento y memoria, pero desmonta completamente instancias React fuera de la ventana de renderizado. Solo deberías desactivar esto con fines de depuración.

Type
boolean

---

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: any,
  index: number,
) => {length: number, offset: number, index: number}

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: any, 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

---

maxToRenderPerBatch

La cantidad máxima de elementos a renderizar en cada lote incremental. Cuantos más se rendericen a la vez, mejor será la tasa de llenado, pero la capacidad de respuesta puede verse afectada porque renderizar contenido puede interferir con toques de botones u otras interacciones.

Type
number

---

onEndReached

Se llama una vez cuando la posición de scroll llega dentro de onEndReachedThreshold desde el final lógico de la lista.

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

---

onEndReachedThreshold

Qué tan lejos del final (en unidades de longitud visible de la lista) debe estar el borde final de la lista desde el final del contenido para activar el callback onEndReached. Así, un valor de 0.5 activará onEndReached cuando el final del contenido esté dentro de la mitad de la longitud visible de la lista.

Type	Default
number	2

---

onRefresh

tsx

() => void;

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

Type
function

---

onScrollToIndexFailed

tsx

(info: {
  index: number,
  highestMeasuredFrameIndex: number,
  averageItemLength: number,
}) => void;

Usado para manejar fallos al hacer scroll a un índice que aún no ha sido medido. La acción recomendada es calcular tu propio offset y hacer scrollTo hacia él, o desplazarse lo más posible e intentar nuevamente tras renderizar más elementos.

Type
function

---

onStartReached

Se llama una vez cuando la posición de desplazamiento llega a onStartReachedThreshold desde el inicio lógico de la lista.

Type
(info: {distanceFromStart: number}) => void

---

onStartReachedThreshold

Distancia desde el inicio (en unidades de longitud visible de la lista) que el borde inicial debe estar del contenido para activar el callback onStartReached. Un valor de 0.5 activará onStartReached cuando el inicio del contenido esté dentro de la mitad de la longitud visible de la lista.

Type	Default
number	2

---

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

---

persistentScrollbar

Type
bool

---

progressViewOffset

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

Type
number

---

refreshControl

Elemento personalizado de control de actualización. Al configurarse, reemplaza el componente <RefreshControl> predeterminado. Las props onRefresh y refreshing se ignoran. Solo funciona para VirtualizedList vertical.

Type
element

---

refreshing

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

Type
boolean

---

removeClippedSubviews

advertencia

Usar esta propiedad puede causar bugs (contenido faltante) en ciertas circunstancias - úsala bajo tu propio riesgo.

Cuando es true, las vistas secundarias fuera de pantalla se eliminan de su supervista nativa de respaldo. Esto puede mejorar el rendimiento del scroll en listas grandes. En Android, el valor predeterminado es true.

Type
boolean

---

renderScrollComponent

tsx

(props: object) => element;

Renderiza un componente de desplazamiento personalizado, ej. con un RefreshControl de estilo diferente.

Type
function

---

viewabilityConfig

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

Type
ViewabilityConfig

---

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

---

updateCellsBatchingPeriod

Tiempo entre lotes de renderizado de baja prioridad, ej. para elementos lejos de la pantalla. Similar compensación de tasa de llenado/responsividad que maxToRenderPerBatch.

Type
number

---

windowSize

Determina la cantidad máxima de elementos renderizados fuera del área visible, en unidades de longitudes visibles. Si tu lista llena la pantalla, windowSize={21} (valor predeterminado) renderizará el área visible más hasta 10 pantallas arriba y 10 abajo. Reducir este número disminuye el consumo de memoria y puede mejorar el rendimiento, pero aumenta la posibilidad de que scroll rápido muestre áreas vacías momentáneas.

Type
number

Métodos

flashScrollIndicators()

tsx

flashScrollIndicators();

---

getScrollableNode()

tsx

getScrollableNode(): any;

---

getScrollRef()

tsx

getScrollRef():
  | React.ElementRef<typeof ScrollView>
  | React.ElementRef<typeof View>
  | null;

---

getScrollResponder()

tsx

getScrollResponder () => ScrollResponderMixin | null;

Provee un manejador al respondedor de desplazamiento subyacente. Nota que this._scrollRef podría no ser un ScrollView, así que debemos verificar si responde a getScrollResponder antes de llamarlo.

---

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' (booleano) - Si la lista debe animarse al desplazarse. Por defecto true.

---

scrollToIndex()

tsx

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

Parámetros válidos (params) consisten en:

• 'index' (número). Requerido.

• 'animated' (booleano). Opcional.

• 'viewOffset' (número). Opcional.

• 'viewPosition' (número). Opcional.

---

scrollToItem()

tsx

scrollToItem(params: {
  item: ItemT;
  animated?: boolean;
  viewOffset?: number;
  viewPosition?: number;
);

Parámetros válidos (params) consisten en:

• 'item' (Item). Requerido.

• 'animated' (booleano). Opcional.

• 'viewOffset' (número). Opcional.

• 'viewPosition' (número). Opcional.

---

scrollToOffset()

tsx

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

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

El parámetro offset espera el desplazamiento objetivo. Si horizontal es true, el offset es el valor X; en otros casos es el valor Y.

El parámetro animated (true por defecto) define si la lista debe animarse al desplazarse.