Imagen

La interfaz de usuario de aplicación multiplataforma de .NET (.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 de gráficos vectoriales escalables (SVG) locales. Para obtener más información sobre cómo agregar imágenes a un proyecto de aplicación MAUI de .NET, consulte Agregar imágenes a un proyecto de aplicación maui de .NET.

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 está reproduciéndose o 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 tener estilos aplicados y servir como destino para enlaces de datos.

Nota

Un Image puede mostrar iconos de fuente especificando los datos del icono de fuente como un objeto FontImageSource. Para obtener más información, consulte Mostrar iconos de fuente.

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

• FromFile devuelve un 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 StreamImageSource que lee una imagen de un flujo 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 Image esté restringido por su diseño, o que se especifique la propiedad HeightRequest o WidthRequest del Image.

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

Carga de una imagen local

Las imágenes se pueden agregar a tu proyecto de aplicación arrastrándolas a la carpeta Resources\Images, donde se establecerá automáticamente su acción de compilación 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 imágenes 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 imagen local deben estar en minúsculas, iniciar y terminar con un carácter de letra y contener solo caracteres alfanuméricos o caracteres de subrayado. Para obtener más información, consulte Introducción a los recursos de la aplicación 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 MAUI de .NET, 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:

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 a 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:

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 de la 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 en caché de imágenes

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

La clase UriImageSource define las siguientes propiedades:

• Uri, de tipo Uri, representa el URI de la imagen que se va a descargar para su visualización.
• 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 está habilitado el almacenamiento en caché de imágenes. El valor predeterminado de esta propiedad es true.

Estas propiedades están respaldadas por objetos BindableProperty, lo que significa que se les puede dar estilo y ser el destino de los enlaces de datos.

Para establecer un período de caché específico, establezca la propiedad Source en un objeto UriImageSource que establece 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:

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 a partir de 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 de los que crear una clave de caché razonable.

Cargar un icono de fuente

La extensión de marcado FontImage 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 extensión de marcado FontImage es compatible con la clase FontImageExtension, 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 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 XAML permite que la clase FontImageExtension se abrevia 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 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 un Image:

Aunque el carácter unicode del icono es \uf30c, debe escaparse en XAML, por lo que se convierte en .

Para obtener información sobre cómo mostrar iconos de fuente especificando los datos del icono de fuente en un objeto de FontImageSource, vea Mostrar 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. Tenga 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: los cuadros de letras de la imagen (si es necesario) para que toda la imagen se ajuste al área de visualización, con espacio en blanco agregado a la parte superior/inferior o a los lados en función de si la imagen es ancha o alta.
• AspectFill: recorta la imagen para que rellene el área de visualización mientras conserva la relación de aspecto.
• Fill: amplía la imagen para rellenar completamente y exactamente el área de visualización. Esto puede dar lugar a que la imagen se distorsiona.
• Center: centra la imagen en el área de visualización a la vez que conserva la relación de aspecto.