Imagen

.NET Multi-platform App UI (.NET MAUI) Image muestra una imagen que se puede cargar desde un archivo local, un URI o una secuencia. También se admiten los formatos de imagen de plataforma estándar, incluidos los GIF animados y los archivos Scalable Vector Graphics (SVG) locales. Para obtener más información sobre cómo agregar imágenes a un proyecto de aplicación .NET MAUI, consulta Adición de imágenes a un proyecto de aplicación .NET MAUI.

Image define las siguientes propiedades:

• Aspect, de tipo Aspect, define el modo de escalado de la imagen.
• IsAnimationPlaying, de tipo bool, determina si un GIF animado se está reproduciendo o está detenido. El valor predeterminado de esta propiedad es false.
• IsLoading, de tipo bool, indica el estado de carga de la imagen. El valor predeterminado de esta propiedad es false.
• IsOpaque, de tipo bool, indica si el motor de representación puede tratar la imagen como opaca mientras la representa. El valor predeterminado de esta propiedad es false.
• Source, de tipo ImageSource, especifica el origen de la imagen.

Estas propiedades están respaldadas por objetos BindableProperty, lo que significa que pueden ser destinos de los enlaces de datos, y con estilo.

Nota:

Los iconos de fuente se pueden mostrar mediante una especificación Image de los datos del icono de fuente como un objeto FontImageSource. Para obtener más información, consulta Visualización de iconos de fuente.

La clase ImageSource define los métodos siguientes que se pueden usar para cargar una imagen desde orígenes diferentes:

• FromFile devuelve un objeto FileImageSource que lee una imagen de un archivo local.
• FromUri devuelve un UriImageSource que descarga y lee una imagen de un URI especificado.
• FromStream devuelve un objeto StreamImageSource que lee una imagen de una secuencia que proporciona datos de imagen.

En XAML, las imágenes se pueden cargar desde archivos y URI especificando el nombre de archivo o el URI como un valor de cadena para la propiedad Source. Las imágenes también se pueden cargar desde secuencias en XAML a través de extensiones de marcado personalizadas.

Importante

Las imágenes se mostrarán en su resolución completa a menos que el tamaño del objeto Image esté restringido por su diseño, o bien se especifique la propiedad HeightRequest o WidthRequest de Image.

Para obtener información sobre cómo agregar iconos de aplicaciones y una pantalla de presentación a la aplicación, consulta Iconos de aplicaciones y Pantalla de presentación.

Carga de una imagen local

Puedes agregar imágenes al proyecto de aplicación arrastrándolas a la carpeta Resources\Images del proyecto, donde su acción de compilación se establecerá automáticamente en MauiImage. En tiempo de compilación, las imágenes vectoriales se cambian de tamaño a las resoluciones correctas para la plataforma y el dispositivo de destino y se agregan al paquete de la aplicación. Esto es necesario porque las distintas plataformas admiten resoluciones de imagen diferentes y el sistema operativo elige la resolución de imagen adecuada en tiempo de ejecución en función de las funcionalidades del dispositivo.

Para cumplir con las reglas de nomenclatura de recursos de Android, todos los nombres de archivo de imágenes locales deben estar en minúsculas, empezar y terminar con un carácter de letra y contener solo caracteres alfanuméricos y de subrayado. Para obtener más información, consulta Información acerca de los recursos de la app en developer.android.com.

Importante

.NET MAUI convierte archivos SVG en archivos PNG. Por lo tanto, al agregar un archivo SVG al proyecto de aplicación .NET MAUI, se debe hacer referencia desde XAML o C# con una extensión .png.

La adhesión a estas reglas para la nomenclatura y colocación de archivos permite que el código XAML siguiente cargue y muestre una imagen:

<Image Source="dotnet_bot.png" />

El código de C# equivalente es el siguiente:

Image image = new Image
{
    Source = ImageSource.FromFile("dotnet_bot.png")
};

El método ImageSource.FromFile requiere un argumento string y devuelve un nuevo objeto FileImageSource que lee la imagen del archivo. También hay un operador de conversión implícito que permite especificar el nombre de archivo como argumento string para la propiedad Image.Source:

Image image = new Image { Source = "dotnet_bot.png" };

Carga de una imagen remota

Las imágenes remotas se pueden descargar y mostrar especificando un URI como valor de la propiedad Source:

<Image Source="https://aka.ms/campus.jpg" />

El código de C# equivalente es el siguiente:

Image image = new Image
{
    Source = ImageSource.FromUri(new Uri("https://aka.ms/campus.jpg"))
};

El método ImageSource.FromUri requiere un argumento Uri y devuelve un nuevo objeto UriImageSource que lee la imagen del Uri. También hay una conversión implícita para los URI basados en cadenas:

Image image = new Image { Source = "https://aka.ms/campus.jpg" };

Almacenamiento de imágenes en caché

El almacenamiento de imágenes descargadas en caché está habilitado de forma predeterminada, con imágenes almacenadas en caché durante 1 día. Este comportamiento se puede cambiar modificando las propiedades de la clase UriImageSource.

La clase UriImageSource define las propiedades siguientes:

• Uri, de tipo Uri, representa el URI de la imagen que se va a descargar para mostrar.
• CacheValidity, de tipo TimeSpan, especifica cuánto tiempo se almacenará la imagen localmente. El valor predeterminado de esta propiedad es 1 día.
• CachingEnabled, de tipo bool, define si el almacenamiento en caché de imágenes está habilitado. El valor predeterminado de esta propiedad es true.

Estas propiedades están respaldadas por objetos BindableProperty, lo que significa que pueden ser destinos de los enlaces de datos, y con estilo.

Para establecer un período de caché específico, establece la propiedad Source en un objeto UriImageSource que establezca su propiedad CacheValidity:

<Image>
    <Image.Source>
        <UriImageSource Uri="https://aka.ms/campus.jpg"
                        CacheValidity="10:00:00:00" />
    </Image.Source>
</Image>

El código de C# equivalente es el siguiente:

Image image = new Image();
image.Source = new UriImageSource
{
    Uri = new Uri("https://aka.ms/campus.jpg"),
    CacheValidity = new TimeSpan(10,0,0,0)
};

En este ejemplo, el período de almacenamiento en caché se establece en 10 días.

Carga de una imagen desde una secuencia

Las imágenes se pueden cargar desde secuencias con el método ImageSource.FromStream:

Image image = new Image
{
    Source = ImageSource.FromStream(() => stream)
};

Importante

El almacenamiento en caché de imágenes está deshabilitado en Android al cargar una imagen desde una secuencia con el método ImageSource.FromStream. Esto se debe a la falta de datos a partir de los cuales se debe crear una clave de caché razonable.

Cargar un icono de fuente

La extensión de marcado FontImage te permite mostrar un icono de fuente en cualquier vista que pueda mostrar un ImageSource. Proporciona la misma funcionalidad que la clase FontImageSource, pero con una representación más concisa.

La clase FontImageExtension admite la extensión de marcado FontImage, que define las siguientes propiedades:

• FontFamily de tipo string, la familia de fuentes a la que pertenece el icono de fuente.
• Glyph de tipo string, el valor de carácter unicode del icono de fuente.
• Color de tipo Color, el color que se va a usar al mostrar el icono de fuente.
• Size de tipo double, el tamaño, en unidades independientes del dispositivo, del icono de fuente representado. El valor predeterminado es 30. Además, esta propiedad se puede establecer en un tamaño de fuente con nombre.

Nota:

El analizador de XAML permite abreviar la clase FontImageExtension como FontImage.

La propiedad Glyph es la propiedad de contenido de FontImageExtension. Por lo tanto, para las expresiones de marcado XAML expresadas con llaves, puedes eliminar la parte Glyph= de la expresión siempre que sea el primer argumento.

En el ejemplo de XAML siguiente, se muestra cómo usar la extensión de marcado FontImage:

<Image BackgroundColor="#D1D1D1"
       Source="{FontImage &#xf30c;, FontFamily=Ionicons, Size=44}" />

En este ejemplo, la versión abreviada del nombre de clase FontImageExtension se usa para mostrar un icono XBox, de la familia de fuentes Ionicons, en una clase Image:

Aunque el carácter unicode del icono es \uf30c, debe tener caracteres de escape en XAML y, por tanto, se convierte en .

Para obtener información sobre cómo mostrar iconos de fuente especificando los datos del icono de fuente en un objeto FontImageSource, consulta Visualización de iconos de fuente.

Carga de GIF animados

.NET MAUI incluye compatibilidad para mostrar GIF pequeños y animados. Esto se logra estableciendo la propiedad Source en un archivo GIF animado:

<Image Source="demo.gif" />

Importante

Aunque la compatibilidad con GIF animado en .NET MAUI incluye la capacidad de descargar archivos, no admite el almacenamiento en caché ni el streaming de GIF animados.

De forma predeterminada, cuando se carga un GIF animado, no se reproducirá. Esto se debe a que la propiedad IsAnimationPlaying, que controla si un GIF animado se está reproduciendo o detenido, tiene un valor predeterminado de false. Por lo tanto, cuando se carga un GIF animado, no se reproducirá hasta que la propiedad IsAnimationPlaying esté establecida en true. La reproducción se puede detener restableciendo la propiedad IsAnimationPlaying en false. Ten en cuenta que esta propiedad no tiene ningún efecto al mostrar un origen de imagen no GIF.

Control del escalado de imágenes

La propiedad Aspect determina cómo se escalará la imagen para ajustarse al área de visualización y debe establecerse en uno de los miembros de la enumeración Aspect:

• AspectFit: aplica el formato letterbox a la imagen (si es necesario) para que la imagen quepa en el área de visualización, con un espacio en blanco agregado a la parte superior o inferior o a los laterales, en función de si la imagen es ancha o alta.
• AspectFill: recorta la imagen para que rellene el área de visualización y conserve la relación de aspecto.
• Fill: ajusta la imagen para rellenar completa y exactamente el área de visualización. Esto puede distorsionar la imagen.
• Center: centra la imagen en el área de visualización y conserva la relación de aspecto.