BitmapImage Classe

Riferimento

Definizione

Spazio dei nomi:: Microsoft.UI.Xaml.Media.Imaging

Importante

Alcune informazioni sono relative alla release non definitiva del prodotto, che potrebbe subire modifiche significative prima della release definitiva. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Modifica

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.Activatable(65536, "Microsoft.UI.Xaml.WinUIContract")]
/// [Windows.Foundation.Metadata.Activatable(Microsoft.UI.Xaml.Media.Imaging.IBitmapImageFactory, 65536, "Microsoft.UI.Xaml.WinUIContract")]
/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class BitmapImage final : BitmapSource

[Windows.Foundation.Metadata.Activatable(65536, "Microsoft.UI.Xaml.WinUIContract")]
[Windows.Foundation.Metadata.Activatable(typeof(Microsoft.UI.Xaml.Media.Imaging.IBitmapImageFactory), 65536, "Microsoft.UI.Xaml.WinUIContract")]
[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
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

Esempio

Ecco un esempio di utilizzo 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 oggetto BitmapImage può essere originato 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 ancora fatto riferimento nel markup XAML come valore di proprietà o nel codice come oggetto che non usa la sintassi awaitable. Quando si crea un oggetto BitmapImage nel codice, inizialmente non ha un'origine valida. È quindi consigliabile impostarne l'origine usando una di queste tecniche:

Usare il costruttore BitmapImage(Uri) anziché il costruttore predefinito. Anche se si tratta di un costruttore che può essere considerato come un comportamento asincrono implicito: BitmapImage non sarà pronto per l'uso fino a quando 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 è in modo esplicito asincrono. Le proprietà in cui è possibile usare bitmapImage, ad esempio Image.Source, sono progettate per questo comportamento asincrono e non generano eccezioni se sono impostate usando un'immagine Bitmap che non ha ancora un'origine completa. Invece di gestire le eccezioni, è consigliabile gestire gli eventi ImageOpened o ImageFailed direttamente in BitmapImage o nel controllo che usa l'origine (se tali eventi sono disponibili nella classe del controllo).

ImageFailed e ImageOpened si escludono a vicenda. Un evento o l'altro verrà sempre generato ogni volta che un oggetto BitmapImage ha il 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, vedi Codec WIC nativi. Per altre info sui formati e su come usare l'URI (Uniform Resource Identifier) per accedere ai file di origine delle immagini provenienti dalle risorse dell'app, vedi Image e 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 vuoi eseguire operazioni speciali con codifica o decodifica delle immagini, che puoi usare se la tua app esegue conversioni o manipolazioni di immagini, devi usare l'API disponibile nello spazio dei nomi Windows.Graphics.Imaging . Queste API per la creazione di immagini possono essere usate dall'app UWP usando C++, C#, Visual Basic o l'app Windows con 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 dell'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 eseguire questa operazione se il contenuto della GIF animata è importante per l'usabilità dell'app.

Se la tua app viene eseguita nelle versioni di Windows 10 precedenti alla versione 1607, devi usare la classe ApiInformation per verificare la presenza di questi membri prima di usarli. Per altre info, vedi Codice adattivo della versione: usare le 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. Questo esempio usa 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 visualizzato il primo fotogramma della GIF, ma non è animato.

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

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 utilizzare per le operazioni di decodifica delle immagini.
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 utilizzare per le operazioni di decodifica delle immagini.
DecodePixelWidthProperty	Identifica la proprietà di dipendenza DecodePixelWidth .
Dispatcher	Restituisce `null` sempre in un'app Windows App SDK. Usare invece DispatcherQueue . (Ereditato da DependencyObject)
DispatcherQueue	Ottiene l'oggetto a cui è associato l'oggetto `DispatcherQueue` . `DispatcherQueue` Rappresenta una funzionalità che può accedere a nel thread dell'interfaccia `DependencyObject` utente anche se il codice viene avviato da un thread non dell'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 è in riproduzione 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 dependencyObject. (Ereditato da DependencyObject)
Play()	Avvia l'animazione di un'immagine animata.
ReadLocalValue(DependencyProperty)	Restituisce il valore locale di una proprietà di dipendenza, se è impostato un valore locale. (Ereditato da DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registra una funzione di notifica per l'ascolto delle modifiche apportate a una dipendenza specifica in questa istanza di DependencyObject . (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 su 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.

Si applica a