Imágenes en Xamarin.Forms

Descarga del ejemplo

Las imágenes se pueden compartir entre plataformas con , se pueden cargar específicamente para cada plataforma o se pueden descargar para mostrarse.

Las imágenes son una parte fundamental de la navegación de la aplicación, la facilidad de uso y la personalidad de marca. Xamarin.Forms Las aplicaciones deben poder compartir imágenes en todas las plataformas, pero también pueden mostrar imágenes diferentes en cada plataforma.

También se requieren imágenes específicas de la plataforma para iconos y pantallas de presentación. deben configurarse por plataforma.

Mostrar imágenes

Xamarin.Forms usa la Image vista para mostrar imágenes en una página. Tiene varias propiedades importantes:

• Xamarin_Forms _Image_Source" data-linktype="absolute-path">: una SourceImageSource instancia, archivo, uri o recurso, que establece la imagen que se va a mostrar.
• Xamarin_Forms _Image_Aspect" data-linktype="absolute-path">- How to Aspect size the image within the bounds it is being displayed within (whether to stretch, crop or letterbox).

ImageSource Las instancias se pueden obtener mediante métodos estáticos para cada tipo de origen de imagen:

• Xamarin_Forms _ImageSource_FromFile_System_String_" data-linktype="absolute-path">: requiere un nombre de archivo o una ruta de acceso de archivo que se pueda resolver en FromFile cada plataforma.
• Xamarin_Forms _ImageSource_FromUri_System_Uri_" data-linktype="absolute-path">- Requiere un FromUri objeto URI, por ejemplo. new Uri("http://server.com/image.jpg") .
• FromResource - Requiere un identificador de recurso para un archivo de imagen insertado en la aplicación o .NET Standard proyecto de biblioteca, con una acción FromResource.
• Xamarin_Forms _ImageSource_FromStream_System_Func_System_IO_Stream__" data-linktype="absolute-path">: requiere un FromStream flujo que proporciona datos de imagen.

La Xamarin_Forms _Image_Aspect" data-linktype="absolute-path">determina cómo se escalará la imagen para ajustarse al Aspect área de presentación:

• Xamarin_Forms _Aspect_Fill" data-linktype="absolute-path">: extiende la imagen para rellenar completamente y exactamente el Fill área de presentación. Esto puede dar lugar a que la imagen se desvirtue.
• Xamarin_Forms _Aspect_AspectFill" data-linktype="absolute-path">: recorta la imagen para que rellene el área de visualización conservando el aspecto (es decir, AspectFill sin distorsión).
• Xamarin_Forms _Aspect_AspectFit" data-linktype="absolute-path">: la imagen se representa en forma de letras (si es necesario) para que toda la imagen se ajuste al área de presentación, con espacio en blanco agregado a la parte superior o inferior o a los lados, en función de si la imagen es ancha o AspectFit alta.

Las imágenes se pueden cargar desde un archivo local,un recurso incrustado,descargadoo cargado desde una secuencia. Además, la vista puede mostrar iconos de fuente especificando los datos del icono de Image fuente en un objeto FontImageSource . Para obtener más información, vea Mostrar iconos de fuente en la guía Fuentes.

Imágenes locales

Los archivos de imagen se pueden agregar a cada proyecto de aplicación y hacer referencia a ellos desde Xamarin.Forms código compartido. Este método de distribución de imágenes es necesario cuando las imágenes son específicas de la plataforma, por ejemplo, al usar resoluciones diferentes en plataformas diversas, o bien al emplear diseños que difieren ligeramente.

Para usar una sola imagen en todas las aplicaciones,se debe usar el mismo nombre de archivo en todas las plataformas y debe ser un nombre de recurso de Android válido (es decir, solo se permiten letras minúsculas, números, el carácter de subrayado y el punto).

• iOS: la manera preferida de administrar y admitir imágenes desde iOS 9 es usar conjuntos de imágenes del catálogo de recursos ,que deben contener todas las versiones de una imagen necesarias para admitir varios dispositivos y factores de escala para una aplicación. Para obtener más información, vea Adding Images to an Asset Catalog Image Set.
• Android: coloque imágenes en el directorio Recursos/drawable con Acción de compilación: AndroidResource. También se pueden proporcionar versiones de valores altos y bajos de PPP de una imagen (en subdirectorios resources con el nombre adecuado, como drawable-ldpi,drawable-hdpiy drawable-xhdpi).
• Plataforma Windows universal (UWP): de forma predeterminada, las imágenes deben colocarse en el directorio raíz de la aplicación con Acción de compilación: Contenido. Como alternativa, las imágenes se pueden colocar en un directorio diferente que, a continuación, se especifica con una plataforma específica. Para obtener más información, vea Directorio de imagen predeterminado en Windows.

La adhesión a estas reglas de nomenclatura y selección de ubicación de archivos permite que el código XAML siguiente cargue y muestre la imagen en todas las plataformas:

<Image Source="waterfront.jpg" />

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

var image = new Image { Source = "waterfront.jpg" };

En las capturas de pantalla siguientes se muestra el resultado de mostrar una imagen local en cada plataforma:

Para mayor flexibilidad, la propiedad se puede usar para seleccionar un archivo de imagen o una ruta de acceso diferentes para algunas o todas las plataformas, como se muestra Device.RuntimePlatform en este ejemplo de código:

image.Source = Device.RuntimePlatform == Device.Android
                ? ImageSource.FromFile("waterfront.jpg")
                : ImageSource.FromFile("Images/waterfront.jpg");

Resoluciones nativas (retina y valores altos de PPP)

iOS, Android y UWP incluyen compatibilidad con diferentes resoluciones de imágenes, donde el sistema operativo elige la imagen adecuada en tiempo de ejecución en función de las funcionalidades del dispositivo. Xamarin.Forms usa las API de las plataformas nativas para cargar imágenes locales, por lo que admite automáticamente resoluciones alternativas si los archivos se denominan correctamente y se encuentran en el proyecto.

La manera preferida de administrar imágenes desde iOS 9 es arrastrar imágenes para cada resolución necesaria al conjunto de imágenes del catálogo de recursos adecuado. Para obtener más información, vea Adding Images to an Asset Catalog Image Set.

Antes de iOS 9, las versiones de retina de la imagen se podían colocar en la carpeta Recursos: dos y tres veces la resolución con un sufijo @2x o @3x en el nombre de archivo antes de la extensión de archivo (por ejemplo, myimage@2x.png). Sin embargo, Apple ha dejado de trabajar con imágenes en una aplicación de iOS. Para obtener más información, vea Tamaños de imagen y Nombres de archivo.

Las imágenes de resolución alternativa de Android deben colocarse en directorios con nombre especial en el proyecto de Android, como se muestra en la captura de pantalla siguiente:

Los nombres de archivo de imagen de UWP pueden tener el sufijo antes de la extensión de archivo , donde es el porcentaje de escalado aplicado al recurso, por xxx ejemplo, xxx. A continuación, se puede hacer referencia a las imágenes en código o XAML sin el modificador de escala, por ejemplo, simplementemyimage.png. La plataforma seleccionará la escala de recursos adecuada más cercana en función del PPP actual de la pantalla.

Controles adicionales que muestran imágenes

Algunos controles tienen propiedades que muestran una imagen, como:

• Buttontiene una propiedad Xamarin_Forms Button _Button_ImageSource" data-linktype="absolute-path">que se puede establecer en una imagen de mapa de bits que se va ImageSource a mostrar en Button . Para obtener más información, vea Uso de mapas de bits con botones.

• ImageButtontiene una Xamarin_Forms ImageButton _ImageButton_Source" data-linktype="absolute-path">Source propiedad que se puede establecer en la imagen que se va a mostrar en ImageButton . Para obtener más información, vea Establecer el origen de la imagen.

• ToolbarItemtiene una propiedad Xamarin_Forms ToolbarItem _MenuItem_IconImageSource" data-linktype="absolute-path">que se puede establecer en una imagen que se carga desde un archivo, recurso incrustado, URI o IconImageSource secuencia.

• ImageCelltiene una propiedad Xamarin_Forms ImageCell _ImageCell_ImageSource" data-linktype="absolute-path">que se puede establecer en una imagen recuperada de un archivo, recurso incrustado, URI o ImageSource secuencia.

• Page. Cualquier tipo de página que derive de tiene Page Xamarin_Forms Page _Page_IconImageSource" data-linktype="absolute-path">IconImageSource and Xamarin_Forms _Page_BackgroundImageSource" data-linktype="absolute-path">properties, which can be assigned BackgroundImageSource a file, embedded resource, URI, or stream. En determinadas circunstancias, como cuando un objeto muestra un , el icono se mostrará si la plataforma NavigationPageContentPage lo admite.

  Importante

  En iOS, la propiedad Xamarin_Forms _Page_IconImageSource" data-linktype="absolute-path">no se puede rellenar a partir de una imagen en un conjunto de imágenes del catálogo de Page.IconImageSource recursos. En su lugar, cargue imágenes de icono Page.IconImageSource para la propiedad desde un archivo, recurso incrustado, URI o secuencia.

Imágenes incrustadas

Las imágenes insertadas también se incluyen con una aplicación (como las imágenes locales), pero en lugar de tener una copia de la imagen en la estructura de archivos de cada aplicación, el archivo de imagen se inserta en el ensamblado como un recurso. Este método de distribución de imágenes se recomienda cuando se usan imágenes idénticas en cada plataforma y es especialmente adecuado para crear componentes, ya que la imagen se incluye con el código.

Para insertar una imagen en un proyecto, haga clic con el botón derecho para agregar nuevos elementos y seleccione las imágenes que desea agregar. De forma predeterminada, la imagen tendrá acción de compilación: None; debe establecerse en Acción de compilación: EmbeddedResource.

Si coloca imágenes incrustadas en carpetas dentro del proyecto, los nombres de carpeta también se separan por puntos (.). en el identificador de recurso. Mover la beach.jpg a una carpeta denominada MyImages daría como resultado un identificador de recurso deWorkingWithImages.MyImages.beach.jpg

El código para cargar una imagen insertada simplemente pasa el identificador de recurso al método , como se muestra a continuación:

Image embeddedImage = new Image
{
    Source = ImageSource.FromResource("WorkingWithImages.beach.jpg", typeof(MyClass).GetTypeInfo().Assembly)
};

Actualmente no hay ninguna conversión implícita para los identificadores de recursos. En su lugar, debe usar ImageSource.FromResource o para cargar imágenes new ResourceImageSource() incrustadas.

En las capturas de pantalla siguientes se muestra el resultado de mostrar una imagen incrustada en cada plataforma:

XAML

Dado que no hay ningún convertidor de tipos integrado de a , XAML no puede cargar estos tipos de stringResourceImageSource imágenes de forma nativa. En su lugar, se puede escribir una extensión de marcado XAML personalizada simple para cargar imágenes mediante un identificador de recurso especificado en XAML:

[ContentProperty (nameof(Source))]
public class ImageResourceExtension : IMarkupExtension
{
 public string Source { get; set; }

 public object ProvideValue (IServiceProvider serviceProvider)
 {
   if (Source == null)
   {
     return null;
   }

   // Do your translation lookup here, using whatever method you require
   var imageSource = ImageSource.FromResource(Source, typeof(ImageResourceExtension).GetTypeInfo().Assembly);

   return imageSource;
 }
}

Para usar esta extensión, agregue un personalizado al XAML, con el espacio de nombres y los valores xmlns de ensamblado correctos para el proyecto. A continuación, el origen de la imagen se puede establecer mediante esta sintaxis: {local:ImageResource WorkingWithImages.beach.jpg} . A continuación se muestra un ejemplo xaml completo:

<?xml version="1.0" encoding="UTF-8" ?>
<ContentPage
   xmlns="http://xamarin.com/schemas/2014/forms"
   xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
   xmlns:local="clr-namespace:WorkingWithImages;assembly=WorkingWithImages"
   x:Class="WorkingWithImages.EmbeddedImagesXaml">
 <StackLayout VerticalOptions="Center" HorizontalOptions="Center">
   <!-- use a custom Markup Extension -->
   <Image Source="{local:ImageResource WorkingWithImages.beach.jpg}" />
 </StackLayout>
</ContentPage>

Solución de problemas de imágenes insertadas

Depurar código

Dado que a veces es difícil entender por qué no se carga un recurso de imagen determinado, se puede agregar temporalmente el siguiente código de depuración a una aplicación para ayudar a confirmar que los recursos están configurados correctamente. Se mostrarán todos los recursos conocidos insertados en el ensamblado dado a la consola para ayudar a depurar los problemas de carga de recursos.

using System.Reflection;
// ...
// NOTE: use for debugging, not in released app code!
var assembly = typeof(MyClass).GetTypeInfo().Assembly;
foreach (var res in assembly.GetManifestResourceNames())
{
    System.Diagnostics.Debug.WriteLine("found resource: " + res);
}

Imágenes insertadas en otros proyectos

De forma predeterminada, ImageSource.FromResource el método solo busca imágenes en el mismo ensamblado que el código que llama al método ImageSource.FromResource . Con el código de depuración anterior puede determinar qué ensamblados contienen un recurso específico cambiando la instrucción a un que se sabe typeof() que está en cada Type ensamblado.

Sin embargo, el ensamblado de origen en el que se busca una imagen incrustada se puede especificar como argumento para el ImageSource.FromResource método :

var imageSource = ImageSource.FromResource("filename.png",
            typeof(MyClass).GetTypeInfo().Assembly);

Descarga de imágenes

Las imágenes se pueden descargar automáticamente para mostrarse, como se muestra en el código XAML siguiente:

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
       xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
       x:Class="WorkingWithImages.DownloadImagesXaml">
  <StackLayout VerticalOptions="Center" HorizontalOptions="Center">
    <Label Text="Image UriSource Xaml" />
    <Image Source="https://aka.ms/campus.jpg" />
    <Label Text="campus.jpg gets downloaded from microsoft.com" />
  </StackLayout>
</ContentPage>

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

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

El Xamarin_Forms _ImageSource_FromUri_System_Uri_" data-linktype="absolute-path">ImageSource.FromUri requiere UriUriImageSource un objeto y devuelve un nuevo que lee de Uri .

También hay una conversión implícita para las cadenas URI, por lo que el ejemplo siguiente también funcionará:

webImage.Source = "https://aka.ms/campus.jpg";

En las capturas de pantalla siguientes se muestra el resultado de mostrar una imagen remota en cada plataforma:

Almacenamiento en caché de imágenes descargadas

También UriImageSource admite el almacenamiento en caché de imágenes descargadas, configuradas a través de las siguientes propiedades:

• Xamarin_Forms _UriImageSource_CachingEnabled" data-linktype="absolute-path">: si el almacenamiento en caché CachingEnabled está habilitado ( de true forma predeterminada).
• Xamarin_Forms _UriImageSource_CacheValidity" data-linktype="absolute-path">: que define cuánto tiempo se almacenará CacheValidity la imagen TimeSpan localmente.

El almacenamiento en caché está habilitado de forma predeterminada y almacenará la imagen localmente durante 24 horas. Para deshabilitar el almacenamiento en caché de una imagen determinada, cree una instancia del origen de la imagen como se muestra a continuación:

image.Source = new UriImageSource { CachingEnabled = false, Uri = new Uri("https://server.com/image") };

Para establecer un período de caché específico (por ejemplo, 5 días), cree una instancia del origen de la imagen como se muestra a continuación:

webImage.Source = new UriImageSource
{
    Uri = new Uri("https://aka.ms/campus.jpg"),
    CachingEnabled = true,
    CacheValidity = new TimeSpan(5,0,0,0)
};

El almacenamiento en caché integrado facilita la compatibilidad con escenarios como el desplazamiento de listas de imágenes, donde puede establecer (o enlazar) una imagen en cada celda y permitir que la caché integrada se haga cargo de volver a cargar la imagen cuando la celda se desplaza de nuevo a la vista.

GIF animados

Xamarin.Forms incluye compatibilidad para mostrar ARCHIVOS GIF pequeños y animados. Esto se logra estableciendo la propiedad Xamarin_Forms _Image_Source" data-linktype="absolute-path">en un Image.Source archivo GIF animado:

<Image Source="demo.gif" />

De forma predeterminada, cuando se carga un GIF animado, no se reproducirá. Esto se debe a que la propiedad , que controla si un GIF animado se está reproduciendo o IsAnimationPlaying detenido, tiene un valor predeterminado de false . Esta propiedad, de tipo , está copiada por un objeto , lo que significa que puede ser el destino de un enlace de datos boolBindableProperty y tiene un estilo.

Por lo tanto, cuando se carga un GIF animado, no se reproducirá hasta que IsAnimationPlaying la propiedad se establezca en true . A continuación, la reproducción se puede detener IsAnimationPlaying estableciendo la propiedad en false . Tenga en cuenta que esta propiedad no tiene ningún efecto al mostrar un origen de imagen que no es GIF.

Iconos y pantallas de presentación

Aunque no están relacionados con la vista, los iconos de aplicación y las pantallas de presentación también son Image un uso importante de las imágenes en los Xamarin.Forms proyectos.

La configuración de iconos y pantallas de presentación Xamarin.Forms para aplicaciones se realiza en cada uno de los proyectos de aplicación. Esto significa generar imágenes con el tamaño correcto para iOS, Android y UWP. Estas imágenes se deben denominar y localizar según los requisitos de cada plataforma.

Iconos

Consulta iOS Working with Images , Google Iconographyy UWP Guidelines for tile and icon assets (Instrucciones para UWP para recursos de icono e icono de iOS)para obtener más información sobre cómo crear estos recursos de aplicación.

Además, la vista puede mostrar iconos de fuente especificando los datos del icono de Image fuente en un objeto FontImageSource . Para obtener más información, vea Mostrar iconos de fuente en la guía Fuentes.

Pantallas de presentación

Solo las aplicaciones iOS y UWP requieren una pantalla de presentación (también denominada pantalla de inicio o imagen predeterminada).

Consulte la documentación para iOS Working with Images and Splash screens (Trabajo con imágenes y pantallas de presentación de iOS) en Windows Centro de desarrollo.

Vínculos relacionados

• WorkingWithImages (ejemplo)
• Trabajo con imágenes de iOS
• Iconografía de Android
• Directrices sobre los activos de iconos y ventanas