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 中创建的，但没有 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 方法来控制动画位图的播放。

如果应用在版本 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 播放示例。

构造函数

属性

方法

事件

适用于

另请参阅

• Image
• BitmapSource
• Source
• ImageSource
• Image 和 ImageBrush
• 动画 GIF 播放 (XAML) 示例