Versión: 0.78

Imagen

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 →

Un componente de React para mostrar diferentes tipos de imágenes, incluyendo imágenes de red, recursos estáticos, imágenes locales temporales e imágenes del disco local, como las del carrete de la cámara.

Este ejemplo muestra cómo obtener y mostrar una imagen del almacenamiento local, así como una de red e incluso de datos proporcionados en el esquema URI 'data:'.

Ten en cuenta que para imágenes de red y datos, ¡deberás especificar manualmente las dimensiones de tu imagen!

Ejemplos

También puedes añadir style a una imagen:

Soporte para GIF y WebP en Android

Al compilar tu propio código nativo, GIF y WebP no están soportados por defecto en Android.

Deberás añadir módulos opcionales en android/app/build.gradle, dependiendo de las necesidades de tu aplicación.

groovy
dependencies {
  // If your app supports Android versions before Ice Cream Sandwich (API level 14)
  implementation 'com.facebook.fresco:animated-base-support:1.3.0'

  // For animated GIF support
  implementation 'com.facebook.fresco:animated-gif:3.6.0'

  // For WebP support, including animated WebP
  implementation 'com.facebook.fresco:animated-webp:3.6.0'
  implementation 'com.facebook.fresco:webpsupport:3.6.0'

  // For WebP support, without animations
  implementation 'com.facebook.fresco:webpsupport:3.6.0'
}

Nota: la versión listada arriba podría no estar actualizada a tiempo. Consulta packages/react-native/gradle/libs.versions.toml en el repositorio principal para ver qué versión de fresco se usa en cada versión etiquetada específica.

Referencia

Props

Props de View

Hereda las View Props.

`accessible`

Cuando es verdadero, indica que la imagen es un elemento de accesibilidad.

Type	Default
bool	`false`

`accessibilityLabel`

El texto que lee el lector de pantalla cuando el usuario interactúa con la imagen.

Type
string

`alt`

Una cadena que define un texto alternativo descriptivo de la imagen, que será leído por el lector de pantalla cuando el usuario interactúe con ella. Usar esto marcará automáticamente este elemento como accesible.

Type
string

`blurRadius`

blurRadius: el radio de desenfoque del filtro añadido a la imagen.

Type
number

Consejo: En iOS, necesitarás aumentar blurRadius a más de 5.

`capInsets`
iOS

Cuando se redimensiona la imagen, las esquinas del tamaño especificado por capInsets mantendrán un tamaño fijo, mientras que el contenido central y los bordes se estirarán. Esto es útil para crear botones redondeados redimensionables, sombras y otros recursos escalables. Más información en la documentación oficial de Apple.

Type
Rect

`crossOrigin`

Una cadena con una palabra clave que especifica el modo CORS a usar al obtener el recurso de imagen. Funciona de forma similar al atributo crossorigin en HTML.

anonymous: Sin intercambio de credenciales de usuario en la solicitud de imagen.
use-credentials: Establece el valor de la cabecera Access-Control-Allow-Credentials a true en la solicitud de imagen.

Type	Default
enum(`'anonymous'`, `'use-credentials'`)	`'anonymous'`

`defaultSource`

Una imagen estática para mostrar mientras se carga el origen de la imagen.

Type
ImageSource

Nota: En Android, la propiedad defaultSource se ignora en las builds de depuración.

`fadeDuration`
Android

Duración de la animación de fundido en milisegundos.

Type	Default
number	`300`

`height`

Altura del componente de imagen.

Type
number

`loadingIndicatorSource`

Similar a source, esta propiedad representa el recurso usado para mostrar el indicador de carga de la imagen. El indicador se muestra hasta que la imagen está lista para visualizarse, típicamente después de su descarga.

Type
ImageSource (`uri` only), number

`onError`

Se invoca cuando ocurre un error de carga.

Type
(`{nativeEvent: {error} }`) => void

`onLayout`

Se invoca al montar y en cambios de diseño.

Type
`({nativeEvent: LayoutEvent} => void`

`onLoad`

Se invoca cuando la carga se completa exitosamente.

Ejemplo: onLoad={({nativeEvent: {source: {width, height}}}) => setImageRealSize({width, height})}

Type
`({nativeEvent: ImageLoadEvent} => void`

`onLoadEnd`

Se invoca cuando la carga tiene éxito o falla.

Type
() => void

`onLoadStart`

Se invoca al iniciar la carga.

Ejemplo: onLoadStart={() => this.setState({loading: true})}

Type
() => void

`onPartialLoad`
iOS

Se invoca cuando se completa una carga parcial de la imagen. La definición de lo que constituye una "carga parcial" depende del cargador, aunque está pensado para cargas progresivas de JPEG.

Type
() => void

`onProgress`

Se invoca durante el progreso de la descarga.

Type
(`{nativeEvent: {loaded, total} }`) => void

`progressiveRenderingEnabled`
Android

Cuando es true, habilita la transmisión progresiva de JPEG - https://frescolib.org/docs/progressive-jpegs.

Type	Default
bool	`false`

`referrerPolicy`

Cadena que indica qué referente usar al obtener el recurso. Establece el valor para el encabezado Referrer-Policy en la solicitud de imagen. Funciona similar al atributo referrerpolicy en HTML.

Type	Default
enum(`'no-referrer'`, `'no-referrer-when-downgrade'`, `'origin'`, `'origin-when-cross-origin'`, `'same-origin'`, `'strict-origin'`, `'strict-origin-when-cross-origin'`, `'unsafe-url'`)	`'strict-origin-when-cross-origin'`

`resizeMethod`
Android

Mecanismo que debe usarse para redimensionar la imagen cuando sus dimensiones difieren de las de la vista. Por defecto es auto.

auto: Usa heurísticas para elegir entre resize y scale.
resize: Operación de software que modifica la imagen codificada en memoria antes de decodificarse. Debe usarse en lugar de scale cuando la imagen es mucho más grande que la vista.
scale: La imagen se dibuja escalada hacia abajo o hacia arriba. Comparado con resize, scale es más rápido (usualmente acelerado por hardware) y produce imágenes de mayor calidad. Debe usarse si la imagen es más pequeña que la vista o ligeramente más grande.
none: No se realiza muestreo y la imagen se muestra en su resolución completa. Solo debe usarse en circunstancias excepcionales porque se considera inseguro, ya que Android lanzará una excepción en tiempo de ejecución al intentar renderizar imágenes que consumen demasiada memoria.

Más detalles sobre resize y scale en https://frescolib.org/docs/resizing.

Type	Default
enum(`'auto'`, `'resize'`, `'scale'`, `'none'`)	`'auto'`

`resizeMode`

Determina cómo redimensionar la imagen cuando el marco no coincide con las dimensiones originales de la imagen. Por defecto es cover.

cover: Escala la imagen uniformemente (manteniendo relación de aspecto) de modo que:
- Ambas dimensiones (ancho y alto) sean iguales o mayores que las correspondientes de la vista (menos el relleno)
- Al menos una dimensión de la imagen escalada sea igual a la correspondiente de la vista (menos el relleno)
contain: Escala la imagen uniformemente (manteniendo la relación de aspecto) de modo que ambas dimensiones (ancho y alto) de la imagen serán iguales o menores que la dimensión correspondiente de la vista (menos el padding).
stretch: Escala el ancho y alto independientemente, lo que puede cambiar la relación de aspecto de la imagen original.
repeat: Repite la imagen para cubrir el marco de la vista. La imagen mantendrá su tamaño y relación de aspecto, a menos que sea más grande que la vista, en cuyo caso se reducirá uniformemente para que quepa en la vista.
center: Centra la imagen en la vista a lo largo de ambas dimensiones. Si la imagen es más grande que la vista, se reduce uniformemente para que quepa en la vista.

Type	Default
enum(`'cover'`, `'contain'`, `'stretch'`, `'repeat'`, `'center'`)	`'cover'`

`resizeMultiplier`
Android

Cuando resizeMethod es resize, las dimensiones destino se multiplican por este valor. El método scale se usa para el resto del redimensionado. Un valor predeterminado de 1.0 significa que el tamaño del bitmap está diseñado para ajustarse a las dimensiones destino. Un multiplicador mayor que 1.0 establecerá opciones de redimensionado más grandes que las dimensiones destino, y el bitmap resultante se escalará a partir del tamaño de hardware. Por defecto es 1.0.

Esta propiedad es especialmente útil cuando las dimensiones de destino son muy pequeñas y la imagen de origen es significativamente más grande. El método de redimensionamiento resize realiza una reducción de muestreo donde se pierde calidad significativa entre las dimensiones de origen y destino, lo que a menudo produce imágenes borrosas. Al usar un multiplicador, la imagen decodificada resulta ligeramente más grande que el tamaño objetivo pero más pequeña que la imagen original (si la fuente es lo suficientemente grande). Esto permite que los artefactos de aliasing generen una calidad aparente mediante operaciones de escalado en la imagen multiplicada.

Si tienes una imagen de origen de 200x200 y dimensiones de destino de 24x24, un resizeMultiplier de 2.0 indica a Fresco que reduzca el muestreo a 48x48. Fresco selecciona la potencia de 2 más cercana (50x50 en este caso) y decodifica la imagen en un bitmap de ese tamaño. Sin el multiplicador, la potencia de 2 más cercana sería 25x25. El sistema escala la imagen resultante.

Type	Default
number	`1.0`

`source`

La fuente de la imagen (puede ser una URL remota o un recurso de archivo local).

Esta propiedad también puede contener múltiples URLs remotas, especificadas junto con su ancho, alto y potencialmente argumentos de escala u otros parámetros URI. El lado nativo elegirá la mejor uri para mostrar según el tamaño medido del contenedor de la imagen. Se puede añadir una propiedad cache para controlar cómo interactúa la solicitud de red con la caché local (más información en Control de caché para imágenes).

Los formatos actualmente compatibles son png, jpg, jpeg, bmp, gif, webp y psd (solo iOS). Además, iOS admite varios formatos RAW de imagen. Consulta la documentación de Apple para ver los modelos de cámara compatibles actualmente (para iOS 12: https://support.apple.com/en-ca/HT208967).

Ten en cuenta que el formato webp en iOS solo es compatible cuando se incluye con el código JavaScript.

Type
ImageSource

`src`

Una cadena que representa la URL remota de la imagen. Esta propiedad tiene prioridad sobre la prop source.

Ejemplo: src={'https://reactnative.dev/img/tiny_logo.png'}

Type
string

`srcSet`

Una cadena que representa una lista separada por comas de posibles fuentes de imagen candidatas. Cada fuente contiene una URL y un descriptor de densidad de píxeles. Si no se especifica descriptor, por defecto es 1x.

Si srcSet no contiene un descriptor 1x, se usa el valor de src como fuente de imagen con descriptor 1x (si está disponible).

Esta propiedad tiene prioridad sobre tanto src como source.

Ejemplo: srcSet={'https://reactnative.dev/img/tiny_logo.png 1x, https://reactnative.dev/img/header_logo.svg 2x'}

Type
string

`style`

Type
Image Style Props, Layout Props, Shadow Props, Transforms

`testID`

Un identificador único para este elemento usado en scripts de pruebas de automatización de UI.

Type
string

`tintColor`

Cambia el color de todos los píxeles no transparentes al tintColor.

Type
color

`width`

Ancho del componente de imagen.

Type
number

Métodos

`abortPrefetch()`
Android

tsx
static abortPrefetch(requestId: number);

Aborta la solicitud de precarga.

Parámetros:

Name	Type	Description
requestId Required	number	Request id as returned by `prefetch()`.

`getSize()`

tsx
static getSize(uri: string): Promise<{width: number, height: number}>;

Obtiene el ancho y alto (en píxeles) de una imagen antes de mostrarla. Este método puede fallar si la imagen no se encuentra o no se descarga.

Para recuperar las dimensiones de la imagen, primero puede ser necesario cargarla o descargarla, tras lo cual se almacenará en caché. Esto significa que en principio podrías usar este método para pre-cargar imágenes, aunque no está optimizado para ese propósito y en el futuro podría implementarse de manera que no cargue/descargue completamente los datos de la imagen. Una forma adecuada y soportada para pre-cargar imágenes se proporcionará como una API separada.

Parámetros:

Name	Type	Description
uri Required	string	The location of the image.

`getSizeWithHeaders()`

tsx
static getSizeWithHeaders(
  uri: string,
  headers: {[index: string]: string}
): Promise<{width: number, height: number}>;

Recupera el ancho y alto (en píxeles) de una imagen antes de mostrarla, con la posibilidad de proporcionar encabezados para la solicitud. Este método puede fallar si la imagen no se encuentra o no se descarga correctamente. Tampoco funciona para recursos de imágenes estáticas.

Parámetros:

Name	Type	Description
uri Required	string	The location of the image.
headers Required	object	The headers for the request.

`prefetch()`

tsx
await Image.prefetch(url);

Precarga una imagen remota para uso futuro descargándola a la caché del disco. Devuelve una promesa que se resuelve en un valor booleano.

Parámetros:

Name	Type	Description
url Required	string	The remote location of the image.
callback	function Android	The function that will be called with the `requestId`.

`queryCache()`

tsx
static queryCache(
  urls: string[],
): Promise<Record<string, 'memory' | 'disk' | 'disk/memory'>>;

Realiza una consulta de caché. Devuelve una promesa que se resuelve en un mapeo desde URL a estado de caché, como "disk", "memory" o "disk/memory". Si una URL solicitada no está en el mapeo, significa que no está en la caché.

Parámetros:

Name	Type	Description
urls Required	array	List of image URLs to check the cache for.

`resolveAssetSource()`

tsx
static resolveAssetSource(source: ImageSourcePropType): {
  height: number;
  width: number;
  scale: number;
  uri: string;
};

Resuelve una referencia a recurso en un objeto que tiene las propiedades uri, scale, width y height.

Parámetros:

Name	Type	Description
source Required	ImageSource, number	A number (opaque type returned by `require('./foo.png')`) or an ImageSource.

Definiciones de tipos

ImageCacheEnum
iOS

Enumeración que puede usarse para configurar el manejo o estrategia de caché para respuestas potencialmente almacenadas en caché.

Type	Default
enum(`'default'`, `'reload'`, `'force-cache'`, `'only-if-cached'`)	`'default'`

default: Usa la estrategia predeterminada de la plataforma nativa.
reload: Los datos para la URL se cargarán desde la fuente original. No se deben usar datos de caché existentes para satisfacer una solicitud de carga de URL.
force-cache: Se usarán los datos en caché existentes para satisfacer la solicitud, independientemente de su antigüedad o fecha de expiración. Si no hay datos existentes en la caché para la solicitud, los datos se cargan desde la fuente original.
only-if-cached: Se usarán los datos en caché existentes para satisfacer la solicitud, independientemente de su antigüedad o fecha de expiración. Si no hay datos existentes en la caché correspondientes a una solicitud de carga de URL, no se intenta cargar los datos desde la fuente original y la carga se considera fallida.

ImageLoadEvent

Objeto devuelto en la devolución de llamada onLoad.

Type
object

Propiedades:

Name	Type	Description
source	object	The source object

Source Object

Propiedades:

Name	Type	Description
width	number	The width of loaded image.
height	number	The height of loaded image.
uri	string	A string representing the resource identifier for the image.

ImageSource

Type
object, array of objects, number

Propiedades (si se pasa como objeto o array de objetos):

Name	Type	Description
uri	string	A string representing the resource identifier for the image, which could be an http address, a local file path, or the name of a static image resource.
width	number	Can be specified if known at build time, in which case the value will be used to set the default `<Image/>` component dimension.
height	number	Can be specified if known at build time, in which case the value will be used to set the default `<Image/>` component dimension.
scale	number	Used to indicate the scale factor of the image. Defaults to `1.0` if unspecified, meaning that one image pixel equates to one display point / DIP.
bundle iOS	string	The iOS asset bundle which the image is included in. This will default to `[NSBundle mainBundle]` if not set.
method	string	The HTTP Method to use. Defaults to `'GET'` if not specified.
headers	object	An object representing the HTTP headers to send along with the request for a remote image.
body	string	The HTTP body to send with the request. This must be a valid UTF-8 string, and will be sent exactly as specified, with no additional encoding (e.g. URL-escaping or base64) applied.
cache iOS	ImageCacheEnum	Determines how the requests handles potentially cached responses.

Si se pasa un número:

number - tipo opaco devuelto por algo como require('./image.jpg').

Ejemplos​

Soporte para GIF y WebP en Android​

Referencia

Props​

Props de View​

accessible​

accessibilityLabel​

alt​

blurRadius​

capInsets iOS​

crossOrigin​

defaultSource​

fadeDuration Android​

height​

loadingIndicatorSource​

onError​

onLayout​

onLoad​

onLoadEnd​

onLoadStart​

onPartialLoad iOS​

onProgress​

progressiveRenderingEnabled Android​

referrerPolicy​

resizeMethod Android​

resizeMode​

resizeMultiplier Android​

source​

src​

srcSet​

style​

testID​

tintColor​

width​

Métodos​

abortPrefetch() Android​

getSize()​

getSizeWithHeaders()​

prefetch()​

queryCache()​

resolveAssetSource()​

Definiciones de tipos​

ImageCacheEnum iOS​

ImageLoadEvent​

Source Object​

ImageSource​

Ejemplos

Soporte para GIF y WebP en Android

Props

Props de View

`accessible`

`accessibilityLabel`

`alt`

`blurRadius`

`capInsets`
iOS

`crossOrigin`

`defaultSource`

`fadeDuration`
Android

`height`

`loadingIndicatorSource`

`onError`

`onLayout`

`onLoad`

`onLoadEnd`

`onLoadStart`

`onPartialLoad`
iOS

`onProgress`

`progressiveRenderingEnabled`
Android

`referrerPolicy`

`resizeMethod`
Android

`resizeMode`

`resizeMultiplier`
Android

`source`

`src`

`srcSet`

`style`

`testID`

`tintColor`

`width`

Métodos

`abortPrefetch()`
Android

`getSize()`

`getSizeWithHeaders()`

`prefetch()`

`queryCache()`

`resolveAssetSource()`

Definiciones de tipos

ImageCacheEnum
iOS

ImageLoadEvent

Source Object

ImageSource