BitmapImage Classe

Definizione

Spazio dei nomi:

Windows.UI.Xaml.Media.Imaging

Fornisce il tipo di origine oggetto pratico per le proprietà Image.Source e ImageBrush.ImageSource . È possibile definire un oggetto BitmapImage usando un URI (Uniform Resource Identifier) che fa riferimento a un file di origine dell'immagine o chiamando SetSourceAsync e fornendo un flusso.

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 .../>

Ereditarietà

Object Platform::Object IInspectable DependencyObject ImageSource BitmapSource BitmapImage

Attributi

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Requisiti Windows

Famiglia di dispositivi	Windows 10 (è stato introdotto in 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (è stato introdotto in v1.0)

Esempio

Ecco un esempio di uso di un oggetto BitmapImage per impostare Image.Source in C#. In questo esempio l'oggetto Image è stato creato in XAML, ma non ha un'origine o altri valori di proprietà; Questi valori vengono invece forniti in fase di esecuzione quando l'immagine viene caricata da 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;
}

Commenti

Un'immagine BitmapImage può essere generata da questi formati di file di immagine:

• Joint Photographic Experts Group (JPEG)
• Portable Network Graphics (PNG)
• bitmap (BMP)
• Graphics Interchange Format (GIF)
• Tagged Image File Format (TIFF)
• JPEG XR
• icone (ICO)

Se l'origine dell'immagine è un flusso, tale flusso deve contenere un file di immagine in uno di questi formati.

La classe BitmapImage rappresenta un'astrazione in modo che un'origine immagine possa essere impostata in modo asincrono, ma che venga comunque fatto riferimento al markup XAML come valore della proprietà o nel codice come oggetto che non usa la sintassi attendabile. Quando si crea un oggetto BitmapImage nel codice, inizialmente non ha alcuna origine valida. È quindi consigliabile impostare l'origine usando una di queste tecniche:

• Usare il costruttore BitmapImage(Uri) anziché il costruttore predefinito. Anche se è un costruttore che può essere pensato come avere un comportamento asincrono implicito: BitmapImage non sarà pronto per l'uso finché non genera un evento ImageOpened che indica un'operazione del set di origine asincrona riuscita.
• Impostare la proprietà UriSource . Come per l'uso del costruttore URI , questa azione è implicitamente asincrona e bitmapImage non sarà pronta per l'uso finché non genera un evento ImageOpened .
• Usare SetSourceAsync. Questo metodo è asincrono in modo esplicito. Le proprietà in cui è possibile usare bitmapImage, ad esempio Image.Source, sono progettate per questo comportamento asincrono e non genereranno eccezioni se vengono impostate usando un'immagine BitmapImage che non ha ancora un'origine completa. Anziché gestire le eccezioni, è consigliabile gestire gli eventi ImageOpened o ImageFailed direttamente sul controllo BitmapImage o sul controllo che usa l'origine (se tali eventi sono disponibili nella classe di controllo).

ImageFailed e ImageOpened si escludono a vicenda. Un evento o l'altro verrà sempre generato ogni volta che un oggetto BitmapImage ha il relativo valore di origine impostato o reimpostato.

BitmapImage e codifica

Il supporto del codec sottostante per i file di immagine viene fornito dall'API Windows Imaging Component (WIC) in Windows. Per altre informazioni sui formati di immagine specifici come documentato per i codec, vedere Codec WIC nativi. Per altre informazioni sui formati e su come usare Uniform Resource Identifier (URI) per accedere ai file di origine delle immagini provenienti dalle risorse dell'app, vedere Image and ImageBrush.

L'API per Image, BitmapImage e BitmapSource non include metodi dedicati per la codifica e la decodifica dei formati multimediali. Tutte le operazioni di codifica e decodifica sono incorporate e, al massimo, espongono aspetti della codifica o della decodifica nell'ambito dei dati degli eventi di caricamento. Se si desidera eseguire operazioni speciali con codifica o decodifica dell'immagine, che è possibile usare se l'app esegue conversioni o manipolazioni di immagini, è consigliabile usare l'API disponibile nello spazio dei nomi Windows.Graphics.Imaging . Queste API di imaging possono essere usate dall'app UWP usando C++, C#o Visual Basic o l'app Windows usando JavaScript. Queste API sono supportate anche dal componente Windows Imaging Component (WIC) di Windows 8.

Immagini animate

A partire da Windows 10 versione 1607, l'elemento Image XAML supporta immagini GIF animate. Quando si usa bitmapImage come origine immagine, è possibile accedere all'API BitmapImage per controllare la riproduzione dell'immagine GIF animata.

• Utilizzare la proprietà AutoPlay , che per impostazione predefinita è true, per specificare se una bitmap animata viene riprodotta non appena viene caricata.
• Utilizzare la proprietà IsAnimatedBitmap per verificare se una bitmap è animata.
• Utilizzare la proprietà IsPlaying insieme ai metodi Play e Stop per controllare la riproduzione di una bitmap animata.

Nota

Per la maggior parte delle app, è consigliabile impostare AutoPlay su false se UISettings.AnimationsEnabled è false, per supportare le esigenze di accessibilità degli utenti. Non farlo se il contenuto della GIF animata è importante per l'usabilità dell'app.

Se l'app viene eseguita nelle versioni di Windows 10 precedenti alla versione 1607, è necessario usare la classe ApiInformation per verificare la presenza di questi membri prima di usarli. Per altre informazioni, vedere Codice adattivo della versione: usare nuove API mantenendo la compatibilità con le versioni precedenti.

In questo esempio viene illustrato come usare una GIF animata. Un pulsante consente all'utente di avviare o arrestare l'animazione. In questo esempio viene usato il codice adattivo della versione in modo che possa essere eseguito in tutte le versioni di Windows 10. Nelle versioni precedenti alla versione 1607 viene visualizzata la prima cornice della GIF, ma non è animata.

<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();
        }
    }
}

Per altri esempi, vedi l'esempio di riproduzione GIF animata.

Cronologia delle versioni

Versione di Windows	Versione dell'SDK	Valore aggiunto
1607	14393	AutoPlay
1607	14393	IsAnimatedBitmap
1607	14393	IsPlaying
1607	14393	Esegui
1607	14393	Stop

Costruttori

BitmapImage()	Inizializza una nuova istanza della classe BitmapImage .
BitmapImage(Uri)	Inizializza una nuova istanza della classe BitmapImage usando l'URI (Uniform Resource Identifier) fornito.

Proprietà

AutoPlay	Ottiene o imposta un valore che indica se un'immagine animata deve essere riprodotta non appena viene caricata.
AutoPlayProperty	Identifica la proprietà di dipendenza AutoPlay .
CreateOptions	Ottiene o imposta bitmapCreateOptions per un oggetto BitmapImage.
CreateOptionsProperty	Identifica la proprietà di dipendenza CreateOptions .
DecodePixelHeight	Ottiene o imposta l'altezza da usare per le operazioni di decodifica dell'immagine.
DecodePixelHeightProperty	Identifica la proprietà di dipendenza DecodePixelHeight .
DecodePixelType	Ottiene o imposta un valore che determina il modo in cui i valori DecodePixelWidth e DecodePixelHeight vengono interpretati per le operazioni di decodifica.
DecodePixelTypeProperty	Identifica la proprietà di dipendenza DecodePixelType .
DecodePixelWidth	Ottiene o imposta la larghezza da usare per le operazioni di decodifica dell'immagine.
DecodePixelWidthProperty	Identifica la proprietà di dipendenza DecodePixelWidth .
Dispatcher	Ottiene CoreDispatcher associato a questo oggetto. CoreDispatcher rappresenta una struttura che può accedere a DependencyObject nel thread dell'interfaccia utente anche se il codice viene avviato da un thread non interfaccia utente. (Ereditato da DependencyObject)
IsAnimatedBitmap	Ottiene un valore che indica se un'immagine è animata.
IsAnimatedBitmapProperty	Identifica la proprietà di dipendenza IsAnimatedBitmap .
IsPlaying	Ottiene un valore che indica se viene riprodotta un'immagine animata.
IsPlayingProperty	Identifica la proprietà di dipendenza IsPlaying .
PixelHeight	Ottiene l'altezza della bitmap in pixel. (Ereditato da BitmapSource)
PixelWidth	Ottiene la larghezza della bitmap in pixel. (Ereditato da BitmapSource)
UriSource	Ottiene o imposta l'URI (Uniform Resource Identifier) del file di origine grafica che ha generato questa BitmapImage.
UriSourceProperty	Identifica la proprietà di dipendenza UriSource .

Metodi

ClearValue(DependencyProperty)	Cancella il valore locale di una proprietà di dipendenza. (Ereditato da DependencyObject)
GetAnimationBaseValue(DependencyProperty)	Restituisce qualsiasi valore di base stabilito per una proprietà di dipendenza, che si applica nei casi in cui un'animazione non è attiva. (Ereditato da DependencyObject)
GetValue(DependencyProperty)	Restituisce il valore effettivo corrente di una proprietà di dipendenza da un oggetto DependencyObject. (Ereditato da DependencyObject)
Play()	Avvia l'animazione di un'immagine animata.
ReadLocalValue(DependencyProperty)	Restituisce il valore locale di una proprietà di dipendenza, se viene impostato un valore locale. (Ereditato da DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registra una funzione di notifica per l'ascolto delle modifiche a un'istanza di DependencyObject specifica. (Ereditato da DependencyObject)
SetSource(IRandomAccessStream)	Imposta l'immagine di origine per bitmapSource accedendo a un flusso. La maggior parte dei chiamanti deve invece usare SetSourceAsync . (Ereditato da BitmapSource)
SetSourceAsync(IRandomAccessStream)	Imposta l'immagine di origine per bitmapSource accedendo a un flusso ed elaborando il risultato in modo asincrono. (Ereditato da BitmapSource)
SetValue(DependencyProperty, Object)	Imposta il valore locale di una proprietà di dipendenza in un oggetto DependencyObject. (Ereditato da DependencyObject)
Stop()	Termina l'animazione di un'immagine animata.
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Annulla una notifica di modifica registrata in precedenza chiamando RegisterPropertyChangedCallback. (Ereditato da DependencyObject)

Eventi

DownloadProgress	Si verifica quando si è verificata una modifica significativa nello stato di avanzamento del download del contenuto BitmapImage .
ImageFailed	Si verifica quando si verifica un errore associato al recupero o al formato dell'immagine.
ImageOpened	Si verifica quando l'origine dell'immagine viene scaricata e decodificata senza errori. È possibile usare questo evento per determinare le dimensioni di un'immagine prima di eseguire il rendering.

Vedi anche

• Image
• BitmapSource
• Source
• ImageSource
• Image e ImageBrush
• Esempio di riproduzione GIF animata (XAML)