ScrollView

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 →

Componente que envuelve el ScrollView de la plataforma proporcionando integración con el sistema de "respondedores" para bloqueo táctil.

Recuerda que los ScrollViews deben tener una altura limitada para funcionar correctamente, ya que contienen hijos de altura ilimitada dentro de un contenedor limitado (a través del desplazamiento). Para limitar la altura de un ScrollView, puedes establecer directamente la altura de la vista (no recomendado) o asegurarte de que todas las vistas padre tengan altura limitada. Olvidar transferir {flex: 1} hacia abajo en la pila de vistas puede causar errores, que el inspector de elementos permite depurar rápidamente.

Aún no admite que otros respondedores contenidos bloqueen esta vista de desplazamiento para convertirse en el respondedor.

<ScrollView> vs <FlatList>: ¿cuál usar?

ScrollView renderiza todos sus componentes hijos de React simultáneamente, pero esto tiene un impacto negativo en el rendimiento.

Imagina que tienes una lista muy larga de elementos para mostrar, quizás contenido equivalente a varias pantallas. Crear componentes JS y vistas nativas para todo a la vez, gran parte de lo cual puede no mostrarse, contribuirá a un renderizado lento y mayor consumo de memoria.

Aquí es donde entra FlatList. FlatList renderiza elementos de forma diferida cuando están a punto de aparecer, y elimina los que se desplazan fuera de pantalla para ahorrar memoria y tiempo de procesamiento.

FlatList también es útil si necesitas renderizar separadores entre elementos, múltiples columnas, carga infinita al desplazar, o cualquier otra característica que soporta de forma nativa.

Ejemplo

---

Referencia

Propiedades

Props de View

Hereda las View Props.

---

StickyHeaderComponent

Componente de React para renderizar encabezados fijos, debe usarse con stickyHeaderIndices. Puede ser necesario si tu encabezado fijo usa transformaciones personalizadas, como cuando quieres un encabezado animado u ocultable. Si no se proporciona, se usará el componente predeterminado ScrollViewStickyHeader.

Type
component, element

---

alwaysBounceHorizontal

iOS

Si es true, la vista de desplazamiento rebota horizontalmente al llegar al final, incluso si el contenido es más pequeño que la propia vista.

Type	Default
bool	true when horizontal={true} false otherwise

---

alwaysBounceVertical

iOS

Si es true, la vista de desplazamiento rebota verticalmente al llegar al final, incluso si el contenido es más pequeño que la propia vista.

Type	Default
bool	false when horizontal={true} true otherwise

---

automaticallyAdjustContentInsets

iOS

Controla si iOS debe ajustar automáticamente el inset de contenido para vistas de desplazamiento detrás de barras de navegación o pestañas/herramientas.

Type	Default
bool	true

---

automaticallyAdjustKeyboardInsets

iOS

Controla si el ScrollView debe ajustar automáticamente su contentInset y scrollViewInsets cuando el teclado cambia de tamaño.

Type	Default
bool	false

---

automaticallyAdjustsScrollIndicatorInsets

iOS

Controla si iOS debe ajustar automáticamente los insets de los indicadores de desplazamiento. Ver documentación de Apple.

Type	Default
bool	true

---

bounces

iOS

Si es true, la vista rebota al final del contenido cuando este es más grande que la vista en el eje de desplazamiento. Si es false, desactiva todos los rebotes incluso si las props alwaysBounce* son true.

Type	Default
bool	true

---

bouncesZoom

iOS

Si es true, los gestos pueden hacer zoom más allá de min/max y se animará al valor límite al finalizar; de lo contrario, el zoom no excede los límites.

Type	Default
bool	true

---

canCancelContentTouches

iOS

Si es false, al iniciar el seguimiento, no intentará arrastrar si el toque se mueve.

Type	Default
bool	true

---

centerContent

iOS

Si es true, la vista centra automáticamente el contenido cuando es más pequeño que los límites del ScrollView; no tiene efecto con contenido más grande.

Type	Default
bool	false

---

contentContainerStyle

Estos estilos se aplicarán al contenedor de contenido del ScrollView que envuelve todas las vistas hijas. Ejemplo:

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

Type
View Style

---

contentInset

iOS

Cantidad de inset desde los bordes del ScrollView para el contenido.

Type	Default
object: {top: number, left: number, bottom: number, right: number}	{top: 0, left: 0, bottom: 0, right: 0}

---

contentInsetAdjustmentBehavior

iOS

Especifica cómo se usan los insets del área segura para modificar el área de contenido del ScrollView. Disponible en iOS 11 y posteriores.

Type	Default
enum('automatic', 'scrollableAxes', 'never', 'always')	'never'

---

contentOffset

Usado para establecer manualmente el desplazamiento inicial (offset).

Type	Default
Point	{x: 0, y: 0}

---

decelerationRate

Número decimal que determina la rapidez con que la vista de desplazamiento decelera después de que el usuario levanta el dedo. También puedes usar atajos de cadena "normal" y "fast" que coinciden con las configuraciones subyacentes de iOS para UIScrollViewDecelerationRateNormal y UIScrollViewDecelerationRateFast respectivamente.

• 'normal': 0.998 en iOS, 0.985 en Android.

• 'fast': 0.99 en iOS, 0.9 en Android.

Type	Default
enum('fast', 'normal'), number	'normal'

---

directionalLockEnabled

iOS

Cuando es true, el ScrollView intentará bloquearse solo en desplazamiento vertical u horizontal durante el arrastre.

Type	Default
bool	false

---

disableIntervalMomentum

Cuando es true, la vista de desplazamiento se detiene en el siguiente índice (en relación con la posición de desplazamiento al soltar) independientemente de la velocidad del gesto. Útil para paginación cuando la página es más pequeña que el ancho del ScrollView horizontal o la altura del ScrollView vertical.

Type	Default
bool	false

---

disableScrollViewPanResponder

Cuando es true, se deshabilita el pan responder predeterminado de JS en el ScrollView, dejando el control total de los toques a sus componentes hijos. Particularmente útil con snapToInterval habilitado, ya que no sigue patrones táctiles típicos. No usar en casos de ScrollView regulares sin snapToInterval ya que puede causar toques inesperados durante el desplazamiento.

Type	Default
bool	false

---

endFillColor

Android

A veces un ScrollView ocupa más espacio del que llena su contenido. En estos casos, esta propiedad rellena el resto del ScrollView con un color para evitar establecer un fondo y crear overdraw innecesario. Es una optimización avanzada no requerida en casos generales.

Type
color

---

fadingEdgeLength

Android

Desvanece los bordes del contenido desplazable.

Si el valor es mayor que 0, los bordes desvanecidos se ajustarán según la dirección y posición actual del desplazamiento, indicando si hay más contenido por mostrar.

Type	Default
number object: {start: number, end: number}	0

---

horizontal

Cuando es true, los elementos hijos se organizan horizontalmente en fila en lugar de verticalmente en columna.

Type	Default
bool	false

---

indicatorStyle

iOS

Estilo de los indicadores de desplazamiento.

• 'default': igual que black.

• 'black', el indicador de desplazamiento es black. Ideal para fondos claros.

• 'white', el indicador de desplazamiento es white. Ideal para fondos oscuros.

Type	Default
enum('default', 'black', 'white')	'default'

---

invertStickyHeaders

Si los encabezados fijos deben anclarse en la parte inferior en lugar de la superior del ScrollView. Normalmente se usa con ScrollViews invertidos.

Type	Default
bool	false

---

keyboardDismissMode

Determina si el teclado se oculta al arrastrar:

• 'none': los arrastres no ocultan el teclado.

• 'on-drag': el teclado se oculta cuando comienza un arrastre.

Solo iOS

• 'interactive': el teclado se oculta interactivamente con el arrastre y se mueve sincronizado con el toque. Arrastrar hacia arriba cancela el ocultamiento. En Android no es compatible y se comporta como 'none'.

Type	Default
enum('none', 'on-drag') Android enum('none', 'on-drag', 'interactive') iOS	'none'

---

keyboardShouldPersistTaps

Determina cuándo el teclado debe permanecer visible después de un toque.

• 'never': tocar fuera del campo de texto enfocado oculta el teclado. Los hijos no recibirán el toque.

• 'always': el teclado no se oculta automáticamente y el ScrollView no captura toques, pero sus hijos pueden capturarlos.

• 'handled': el teclado no se oculta automáticamente si el toque fue manejado por hijos del ScrollView.

• false (obsoleto, usar 'never')

• true (obsoleto, usar 'always')

Type	Default
enum('always', 'never', 'handled', false, true)	'never'

---

maintainVisibleContentPosition

Cuando se establece, el ScrollView ajustará la posición de desplazamiento para que el primer elemento hijo actualmente visible y en o más allá de minIndexForVisible no cambie de posición. Esto es útil para listas que cargan contenido en ambas direcciones, como un hilo de chat, donde nuevos mensajes entrantes podrían causar saltos en la posición de desplazamiento. Un valor de 0 es común, pero otros valores como 1 pueden usarse para omitir spinners de carga u otro contenido que no deba mantener su posición.

El parámetro opcional autoscrollToTopThreshold puede usarse para hacer que el contenido se desplace automáticamente al inicio después del ajuste, si el usuario estaba dentro del umbral superior antes del ajuste. También es útil en aplicaciones tipo chat donde se desea ver nuevos mensajes desplazándose a su lugar, pero no si el usuario ha desplazado hacia arriba y sería disruptivo un desplazamiento brusco.

Advertencia 1: Reordenar elementos en el ScrollView con esta función activada probablemente causará saltos y comportamiento irregular. Tiene solución pero actualmente no está planificado implementarla. Por ahora, no reordenes el contenido de ningún ScrollView o List que use esta función.

Advertencia 2: Esta función usa contentOffset y frame.origin en código nativo para calcular la visibilidad. Oclusiones, transformaciones y otras complejidades no se consideran para determinar si el contenido es "visible".

Type
object: {minIndexForVisible: number, autoscrollToTopThreshold: number}

---

maximumZoomScale

iOS

La escala máxima de zoom permitida.

Type	Default
number	1.0

---

minimumZoomScale

iOS

La escala mínima de zoom permitida.

Type	Default
number	1.0

---

nestedScrollEnabled

Android

Habilita el desplazamiento anidado para Android API nivel 21+.

Type	Default
bool	false

---

onContentSizeChange

Se llama cuando cambia el tamaño del contenido desplazable del ScrollView.

La función manejadora recibe dos parámetros: ancho y alto del contenido (contentWidth, contentHeight).

Se implementa usando el manejador onLayout adjunto al contenedor de contenido que renderiza este ScrollView.

Type
function

---

onMomentumScrollBegin

Se llama cuando comienza el desplazamiento por inercia (desplazamiento que ocurre cuando el ScrollView comienza a deslizarse).

Type
function

---

onMomentumScrollEnd

Se llama cuando termina el desplazamiento por inercia (desplazamiento que ocurre cuando el ScrollView se detiene gradualmente).

Type
function

---

onScroll

Se dispara como máximo una vez por fotograma durante el desplazamiento. El evento tiene la siguiente forma (todos los valores sin tipo especificado son números):

js

{
  nativeEvent: {
    contentInset: {bottom, left, right, top},
    contentOffset: {x, y},
    contentSize: {height, width},
    layoutMeasurement: {height, width},
    velocity: {x, y},
    responderIgnoreScroll: boolean,
    zoomScale,
    // iOS only
    targetContentOffset: {x, y}
  }
}

Type
function

---

onScrollBeginDrag

Se llama cuando el usuario comienza a arrastrar el ScrollView.

Type
function

---

onScrollEndDrag

Se llama cuando el usuario deja de arrastrar el ScrollView y este se detiene o comienza a deslizarse por inercia.

Type
function

---

onScrollToTop

iOS

Se dispara cuando el ScrollView se desplaza al inicio después de tocar la barra de estado.

Type
function

---

overScrollMode

Android

Usado para sobrescribir el valor predeterminado del modo overScroll.

Valores posibles:

• 'auto' - Permite over-scroll solo si el contenido es lo suficientemente grande como para desplazarse significativamente.

• 'always' - Siempre permite over-scroll en esta vista.

• 'never' - Nunca permite over-scroll en esta vista.

Type	Default
enum('auto', 'always', 'never')	'auto'

---

pagingEnabled

Cuando es true, el ScrollView se detiene en múltiplos del tamaño del ScrollView al desplazarse. Útil para paginación horizontal.

Type	Default
bool	false

---

persistentScrollbar

Android

Evita que las barras de desplazamiento se vuelvan transparentes cuando no están en uso.

Type	Default
bool	false

---

pinchGestureEnabled

iOS

Cuando es true, ScrollView permite gestos de pellizco para hacer zoom.

Type	Default
bool	true

---

refreshControl

Componente RefreshControl que proporciona funcionalidad pull-to-refresh. Solo funciona en ScrollViews verticales (la prop horizontal debe ser false).

Ver RefreshControl.

Type
element

---

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

---

scrollEnabled

Cuando es false, la vista no se puede desplazar mediante interacción táctil.

Nota: La vista siempre puede desplazarse llamando a scrollTo.

Type	Default
bool	true

---

scrollEventThrottle

Limita la frecuencia con que se disparan eventos de desplazamiento durante el scroll, especificado como intervalo de tiempo en ms. Útil cuando se realizan operaciones costosas en respuesta al desplazamiento. Valores ≤ 16 desactivan el throttling, independientemente de la tasa de refresco del dispositivo.

Type	Default
number	0

---

scrollIndicatorInsets

iOS

La cantidad en que los indicadores de desplazamiento se insertan desde los bordes del ScrollView. Normalmente debe establecerse al mismo valor que contentInset.

Type	Default
object: {top: number, left: number, bottom: number, right: number}	{top: 0, left: 0, bottom: 0, right: 0}

---

scrollPerfTag

Android

Etiqueta para registrar rendimiento de scroll en esta vista. Fuerza activación de eventos de momentum (ver sendMomentumEvents). Requiere implementar un FpsListener nativo personalizado para ser útil.

Type
string

---

scrollToOverflowEnabled

iOS

Cuando es true, el ScrollView puede desplazarse programáticamente más allá de su tamaño de contenido.

Type	Default
bool	false

---

scrollsToTop

iOS

Cuando es true, el ScrollView se desplaza al tope al tocar la barra de estado.

Type	Default
bool	true

---

showsHorizontalScrollIndicator

Cuando es true, muestra un indicador de desplazamiento horizontal.

Type	Default
bool	true

---

showsVerticalScrollIndicator

Cuando es true, muestra un indicador de desplazamiento vertical.

Type	Default
bool	true

---

snapToAlignment

Cuando snapToInterval está establecido, snapToAlignment define la relación del snap con el ScrollView:

Valores posibles:

• 'start' alinea el snap a la izquierda (horizontal) o superior (vertical).

• 'center' alinea el snap al centro.

• 'end' alinea el snap a la derecha (horizontal) o inferior (vertical).

Type	Default
enum('start', 'center', 'end')	'start'

---

snapToEnd

Úsalo con snapToOffsets. Por defecto, el final de la lista cuenta como offset de snap. Establece snapToEnd en false para desactivar esto y permitir scroll libre entre el final y el último offset de snapToOffsets.

Type	Default
bool	true

---

snapToInterval

Al establecerlo, el ScrollView se detiene en múltiplos del valor de snapToInterval. Útil para paginar hijos más pequeños que la vista. Normalmente se combina con snapToAlignment y decelerationRate="fast". Anula la prop pagingEnabled.

Type
number

---

snapToOffsets

Al establecerlo, el ScrollView se detiene en los offsets definidos. Útil para paginar hijos de varios tamaños. Normalmente se combina con decelerationRate="fast". Anula las props pagingEnabled y snapToInterval.

Type
array of number

---

snapToStart

Úsalo con snapToOffsets. Por defecto, el inicio de la lista cuenta como offset de snap. Establece snapToStart en false para permitir scroll libre entre el inicio y el primer offset de snapToOffsets.

Type	Default
bool	true

---

stickyHeaderHiddenOnScroll

Cuando es true, el encabezado sticky se oculta al desplazar hacia abajo y se acopla al tope al desplazar hacia arriba.

Type	Default
bool	false

---

stickyHeaderIndices

Un array de índices de hijos que determina qué hijos se anclan en la parte superior de la pantalla al desplazarse. Por ejemplo, pasar stickyHeaderIndices={[0]} hará que el primer hijo se fije en la parte superior del ScrollView. También puedes usar [x,y,z] para fijar múltiples elementos cuando estén en la parte superior. Esta propiedad no es compatible con horizontal={true}.

Type
array of number

---

zoomScale

iOS

La escala actual del contenido del ScrollView.

Type	Default
number	1.0

---

Métodos

flashScrollIndicators()

tsx

flashScrollIndicators();

Muestra momentáneamente los indicadores de desplazamiento.

---

scrollTo()

tsx

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

Desplaza hasta un desplazamiento x, y dado, ya sea inmediatamente o con una animación suave.

Ejemplo:

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

nota

La extraña firma de la función se debe a que, por razones históricas, también acepta argumentos separados como alternativa al objeto de opciones. Esto está obsoleto debido a la ambigüedad (y antes de x), y NO DEBE USARSE.

---

scrollToEnd()

tsx

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

Si es un ScrollView vertical, se desplaza hasta el final. Si es un ScrollView horizontal, se desplaza hasta la derecha.

Usa scrollToEnd({animated: true}) para un desplazamiento animado suave, scrollToEnd({animated: false}) para desplazamiento inmediato. Si no se pasan opciones, animated por defecto es true.