Share via

Imagens em Xamarin.Forms

  • Artigo

As imagens podem ser compartilhadas entre plataformas com Xamarin.Formso , elas podem ser carregadas especificamente para cada plataforma ou podem ser baixadas para exibição.

As imagens são uma parte crucial da navegação, usabilidade e identidade visual do aplicativo. Xamarin.Forms Os aplicativos precisam ser capazes de compartilhar imagens em todas as plataformas, mas também potencialmente exibir imagens diferentes em cada plataforma.

Imagens específicas da plataforma também são necessárias para ícones e telas iniciais; eles precisam ser configurados por plataforma.

Exibir imagens

Xamarin.Forms Usa o Image modo de exibição para exibir imagens em uma página. Tem várias propriedades importantes:

  • Source - Uma ImageSource instância, File, Uri ou Resource, que define a imagem para exibição.
  • Aspect - Como dimensionar a imagem dentro dos limites dentro dos quais ela está sendo exibida (seja para esticar, cortar ou caixa de correio).

ImageSource As instâncias podem ser obtidas usando métodos estáticos para cada tipo de fonte de imagem:

  • FromFile - Requer um nome de arquivo ou caminho de arquivo que pode ser resolvido em cada plataforma.
  • FromUri - Requer um objeto Uri, por exemplo. new Uri("http://server.com/image.jpg") .
  • FromResource - Requer um identificador de recurso para um arquivo de imagem incorporado no aplicativo ou no projeto de biblioteca do .NET Standard, com um Build Action:EmbeddedResource.
  • FromStream - Requer um fluxo que forneça dados de imagem.

A Aspect propriedade determina como a imagem será dimensionada para se ajustar à área de exibição:

  • Fill - Estende a imagem para preencher completamente e exatamente a área de exibição. Isso pode resultar na distorção da imagem.
  • AspectFill - Recorta a imagem para que ela preencha a área de exibição, preservando o aspecto (ou seja, sem distorção).
  • AspectFit - Letterboxes a imagem (se necessário) para que a imagem inteira se encaixe na área de exibição, com espaço em branco adicionado para a parte superior / inferior ou laterais, dependendo se a imagem é larga ou alta.

As imagens podem ser carregadas de um arquivo local, um recurso incorporado, baixadas ou carregadas de um fluxo. Além disso, os Image ícones de fonte podem ser exibidos pela exibição especificando os dados do ícone de fonte em um FontImageSource objeto. Para obter mais informações, consulte Exibir ícones de fonte no guia Fontes .

Imagens locais

Os arquivos de imagem podem ser adicionados a cada projeto de aplicativo e referenciados a partir de Xamarin.Forms código compartilhado. Esse método de distribuição de imagens é necessário quando as imagens são específicas da plataforma, como ao usar resoluções diferentes em diferentes plataformas ou designs ligeiramente diferentes.

Para usar uma única imagem em todos os aplicativos, o mesmo nome de arquivo deve ser usado em todas as plataformas e deve ser um nome de recurso válido do Android (ou seja, apenas letras minúsculas, numerais, o sublinhado e o ponto são permitidos).

  • iOS - A maneira preferida de gerenciar e oferecer suporte a imagens desde o iOS 9 é usar os Conjuntos de Imagens do Catálogo de Ativos, que devem conter todas as versões de uma imagem necessárias para suportar vários dispositivos e fatores de escala para um aplicativo. Para obter mais informações, consulte Adicionando imagens a um conjunto de imagens do catálogo de ativos.
  • Android - Coloque imagens no diretório Resources/drawable com Build Action: AndroidResource. Versões de alto e baixo DPI de uma imagem também podem ser fornecidas (em subdiretórios de recursos apropriadamente nomeados, como drawable-ldpi, drawable-hdpi e drawable-xhdpi).
  • Plataforma Universal do Windows (UWP) - Por padrão, as imagens devem ser colocadas no diretório raiz do aplicativo com Build Action: Content. Alternativamente, as imagens podem ser colocadas em um diretório diferente, que é especificado com uma plataforma específica. Para obter mais informações, consulte Diretório de imagem padrão no Windows.

Importante

Antes do iOS 9, as imagens eram normalmente colocadas na pasta Recursos com Build Action: BundleResource. No entanto, esse método de trabalhar com imagens em um aplicativo iOS foi preterido pela Apple. Para obter mais informações, consulte Tamanhos de imagem e nomes de arquivos.

A adesão a essas regras de nomeação e posicionamento de arquivos permite que o seguinte XAML carregue e exiba a imagem em todas as plataformas:

<Image Source="waterfront.jpg" />

O código C# equivalente é o seguinte:

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

As capturas de tela a seguir mostram o resultado da exibição de uma imagem local em cada plataforma:

Aplicativo de exemplo exibindo uma imagem local

Para obter mais flexibilidade, a Device.RuntimePlatform propriedade pode ser usada para selecionar um arquivo de imagem ou caminho diferente para algumas ou todas as plataformas, conforme mostrado neste exemplo de código:

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

Importante

Para usar o mesmo nome de arquivo de imagem em todas as plataformas, o nome deve ser válido em todas as plataformas. Os drawables do Android têm restrições de nomenclatura – apenas letras minúsculas, números, sublinhado e ponto são permitidos – e para compatibilidade entre plataformas isso deve ser seguido em todas as outras plataformas também. O exemplo de nome de arquivo waterfront.png segue as regras, mas exemplos de nomes de arquivos inválidos incluem "water front.png", "WaterFront.png", "water-front.png" e "wåterfront.png".

Resoluções nativas (retina e alto DPI)

iOS, Android e UWP incluem suporte para diferentes resoluções de imagem, onde o sistema operacional escolhe a imagem apropriada em tempo de execução com base nos recursos do dispositivo. Xamarin.Forms usa as APIs das plataformas nativas para carregar imagens locais, portanto, oferece suporte automaticamente a resoluções alternativas se os arquivos estiverem corretamente nomeados e localizados no projeto.

A maneira preferida de gerenciar imagens desde o iOS 9 é arrastar imagens para cada resolução necessária para o conjunto de imagens do catálogo de ativos apropriado. Para obter mais informações, consulte Adicionando imagens a um conjunto de imagens do catálogo de ativos.

Antes do iOS 9, as versões retina da imagem podiam ser colocadas na pasta Recursos - duas e três vezes a resolução com uma @2x ou @3x sufixos no nome do arquivo antes da extensão do arquivo (por exemplo). myimage@2x.png No entanto, esse método de trabalhar com imagens em um aplicativo iOS foi preterido pela Apple. Para obter mais informações, consulte Tamanhos de imagem e nomes de arquivos.

As imagens de resolução alternativa do Android devem ser colocadas em diretórios especialmente nomeados no projeto Android, conforme mostrado na captura de tela a seguir:

Localização da imagem de resolução múltipla do Android

Os nomes de arquivo de imagem UWP podem ser sufixados antes .scale-xxx da extensão de arquivo, onde xxx é a porcentagem de dimensionamento aplicada ao ativo, por exemplo , myimage.scale-200.png. As imagens podem então ser referenciadas em código ou XAML sem o modificador de escala, por exemplo, apenas myimage.png. A plataforma selecionará a escala de ativos apropriada mais próxima com base no DPI atual da tela.

Controles adicionais que exibem imagens

Alguns controles têm propriedades que exibem uma imagem, como:

  • Button tem uma ImageSource propriedade que pode ser definida como uma imagem de bitmap a ser exibida no Button. Para obter mais informações, consulte Usando bitmaps com botões.

  • ImageButton tem uma Source propriedade que pode ser definida como a imagem a ser exibida no ImageButton. Para obter mais informações, consulte Definindo a origem da imagem.

  • ToolbarItem tem uma IconImageSource propriedade que pode ser definida como uma imagem carregada de um arquivo, recurso incorporado, URI ou fluxo.

  • ImageCell tem uma ImageSource propriedade que pode ser definida como uma imagem recuperada de um arquivo, recurso incorporado, URI ou fluxo.

  • Page. Qualquer tipo de página derivado de Page tem IconImageSource e BackgroundImageSource propriedades, que pode ser atribuído a um arquivo, recurso incorporado, URI ou fluxo. Em determinadas circunstâncias, como quando um NavigationPage está exibindo um ContentPage, o ícone será exibido se suportado pela plataforma.

    Importante

    No iOS, a Page.IconImageSource propriedade não pode ser preenchida a partir de uma imagem em um conjunto de imagens do catálogo de ativos. Em vez disso, carregue imagens de ícone para a Page.IconImageSource propriedade de um arquivo, recurso incorporado, URI ou fluxo.

Imagens incorporadas

As imagens incorporadas também são fornecidas com um aplicativo (como imagens locais), mas em vez de ter uma cópia da imagem na estrutura de arquivos de cada aplicativo, o arquivo de imagem é incorporado no assembly como um recurso. Esse método de distribuição de imagens é recomendado quando imagens idênticas são usadas em cada plataforma e é particularmente adequado para criar componentes, já que a imagem é empacotada com o código.

Para incorporar uma imagem em um projeto, clique com o botão direito do mouse para adicionar novos itens e selecione a(s) imagem(ns) que deseja adicionar. Por padrão, a imagem terá Build Action: None, isso precisa ser definido como Build Action: EmbeddedResource.

Definir ação de compilação como recurso incorporado

A Ação de Criação pode ser exibida e alterada na janela Propriedades de um arquivo.

Neste exemplo, a ID do recurso é WorkingWithImages.beach.jpg. O IDE gerou esse padrão concatenando o namespace padrão para este projeto com o nome do arquivo, usando um ponto (.) entre cada valor.

Se você colocar imagens incorporadas em pastas dentro do seu projeto, os nomes das pastas também serão separados por pontos (.) na ID do recurso. Mover a imagem beach.jpg para uma pasta chamada MyImages resultaria em uma ID de recurso de WorkingWithImages.MyImages.beach.jpg

O código para carregar uma imagem incorporada simplesmente passa a ID do recurso para o ImageSource.FromResource método, conforme mostrado abaixo:

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

Observação

Para oferecer suporte à exibição de imagens incorporadas no modo de versão na Plataforma Universal do Windows, é necessário usar a sobrecarga que especifica o assembly de ImageSource.FromResource origem no qual procurar a imagem.

No momento, não há conversão implícita para identificadores de recursos. Em vez disso, você deve usar ImageSource.FromResource ou new ResourceImageSource() carregar imagens incorporadas.

As capturas de tela a seguir mostram o resultado da exibição de uma imagem incorporada em cada plataforma:

Aplicativo de exemplo exibindo uma imagem incorporada

XAML

Como não há nenhum conversor de tipo interno de string para ResourceImageSource, esses tipos de imagens não podem ser carregados nativamente por XAML. Em vez disso, uma extensão de marcação XAML personalizada simples pode ser gravada para carregar imagens usando uma ID de recurso especificada em 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;
 }
}

Observação

Para oferecer suporte à exibição de imagens incorporadas no modo de versão na Plataforma Universal do Windows, é necessário usar a sobrecarga que especifica o assembly de ImageSource.FromResource origem no qual procurar a imagem.

Para usar essa extensão, adicione um personalizado xmlns ao XAML, usando os valores corretos de namespace e assembly para o projeto. A origem da imagem pode então ser definida usando esta sintaxe: {local:ImageResource WorkingWithImages.beach.jpg}. Um exemplo completo de XAML é mostrado abaixo:

<?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>

Solucionar problemas de imagens incorporadas

Depurar o código

Como às vezes é difícil entender por que um determinado recurso de imagem não está sendo carregado, o código de depuração a seguir pode ser adicionado temporariamente a um aplicativo para ajudar a confirmar se os recursos estão configurados corretamente. Ele enviará todos os recursos conhecidos incorporados no assembly fornecido para o Console para ajudar a depurar problemas de carregamento 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);
}

Imagens incorporadas em outros projetos

Por padrão, o ImageSource.FromResource método procura apenas imagens no mesmo assembly que o código que chama o ImageSource.FromResource método. Usando o código de depuração acima, você pode determinar quais assemblies contêm um recurso específico alterando a typeof() instrução para um Type conhecido em cada assembly.

No entanto, o assembly de origem que está sendo pesquisado para uma imagem incorporada pode ser especificado como um argumento para o ImageSource.FromResource método:

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

Download de imagens

As imagens podem ser baixadas automaticamente para exibição, conforme mostrado no seguinte XAML:

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

O código C# equivalente é o seguinte:

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

O ImageSource.FromUri método requer um Uri objeto e retorna um novo UriImageSource que lê do Uri.

Há também uma conversão implícita para cadeias de caracteres de URI, portanto, o exemplo a seguir também funcionará:

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

As capturas de tela a seguir mostram o resultado da exibição de uma imagem remota em cada plataforma:

Aplicativo de exemplo exibindo uma imagem baixada

Cache de imagem baixado

A UriImageSource também suporta cache de imagens baixadas, configurado através das seguintes propriedades:

  • CachingEnabled - Se o cache está habilitado (true por padrão).
  • CacheValidity - A TimeSpan que define por quanto tempo a imagem será armazenada localmente.

O cache é habilitado por padrão e armazenará a imagem localmente por 24 horas. Para desabilitar o cache de uma imagem específica, instancie a origem da imagem da seguinte maneira:

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

Para definir um período de cache específico (por exemplo, 5 dias), instancie a origem da imagem da seguinte maneira:

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

O cache integrado torna muito fácil oferecer suporte a cenários como listas de rolagem de imagens, onde você pode definir (ou vincular) uma imagem em cada célula e permitir que o cache interno se encarregue de recarregar a imagem quando a célula for rolada de volta para a exibição.

GIFs animados

Xamarin.Forms inclui suporte para exibir GIFs pequenos e animados. Isso é feito definindo a Image.Source propriedade como um arquivo GIF animado:

<Image Source="demo.gif" />

Importante

Embora o suporte a GIFs animados inclua Xamarin.Forms a capacidade de baixar arquivos, ele não oferece suporte a cache ou streaming de GIFs animados.

Por padrão, quando um GIF animado é carregado, ele não será reproduzido. Isso ocorre porque a propriedade, que controla IsAnimationPlaying se um GIF animado está sendo reproduzido ou parado, tem um valor padrão de false. Essa propriedade, do tipo bool, é apoiada por um BindableProperty objeto, o que significa que ela pode ser o destino de uma associação de dados e estilizada.

Portanto, quando um GIF animado é carregado, ele não será reproduzido até que a IsAnimationPlaying propriedade seja definida como true. A reprodução pode ser interrompida definindo a IsAnimationPlaying propriedade como false. Observe que essa propriedade não tem efeito ao exibir uma fonte de imagem não GIF.

Observação

No Android, o suporte a GIFs animados requer que seu aplicativo esteja usando renderizadores rápidos e não funcionará se você tiver optado por usar os renderizadores herdados. Na UWP, o suporte a GIFs animados requer uma versão mínima da Atualização de Aniversário do Windows 10 (versão 1607).

Ícones e telas iniciais

Embora não estejam relacionados à Image exibição, ícones de aplicativos e telas iniciais também são um uso importante de imagens em Xamarin.Forms projetos.

A configuração de ícones e telas iniciais para Xamarin.Forms aplicativos é feita em cada um dos projetos de aplicativos. Isso significa gerar imagens de tamanho correto para iOS, Android e UWP. Essas imagens devem ser nomeadas e localizadas de acordo com as necessidades de cada plataforma.

Ícones

Consulte as Diretrizes para iOS Trabalhando com imagens, Iconografia do Google e UWP para ativos de bloco e ícone para obter mais informações sobre como criar esses recursos de aplicativo.

Além disso, os Image ícones de fonte podem ser exibidos pela exibição especificando os dados do ícone de fonte em um FontImageSource objeto. Para obter mais informações, consulte Exibir ícones de fonte no guia Fontes .

Telas iniciais

Somente aplicativos iOS e UWP exigem uma tela inicial (também chamada de tela de inicialização ou imagem padrão).

Consulte a documentação do iOS Trabalhando com imagens e telas iniciais no Centro de Desenvolvimento do Windows.