BitmapImage Класс

Определение

Пространство имен:

Windows.UI.Xaml.Media.Imaging

Предоставляет практический тип источника объекта для свойств Image.Source и ImageBrush.ImageSource . BitmapImage можно определить с помощью универсального кода ресурса (URI), который ссылается на исходный файл изображения, или путем вызова 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 для задания Image.Source в C#. В этом примере объект 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
• PNG
• BMP
• GIF
• TIFF
• JPEG XR
• значки (ICO)

Если источником изображения является поток, ожидается, что этот поток будет содержать файл изображения в одном из этих форматов.

Класс BitmapImage представляет абстракцию, так что источник изображения можно задать асинхронно, но он по-прежнему ссылается в разметке XAML как на значение свойства или в коде как на объект, который не использует ожидающий синтаксис. При создании объекта BitmapImage в коде он изначально не имеет допустимого источника. Затем следует задать его источник с помощью одного из следующих методов:

• Используйте конструктор BitmapImage(Uri), а не конструктор по умолчанию. Хотя это конструктор, вы можете представить это как неявное асинхронное поведение: BitmapImage не будет готов к использованию, пока не вызовет событие ImageOpened , которое указывает на успешную операцию асинхронного набора источника.
• Задайте свойство UriSource . Как и в случае с конструктором URI , это действие неявно асинхронно, и BitmapImage не будет готов к использованию, пока не вызовет событие ImageOpened .
• Используйте SetSourceAsync. Этот метод явно асинхронен. Свойства, в которых можно использовать BitmapImage, например Image.Source, предназначены для этого асинхронного поведения и не будут вызывать исключения, если они заданы с помощью BitmapImage, у которого еще нет полного источника. Вместо обработки исключений следует обрабатывать события ImageOpened или ImageFailed непосредственно в BitmapImage или в элементе управления, использующем источник (если эти события доступны в классе элемента управления).

ImageFailed и ImageOpened являются взаимоисключающими. Одно или другое событие всегда возникает, когда для объекта BitmapImage задано или сбрасывается исходное значение.

BitmapImage и кодировка

Базовая поддержка кодека для файлов изображений предоставляется API компонента образов Windows (WIC) в Windows. Дополнительные сведения о конкретных форматах изображений, как описано для кодеков, см. в разделе Собственные кодеки WIC. Дополнительные сведения о форматах и использовании универсального кода ресурса (URI) для доступа к исходным файлам изображений, поступающим из ресурсов приложения, см. в разделе Image и ImageBrush.

API для Image, BitmapImage и BitmapSource не включает специальные методы кодирования и декодирования форматов мультимедиа. Все операции кодирования и декодирования — встроенные, и только некоторые аспекты кодирования и декодирования могут быть включены в данные для событий загрузки. Если вы хотите выполнить какую-либо специальную работу с кодировкой или декодированием изображений, которую вы можете использовать, если приложение выполняет преобразование изображений или манипуляции, следует использовать API, доступные в пространстве имен Windows.Graphics.Imaging . Эти API образов могут использоваться приложением UWP на C++, C# или Visual Basic или приложением Для Windows с помощью JavaScript. Эти API также поддерживаются компонентом Windows Imaging Component (WIC) Windows 8.

Анимированные изображения

Начиная с Windows 10 версии 1607 элемент XAML Image поддерживает анимированные GIF-изображения. При использовании BitmapImage в качестве источника изображения вы можете получить доступ к API BitmapImage для управления воспроизведением анимированного GIF-изображения.

• Используйте свойство Автозапуск , которое по умолчанию имеет значение true, чтобы указать, воспроизводится ли анимированное растровое изображение сразу после загрузки.
• Используйте свойство IsAnimatedBitmap, чтобы проверка, анимируется ли растровое изображение.
• Используйте свойство IsPlaying вместе с методами Play и Stop , чтобы управлять воспроизведением анимированного растрового изображения.

Примечание

Для большинства приложений рекомендуется задать для параметра AutoPlayзначение false , если uiSettings.AnimationsEnabled имеет значение false, чтобы обеспечить поддержку специальных возможностей пользователей. Не делайте этого, если содержимое анимированного GIF-файла важно для удобства использования приложения.

Если приложение выполняется в выпусках Windows 10 до версии 1607, необходимо использовать класс 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)	Инициализирует новый экземпляр класса BitmapImage , используя предоставленный универсальный код ресурса (URI).

Свойства

AutoPlay	Возвращает или задает значение, указывающее, должно ли воспроизводиться анимированное изображение сразу после загрузки.
AutoPlayProperty	Идентифицирует свойство зависимостей автозапуска .
CreateOptions	Возвращает или задает bitmapCreateOptions для bitmapImage.
CreateOptionsProperty	Определяет свойство зависимости CreateOptions .
DecodePixelHeight	Возвращает или задает высоту, используемую для операций декодирования изображений.
DecodePixelHeightProperty	Определяет свойство зависимости DecodePixelHeight .
DecodePixelType	Возвращает или задает значение, определяющее способ интерпретации значений DecodePixelWidth и DecodePixelHeight для операций декодирования.
DecodePixelTypeProperty	Определяет свойство зависимости DecodePixelType .
DecodePixelWidth	Возвращает или задает ширину, используемую для операций декодирования изображений.
DecodePixelWidthProperty	Определяет свойство зависимости DecodePixelWidth .
Dispatcher	Возвращает CoreDispatcher , с которым связан этот объект. CoreDispatcher представляет средство, которое может получить доступ к DependencyObject в потоке пользовательского интерфейса, даже если код инициируется потоком, не относящегося к пользовательскому интерфейсу. (Унаследовано от DependencyObject)
IsAnimatedBitmap	Возвращает значение, указывающее, анимируется ли изображение.
IsAnimatedBitmapProperty	Определяет свойство зависимости IsAnimatedBitmap .
IsPlaying	Возвращает значение, указывающее, воспроизводится ли анимированное изображение.
IsPlayingProperty	Определяет свойство зависимости IsPlaying .
PixelHeight	Получает высоту растрового изображения в пикселях. (Унаследовано от BitmapSource)
PixelWidth	Получает ширину растрового изображения в пикселях. (Унаследовано от BitmapSource)
UriSource	Возвращает или задает универсальный код ресурса (URI) исходного графического файла, создающего этот bitmapImage.
UriSourceProperty	Определяет свойство зависимости UriSource .

Методы

ClearValue(DependencyProperty)	Очищает локальное значение свойства зависимостей. (Унаследовано от DependencyObject)
GetAnimationBaseValue(DependencyProperty)	Возвращает любое базовое значение, установленное для свойства зависимостей, которое применяется в случаях, когда анимация не активна. (Унаследовано от DependencyObject)
GetValue(DependencyProperty)	Возвращает текущее действующее значение свойства зависимостей из DependencyObject. (Унаследовано от DependencyObject)
Play()	Запускает анимацию анимированного изображения.
ReadLocalValue(DependencyProperty)	Возвращает локальное значение свойства зависимостей, если задано локальное значение. (Унаследовано от DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Регистрирует функцию уведомления для прослушивания изменений определенной DependencyProperty в этом экземпляре DependencyObject . (Унаследовано от 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
• Изображения и кисти изображений
• Пример воспроизведения анимированного GIF-файла (XAML)