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.

Esses são 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 Galeria da WinUI 3 inclui exemplos interativos da maioria dos controles, recursos e funcionalidades da WinUI 3. Obtenha o aplicativo na Microsoft Store ou obtenha o 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 Image 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 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 elipse ou da propriedade Background de um Canvas.

O exemplo a seguir 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 largura ou altura de uma imagem, ela será exibida com as dimensões da imagem especificadas pela Origem. Definir a Largura e a Altura cria uma área retangular que contém a imagem exibida. Você pode especificar como a imagem preenche essa área que contém 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 essa configuração Stretch: se a imagem de origem for maior que a área de conteúdo, sua imagem será recortada e, geralmente, isso não é desejável, pois você não tem controle sobre o visor, como em um Clip deliberado.
• Uniforme: a imagem é dimensionada para se ajustar às dimensões de saída. Mas a proporção do conteúdo é preservada. Esse é o valor padrão.
• UniformToFill: a imagem é escalada para que preencha 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 de forma independente, a taxa de 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.

Cortar uma imagem

Você pode usar a propriedade Clip para recortar uma área da saída da imagem. Você definiu a propriedade Clip para uma Geometria . Atualmente, não há suporte para recorte não retangular.

O próximo exemplo mostra como usar uma RectangleGeometry como a região de recorte de uma imagem. Neste exemplo, definimos um objeto Image 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. Somente 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 recortada em um fundo preto.

Aplicar uma opacidade

Aplique Opacity a uma imagem, de forma que a imagem seja renderizada como semitranslúcida. Os valores de opacidade são de 0,0 a 1,0, em que 1,0 é totalmente opaco e 0,0 é totalmente transparente. Este exemplo mostra como aplicar uma opacidade de 0,5 a uma imagem.

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

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

Formatos de arquivo de imagem

Image e ImageBrush podem exibir estes formatos de arquivo de imagem:

• JPEG (Grupo Conjunto de Especialistas em Fotografia)
• Png (Gráficos de Rede Portátil)
• BMP (bitmap)
• Gif (formato de intercâmbio de elementos gráficos)
• TIFF (Formato de Arquivo de Imagem Marcado)
• JPEG XR
• ícones (ICO)

As APIs de Imagem, BitmapImage e BitmapSource não incluem métodos dedicados para codificação e decodificação de formatos de mídia. Todas as operações de codificação e decodificação são internas e, no máximo, apresentarão aspectos de codificação ou decodificação como parte dos dados de evento para eventos de carga. Se você quiser fazer qualquer trabalho especial com codificação ou decodificação de imagem, que poderá ser usado se o aplicativo estiver fazendo conversões ou manipulação de imagem, use as APIs disponíveis no namespace Windows.Graphics.Imaging . Essas APIs também são compatíveis com o WIC (Windows Imaging Component) no Windows.

Para obter mais informações sobre recursos de aplicativo e como empacotar fontes de imagem em um aplicativo, consulte Carregar imagens e ativos personalizados para escala, tema, alto contraste e outros.

Mapa de bits gravável

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 imagens dinamicamente e renderizar novamente a imagem atualizada. Para definir o conteúdo do buffer de um WriteableBitmap, acesse o buffer usando a propriedade PixelBuffer e preencha-o usando um fluxo ou um tipo de buffer específico do idioma. Para código de exemplo, consulte WriteableBitmap .

RenderTargetBitmap

A classe RenderTargetBitmap pode capturar a árvore de interface do usuário XAML de um aplicativo em execução e, em seguida, representa uma fonte de imagem 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 é criar uma miniatura de 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ão 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 suas fontes de imagem em vários tamanhos recomendados, para garantir que seu aplicativo tenha uma ótima aparência quando o Windows o dimensionar. Ao especificar um de Origem para umde Imagem , você pode usar uma convenção de nomenclatura que referenciará automaticamente o 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 obter mais informações sobre como projetar para dimensionamento, consulte as diretrizes de UX para layout e dimensionamento.

Image e ImageBrush no 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 uma Imagem ou ImageBrush usando código, use os construtores padrão e defina a propriedade de origem 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 origem for um URI, que inclui conteúdo no seu aplicativo usando os esquemas ms-appx ou ms-resource, utilize o construtor BitmapImage que aceita um URI. Você também poderá considerar o tratamento do evento ImageOpened se houver problemas de tempo com a recuperação ou decodificação da origem da imagem, em que talvez seja necessário exibir conteúdo alternativo até que a origem da imagem esteja disponível. Para obter o código de exemplo, consulte o exemplo da Galeria WinUI.

UWP e WinUI 2

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

É recomendável usar o 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 dá suporte a imagens GIF animadas. Ao usar um BitmapImage como a origem da imagem, você pode acessar APIs bitmapImage para controlar a reprodução da imagem GIF animada. Para obter mais informações, consulte as Observações na página da classe BitmapImage .

Artigos relacionados

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