Imagem

A interface do usuário do aplicativo .NET multiplataforma (.NET MAUI) Image exibe uma imagem que pode ser carregada de um arquivo local, um URI ou um fluxo. Há suporte para os formatos de imagem de plataforma padrão, incluindo GIFs animados e arquivos SVG (Gráficos vetoriais escalonáveis) locais. 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 seguintes propriedades:

• 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 ao renderizá-la. O valor padrão dessa propriedade é false.
• Source, do tipo ImageSource, especifica a origem da imagem.

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

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

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

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

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 Recursos\Imagens do projeto, em que sua ação de build será automaticamente definida como MauiImage. No momento do build, as imagens de vetor 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 dão suporte a resoluções de imagem diferentes e o sistema operacional escolhe a resolução de imagem apropriada em runtime com base nos recursos do dispositivo.

Para cumprir as regras de nomenclatura de recursos do Android, todos os nomes de arquivo de imagem local devem ser minúsculos, iniciar 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 em developer.android.com.

Aderir a essas regras para nomenclatura e posicionamento de arquivo permite que o XAML a seguir carregue e exiba uma imagem:

<Image Source="dotnet_bot.png" />

O código C# equivalente é:

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

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

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 propriedade Source:

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

O código C# equivalente é:

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

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

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

Cache de imagem

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

A classe UriImageSource 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 objetos BindableProperty, o que significa que eles podem ser estilizados e ser o destino das associações de dados.

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

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

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 de fluxos com o método ImageSource.FromStream:

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

Carregar um ícone de fonte

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

Carregar GIFs animados

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

<Image Source="demo.gif" />

Por padrão, quando um GIF animado é carregado, ele não será reproduzido. Isso ocorre porque a propriedade IsAnimationPlaying, que controla 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 propriedade IsAnimationPlaying seja definida como true. A reprodução pode ser interrompida redefinindo a propriedade IsAnimationPlaying para false. Observe que essa propriedade não tem efeito ao exibir uma fonte de imagem não GIF.

Controle de dimensionamento da imagem

A propriedade Aspect determina como a imagem será dimensionada para se ajustar à área de exibição e deve ser definida como um dos membros da enumeração Aspect:

• AspectFit – caixas de correio da imagem (se necessário) para que toda a imagem se ajuste à área de exibição, com espaço em branco adicionado à parte superior/inferior ou laterais, dependendo se a imagem é larga ou alta.
• AspectFill - ajusta a imagem de forma que ela preencha a área de exibição, preservando a proporção.
• Fill - estende a imagem para preencher completamente e exatamente a área de exibição. Isso pode resultar na distorção da imagem.
• Center - centraliza a imagem na área de exibição, preservando a proporção.