BitmapImage Klasse

Definition

Namespace:

Windows.UI.Xaml.Media.Imaging

Stellt den praktischen Objektquelltyp für die Eigenschaften Image.Source und ImageBrush.ImageSource bereit . Sie können ein BitmapImage definieren, indem Sie einen URI (Uniform Resource Identifier) verwenden, der auf eine Bildquelldatei verweist, oder indem Sie SetSourceAsync aufrufen und einen Stream bereitstellen.

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

Vererbung

Object Platform::Object IInspectable DependencyObject ImageSource BitmapSource BitmapImage

Attribute

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows-Anforderungen

Gerätefamilie	Windows 10 (eingeführt in 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (eingeführt in v1.0)

Beispiele

Hier sehen Sie ein Beispiel für die Verwendung eines BitmapImage-Objekts zum Festlegen von Image.Source in C#. In diesem Beispiel wurde das Image-Objekt in XAML erstellt, verfügt aber nicht über eine Quelle oder andere Eigenschaftswerte. Stattdessen werden diese Werte zur Laufzeit bereitgestellt, wenn das Image aus XAML geladen wird.

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

Hinweise

Ein BitmapImage kann aus den folgenden Bilddateiformaten stammen:

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

Wenn es sich bei der Bildquelle um einen Stream handelt, wird erwartet, dass dieser Stream eine Bilddatei in einem dieser Formate enthält.

Die BitmapImage-Klasse stellt eine Abstraktion dar, sodass eine Bildquelle asynchron festgelegt werden kann, aber dennoch im XAML-Markup als Eigenschaftswert oder im Code als Objekt verwiesen werden kann, das keine erwartbare Syntax verwendet. Wenn Sie ein BitmapImage-Objekt im Code erstellen, verfügt es zunächst über keine gültige Quelle. Anschließend sollten Sie die Quelle mit einer der folgenden Techniken festlegen:

• Verwenden Sie den BitmapImage(Uri)- Konstruktor anstelle des Standardkonstruktors. Obwohl es sich um einen Konstruktor handelt, können Sie sich dies als implizites asynchrones Verhalten vorstellen: BitmapImage ist erst einsatzbereit, wenn es ein ImageOpened-Ereignis auslöst, das auf einen erfolgreichen asynchronen Quellsatzvorgang hinweist.
• Legen Sie die UriSource-Eigenschaft fest. Wie bei der Verwendung des URI-Konstruktors ist diese Aktion implizit asynchron, und BitmapImage ist erst einsatzbereit, wenn ein ImageOpened-Ereignis ausgelöst wird .
• Verwenden Sie SetSourceAsync. Diese Methode ist explizit asynchron. Die Eigenschaften, in denen Sie ein BitmapImage verwenden können, z . B. Image.Source, sind für dieses asynchrone Verhalten konzipiert und lösen keine Ausnahmen aus, wenn sie mit einem BitmapImage festgelegt werden, das noch keine vollständige Quelle hat. Anstatt Ausnahmen zu behandeln, sollten Sie ImageOpened - oder ImageFailed-Ereignisse entweder direkt für BitmapImage oder für das Steuerelement behandeln, das die Quelle verwendet (wenn diese Ereignisse für die Steuerelementklasse verfügbar sind).

ImageFailed und ImageOpened schließen sich gegenseitig aus. Das eine oder andere Ereignis wird immer ausgelöst, wenn für ein BitmapImage-Objekt der Quellwert festgelegt oder zurückgesetzt wird.

BitmapImage und Codierung

Die zugrunde liegende Codecunterstützung für Bilddateien wird von der WIC-API (Windows Imaging Component) in Windows bereitgestellt. Weitere Informationen zu bestimmten Bildformaten, die für die Codecs dokumentiert sind, finden Sie unter Native WIC-Codecs. Weitere Informationen zu Formaten und zur Verwendung des URI (Uniform Resource Identifier) für den Zugriff auf Bildquelldateien, die aus App-Ressourcen stammen, finden Sie unter Image und ImageBrush.

Die API für Image, BitmapImage und BitmapSource enthält keine dedizierten Methoden zum Codieren und Decodieren von Medienformaten. Sämtliche Codier- und Decodiervorgänge sind integriert. Aspekte dieser Vorgänge sind auf der Oberfläche allenfalls als Bestandteil von Ereignisdaten für Load-Ereignisse sichtbar. Wenn Sie spezielle Aufgaben mit der Bildcodierung oder -decodierung ausführen möchten, die Sie möglicherweise verwenden können, wenn Ihre App Bildkonvertierungen oder -manipulationen durchführt, sollten Sie die API verwenden, die im Windows.Graphics.Imaging-Namespace verfügbar ist. Diese Imageerstellungs-API kann entweder von UWP-Apps mit C++, C#, Visual Basic oder Windows-App mit JavaScript verwendet werden. Diese APIs werden auch von der WIC-Komponente (Windows Imaging Component) von Windows 8 unterstützt.

Animierte Bilder

Ab Windows 10 Version 1607 unterstützt das XAML Image-Element animierte GIF-Bilder. Wenn Sie ein BitmapImage als Bildquelle verwenden, können Sie auf die BitmapImage-API zugreifen, um die Wiedergabe des animierten GIF-Bilds zu steuern.

• Verwenden Sie die AutoPlay-Eigenschaft , die standardmäßig auf true festgelegt ist, um anzugeben, ob eine animierte Bitmap beim Laden wiedergegeben wird.
• Verwenden Sie die IsAnimatedBitmap-Eigenschaft , um zu überprüfen, ob eine Bitmap animiert ist.
• Verwenden Sie die IsPlaying-Eigenschaft zusammen mit den Play- und Stop-Methoden, um die Wiedergabe einer animierten Bitmap zu steuern.

Hinweis

Für die meisten Apps wird empfohlen, autoPlay auf false festzulegen, wenn UISettings.AnimationEnabledauf false festgelegt ist, um die Barrierefreiheitsanforderungen von Benutzern zu unterstützen. Tun Sie dies nicht, wenn der Inhalt des animierten GIF für die Benutzerfreundlichkeit Ihrer App wichtig ist.

Wenn Ihre App in Releases von Windows 10 vor Version 1607 ausgeführt wird, müssen Sie die ApiInformation-Klasse verwenden, um zu überprüfen, ob diese Member vorhanden sind, bevor Sie sie verwenden. Weitere Informationen finden Sie unter Versionsadaptiver Code: Verwenden neuer APIs unter Beibehaltung der Kompatibilität mit früheren Versionen.

In diesem Beispiel wird gezeigt, wie ein animiertes GIF verwendet wird. Mit einer Schaltfläche kann der Benutzer die Animation starten oder beenden. In diesem Beispiel wird versionsadaptiven Code verwendet, damit er in allen Versionen von Windows 10 ausgeführt werden kann. In Versionen vor Version 1607 wird der erste Frame des GIF angezeigt, jedoch nicht animiert.

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

Weitere Beispiele finden Sie im Beispiel für die Animierte GIF-Wiedergabe.

Versionsverlauf

Windows-Version	SDK-Version	Mehrwert
1607	14393	Automatische Wiedergabe
1607	14393	IsAnimatedBitmap
1607	14393	IsPlaying
1607	14393	Abspielen
1607	14393	Beenden

Konstruktoren

BitmapImage()	Initialisiert eine neue instance der BitmapImage-Klasse.
BitmapImage(Uri)	Initialisiert eine neue instance der BitmapImage-Klasse unter Verwendung des angegebenen URI (Uniform Resource Identifier).

Eigenschaften

AutoPlay	Ruft einen Wert ab, der angibt, ob ein animiertes Bild wiedergegeben werden soll, sobald es geladen wird, oder legt diesen fest.
AutoPlayProperty	Gibt die Abhängigkeitseigenschaft AutoPlay an.
CreateOptions	Ruft bitmapCreateOptions für ein BitmapImage ab oder legt diese fest.
CreateOptionsProperty	Identifiziert die CreateOptions-Abhängigkeitseigenschaft .
DecodePixelHeight	Ruft die Höhe ab, die für Bilddecodierungsvorgänge verwendet werden soll, oder legt sie fest.
DecodePixelHeightProperty	Identifiziert die DecodePixelHeight-Abhängigkeitseigenschaft .
DecodePixelType	Ruft einen Wert ab, der bestimmt, wie die Werte DecodePixelWidth und DecodePixelHeight für Decodierungsvorgänge interpretiert werden, oder legt diesen fest.
DecodePixelTypeProperty	Identifiziert die DecodePixelType-Abhängigkeitseigenschaft .
DecodePixelWidth	Ruft die Breite ab, die für Bilddecodierungsvorgänge verwendet werden soll, oder legt sie fest.
DecodePixelWidthProperty	Identifiziert die DecodePixelWidth-Abhängigkeitseigenschaft .
Dispatcher	Ruft den CoreDispatcher ab, dem dieses Objekt zugeordnet ist. CoreDispatcher stellt eine Funktion dar, die auf das DependencyObject im UI-Thread zugreifen kann, auch wenn der Code von einem Nicht-UI-Thread initiiert wird. (Geerbt von DependencyObject)
IsAnimatedBitmap	Ruft einen Wert ab, der angibt, ob ein Bild animiert wird.
IsAnimatedBitmapProperty	Identifiziert die IsAnimatedBitmap-Abhängigkeitseigenschaft .
IsPlaying	Ruft einen Wert ab, der angibt, ob ein animiertes Bild wiedergegeben wird.
IsPlayingProperty	Identifiziert die IsPlaying-Abhängigkeitseigenschaft .
PixelHeight	Ruft die Höhe der Bitmap in Pixeln ab. (Geerbt von BitmapSource)
PixelWidth	Ruft die Breite der Bitmap in Pixeln ab. (Geerbt von BitmapSource)
UriSource	Ruft den URI (Uniform Resource Identifier) der Grafikquelldatei ab, die dieses BitmapImage generiert hat, oder legt diesen fest.
UriSourceProperty	Identifiziert die UriSource-Abhängigkeitseigenschaft .

Methoden

ClearValue(DependencyProperty)	Löscht den lokalen Wert einer Abhängigkeitseigenschaft. (Geerbt von DependencyObject)
GetAnimationBaseValue(DependencyProperty)	Gibt einen beliebigen Basiswert zurück, der für eine Abhängigkeitseigenschaft eingerichtet wurde, der in Fällen gilt, in denen eine Animation nicht aktiv ist. (Geerbt von DependencyObject)
GetValue(DependencyProperty)	Gibt den aktuellen effektiven Wert einer Abhängigkeitseigenschaft aus einem DependencyObject zurück. (Geerbt von DependencyObject)
Play()	Startet die Animation eines animierten Bilds.
ReadLocalValue(DependencyProperty)	Gibt den lokalen Wert einer Abhängigkeitseigenschaft zurück, wenn ein lokaler Wert festgelegt ist. (Geerbt von DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registriert eine Benachrichtigungsfunktion zum Lauschen auf Änderungen an einer bestimmten DependencyProperty für dieses DependencyObject-instance. (Geerbt von DependencyObject)
SetSource(IRandomAccessStream)	Legt das Quellbild für eine BitmapSource durch Zugriff auf einen Stream fest. Die meisten Aufrufer sollten stattdessen SetSourceAsync verwenden. (Geerbt von BitmapSource)
SetSourceAsync(IRandomAccessStream)	Legt das Quellbild für eine BitmapSource fest, indem auf einen Stream zugegriffen und das Ergebnis asynchron verarbeitet wird. (Geerbt von BitmapSource)
SetValue(DependencyProperty, Object)	Legt den lokalen Wert einer Abhängigkeitseigenschaft für ein DependencyObject fest. (Geerbt von DependencyObject)
Stop()	Beendet die Animation eines animierten Bilds.
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Bricht eine Änderungsbenachrichtigung ab, die zuvor durch Aufrufen von RegisterPropertyChangedCallback registriert wurde. (Geerbt von DependencyObject)

Ereignisse

DownloadProgress	Tritt auf, wenn eine erhebliche Änderung am Downloadstatus des BitmapImage-Inhalts aufgetreten ist.
ImageFailed	Tritt auf, wenn ein Fehler im Zusammenhang mit dem Bildabruf oder -format auftritt.
ImageOpened	Tritt auf, wenn die Imagequelle heruntergeladen und ohne Fehler decodiert wird. Sie können dieses Ereignis verwenden, um die Größe eines Bilds vor dem Rendern zu bestimmen.

Weitere Informationen

• Image
• BitmapSource
• Source
• ImageSource
• Image und ImageBrush
• Beispiel für animierte GIF-Wiedergabe (XAML)