BitmapImage 類別

參考

定義

命名空間:: Microsoft.UI.Xaml.Media.Imaging

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

編輯

提供 Image.Source 和 ImageBrush.ImageSource 屬性的實際物件來源類型。您可以使用參考影像來源檔案的統一資源識別項 (URI) ，或呼叫 SetSourceAsync 並提供資料流程，來定義 BitmapImage。

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

繼承: Object Platform::Object IInspectable DependencyObject ImageSource BitmapSource BitmapImage

屬性: ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

範例

以下是使用 BitmapImage 物件在 C# 中設定 Image.Source 的範例。在此範例中， Image 物件是在 XAML 中建立，但沒有來源或任何其他屬性值;而是在從 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;
}

備註

BitmapImage 可以從下列影像檔案格式取得：

JPEG 格式 (JPEG)
可攜式網路圖形 (PNG)
點陣圖 (BMP)
圖形交換格式 (GIF)
標記的影像檔案格式 (TIFF)
JPEG XR
圖示 (ICO)

如果影像來源是資料流程，該資料流程預期會以下列其中一種格式包含影像檔。

BitmapImage 類別代表抽象概念，以便以非同步方式設定影像來源，但仍可在 XAML 標記中參考為屬性值，或在程式碼中作為不使用可等候語法的物件。當您在程式碼中建立 BitmapImage 物件時，它一開始沒有有效的來源。然後，您應該使用下列其中一種技術來設定其來源：

使用 BitmapImage (Uri) 建構函式，而不是預設建構函式。雖然它是建構函式，但您可以將它視為具有隱含非同步行為：BitmapImage 在引發 ImageOpened 事件，指出成功非同步來源集作業之前，BitmapImage 將無法使用。
設定 UriSource 屬性。如同使用 Uri 建構函式一樣，此動作是隱含非同步，而且 BitmapImage 在引發 ImageOpened 事件之前將無法使用。
使用 SetSourceAsync。這個方法是明確非同步。您可以使用 Image.Source等 BitmapImage 的屬性是針對這個非同步行為所設計，而且如果使用尚未完整來源的 BitmapImage 設定，則不會擲回例外狀況。您應該直接處理 BitmapImage 上的 ImageOpened 或 ImageFailed 事件，或是直接在控制項類別上使用來源 (的控制項上處理 ImageOpened 或 ImageFailed 事件) 。

ImageFailed 和 ImageOpened 互斥。每當 BitmapImage 物件已設定或重設其來源值時，一律會引發一個事件或另一個事件。

BitmapImage 和編碼

Windows 映像處理元件 (WIC) API 提供映射檔的基礎編解碼器支援。如需針對編解碼器記載的特定影像格式詳細資訊，請參閱原生 WIC 編解碼器。如需格式的詳細資訊，以及如何使用統一資源識別項 (URI) 來存取來自應用程式資源的影像來源檔案，請參閱 Image 和 ImageBrush。

Image、BitmapImage 和BitmapSource的 API 不包含用於編碼和解碼媒體格式的任何專用方法。所有編碼及解碼作業都是內建作業，最多只會將編碼或解碼的各個層面呈現為載入事件的部分事件資料。如果您想要對影像編碼或解碼執行任何特殊工作，如果應用程式正在執行影像轉換或操作，您應該使用 Windows.Graphics.Imaging 命名空間中可用的 API。您可以使用 C++、C# 或 Visual Basic 或 Visual Basic 或 Windows 應用程式，使用 JavaScript 的 UWP 應用程式使用這些映射 API。 Windows 映像處理元件 (WINDOWS 8 的 WIC) 元件也支援這些 API。

動畫影像

從 Windows 10 1607 版開始，XAML Image元素支援動畫 GIF 影像。當您使用 BitmapImage 做為影像來源時，您可以存取 BitmapImage API 來控制動畫 GIF 影像的播放。

使用預設為true的AutoPlay屬性，指定動畫點陣圖在載入時是否播放。
使用 IsAnimatedBitmap 屬性來檢查點陣圖是否為動畫。
使用 IsPlaying 屬性以及 Play 和 Stop 方法來控制動畫點陣圖的播放。

注意

對於大部分的應用程式，建議您在UISettings.AnimationsEnabled為false時將AutoPlay設定為false，以支援使用者的協助工具需求。如果動畫 GIF 的內容對於應用程式的可用性很重要，請勿這麼做。

如果您的應用程式在 1607 版之前的 Windows 10 版本上執行，您必須使用ApiInformation類別來檢查這些成員是否存在，才能使用這些成員。如需詳細資訊，請參閱版本調適型程式碼：使用新的 API，同時維持與舊版的相容性。

此範例示範如何使用動畫 GIF。按鈕可讓使用者啟動或停止動畫。此範例會使用版本調適型程式碼，以便在所有版本的 Windows 10上執行。在 1607 版之前的版本中，會顯示 GIF 的第一個畫面格，但不會以動畫顯示。

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

如需更多範例，請參閱動畫 GIF 播放範例。

建構函式

BitmapImage()	初始化 BitmapImage 類別的新實例。
BitmapImage(Uri)	使用提供的統一資源識別項 (URI) ，初始化 BitmapImage 類別的新實例。

屬性

AutoPlay	取得或設定值，這個值表示動畫影像是否應該在載入時立即播放。
AutoPlayProperty	識別 AutoPlay 相依性屬性。
CreateOptions	取得或設定BitmapImage的BitmapCreateOptions。
CreateOptionsProperty	識別 CreateOptions 相依性屬性。
DecodePixelHeight	取得或設定用於影像解碼作業的高度。
DecodePixelHeightProperty	識別 DecodePixelHeight 相依性屬性。
DecodePixelType	取得或設定值，決定解碼作業的 DecodePixelWidth 和 DecodePixelHeight 值如何解譯。
DecodePixelTypeProperty	識別 DecodePixelType 相依性屬性。
DecodePixelWidth	取得或設定要用於影像解碼作業的寬度。
DecodePixelWidthProperty	識別 DecodePixelWidth 相依性屬性。
Dispatcher	一律會在 `null` Windows 應用程式 SDK應用程式中傳回。請改用 DispatcherQueue 。 (繼承來源 DependencyObject)
DispatcherQueue	`DispatcherQueue`取得與這個物件相關聯的。 `DispatcherQueue`表示即使程式碼是由非 UI 執行緒起始，也可以存取 `DependencyObject` UI 執行緒上的。 (繼承來源 DependencyObject)
IsAnimatedBitmap	取得值，這個值表示影像是否為動畫。
IsAnimatedBitmapProperty	識別 IsAnimatedBitmap 相依性屬性。
IsPlaying	取得值，指出動畫影像是否現正播放。
IsPlayingProperty	識別 IsPlaying 相依性屬性。
PixelHeight	取得點陣圖的高度 (以像素為單位)。 (繼承來源 BitmapSource)
PixelWidth	取得點陣圖的寬度 (以像素為單位)。 (繼承來源 BitmapSource)
UriSource	取得或設定產生此 BitmapImage之圖形來源檔案的統一資源識別項 (URI) 。
UriSourceProperty	識別 UriSource 相依性屬性。

方法

ClearValue(DependencyProperty)	清除相依性屬性的本機值。 (繼承來源 DependencyObject)
GetAnimationBaseValue(DependencyProperty)	傳回針對相依性屬性所建立的任何基底值，如果動畫未使用中，則會套用。 (繼承來源 DependencyObject)
GetValue(DependencyProperty)	從 DependencyObject傳回相依性屬性的目前有效值。 (繼承來源 DependencyObject)
Play()	啟動動畫影像的動畫。
ReadLocalValue(DependencyProperty)	如果已設定本機值，則傳回相依性屬性的本機值。 (繼承來源 DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	註冊通知函式，以接聽此DependencyObject實例上特定DependencyProperty的變更。 (繼承來源 DependencyObject)
SetSource(IRandomAccessStream)	藉由存取資料流程來設定 BitmapSource 的來源影像。大部分呼叫端都應該改用 SetSourceAsync 。 (繼承來源 BitmapSource)
SetSourceAsync(IRandomAccessStream)	藉由存取資料流程並以非同步方式處理結果，來設定 BitmapSource 的來源影像。 (繼承來源 BitmapSource)
SetValue(DependencyProperty, Object)	在 DependencyObject上設定相依性屬性的本機值。 (繼承來源 DependencyObject)
Stop()	結束動畫影像的動畫。
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	取消先前透過呼叫 RegisterPropertyChangedCallback註冊的變更通知。 (繼承來源 DependencyObject)

事件

DownloadProgress	發生于 BitmapImage 內容的下載進度發生重大變更時。
ImageFailed	發生于與影像擷取或格式相關聯的錯誤時。
ImageOpened	發生于下載並解碼影像來源時，不會失敗。您可以在轉譯影像之前，使用此事件來判斷影像的大小。

適用於

共用方式為

BitmapImage 類別

定義

範例

備註

BitmapImage 和編碼

動畫影像

建構函式

屬性

方法

事件

適用於

另請參閱

意見反應

其他資源