Partilhar via

Imagens e pincéis de imagem

  • Artigo

Para exibir uma imagem, você pode usar o objeto Image ou o ImageBrush objeto. Um objeto Image renderiza uma imagem e um objeto ImageBrush pinta outro objeto com uma imagem.

São estes os elementos certos?

Utilize um elemento Image para exibir uma imagem independente na sua aplicação.

Use um ImageBrush para aplicar uma imagem a outro objeto. Os usos de um ImageBrush incluem efeitos decorativos para texto ou planos de fundo para controles ou contêineres de layout.

Criar uma imagem

Abra o aplicativo WinUI 3 Gallery e veja ImageBrushes em ação

O aplicativo WinUI 3 Gallery inclui exemplos interativos da maioria dos controles, recursos e funcionalidades do WinUI 3. Obtenha o aplicativo no da Microsoft Store ou obtenha o código-fonte em do GitHub

Imagem

Este exemplo mostra como criar uma imagem usando o objeto Image.

<Image Width="200" Source="sunset.jpg" />

Aqui está o objeto Imagem renderizado.

Exemplo de um elemento de imagem

Neste exemplo, a propriedade Source especifica o local da imagem que você deseja exibir. Você pode definir a Origem especificando uma URL absoluta (por exemplo, http://contoso.com/myPicture.jpg) ou especificando uma URL relativa à estrutura de empacotamento do aplicativo. Para o nosso exemplo, colocamos o arquivo de imagem "sunset.jpg" na pasta raiz do nosso projeto e declaramos as configurações do projeto que incluem o arquivo de imagem como conteúdo.

Pincel de imagem

Com o objeto ImageBrush, pode-se usar uma imagem para pintar uma área que suporta um objeto Brush. Por exemplo, você pode usar um ImageBrush para o valor da propriedade Fill de um Ellipse ou da propriedade Background de um Canvas.

O próximo exemplo mostra como usar um ImageBrush para pintar uma elipse.

<Ellipse Height="200" Width="300">
   <Ellipse.Fill>
     <ImageBrush ImageSource="sunset.jpg" />
   </Ellipse.Fill>
</Ellipse>

Aqui está a elipse pintada pelo ImageBrush.

Uma elipse pintada por um ImageBrush.

Esticar uma imagem

Se você não definir os valores Width ou Height de um Image, ele será exibido com as dimensões da imagem especificadas pelo Source. Definir a Largura e Altura cria uma área retangular na qual a imagem é exibida. Você pode especificar como a imagem preenche essa área de contenção usando a propriedade Stretch. A propriedade Stretch aceita esses valores, que a enumeração Stretch define:

  • Nenhum: A imagem não se estende para preencher as dimensões de saída. Tenha cuidado com esta configuração Stretch: se a imagem de origem for maior do que a área que a contém, sua imagem será cortada, e isso geralmente não é desejável porque você não tem nenhum controle sobre o visor como faz com um deliberadoClip.
  • : A imagem é dimensionada uniformemente para se ajustar às dimensões de saída. Mas a proporção do conteúdo é preservada. Este é o valor padrão.
  • UniformToFill: A imagem é dimensionada para preencher completamente a área de saída, mas preserva a sua proporção original.
  • Preenchimento de: A imagem é dimensionada para ajustar-se às dimensões de saída. Como a altura e a largura do conteúdo são dimensionadas independentemente, a proporção original da imagem pode não ser preservada. Ou seja, a imagem pode ser distorcida para preencher completamente a área de saída.

Um exemplo de configurações de alongamento.

Recortar uma imagem

Você pode usar a propriedade Clip para recortar uma área da saída da imagem. Definir a propriedade Clip como Geometria . Atualmente, não é suportado o recorte não retangular.

O próximo exemplo mostra como usar um RectangleGeometry como a região de corte de uma imagem. Neste exemplo, definimos um objeto de imagem com uma altura de 200. Um RectangleGeometry define um retângulo para a área da imagem que será exibida. A propriedade Rect é definida como "25,25,100,150", que define um retângulo começando na posição "25,25" com uma largura de 100 e uma altura de 150. Apenas a parte da imagem que está dentro da área do retângulo é exibida.

<Image Source="sunset.jpg" Height="200">
    <Image.Clip>
        <RectangleGeometry Rect="25,25,100,150" />
    </Image.Clip>
</Image>

Aqui está a imagem cortada em um fundo preto.

Um objeto Imagem recortado por um RectangleGeometry.

Aplicar uma opacidade

Você pode aplicar uma opacidade a uma imagem para que ela seja processada semitranslúcida. Os valores de opacidade são de 0,0 a 1,0, onde 1,0 é totalmente opaco e 0,0 é totalmente transparente. Este exemplo mostra como aplicar uma opacidade de 0,5 a uma Image.

<Image Height="200" Source="sunset.jpg" Opacity="0.5" />

Aqui está a imagem renderizada com uma opacidade de 0,5 e um fundo preto mostrando através da opacidade parcial.

Um objeto Image com uma opacidade de 0,5.

Formatos de arquivo de imagem

Imagem e ImageBrush podem exibir os seguintes formatos de arquivo de imagem:

  • Grupo Conjunto de Peritos Fotográficos (JPEG)
  • Gráficos de rede portáteis (PNG)
  • mapa de bits (BMP)
  • GIF (Graphics Interchange Format)
  • Formato de arquivo de imagem com tags (TIFF)
  • JPEG XR
  • ícones (ICO)

As APIs para Image, BitmapImage e BitmapSource não incluem nenhum método dedicado para codificação e decodificação de formatos de mídia. Todas as operações de codificação e decodificação são embutidas e, no máximo, apresentarão aspetos de codificação ou decodificação como parte dos dados dos eventos de carregamento. Se você quiser fazer qualquer trabalho especial com codificação ou decodificação de imagem, que você pode usar se seu aplicativo estiver fazendo conversões ou manipulação de imagem, use as APIs que estão disponíveis no namespace Windows.Graphics.Imaging. Essas APIs também são suportadas pelo Windows Imaging Component (WIC) no Windows.

Para saber mais sobre os recursos da aplicação e como empacotar fontes de imagem numa aplicação, veja Carregar imagens e recursos adaptados para escala, tema, alto contraste e outros.

WriteableBitmap

Um WriteableBitmap fornece um BitmapSource que pode ser modificado e que não usa a decodificação básica baseada em arquivo do WIC. Você pode alterar as imagens dinamicamente e renderizar novamente a imagem atualizada. Para definir o conteúdo do buffer de um WriteableBitmap, use a propriedade PixelBuffer para aceder ao buffer e use um fluxo ou um tipo de buffer específico do idioma para o preencher. Para obter um código de exemplo, consulte WriteableBitmap.

RenderTargetBitmap

A classe RenderTargetBitmap pode capturar a árvore da interface do usuário XAML de um aplicativo em execução e, em seguida, representa uma fonte de imagem de bitmap. Após a captura, essa fonte de imagem pode ser aplicada a outras partes do aplicativo, salva como um recurso ou dados do aplicativo pelo usuário ou usada para outros cenários. Um cenário particularmente útil é a criação de uma miniatura em tempo de execução de uma página XAML para um esquema de navegação. RenderTargetBitmap tem algumas limitações no conteúdo que aparecerá na imagem capturada. Para obter mais informações, consulte o tópico de referência da API para RenderTargetBitmap.

Fontes de imagem e dimensionamento

Você deve criar as suas fontes de imagem em vários tamanhos sugeridos, para garantir que a sua aplicação tenha uma ótima aparência quando o Windows as escalar. Ao especificar um de origem de para um de imagem, você pode usar uma convenção de nomenclatura que fará referência automática ao recurso correto para o dimensionamento atual. Para obter detalhes da convenção de nomenclatura e mais informações, consulte Início Rápido: usando recursos de arquivo ou imagem.

Para mais informações sobre como desenhar para escalabilidade, veja Diretrizes de UX para layout e dimensionamento.

Image e ImageBrush em código

É comum especificar elementos Image e ImageBrush usando XAML em vez de código. Isso ocorre porque esses elementos geralmente são a saída de ferramentas de design como parte de uma definição de interface do usuário XAML.

Se você definir um Image ou ImageBrush usando código, use os construtores padrão e, em seguida, defina a propriedade source relevante (Image.Source ou ImageBrush.ImageSource). As propriedades de origem exigem um BitmapImage (não um URI) quando você as define usando código. Se sua origem for um fluxo, use o método SetSourceAsync para inicializar o valor. Se sua origem for um URI, que inclui conteúdo em seu aplicativo que usa o ms-appx ou esquemas de ms-resource, use o BitmapImage construtor que usa um URI. Você também pode considerar lidar com o evento ImageOpened se houver algumas questões de timing com a recuperação ou decodificação da fonte da imagem, caso precise de conteúdo alternativo para exibir até que a fonte da imagem esteja disponível. Para obter um código de exemplo, consulte o exemplo de WinUI Gallery.

Observação

Se estabelecer imagens usando código, pode usar a manipulação automática para aceder a recursos não qualificados com qualificadores de escala e cultura atuais, ou pode usar ResourceManager e ResourceMap com qualificadores para cultura e escala para obter os recursos diretamente. Para obter mais informações, consulte Sistema de gerenciamento de recursos.

UWP e WinUI 2

Importante

As informações e os exemplos neste artigo são otimizados para aplicativos que usam o SDK de Aplicativo Windows e WinUI 3, mas geralmente são aplicáveis a aplicativos UWP que usam WinUI 2. Consulte a referência da API UWP para obter informações e exemplos específicos da plataforma.

Esta seção contém informações que você precisa para usar o controle em um aplicativo UWP ou WinUI 2.

As APIs para este controlo existem nos namespaces Windows.UI.Xaml.Controls e Windows.UI.Xaml.Media.

Recomendamos usar o mais recente WinUI 2 para obter os estilos e modelos mais atuais para todos os controles.

A partir do Windows 10, versão 1607, o elemento Image suporta imagens GIF animadas. Ao utilizar um BitmapImage como fonte de imagem , pode aceder às APIs do BitmapImage para controlar a reprodução da imagem GIF animada. Para mais informações, consulte a seção "Observações" na página da classe BitmapImage .

Observação

O suporte a GIFs animados está disponível quando seu aplicativo é compilado para Windows 10, versão 1607 e executado na versão 1607 (ou posterior). Quando seu aplicativo é compilado ou executado em versões anteriores, o primeiro quadro do GIF é mostrado, mas não é animado.