Agregar assets e imágenes

Las apps de Flutter pueden incluir tanto código como assets (a veces llamados recursos). Un asset es un archivo que se empaqueta y despliega con tu app, y es accesible en tiempo de ejecución. Los tipos comunes de assets incluyen datos estáticos (por ejemplo, archivos JSON), archivos de configuración, iconos e imágenes (JPEG, WebP, GIF, WebP/GIF animados, PNG, BMP y WBMP).

Flutter usa el archivo pubspec.yaml, ubicado en la raíz de tu proyecto, para identificar los assets requeridos por una app.

Aquí hay un ejemplo:

flutter:
  assets:
    - assets/my_icon.png
    - assets/background.png

Para incluir todos los assets dentro de un directorio, especifica el nombre del directorio con el carácter / al final:

flutter:
  assets:
    - directory/
    - directory/subdirectory/

La subsección assets de la sección flutter especifica archivos que deben ser incluidos con la app. Cada asset se identifica por una ruta explícita (relativa al archivo pubspec.yaml) donde se encuentra el archivo de asset. El orden en el que se declaran los assets no importa. El nombre real del directorio utilizado (assets en el primer ejemplo o directory en el ejemplo anterior) no importa.

Durante una compilación (build), Flutter coloca los assets en un archivo especial llamado asset bundle del cual las apps leen en tiempo de ejecución.

Flutter admite el uso de un paquete de Dart para transformar archivos de assets al compilar tu app. Para hacer esto, especifica los archivos de assets y el paquete transformador en tu archivo pubspec. Para aprender cómo hacer esto y escribir tus propios paquetes de transformación de assets, consulta Transformar assets al momento de la compilación.

Tu app puede acceder a sus assets a través de un objeto AssetBundle.

Los dos métodos principales en un asset bundle te permiten cargar un asset de cadena/texto (loadString()) o un asset de imagen/binario (load()) del bundle, dada una clave lógica. La clave lógica se mapea a la ruta al asset especificada en el archivo pubspec.yaml al momento de la compilación.

Cada app de Flutter tiene un objeto rootBundle para acceder fácilmente al asset bundle principal. Es posible cargar assets directamente usando el estático global rootBundle de package:flutter/services.dart.

Sin embargo, se recomienda obtener el AssetBundle para el BuildContext actual usando DefaultAssetBundle, en lugar del asset bundle predeterminado que se construyó con la app; este enfoque permite que un widget padre sustituya un AssetBundle diferente en tiempo de ejecución, lo cual puede ser útil para escenarios de localización o pruebas.

Típicamente, usarás DefaultAssetBundle.of() para cargar indirectamente un asset, por ejemplo un archivo JSON, desde el rootBundle en tiempo de ejecución de la app.

Fuera del contexto de un Widget, o cuando no se dispone de una referencia a un AssetBundle, puedes usar rootBundle para cargar directamente dichos assets. Por ejemplo:

import 'package:flutter/services.dart' show rootBundle;
​
Future<String> loadAsset() async {
  return await rootBundle.loadString('assets/config.json');
}

Para cargar una imagen, usa la clase AssetImage en el método build() de un widget.

Por ejemplo, tu app puede cargar la imagen de fondo desde las declaraciones de assets del ejemplo anterior:

return const Image(image: AssetImage('assets/background.png'));

Flutter puede cargar imágenes apropiadas para la resolución según el device pixel ratio actual.

AssetImage mapeará un asset solicitado lógico a uno que coincida más cercanamente con el device pixel ratio actual.

Para que este mapeo funcione, los assets deben organizarse de acuerdo con una estructura de directorios particular:

.../image.png
.../Mx/image.png
.../Nx/image.png
...etc.

Donde M y N son identificadores numéricos que corresponden a la resolución nominal de las imágenes contenidas en su interior. En otras palabras, especifican el device pixel ratio para el cual están destinadas las imágenes.

En este ejemplo, image.png se considera el asset principal, mientras que Mx/image.png y Nx/image.png se consideran variantes.

Se asume que el asset principal corresponde a una resolución de 1.0. Por ejemplo, considera la siguiente disposición de assets para una imagen llamada my_icon.png:

.../my_icon.png       (mdpi baseline)
.../1.5x/my_icon.png  (hdpi)
.../2.0x/my_icon.png  (xhdpi)
.../3.0x/my_icon.png  (xxhdpi)
.../4.0x/my_icon.png  (xxxhdpi)

En dispositivos con un device pixel ratio de 1.8, se elige el asset .../2.0x/my_icon.png. Para un device pixel ratio de 2.7, se elige el asset .../3.0x/my_icon.png.

Si el ancho y el alto de la imagen renderizada no están especificados en el widget Image, se utiliza la resolución nominal para escalar el asset de modo que ocupe la misma cantidad de espacio en pantalla que habría ocupado el asset principal, solo que con una resolución más alta. Es decir, si .../my_icon.png es de 72px por 72px, entonces .../3.0x/my_icon.png debería ser de 216px por 216px; pero ambos se renderizan en 72px por 72px (en píxeles lógicos), si no se especifican el ancho y el alto.

Solo necesitas especificar el asset principal o su directorio padre en la sección assets de pubspec.yaml. Flutter empaqueta las variantes por ti. Cada entrada debe corresponder a un archivo real, a excepción de la entrada del asset principal. Si la entrada del asset principal no corresponde a un archivo real, entonces el asset con la resolución más baja se utiliza como alternativa (fallback) para dispositivos con device pixel ratios por debajo de esa resolución. Sin embargo, la entrada aún debe incluirse en el manifiesto pubspec.yaml.

Cualquier cosa que use el asset bundle predeterminado hereda la consciencia de resolución al cargar imágenes. (Si trabajas con algunas de las clases de nivel inferior, como ImageStream o ImageCache, también notarás parámetros relacionados con la escala).

Para cargar una imagen desde una dependencia de paquete, se debe proporcionar el argumento package a AssetImage.

Por ejemplo, supón que tu aplicación depende de un paquete llamado my_icons, que tiene la siguiente estructura de directorios:

.../pubspec.yaml
.../icons/heart.png
.../icons/1.5x/heart.png
.../icons/2.0x/heart.png
...etc.

Para cargar la imagen, usa:

return const AssetImage('icons/heart.png', package: 'my_icons');

Los assets utilizados por el propio paquete también se deben obtener usando el argumento package como se indicó anteriormente.

Si el asset deseado está especificado en el archivo pubspec.yaml del paquete, se empaqueta automáticamente con la aplicación. En particular, los assets utilizados por el propio paquete deben especificarse en su pubspec.yaml.

Un paquete también puede optar por tener assets en su carpeta lib/ que no estén especificados en su archivo pubspec.yaml. En este caso, para que esas imágenes se empaqueten, la aplicación debe especificar cuáles incluir en su pubspec.yaml. Por ejemplo, un paquete llamado fancy_backgrounds podría tener los siguientes archivos:

.../lib/backgrounds/background1.png
.../lib/backgrounds/background2.png
.../lib/backgrounds/background3.png

Para incluir, por ejemplo, la primera imagen, el pubspec.yaml de la aplicación debe especificarla en la sección assets:

flutter:
  assets:
    - packages/fancy_backgrounds/backgrounds/background1.png

El lib/ está implícito, por lo que no se debe incluir en la ruta del asset.

Si estás desarrollando un paquete, para cargar un asset dentro del paquete, especifícalo en el pubspec.yaml del paquete:

flutter:
  assets:
    - assets/images/

Para cargar la imagen dentro de tu paquete, usa:

return const AssetImage('packages/fancy_backgrounds/backgrounds/background1.png');

Los assets de Flutter están fácilmente disponibles para el código de la plataforma usando el AssetManager en Android y NSBundle en iOS.

En Android los assets están disponibles a través de la API AssetManager. La clave de búsqueda utilizada en, por ejemplo openFd, se obtiene de lookupKeyForAsset en PluginRegistry.Registrar o getLookupKeyForAsset en FlutterView. PluginRegistry.Registrar está disponible cuando desarrollas un plugin, mientras que FlutterView sería la opción cuando desarrollas una app que incluye una vista de plataforma.

Como ejemplo, supón que has especificado lo siguiente en tu pubspec.yaml

flutter:
  assets:
    - icons/heart.png

Esto refleja la siguiente estructura en tu app de Flutter.

.../pubspec.yaml
.../icons/heart.png
...etc.

Para acceder a icons/heart.png desde tu código plugin de Java, haz lo siguiente:

AssetManager assetManager = registrar.context().getAssets();
String key = registrar.lookupKeyForAsset("icons/heart.png");
AssetFileDescriptor fd = assetManager.openFd(key);

En iOS los assets están disponibles a través del mainBundle. La clave de búsqueda utilizada en, por ejemplo pathForResource:ofType:, se obtiene de lookupKeyForAsset o lookupKeyForAsset:fromPackage: en FlutterPluginRegistrar, o lookupKeyForAsset: o lookupKeyForAsset:fromPackage: en FlutterViewController. FlutterPluginRegistrar está disponible cuando desarrollas un plugin, mientras que FlutterViewController sería la opción al desarrollar una app que incluye una vista de plataforma.

Como ejemplo, supón que tienes la configuración de Flutter de arriba.

Para acceder a icons/heart.png desde tu código plugin de Objective-C, harías lo siguiente:

NSString* key = [registrar lookupKeyForAsset:@"icons/heart.png"];
NSString* path = [[NSBundle mainBundle] pathForResource:key ofType:nil];

Para acceder a icons/heart.png desde tu app de Swift, harías lo siguiente:

let key = controller.lookupKey(forAsset: "icons/heart.png")
let mainBundle = Bundle.main
let path = mainBundle.path(forResource: key, ofType: nil)

Para un ejemplo más completo, consulta la implementación del plugin video_player de Flutter en pub.dev.

Al implementar Flutter agregándolo a una app de iOS existente, es posible que tengas imágenes alojadas en iOS que quieras usar en Flutter. Para lograr eso, usa platform channels para pasar los datos de la imagen a Dart como FlutterStandardTypedData.

Hay otras ocasiones para trabajar con assets en los proyectos de la plataforma directamente. A continuación hay dos casos comunes donde se usan assets antes de que el framework de Flutter esté cargado y ejecutándose.

Actualizar el icono de inicio de una aplicación Flutter funciona de la misma manera que actualizar los iconos de inicio en aplicaciones nativas de Android o iOS.

En el directorio raíz de tu proyecto de Flutter, navega a .../android/app/src/main/res. Las diversas carpetas de recursos bitmap tales como mipmap-hdpi ya contienen imágenes de marcador de posición llamadas ic_launcher.png. Reemplázalas con tus assets deseados respetando el tamaño de icono recomendado por densidad de pantalla como indica la Guía de Desarrolladores de Android.

En el directorio raíz de tu proyecto de Flutter, navega a .../ios/Runner. El directorio Assets.xcassets/AppIcon.appiconset ya contiene imágenes de marcador de posición. Reemplázalas con las imágenes de tamaño adecuado como se indica por su nombre de archivo dictado por las Human Interface Guidelines de Apple. Conserva los nombres de archivo originales.

Flutter también utiliza mecanismos nativos de la plataforma para dibujar pantallas de inicio (launch screens) de transición en tu app de Flutter mientras se carga el framework de Flutter. Esta pantalla de inicio persiste hasta que Flutter renderiza el primer fotograma de tu aplicación.

Para agregar una pantalla de inicio (también conocida como "splash screen") a tu aplicación de Flutter, navega a .../android/app/src/main. En res/drawable/launch_background.xml, usa este XML de layer list drawable para personalizar el aspecto de tu pantalla de inicio. La plantilla existente proporciona un ejemplo de cómo agregar una imagen en el medio de una pantalla splash blanca en código comentado. Puedes desmarcarlo o usar otros drawables para lograr el efecto deseado.

Para más detalles, consulta Agregar una pantalla splash a tu app de Android.

Para agregar una imagen al centro de tu "pantalla splash", navega a .../ios/Runner. En Assets.xcassets/LaunchImage.imageset, arrastra imágenes llamadas LaunchImage.png, LaunchImage@2x.png, LaunchImage@3x.png. Si usas nombres de archivo diferentes, actualiza el archivo Contents.json en el mismo directorio.

También puedes personalizar completamente el storyboard de tu pantalla de inicio en Xcode abriendo .../ios/Runner.xcworkspace. Navega a Runner/Runner en el Project Navigator y arrastra imágenes abriendo Assets.xcassets o realiza cualquier personalización usando el Interface Builder en LaunchScreen.storyboard.

Para más detalles, consulta Agregar una pantalla splash a tu app de iOS.