Imagem

  • Artigo

A interface do usuário do aplicativo multiplataforma .NET (.NET MAUI) Image exibe uma imagem que pode ser carregada de um arquivo local, um URI ou um fluxo. Os formatos de imagem de plataforma padrão são suportados, incluindo GIFs animados, e arquivos SVG (Scalable Vector Graphics) locais também são suportados. Para obter mais informações sobre como adicionar imagens a um projeto de aplicativo .NET MAUI, consulte Adicionar imagens a um projeto de aplicativo .NET MAUI.

Image define as propriedades a seguir:

  • Aspect, do tipo Aspect, define o modo de dimensionamento da imagem.
  • IsAnimationPlaying, do tipo bool, determina se um GIF animado está sendo reproduzido ou interrompido. O valor padrão dessa propriedade é false.
  • IsLoading, do tipo bool, indica o status de carregamento da imagem. O valor padrão dessa propriedade é false.
  • IsOpaque, do tipo bool, indica se o mecanismo de renderização pode tratar a imagem como opaca durante a renderização. O valor padrão dessa propriedade é false.
  • Source, do tipo ImageSource, especifica a origem da imagem.

Essas propriedades são apoiadas por BindableProperty objetos, o que significa que elas podem ser estilizadas e ser o destino de associações de dados.

Observação

Os ícones de fonte podem ser exibidos por um especificando os dados do ícone de fonte como um ImageFontImageSource objeto. Para obter mais informações, consulte Exibir ícones de fonte.

A ImageSource classe define os seguintes métodos que podem ser usados para carregar uma imagem de diferentes fontes:

  • FromFile Retorna um que lê uma imagem de um FileImageSource arquivo local.
  • FromUri retorna um que baixa e lê uma imagem de um UriImageSource URI especificado.
  • FromStream Retorna um que lê uma imagem de um StreamImageSource fluxo que fornece dados de imagem.

Em XAML, as imagens podem ser carregadas de arquivos e URIs especificando o nome do arquivo ou URI como um valor de cadeia de caracteres para a Source propriedade. As imagens também podem ser carregadas de fluxos em XAML por meio de extensões de marcação personalizadas.

Importante

As imagens serão exibidas em sua resolução total, a menos que o tamanho do seja restrito por seu layout, ou a HeightRequest propriedade ou WidthRequest do ImageImage seja especificada.

Para obter informações sobre como adicionar ícones de aplicativo e uma tela inicial ao seu aplicativo, consulte Ícones de aplicativo e Tela inicial.

Carregar uma imagem local

As imagens podem ser adicionadas ao seu projeto de aplicativo arrastando-as para a pasta Resources\Images do seu projeto, onde sua ação de compilação será definida automaticamente como MauiImage. Em tempo de compilação, as imagens vetoriais são redimensionadas para as resoluções corretas para a plataforma e o dispositivo de destino e adicionadas ao pacote do aplicativo. Isso é necessário porque diferentes plataformas oferecem suporte a diferentes resoluções de imagem e o sistema operacional escolhe a resolução de imagem apropriada em tempo de execução com base nos recursos do dispositivo.

Para estar em conformidade com as regras de nomenclatura de recursos do Android, todos os nomes de arquivos de imagem locais devem ser minúsculos, começar e terminar com um caractere de letra e conter apenas caracteres alfanuméricos ou sublinhados. Para obter mais informações, consulte Visão geral dos recursos do aplicativo no developer.android.com.

Importante

O .NET MAUI converte arquivos SVG em arquivos PNG. Portanto, ao adicionar um arquivo SVG ao seu projeto de aplicativo .NET MAUI, ele deve ser referenciado de XAML ou C# com uma extensão .png.

A adesão a essas regras para nomeação e posicionamento de arquivos permite que o seguinte XAML carregue e exiba uma imagem:

<Image Source="dotnet_bot.png" />

Este é o código C# equivalente:

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

O ImageSource.FromFile método requer um argumento e retorna um string novo FileImageSource objeto que lê a imagem do arquivo. Há também um operador de conversão implícito que permite que o nome do arquivo seja especificado como um string argumento para a Image.Source propriedade:

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

Carregar uma imagem remota

As imagens remotas podem ser baixadas e exibidas especificando um URI como o valor da Source propriedade:

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

Este é o código C# equivalente:

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

O ImageSource.FromUri método requer um argumento e retorna um Uri novo UriImageSource objeto que lê a imagem do Uri. Há também uma conversão implícita para URIs baseados em cadeia de caracteres:

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

Cache de imagens

O cache de imagens baixadas é habilitado por padrão, com imagens armazenadas em cache por 1 dia. Esse comportamento pode ser alterado definindo propriedades da UriImageSource classe.

A UriImageSource classe define as seguintes propriedades:

  • Uri, do tipo Uri, representa o URI da imagem a ser baixada para exibição.
  • CacheValidity, do tipo TimeSpan, especifica por quanto tempo a imagem será armazenada localmente. O valor padrão dessa propriedade é 1 dia.
  • CachingEnabled, do tipo bool, define se o cache de imagem está habilitado. O valor padrão dessa propriedade é true.

Essas propriedades são apoiadas por BindableProperty objetos, o que significa que elas podem ser estilizadas e ser o destino de associações de dados.

Para definir um período de cache específico, defina a Source propriedade como um UriImageSource objeto que defina sua CacheValidity propriedade:

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

Este é o código C# equivalente:

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

Neste exemplo, o período de cache é definido como 10 dias.

Carregar uma imagem de um fluxo

As imagens podem ser carregadas a partir de fluxos com o ImageSource.FromStream método:

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

Importante

O cache de imagens é desativado no Android ao carregar uma imagem de um fluxo com o ImageSource.FromStream método. Isso se deve à falta de dados a partir dos quais criar uma chave de cache razoável.

Carregar um ícone de fonte

A FontImage extensão de marcação permite que você exiba um ícone de fonte em qualquer modo de exibição que possa exibir um ImageSourcearquivo . Ele fornece a mesma funcionalidade que a FontImageSource classe, mas com uma representação mais concisa.

A FontImage extensão de marcação é suportada FontImageExtension pela classe, que define as seguintes propriedades:

  • FontFamily do tipo string, a família de fontes à qual o ícone de fonte pertence.
  • Glyph do tipo , o valor do caractere unicode do stringícone de fonte.
  • Color do tipo Color, a cor a ser usada ao exibir o ícone de fonte.
  • Size do tipo double, o tamanho, em unidades independentes do dispositivo, do ícone de fonte renderizada. O valor padrão é 30. Além disso, essa propriedade pode ser definida como um tamanho de fonte nomeado.

Observação

O analisador XAML permite que a FontImageExtension classe seja abreviada como FontImage.

A Glyph propriedade é a propriedade content de FontImageExtension. Portanto, para expressões de marcação XAML expressas com chaves, você pode eliminar a Glyph= parte da expressão, desde que seja o primeiro argumento.

O exemplo XAML a seguir mostra como usar a extensão de FontImage marcação:

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

Neste exemplo, a FontImageExtension versão abreviada do nome da classe é usada para exibir um ícone XBox, da família de fontes Ionicons, em um Image:

Screenshot of the FontImage markup extension.

Enquanto o caractere unicode para o ícone é \uf30c, ele precisa ser escapado em XAML e assim se torna &#xf30c;.

Para obter informações sobre como exibir ícones de fonte especificando os dados do ícone de fonte em um objeto, consulte Exibir ícones de FontImageSource fonte.

Carregar GIFs animados

O .NET MAUI inclui suporte para exibir GIFs pequenos e animados. Isso é feito definindo a Source propriedade como um arquivo GIF animado:

<Image Source="demo.gif" />

Importante

Embora o suporte a GIFs animados no .NET MAUI inclua 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. 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 redefinindo a IsAnimationPlaying propriedade para false. Observe que essa propriedade não tem efeito ao exibir uma fonte de imagem não GIF.

Controlar o dimensionamento de imagens

A Aspect propriedade determina como a imagem será dimensionada para se ajustar à área de exibição e deve ser definida como um dos membros da Aspect enumeraçã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 na parte superior/inferior ou laterais, dependendo se a imagem é larga ou alta.
  • AspectFill – Recorta a imagem para que preencha a área de exibição e preserve a taxa de proporção.
  • Fill – Alonga a imagem para preencher a área de exibição de modo completo e exato. Isso pode resultar na distorção da imagem.
  • Center - centraliza a imagem na área de exibição, preservando a proporção.