BitmapImage Classe

Definição

Namespace:

Windows.UI.Xaml.Media.Imaging

Fornece o tipo de fonte de objeto prático para as propriedades Image.Source e ImageBrush.ImageSource . Você pode definir um BitmapImage usando um URI (Uniform Resource Identifier) que faz referência a um arquivo de origem de imagem ou chamando SetSourceAsync e fornecendo um fluxo.

public ref class BitmapImage sealed : BitmapSource

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.Activatable(Windows.UI.Xaml.Media.Imaging.IBitmapImageFactory, 65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
class BitmapImage final : BitmapSource

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.UI.Xaml.Media.Imaging.IBitmapImageFactory), 65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
public sealed class BitmapImage : BitmapSource

Public NotInheritable Class BitmapImage
Inherits BitmapSource

<BitmapImage .../>

Herança

Object Platform::Object IInspectable DependencyObject ImageSource BitmapSource BitmapImage

Atributos

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Requisitos do Windows

Família de dispositivos	Windows 10 (introduzida na 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (introduzida na v1.0)

Exemplos

Aqui está um exemplo de como usar um objeto BitmapImage para definir Image.Source em C#. Neste exemplo, o objeto Image foi criado em XAML, mas não tem uma origem ou outros valores de propriedade; Em vez disso, esses valores são fornecidos em tempo de execução quando a imagem é carregada de XAML.

<Image Loaded="Image_Loaded"/>

void Image_Loaded(object sender, RoutedEventArgs e)
{
    Image img = sender as Image; 
    BitmapImage bitmapImage = new BitmapImage();
    img.Width = bitmapImage.DecodePixelWidth = 80; 
    // Natural px width of image source.
    // You don't need to set Height; the system maintains aspect ratio, and calculates the other
    // dimension, as long as one dimension measurement is provided.
    bitmapImage.UriSource = new Uri(img.BaseUri,"Assets/StoreLogo.png");
    img.Source = bitmapImage;
}

Comentários

Um BitmapImage pode ser originado destes formatos de arquivo de imagem:

• JPEG
• PNG
• BMP
• GIF
• TIFF
• JPEG XR
• ícones (ICO)

Se a origem da imagem for um fluxo, espera-se que esse fluxo contenha um arquivo de imagem em um desses formatos.

A classe BitmapImage representa uma abstração para que uma fonte de imagem possa ser definida de forma assíncrona, mas ainda seja referenciada na marcação XAML como um valor de propriedade ou no código como um objeto que não usa sintaxe aguardável. Quando você cria um objeto BitmapImage no código, ele inicialmente não tem uma origem válida. Em seguida, você deve definir sua origem usando uma destas técnicas:

• Use o construtor BitmapImage(Uri) em vez do construtor padrão. Embora seja um construtor, você pode pensar nisso como tendo um comportamento assíncrono implícito: o BitmapImage não estará pronto para uso até que ele gere um evento ImageOpened que indique uma operação de conjunto de origem assíncrona bem-sucedida.
• Defina a propriedade UriSource . Assim como acontece com o uso do construtor Uri , essa ação é implicitamente assíncrona e a BitmapImage não estará pronta para uso até gerar um evento ImageOpened .
• Use SetSourceAsync. Esse método é explicitamente assíncrono. As propriedades em que você pode usar um BitmapImage, como Image.Source, foram projetadas para esse comportamento assíncrono e não gerarão exceções se forem definidas usando um BitmapImage que ainda não tenha uma fonte completa. Em vez de lidar com exceções, você deve manipular eventos ImageOpened ou ImageFailed diretamente no BitmapImage ou no controle que usa a origem (se esses eventos estiverem disponíveis na classe de controle).

ImageFailed e ImageOpened são mutuamente exclusivos. Um evento ou outro sempre será gerado sempre que um objeto BitmapImage tiver seu valor de origem definido ou redefinido.

BitmapImage e codificação

O suporte de codec subjacente para arquivos de imagem é fornecido pela API wic (componente de imagem do Windows) no Windows. Para obter mais informações sobre formatos de imagem específicos, conforme documentado para os codecs, consulte Codecs wic nativos. Para obter mais informações sobre formatos e como usar o URI (Uniform Resource Identifier) para acessar arquivos de origem de imagem provenientes de recursos de aplicativo, consulte Image e ImageBrush.

A API para Imagem, BitmapImage e BitmapSource não inclui 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 internas e irão, no máximo, trazer à tona aspectos de codificação e decodificação como parte dos dados de 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 de imagem ou manipulação, você deve usar a API que está disponível no namespace Windows.Graphics.Imaging . Essa API de geração de imagens pode ser usada por um aplicativo UWP usando C++, C#ou Visual Basic ou aplicativo do Windows usando JavaScript. Essas APIs também são compatíveis com o componente WIC (Componente de Imagem do Windows) do Windows 8.

Imagens animadas

A partir do Windows 10, versão 1607, o elemento Imagem XAML dá suporte a imagens GIF animadas. Ao usar um BitmapImage como a imagem Fonte, você pode acessar a API BitmapImage para controlar a reprodução da imagem GIF animada.

• Use a propriedade AutoPlay , que usa como padrão true, para especificar se um bitmap animado será reproduzido assim que ele for carregado ou não.
• Use a propriedade IsAnimatedBitmap para marcar se um bitmap é animado.
• Use a propriedade IsPlaying junto com os métodos Play e Stop para controlar a reprodução de um bitmap animado.

Observação

Para a maioria dos aplicativos, recomendamos que você defina AutoPlay como false se UISettings.AnimationsEnabled for false, para dar suporte às necessidades de acessibilidade dos usuários. Não faça isso se o conteúdo do GIF animado for importante para a usabilidade do seu aplicativo.

Se seu aplicativo for executado em versões do Windows 10 anteriores à versão 1607, você deverá usar a classe ApiInformation para marcar para a presença desses membros antes de usá-los. Para obter mais informações, consulte Código adaptável de versão: usar novas APIs enquanto mantém a compatibilidade com versões anteriores.

Este exemplo mostra como usar um GIF animado. Um botão permite que o usuário inicie ou interrompa a animação. Este exemplo usa código adaptável de versão para que possa ser executado em todas as versões do Windows 10. Em versões anteriores à versão 1607, o primeiro quadro do GIF é mostrado, mas não é animado.

<Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
    <Image Loaded="Image_Loaded">
        <Image.Source>
            <BitmapImage x:Name="imageSource"
                         UriSource="Assets/example.gif"
                         ImageOpened="imageSource_ImageOpened"/>
        </Image.Source>
    </Image>

    <AppBarButton x:Name="playButton"
              Icon="Play"
              Visibility="Collapsed"
              Click="playButton_Click"/>
</Grid>

// Set the AutoPlay property.
private void Image_Loaded(object sender, RoutedEventArgs e)
{
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "AutoPlay") == true)
    {
        imageSource.AutoPlay = false;
    }
}

// Show the play/stop button if the image is animated.
private void imageSource_ImageOpened(object sender, RoutedEventArgs e)
{
    var bitmapImage = (BitmapImage)sender;
    // At this point you can query whether the image is animated or not.
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "IsAnimatedBitmap") 
        && bitmapImage.IsAnimatedBitmap == true)
    {
        // Enable the play button
        playButton.Visibility = Visibility.Visible;
    }
}

// Play or stop the animated bitmap.
void playButton_Click(object sender, RoutedEventArgs e)
{
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "IsPlaying"))
    {
        // You can call the Play and Stop methods safely because is the IsPlaying property is
        // present, these methods are also present.
        if (imageSource.IsPlaying == true)
        {
            playButton.Icon = new SymbolIcon(Symbol.Play);
            imageSource.Stop();
        }
        else
        {
            playButton.Icon = new SymbolIcon(Symbol.Stop);
            imageSource.Play();
        }
    }
}

Para obter mais exemplos, consulte o exemplo de reprodução de GIF animado.

Histórico de versão

Versão do Windows	Versão do SDK	Valor adicionado
1607	14393	Reprodução Automática
1607	14393	IsAnimatedBitmap
1607	14393	IsPlaying
1607	14393	Reproduzir
1607	14393	Stop

Construtores

BitmapImage()	Inicializa uma nova instância da classe BitmapImage .
BitmapImage(Uri)	Inicializa uma nova instância da classe BitmapImage , usando o URI (Uniform Resource Identifier) fornecido.

Propriedades

AutoPlay	Obtém ou define um valor que indica se uma imagem animada deve ser reproduzida assim que for carregada.
AutoPlayProperty	Identifica a propriedade de dependência de Reprodução Automática .
CreateOptions	Obtém ou define o BitmapCreateOptions para um BitmapImage.
CreateOptionsProperty	Identifica a propriedade de dependência CreateOptions .
DecodePixelHeight	Obtém ou define a altura a ser usada para operações de decodificação de imagem.
DecodePixelHeightProperty	Identifica a propriedade de dependência DecodePixelHeight .
DecodePixelType	Obtém ou define um valor que determina como os valores DecodePixelWidth e DecodePixelHeight são interpretados para operações de decodificação.
DecodePixelTypeProperty	Identifica a propriedade de dependência DecodePixelType .
DecodePixelWidth	Obtém ou define a largura a ser usada para operações de decodificação de imagem.
DecodePixelWidthProperty	Identifica a propriedade de dependência DecodePixelWidth .
Dispatcher	Obtém o CoreDispatcher ao qual esse objeto está associado. O CoreDispatcher representa uma instalação que pode acessar o DependencyObject no thread da interface do usuário, mesmo que o código seja iniciado por um thread que não seja da interface do usuário. (Herdado de DependencyObject)
IsAnimatedBitmap	Obtém um valor que indica se uma imagem é animada.
IsAnimatedBitmapProperty	Identifica a propriedade de dependência IsAnimatedBitmap .
IsPlaying	Obtém um valor que indica se uma imagem animada está sendo reproduzida.
IsPlayingProperty	Identifica a propriedade de dependência IsPlaying .
PixelHeight	Obtém a altura do bitmap em pixels. (Herdado de BitmapSource)
PixelWidth	Obtém a largura do bitmap em pixels. (Herdado de BitmapSource)
UriSource	Obtém ou define o URI (Uniform Resource Identifier) do arquivo de origem gráfico que gerou esse BitmapImage.
UriSourceProperty	Identifica a propriedade de dependência UriSource .

Métodos

ClearValue(DependencyProperty)	Limpa o valor local de uma propriedade de dependência. (Herdado de DependencyObject)
GetAnimationBaseValue(DependencyProperty)	Retorna qualquer valor base estabelecido para uma propriedade de dependência, que se aplicaria nos casos em que uma animação não está ativa. (Herdado de DependencyObject)
GetValue(DependencyProperty)	Retorna o valor efetivo atual de uma propriedade de dependência de um DependencyObject. (Herdado de DependencyObject)
Play()	Inicia a animação de uma imagem animada.
ReadLocalValue(DependencyProperty)	Retorna o valor local de uma propriedade de dependência, se um valor local for definido. (Herdado de DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registra uma função de notificação para escutar alterações em uma DependencyProperty específica nessa instância dependencyObject . (Herdado de DependencyObject)
SetSource(IRandomAccessStream)	Define a imagem de origem de um BitmapSource acessando um fluxo. Em vez disso, a maioria dos chamadores deve usar SetSourceAsync . (Herdado de BitmapSource)
SetSourceAsync(IRandomAccessStream)	Define a imagem de origem para um BitmapSource acessando um fluxo e processando o resultado de forma assíncrona. (Herdado de BitmapSource)
SetValue(DependencyProperty, Object)	Define o valor local de uma propriedade de dependência em um DependencyObject. (Herdado de DependencyObject)
Stop()	Encerra a animação de uma imagem animada.
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Cancela uma notificação de alteração que foi registrada anteriormente chamando RegisterPropertyChangedCallback. (Herdado de DependencyObject)

Eventos

DownloadProgress	Ocorre quando ocorreu uma alteração significativa no progresso do download do conteúdo bitmapImage .
ImageFailed	Ocorre quando há um erro associado à recuperação ou ao formato da imagem.
ImageOpened	Ocorre quando a origem da imagem é baixada e decodificada sem falha. Você pode usar esse evento para determinar o tamanho de uma imagem antes de renderizá-la.

Confira também

• Image
• BitmapSource
• Source
• ImageSource
• Image e ImageBrush
• Exemplo de reprodução de GIF animado (XAML)