BitmapImage 類別

定義

命名空間:

Windows.UI.Xaml.Media.Imaging

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

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

繼承

Object Platform::Object IInspectable DependencyObject ImageSource BitmapSource BitmapImage

屬性

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows 需求

裝置系列	Windows 10 (已於 10.0.10240.0 引進)
API contract	Windows.Foundation.UniversalApiContract (已於 v1.0 引進)

範例

以下是使用 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。 這個方法明確非同步。 您可以使用 BitmapImage 的屬性，例如 Image.Source，是針對這個非同步行為所設計，而且如果使用尚未擁有完整來源的 BitmapImage 進行設定，則不會擲回例外狀況。 您應該直接處理 BitmapImage 上的 ImageOpened 或 ImageFailed 事件，或是在使用來源 (的控制項上，如果控制項類別上可以使用這些事件) ，則不要處理例外狀況。

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

BitmapImage 和編碼

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

Image、BitmapImage 和BitmapSource的 API 不包含用於編碼和解碼媒體格式的任何專用方法。 所有編碼及解碼作業都是內建作業，最多只會將編碼或解碼的各個層面呈現為載入事件的部分事件資料。 如果您想要對影像編碼或解碼執行任何特殊工作，如果應用程式執行影像轉換或操作，您應該使用 Windows.Graphics.Imaging 命名空間中可用的 API。 使用 C++、C# 或 Visual Basic 或使用 JavaScript 的 Windows 應用程式，UWP app 可以使用這些映射 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 播放範例。

版本歷程記錄

Windows 版本	SDK 版本	已新增值
1607	14393	自動播放
1607	14393	IsAnimatedBitmap
1607	14393	IsPlaying
1607	14393	播放
1607	14393	Stop

建構函式

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	取得這個 物件相關聯的 CoreDispatcher 。 CoreDispatcher代表可在 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	發生于下載並解碼影像來源時，不會失敗。 您可以使用此事件來判斷影像的大小，再轉譯影像。

另請參閱

• Image
• BitmapSource
• Source
• ImageSource
• Image 和 ImageBrush
• XAML) 範例 (動畫 GIF 播放