Imagens e pincéis de imagem

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

São estes os elementos certos?

Use um elemento Image para exibir uma imagem autônoma em seu aplicativo.

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

A aplicação WinUI 3 Gallery inclui exemplos interativos de controlos e funcionalidades WinUI. Descarrega a aplicação na Microsoft Store ou navega pelo código-fonte no 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.

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. No nosso exemplo, colocamos o ficheiro de imagem "sunset.jpg" na pasta raiz do nosso projeto e declaramos as configurações do projeto que incluem o ficheiro de imagem como parte do conteúdo.

Pincel de imagem

Com o objeto ImageBrush , você pode usar uma imagem para pintar uma área que usa um objeto Brush . Por exemplo, você pode usar um ImageBrush para o valor da propriedade Fill de uma Ellipse ou a propriedade Background de uma 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.

Esticar uma imagem

Se você não definir os valores de Largura ou Altura de uma Imagem, ela será exibida com as dimensões da imagem especificadas pela Fonte. Definir a Largura e a 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 de alongamento: se a imagem de origem for maior do que a área que a contém, a imagem será cortada, e isso geralmente não é desejável porque não tem nenhum controlo sobre a área de visualização como acontece com um Corte deliberado.
• : 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 sua proporção original.
• Preenchimento: A imagem é dimensionada para se ajustar à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.

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 área de recorte para 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.

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.

Formatos de arquivo de imagem

Image e ImageBrush podem exibir estes 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 incorporadas e, no máximo, irão apresentar aspectos de codificação ou decodificação como parte dos dados de eventos de carregamento. Se quiseres fazer algum trabalho especial com codificação ou decodificação de imagens, que podes usar se a tua aplicação estiver a fazer conversões ou manipulação de imagens, deves usar as APIs disponíveis no Windows. Graphics.Imaging espaço de nomes. Estas APIs também são suportadas pelo Windows Imaging Component (WIC) no Windows.

Para saber mais sobre os recursos do aplicativo e como empacotar fontes de imagem em um aplicativo, veja Carregar imagens e ativos 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, utilize a propriedade PixelBuffer para aceder ao buffer e use um fluxo ou tipo de buffer específico do idioma para preenchê-lo. 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

Deves criar as tuas fontes de imagem em vários tamanhos recomendados, para garantir que a tua aplicação fica ótima quando o Windows a escalar. Ao especificar uma Origem para uma 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 Guia de início rápido: usando recursos de arquivo ou imagem.

Para obter mais informações sobre como projetar para dimensionamento, consulte as diretrizes de UX para dimensionamento e layout.

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 a sua origem for um URI, que inclui conteúdo na sua aplicação que usam os esquemas ms-appx ou ms-resource, use o construtor BitmapImage que recebe um URI. Você também pode considerar manipular o evento ImageOpened se houver algum problema de tempo com a recuperação ou decodificação da fonte da imagem, onde você pode precisar de conteúdo alternativo para exibir até que a fonte da imagem esteja disponível. Para código de exemplo, consulte o exemplo da galeria WinUI 3.

Artigos relacionados

• Áudio, vídeo e câmera
• Classe de imagem
• Classe ImageBrush