BitmapImage 类

定义

命名空间:

Windows.UI.Xaml.Media.Imaging

提供 Image.Source 和 ImageBrush.ImageSource 属性的实用对象源类型。 可以使用引用图像源文件的统一资源标识符 (URI) ，或通过调用 SetSourceAsync 并提供流来定义 BitmapImage。

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 中创建的，但没有 source 或任何其他属性值;而是在从 XAML 加载 Image 时在运行时提供这些值。

<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)
• 可移植网络图形 (PNG)
• 位图 (BMP)
• 图形交换格式 (GIF)
• 标记图像文件格式 (TIFF)
• JPEG XR
• 图标 (ICO)

如果图像源是流，则该流应包含这些格式之一的图像文件。

BitmapImage 类表示一个抽象，以便可以异步设置图像源，但仍可在 XAML 标记中作为属性值引用，或在代码中作为不使用可等待语法的对象引用。 在代码中创建 BitmapImage 对象时，它最初没有有效的源。 然后，应使用以下方法之一设置其源：

• 使用 BitmapImage (Uri) 构造函数而不是默认构造函数。 尽管它是一个构造函数，但你可以将其视为具有隐式异步行为：BitmapImage 在引发指示异步源集操作成功的 ImageOpened 事件之前，它不会准备好使用。
• 设置 UriSource 属性。 与使用 Uri 构造函数一样，此操作是隐式异步的，在引发 ImageOpened 事件之前，BitmapImage 不会准备好使用。
• 使用 SetSourceAsync。 此方法是显式异步的。 可以使用 BitmapImage 的属性（如 Image.Source）专为此异步行为而设计，如果使用尚未具有完整源的 BitmapImage 进行设置，则不会引发异常。 如果这些事件在控件类) 上可用，则应直接在 BitmapImage 上或使用源 (的控件上处理 ImageOpened 或 ImageFailed 事件，而不是处理异常。

ImageFailed 和 ImageOpened 是互斥的。 每当 BitmapImage 对象设置或重置其源值时，始终会引发一个事件或另一个事件。

BitmapImage 和编码

Windows 映像组件 (Windows 中的 WIC) API 提供对图像文件的基础编解码器支持。 有关编解码器记录的特定图像格式的详细信息，请参阅 本机 WIC 编解码器。 有关格式和如何使用统一资源标识符 (URI) 访问来自应用资源的图像源文件的详细信息，请参阅 Image 和 ImageBrush。

Image、BitmapImage 和 BitmapSource 的 API 不包含任何用于对媒体格式进行编码和解码的专用方法。 所有的编码和解码操作都是内置的，并且至多将编码和解码方面展现为加载事件的事件数据的一部分。 如果要对图像编码或解码执行任何特殊工作（在应用执行图像转换或操作时可以使用），则应使用 Windows.Graphics.Imaging 命名空间中提供的 API。 这些图像处理 API 可由使用 C++、C# 的 UWP 应用或 Visual Basic 或使用 JavaScript 的 Windows 应用使用。 Windows 8 的 Windows 图像处理组件 (WIC) 组件也支持这些 API。

动画图像

从 Windows 10 版本 1607 开始，XAML Image 元素支持动态 GIF 图像。 使用 BitmapImage 作为图像 源时，可以访问 BitmapImage API 来控制动画 GIF 图像的播放。

• 使用 AutoPlay 属性（默认为 true）指定动画位图在加载时是否立即播放。
• 使用 IsAnimatedBitmap 属性检查位图是否为动画。
• 使用 IsPlaying 属性以及 Play 和 Stop 方法来控制动画位图的播放。

注意

对于大多数应用，如果 UISettings.AnimationsEnabled 为 false，建议将“自动播放”设置为 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	停止

构造函数

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
• 动画 GIF 播放 (XAML) 示例