BitmapImage Класс

Определение

Предоставляет практический тип источника объекта для свойств Image.Source и ImageBrush.ImageSource . BitmapImage можно определить с помощью универсального кода ресурса (URI), который ссылается на исходный файл изображения, или путем вызова SetSourceAsync и предоставления потока.

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 для задания 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. Дополнительные сведения о конкретных форматах изображений, как описано для кодеков, см. в разделе Native WIC Codecs. Дополнительные сведения о форматах и использовании универсального кода ресурса (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-файлов.

Конструкторы

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

Всегда возвращает в null приложении Windows App SDK. Вместо этого используйте DispatcherQueue .

(Унаследовано от DependencyObject)
DispatcherQueue

Возвращает объект , DispatcherQueue с которым связан этот объект. представляет DispatcherQueue средство, которое может получить доступ к в потоке 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

Происходит при загрузке и декодировании источника изображения без сбоев. Это событие можно использовать для определения размера изображения перед его отрисовкой.

Применяется к

См. также раздел