BitmapImage Kelas

Definisi

Menyediakan jenis sumber objek praktis untuk properti Image.Source dan ImageBrush.ImageSource . Anda dapat menentukan BitmapImage dengan menggunakan Pengidentifikasi Sumber Daya Seragam (URI) yang mereferensikan file sumber gambar, atau dengan memanggil SetSourceAsync dan menyediakan aliran.

public ref class BitmapImage sealed : BitmapSource
/// [Windows.Foundation.Metadata.Activatable(Windows.UI.Xaml.Media.Imaging.IBitmapImageFactory, 65536, Windows.Foundation.UniversalApiContract)]
/// [Windows.Foundation.Metadata.Activatable(65536, Windows.Foundation.UniversalApiContract)]
/// [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)]
class BitmapImage final : 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.Activatable(typeof(Windows.UI.Xaml.Media.Imaging.IBitmapImageFactory), 65536, typeof(Windows.Foundation.UniversalApiContract))]
[Windows.Foundation.Metadata.Activatable(65536, typeof(Windows.Foundation.UniversalApiContract))]
[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)]
public sealed class BitmapImage : 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 .../>
Warisan
Object Platform::Object IInspectable DependencyObject ImageSource BitmapSource BitmapImage
Atribut

Persyaratan Windows

Rangkaian perangkat
Windows 10 (diperkenalkan dalam 10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (diperkenalkan dalam v1.0)

Contoh

Berikut adalah contoh penggunaan objek BitmapImage untuk mengatur Image.Source di C#. Dalam contoh ini, objek Gambar dibuat di XAML tetapi tidak memiliki sumber atau nilai properti lainnya; sebaliknya nilai-nilai ini disediakan pada run-time ketika Gambar dimuat dari 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;
}

Keterangan

BitmapImage dapat bersumber dari format file gambar ini:

  • Joint Photographic Experts Group (JPEG)
  • Grafik Jaringan Portabel (PNG)
  • bitmap (BMP)
  • Graphics Interchange Format (GIF)
  • Format File Gambar Bertag (TIFF)
  • JPEG XR
  • ikon (ICO)

Jika sumber gambar adalah aliran, aliran tersebut diharapkan berisi file gambar dalam salah satu format ini.

Kelas BitmapImage mewakili abstraksi sehingga sumber gambar dapat diatur secara asinkron tetapi masih direferensikan dalam markup XAML sebagai nilai properti, atau dalam kode sebagai objek yang tidak menggunakan sintaks yang dapat ditunggu. Saat Anda membuat objek BitmapImage dalam kode, awalnya tidak memiliki sumber yang valid. Anda kemudian harus mengatur sumbernya menggunakan salah satu teknik ini:

  • Gunakan konstruktor BitmapImage(Uri) daripada konstruktor default. Meskipun ini adalah konstruktor, Anda dapat menganggapnya sebagai memiliki perilaku asinkron implisit: BitmapImage tidak akan siap digunakan sampai memunculkan peristiwa ImageOpened yang menunjukkan operasi set sumber asinkron yang berhasil.
  • Atur properti UriSource . Seperti halnya menggunakan konstruktor Uri , tindakan ini secara implisit asinkron, dan BitmapImage tidak akan siap digunakan sampai memunculkan peristiwa ImageOpened .
  • Gunakan SetSourceAsync. Metode ini secara eksplisit asinkron. Properti tempat Anda mungkin menggunakan BitmapImage, seperti Image.Source, dirancang untuk perilaku asinkron ini, dan tidak akan melemparkan pengecualian jika diatur menggunakan BitmapImage yang belum memiliki sumber lengkap. Daripada menangani pengecualian, Anda harus menangani peristiwa ImageOpened atau ImageFailed baik pada BitmapImage secara langsung atau pada kontrol yang menggunakan sumber (jika peristiwa tersebut tersedia di kelas kontrol).

ImageFailed dan ImageOpened saling eksklusif. Satu peristiwa atau yang lain akan selalu dinaikkan setiap kali objek BitmapImage memiliki set nilai sumber atau reset.

BitmapImage dan pengodean

Dukungan codec yang mendasari untuk file gambar disediakan oleh Windows Imaging Component (WIC) API di Windows. Untuk informasi selengkapnya tentang format gambar tertentu seperti yang didokumenkan untuk codec, lihat Codec WIC Asli. Untuk informasi selengkapnya tentang format dan cara menggunakan Pengidentifikasi Sumber Daya Seragam (URI) untuk mengakses file sumber gambar yang berasal dari sumber daya aplikasi, lihat Gambar dan ImageBrush.

API untuk Gambar, BitmapImage, dan BitmapSource tidak menyertakan metode khusus untuk pengodean dan pendekodean format media. Semua operasi pengodean dan dekode bawaan, dan paling banyak akan memunculkan aspek pengodean atau dekode sebagai bagian dari data peristiwa untuk peristiwa beban. Jika Anda ingin melakukan pekerjaan khusus dengan pengodean atau dekode gambar, yang mungkin Anda gunakan jika aplikasi Anda melakukan konversi atau manipulasi gambar, Anda harus menggunakan API yang tersedia di namespace Windows.Graphics.Imaging . API pencitraan ini dapat digunakan oleh aplikasi UWP menggunakan aplikasi C++, C#, atau Visual Basic atau Windows menggunakan JavaScript. API ini juga didukung oleh komponen Windows Imaging Component (WIC) Windows 8.

Gambar animasi

Mulai dari Windows 10, versi 1607, elemen Gambar XAML mendukung gambar GIF animasi. Saat Anda menggunakan BitmapImage sebagai Sumber gambar, Anda dapat mengakses BITMAPImage API untuk mengontrol pemutaran gambar GIF animasi.

  • Gunakan properti AutoPlay , yang default ke true, untuk menentukan apakah bitmap animasi diputar atau tidak segera setelah dimuat.
  • Gunakan properti IsAnimatedBitmap untuk memeriksa apakah bitmap dianimasikan.
  • Gunakan properti IsPlaying bersama dengan metode Putar dan Hentikan untuk mengontrol pemutaran bitmap animasi.

Catatan

Untuk sebagian besar aplikasi, kami sarankan Anda mengatur AutoPlay ke false jika UISettings.AnimationsEnabledsalah, untuk mendukung kebutuhan aksesibilitas pengguna. Jangan lakukan ini jika konten GIF animasi penting untuk kegunaan aplikasi Anda.

Jika aplikasi Anda berjalan pada rilis Windows 10 sebelum versi 1607, Anda harus menggunakan kelas ApiInformation untuk memeriksa keberadaan anggota ini sebelum menggunakannya. Untuk informasi selengkapnya, lihat Kode adaptif versi: Gunakan API baru sambil mempertahankan kompatibilitas dengan versi sebelumnya.

Contoh ini menunjukkan cara menggunakan GIF animasi. Tombol memungkinkan pengguna memulai atau menghentikan animasi. Contoh ini menggunakan kode adaptif versi sehingga dapat berjalan pada semua versi Windows 10. Pada versi sebelum versi 1607, bingkai pertama GIF ditampilkan, tetapi tidak dianimasikan.

<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();
        }
    }
}

Untuk contoh selengkapnya, lihat sampel pemutaran GIF Animasi.

Riwayat versi

Versi Windows Versi SDK Nilai ditambahkan
1607 14393 Autoplay
1607 14393 IsAnimatedBitmap
1607 14393 IsPlaying
1607 14393 Putar
1607 14393 Hentikan

Konstruktor

BitmapImage()

Menginisialisasi instans baru kelas BitmapImage .

BitmapImage(Uri)

Menginisialisasi instans baru kelas BitmapImage , menggunakan Pengidentifikasi Sumber Daya Seragam (URI) yang disediakan.

Properti

AutoPlay

Mendapatkan atau menetapkan nilai yang menunjukkan apakah gambar animasi harus diputar segera setelah dimuat.

AutoPlayProperty

Mengidentifikasi properti dependensi AutoPlay .

CreateOptions

Mendapatkan atau mengatur BitmapCreateOptions untuk BitmapImage.

CreateOptionsProperty

Mengidentifikasi properti dependensi CreateOptions .

DecodePixelHeight

Mendapatkan atau mengatur tinggi yang akan digunakan untuk operasi pendekodean gambar.

DecodePixelHeightProperty

Mengidentifikasi properti dependensi DecodePixelHeight .

DecodePixelType

Mendapatkan atau menetapkan nilai yang menentukan bagaimana nilai DecodePixelWidth dan DecodePixelHeight ditafsirkan untuk operasi pendekodean.

DecodePixelTypeProperty

Mengidentifikasi properti dependensi DecodePixelType .

DecodePixelWidth

Mendapatkan atau mengatur lebar yang akan digunakan untuk operasi pendekodean gambar.

DecodePixelWidthProperty

Mengidentifikasi properti dependensi DecodePixelWidth .

Dispatcher

Mendapatkan CoreDispatcher yang dikaitkan dengan objek ini. CoreDispatcher mewakili fasilitas yang dapat mengakses DependencyObject pada utas UI meskipun kode dimulai oleh utas non-UI.

(Diperoleh dari DependencyObject)
IsAnimatedBitmap

Mendapatkan nilai yang menunjukkan apakah gambar dianimasikan.

IsAnimatedBitmapProperty

Mengidentifikasi properti dependensi IsAnimatedBitmap .

IsPlaying

Mendapatkan nilai yang menunjukkan apakah gambar animasi sedang diputar.

IsPlayingProperty

Mengidentifikasi properti dependensi IsPlaying .

PixelHeight

Mendapatkan tinggi bitmap dalam piksel.

(Diperoleh dari BitmapSource)
PixelWidth

Mendapatkan lebar bitmap dalam piksel.

(Diperoleh dari BitmapSource)
UriSource

Mendapatkan atau mengatur Pengidentifikasi Sumber Daya Seragam (URI) dari file sumber grafis yang menghasilkan BitmapImage ini.

UriSourceProperty

Mengidentifikasi properti dependensi UriSource .

Metode

ClearValue(DependencyProperty)

Menghapus nilai lokal properti dependensi.

(Diperoleh dari DependencyObject)
GetAnimationBaseValue(DependencyProperty)

Mengembalikan nilai dasar apa pun yang ditetapkan untuk properti dependensi, yang akan berlaku dalam kasus di mana animasi tidak aktif.

(Diperoleh dari DependencyObject)
GetValue(DependencyProperty)

Mengembalikan nilai efektif properti dependensi saat ini dari DependencyObject.

(Diperoleh dari DependencyObject)
Play()

Memulai animasi gambar animasi.

ReadLocalValue(DependencyProperty)

Mengembalikan nilai lokal properti dependensi, jika nilai lokal ditetapkan.

(Diperoleh dari DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)

Mendaftarkan fungsi pemberitahuan untuk mendengarkan perubahan pada DependencyProperty tertentu pada instans DependencyObject ini.

(Diperoleh dari DependencyObject)
SetSource(IRandomAccessStream)

Mengatur gambar sumber untuk BitmapSource dengan mengakses aliran. Sebagian besar penelepon harus menggunakan SetSourceAsync sebagai gantinya.

(Diperoleh dari BitmapSource)
SetSourceAsync(IRandomAccessStream)

Mengatur gambar sumber untuk BitmapSource dengan mengakses aliran dan memproses hasilnya secara asinkron.

(Diperoleh dari BitmapSource)
SetValue(DependencyProperty, Object)

Mengatur nilai lokal properti dependensi pada DependencyObject.

(Diperoleh dari DependencyObject)
Stop()

Mengakhiri animasi gambar animasi.

UnregisterPropertyChangedCallback(DependencyProperty, Int64)

Membatalkan pemberitahuan perubahan yang sebelumnya terdaftar dengan memanggil RegisterPropertyChangedCallback.

(Diperoleh dari DependencyObject)

Acara

DownloadProgress

Terjadi ketika perubahan signifikan telah terjadi dalam kemajuan unduhan konten BitmapImage .

ImageFailed

Terjadi ketika ada kesalahan yang terkait dengan pengambilan gambar atau format.

ImageOpened

Terjadi ketika sumber gambar diunduh dan didekode tanpa kegagalan. Anda dapat menggunakan peristiwa ini untuk menentukan ukuran gambar sebelum merendernya.

Berlaku untuk

Lihat juga