共用方式為


BitmapImage 類別

定義

提供 Image.SourceImageBrush.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
屬性

範例

以下是使用 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 事件) 。

ImageFailedImageOpened 互斥。 每當 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 影像的播放。

  • 使用預設為trueAutoPlay屬性,指定動畫點陣圖在載入時是否播放。
  • 使用 IsAnimatedBitmap 屬性來檢查點陣圖是否為動畫。
  • 使用 IsPlaying 屬性以及 PlayStop 方法來控制動畫點陣圖的播放。

注意

對於大部分的應用程式,建議您在UISettings.AnimationsEnabledfalse時將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

取得或設定BitmapImageBitmapCreateOptions

CreateOptionsProperty

識別 CreateOptions 相依性屬性。

DecodePixelHeight

取得或設定用於影像解碼作業的高度。

DecodePixelHeightProperty

識別 DecodePixelHeight 相依性屬性。

DecodePixelType

取得或設定值,決定解碼作業的 DecodePixelWidthDecodePixelHeight 值如何解譯。

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

發生于下載並解碼影像來源時,不會失敗。 您可以在轉譯影像之前,使用此事件來判斷影像的大小。

適用於

另請參閱