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

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.

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

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 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 WinUI Gallery.

UWP e WinUI 2

As APIs para esse controle existem nos namespaces Windows.UI.Xaml.Controls e Windows.UI.Xaml.Media .

Recomendamos usar a WinUI 2 mais recente 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. Quando você usa um BitmapImage como a fonte da imagem, você pode acessar APIs 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 .

Artigos relacionados

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