Imágenes
Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →
Recursos de imágenes estáticas
React Native proporciona una forma unificada de gestionar imágenes y otros recursos multimedia en tus aplicaciones para Android e iOS. Para añadir una imagen estática a tu aplicación, colócala en algún lugar del árbol de tu código fuente y refiérete a ella así:
<Image source={require('./my-icon.png')} />
El nombre de la imagen se resuelve de la misma manera que los módulos de JavaScript. En el ejemplo anterior, el bundler buscará my-icon.png en la misma carpeta que el componente que lo requiere.
Puedes usar los sufijos @2x y @3x para proporcionar imágenes para diferentes densidades de pantalla. Si tienes la siguiente estructura de archivos:
.
├── button.js
└── img
├── check.png
├── check@2x.png
└── check@3x.png
...y el código en button.js contiene:
<Image source={require('./img/check.png')} />
...el bundler empaquetará y servirá la imagen correspondiente a la densidad de pantalla del dispositivo. Por ejemplo, check@2x.png se usará en un iPhone 7, mientras que check@3x.png se usará en un iPhone 7 Plus o Nexus 5. Si no hay una imagen que coincida con la densidad de pantalla, se seleccionará la opción más cercana disponible.
En Windows, es posible que necesites reiniciar el bundler si añades nuevas imágenes a tu proyecto.
Estos son algunos beneficios que obtienes:
-
Mismo sistema para Android e iOS.
-
Las imágenes residen en la misma carpeta que tu código JavaScript. Los componentes son autocontenidos.
-
Sin espacio de nombres global, es decir, no debes preocuparte por colisiones de nombres.
-
Solo las imágenes realmente utilizadas se incluirán en tu aplicación.
-
Añadir y cambiar imágenes no requiere recompilar la aplicación; puedes refrescar el simulador como lo haces normalmente.
-
El bundler conoce las dimensiones de la imagen, no es necesario duplicarlas en el código.
-
Las imágenes pueden distribuirse mediante paquetes de npm.
Para que esto funcione, el nombre de la imagen en require debe conocerse estáticamente.
// GOOD
<Image source={require('./my-icon.png')} />;
// BAD
const icon = this.props.active
? 'my-icon-active'
: 'my-icon-inactive';
<Image source={require('./' + icon + '.png')} />;
// GOOD
const icon = this.props.active
? require('./my-icon-active.png')
: require('./my-icon-inactive.png');
<Image source={icon} />;
Ten en cuenta que las fuentes de imagen requeridas de esta manera incluyen información de tamaño (ancho, alto) para el componente Image. Si necesitas escalar la imagen dinámicamente (por ejemplo, mediante flex), es posible que debas establecer manualmente {width: undefined, height: undefined} en el atributo de estilo.
Recursos estáticos no visuales
La sintaxis require descrita anteriormente también puede usarse para incluir estáticamente archivos de audio, video o documentos en tu proyecto. Se admiten los formatos más comunes, incluidos .mp3, .wav, .mp4, .mov, .html y .pdf. Consulta los valores predeterminados del bundler para ver la lista completa.
Puedes añadir soporte para otros tipos agregando una opción assetExts en tu configuración de Metro.
Una advertencia es que los videos deben usar posicionamiento absoluto en lugar de flexGrow, ya que actualmente no se transfiere información de tamaño para recursos no visuales. Esta limitación no ocurre con videos vinculados directamente en Xcode o en la carpeta Assets de Android.
Imágenes de recursos de aplicaciones híbridas
Si estás desarrollando una aplicación híbrida (algunas interfaces en React Native, otras en código nativo) aún puedes usar imágenes ya incluidas en la aplicación.
Para imágenes incluidas mediante catálogos de assets de Xcode o en la carpeta drawable de Android, usa el nombre de la imagen sin extensión:
<Image
source={{uri: 'app_icon'}}
style={{width: 40, height: 40}}
/>
Para imágenes en la carpeta assets de Android, usa el esquema asset:/:
<Image
source={{uri: 'asset:/app_icon.png'}}
style={{width: 40, height: 40}}
/>
Estos enfoques no incluyen verificaciones de seguridad. Eres responsable de garantizar que esas imágenes estén disponibles en la aplicación. Además, debes especificar manualmente las dimensiones de las imágenes.
Imágenes de red
Muchas imágenes que mostrarás en tu aplicación no estarán disponibles en tiempo de compilación, o querrás cargar algunas dinámicamente para mantener reducido el tamaño del binario. A diferencia de los recursos estáticos, deberás especificar manualmente las dimensiones de tu imagen. Es muy recomendable usar https además para cumplir con los requisitos de App Transport Security en iOS.
// GOOD
<Image source={{uri: 'https://reactjs.org/logo-og.png'}}
style={{width: 400, height: 400}} />
// BAD
<Image source={{uri: 'https://reactjs.org/logo-og.png'}} />
Solicitudes de Red para Imágenes
Si deseas configurar elementos como el verbo HTTP, cabeceras o un cuerpo junto con la solicitud de imagen, puedes hacerlo definiendo estas propiedades en el objeto fuente:
<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
method: 'POST',
headers: {
Pragma: 'no-cache',
},
body: 'Your Body goes here',
}}
style={{width: 400, height: 400}}
/>
Imágenes con URI de Datos
A veces, podrías recibir datos de imagen codificados desde una llamada a API REST. Puedes usar el esquema URI 'data:' para utilizar estas imágenes. Al igual que con recursos de red, deberás especificar manualmente las dimensiones de tu imagen.
Esto se recomienda solo para imágenes muy pequeñas y dinámicas, como iconos en listas provenientes de una base de datos.
// include at least width and height!
<Image
style={{
width: 51,
height: 51,
resizeMode: 'contain',
}}
source={{
uri: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADMAAAAzCAYAAAA6oTAqAAAAEXRFWHRTb2Z0d2FyZQBwbmdjcnVzaEB1SfMAAABQSURBVGje7dSxCQBACARB+2/ab8BEeQNhFi6WSYzYLYudDQYGBgYGBgYGBgYGBgYGBgZmcvDqYGBgmhivGQYGBgYGBgYGBgYGBgYGBgbmQw+P/eMrC5UTVAAAAABJRU5ErkJggg==',
}}
/>
Control de Caché
En algunos casos, quizás solo quieras mostrar una imagen si ya está en la caché local, es decir, un marcador de posición de baja resolución hasta que esté disponible una resolución mayor. En otros casos, no te importará si la imagen está desactualizada y estarás dispuesto a mostrarla para ahorrar ancho de banda. La propiedad cache del origen te da control sobre cómo interactúa la capa de red con la caché.
-
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.
<Image
source={{
uri: 'https://reactjs.org/logo-og.png',
cache: 'only-if-cached',
}}
style={{width: 400, height: 400}}
/>
Imágenes del Sistema de Archivos Local
Consulta CameraRoll para ver un ejemplo de uso de recursos locales fuera de Images.xcassets.
Recursos Dibujables (Drawables)
Android admite cargar recursos dibujables mediante archivos xml. Esto significa que puedes usar vectores dibujables para iconos o formas dibujables para crear formas. Puedes importar y usar estos recursos igual que cualquier recurso estático o híbrido. Debes especificar manualmente las dimensiones.
Para recursos dibujables estáticos ubicados junto a tu código JS, usa la sintaxis require o import (ambas funcionan igual):
<Image
source={require('./img/my_icon.xml')}
style={{width: 40, height: 40}}
/>
Para recursos dibujables en la carpeta de Android (res/drawable), usa el nombre del recurso sin extensión:
<Image
source={{uri: 'my_icon'}}
style={{width: 40, height: 40}}
/>
La diferencia clave entre recursos dibujables y otros tipos de imágenes es que el recurso debe referenciarse durante la compilación de la aplicación Android, pues requiere ejecutar la Herramienta de Empaquetado de Activos Android (AAPT). El XML binario generado por AAPT no puede cargarse por red mediante Metro. Si cambias el directorio o nombre de un recurso, deberás recompilar la aplicación Android cada vez.
Creando Recursos Dibujables XML
Android ofrece documentación exhaustiva sobre cada tipo de recurso dibujable compatible en su guía de Recursos dibujables, junto con ejemplos de archivos XML sin procesar. Puedes utilizar herramientas de Android Studio como el Vector Asset Studio para crear recursos vectoriales a partir de archivos Scalable Vector Graphic (SVG) y Adobe Photoshop Document (PSD).
Debes intentar evitar referencias a otros recursos en el archivo XML que crees si deseas tratarlo como un recurso de imagen estática (es decir, con una declaración import o require). Si necesitas utilizar referencias a otros dibujables o atributos, como listas de estados de color o recursos de dimensión, debes incluir tu dibujable como un recurso híbrido e importarlo por nombre.
Mejor imagen del carrete de cámara
iOS guarda múltiples tamaños para la misma imagen en tu Carrete de Cámara. Es crucial seleccionar el más adecuado por razones de rendimiento. No querrías usar una imagen completa de 3264x2448 como fuente al mostrar una miniatura de 200x200. Si hay una coincidencia exacta, React Native la seleccionará; de lo contrario, usará la primera que sea al menos un 50% más grande para evitar desenfoque al redimensionar. Todo esto ocurre automáticamente, evitando que escribas código tedioso (y propenso a errores).
¿Por qué no dimensionar todo automáticamente?
En el navegador, si no das tamaño a una imagen, este renderizará un elemento 0x0, descargará la imagen y luego la mostrará con el tamaño correcto. El gran problema es que tu interfaz saltará por todas partes mientras las imágenes cargan, creando una mala experiencia de usuario. Esto se llama Cambio Acumulativo de Diseño (CLS).
En React Native, este comportamiento no se implementa intencionalmente. Requiere más trabajo conocer las dimensiones (o relación de aspecto) de la imagen remota de antemano, pero creemos que conduce a una mejor experiencia de usuario. Las imágenes estáticas cargadas desde el paquete de la aplicación mediante require('./my-icon.png') pueden dimensionarse automáticamente porque sus dimensiones están disponibles inmediatamente al montarse.
Por ejemplo, el resultado de require('./my-icon.png') podría ser:
{"__packager_asset":true,"uri":"my-icon.png","width":591,"height":573}
Fuente como un objeto
Fuente como objeto: el atributo src se llama source y no toma una cadena sino un objeto con un atributo uri
<Image source={{uri: 'something.jpg'}} />
En el lado de la infraestructura, la razón es que nos permite adjuntar metadatos a este objeto. Por ejemplo, si estás usando require('./my-icon.png'), entonces añadimos información sobre su ubicación real y tamaño (¡no dependas de esto, podría cambiar en el futuro!). Esto también es una preparación para el futuro, por ejemplo, podríamos querer admitir sprites en algún punto, en lugar de devolver {uri: ...}, podemos devolver {uri: ..., crop: {left: 10, top: 50, width: 20, height: 40}} y admitir transparentemente sprites en todos los sitios de llamada existentes.
En el lado del usuario, esto te permite anotar el objeto con atributos útiles como las dimensiones de la imagen para calcular el tamaño en el que se mostrará. Siéntete libre de usarlo como tu estructura de datos para almacenar más información sobre tu imagen.
Imagen de fondo mediante anidamiento
Una solicitud común de desarrolladores familiarizados con la web es background-image. Para estos casos, usa el componente <ImageBackground>, que tiene las mismas props que <Image>, y añade cualquier elemento hijo que quieras superponer sobre él.
En algunos casos, es posible que no desees usar <ImageBackground>, ya que su implementación es básica. Consulta la documentación de <ImageBackground> para más detalles, y crea tu propio componente personalizado cuando sea necesario.
return (
<ImageBackground source={...} style={{width: '100%', height: '100%'}}>
<Text>Inside</Text>
</ImageBackground>
);
Ten en cuenta que debes especificar algunos atributos de estilo para el ancho y alto.
Estilos de Radio de Borde en iOS
Por favor, ten en cuenta que las siguientes propiedades de estilo de radio de borde específicas para esquinas podrían ser ignoradas por el componente de imagen de iOS:
-
borderTopLeftRadius -
borderTopRightRadius -
borderBottomLeftRadius -
borderBottomRightRadius
Decodificación en Subprocesos
La decodificación de imágenes puede tomar más tiempo que un fotograma. Esta es una de las principales causas de caída de fotogramas en la web porque la decodificación se realiza en el hilo principal. En React Native, la decodificación de imágenes se realiza en un hilo diferente. En la práctica, ya necesitas manejar el caso cuando la imagen aún no se ha descargado, por lo que mostrar el marcador de posición durante algunos fotogramas más mientras se decodifica no requiere cambios en el código.
Configuración de Límites de Caché de Imágenes en iOS
En iOS, exponemos una API para anular los límites predeterminados de la caché de imágenes de React Native. Esto debe llamarse desde el código nativo de tu AppDelegate (por ejemplo, dentro de didFinishLaunchingWithOptions).
RCTSetImageCacheLimits(4*1024*1024, 200*1024*1024);
Parámetros:
| Name | Type | Required | Description |
|---|---|---|---|
| imageSizeLimit | number | Yes | Image cache size limit. |
| totalCostLimit | number | Yes | Total cache cost limit. |
En el ejemplo de código anterior, el límite de tamaño de imagen se establece en 4 MB y el límite de costo total en 200 MB.