Image.Source Properti
Definisi
Penting
Beberapa informasi terkait produk prarilis yang dapat diubah secara signifikan sebelum dirilis. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.
Mendapatkan atau mengatur sumber untuk gambar.
public:
property ImageSource ^ Source { ImageSource ^ get(); void set(ImageSource ^ value); };ImageSource Source();
void Source(ImageSource value);public ImageSource Source { get; set; }var imageSource = image.source;
image.source = imageSource;Public Property Source As ImageSource<Image Source="uri"/>
Nilai Properti
Objek yang mewakili file sumber gambar untuk gambar yang digambar. Biasanya Anda mengatur ini dengan objek BitmapImage , dibangun dengan Pengidentifikasi Sumber Daya Seragam (URI) yang menjelaskan jalur ke file sumber gambar yang valid. Atau, Anda dapat menginisialisasi BitmapSource dengan aliran, mungkin aliran dari file penyimpanan.
Keterangan
Mengatur properti Sumber secara inheren adalah tindakan asinkron. Karena ini adalah properti , tidak ada sintaks yang dapat ditunggu, tetapi untuk sebagian besar skenario Anda tidak perlu berinteraksi dengan aspek asinkron dari pemuatan file sumber gambar. Kerangka kerja akan menunggu sumber gambar dikembalikan, dan akan menjalankan ulang tata letak saat file sumber gambar tersedia.
Mengatur sumber ke nilai Pengidentifikasi Sumber Daya Seragam (URI) yang tidak dapat diselesaikan ke file sumber gambar yang valid tidak memberikan pengecualian. Sebaliknya, ia menembakkan peristiwa ImageFailed . Kegagalan pendekodean juga menembakkan ImageFailed. Anda dapat menulis handler ImageFailed dan melampirkannya ke objek Gambar untuk mendeteksi ini, dan mungkin menggunakan ErrorMessage dalam data peristiwa untuk menentukan sifat kegagalan. Selain itu, jika Anda ingin memverifikasi bahwa file sumber gambar dimuat dengan benar, Anda dapat menangani peristiwa ImageOpened pada elemen Gambar .
Mengatur Sumber di XAML
Anda dapat mengatur properti Sumber sebagai atribut di XAML. Dalam hal ini, Anda mengatur nilai atribut Sumber sebagai string Pengidentifikasi Sumber Daya Seragam (URI) yang menjelaskan lokasi file gambar sumber. Perilaku ini bergantung pada konversi jenis yang mendasar yang memproses string sebagai Pengidentifikasi Sumber Daya Seragam (URI), dan memanggil yang setara dengan konstruktor BitmapImage(Uri ). Mengatur properti Sumber menggunakan string Pengidentifikasi Sumber Daya Seragam (URI) adalah pintasan yang diaktifkan oleh XAML. Perhatikan bahwa Pengidentifikasi Sumber Daya Seragam (URI) di sini tampaknya merupakan Pengidentifikasi Sumber Daya Seragam (URI) relatif; mendukung Pengidentifikasi Sumber Daya Seragam Parsial (URI) adalah pintasan XAML lainnya.
<Image Width="200" Source="Images/myImage.png"/>
Pengurai XAML menginterpretasikan string apa pun yang mewakili Pengidentifikasi Sumber Daya Seragam (URI) relatif menggunakan Pengidentifikasi Sumber Daya Seragam (URI) dasar dari halaman XAML yang sedang diurai. Misalnya, jika Anda menentukan nilai "Gambar/myImage.png" di XAML, string tersebut ditafsirkan sebagai akhiran jalur relatif yang ditambahkan ke lokasi Pengidentifikasi Sumber Daya Seragam (URI) dasar dalam paket aplikasi tempat halaman XAML itu sendiri berada. Jika elemen Gambar sebelumnya ditambahkan ke halaman yang berada di akar paket aplikasi, Pengidentifikasi Sumber Daya Seragam (URI) ditafsirkan sebagai ms-appx:///Images/myImage.png. Jika Gambar ditambahkan ke halaman yang ada di folder Pages di aplikasi, Pengidentifikasi Sumber Daya Seragam (URI) ditafsirkan sebagai ms-appx:///Pages/Images/myImage.png.
Jika gambar sumber bukan bagian dari paket aplikasi, Anda harus menggunakan Pengidentifikasi Sumber Daya Seragam (URI) absolut untuk mengatur properti Sumber di XAML. Untuk informasi selengkapnya, lihat Cara memuat sumber daya file, dan contoh nanti dalam dokumen ini.
Sintaks elemen properti dalam XAML juga dimungkinkan, menentukan elemen objek BitmapImage dengan sumber yang valid sebagai nilai properti.
Mengatur Sumber dalam kode
Untuk mengatur properti Image.Source dalam kode memerlukan instans BitmapImage (atau BitmapSource), yang juga harus Anda buat. Jika sumber gambar Anda adalah aliran, gunakan metode Async SetSourceAsyncbitmapImage untuk menentukan informasi gambar dari aliran.
Jika sumber gambar Anda adalah file yang direferensikan oleh Pengidentifikasi Sumber Daya Seragam (URI), atur properti BitmapImage.UriSource , atau gunakan konstruktor BitmapImage yang mengambil parameter Pengidentifikasi Sumber Daya Seragam (URI). Windows Runtime memberlakukan bahwa Pengidentifikasi Sumber Daya Seragam (URI) harus absolut; Anda tidak dapat menggunakan Pengidentifikasi Sumber Daya Seragam (URI) relatif dalam kode Windows Runtime. Jika Anda menggunakan nilai .NET Framework System.Uri, dan Anda menggunakan tanda tangan yang memerlukan nilai UriKind, pastikan untuk menentukan Absolut.
Saat mereferensikan konten lokal, Anda harus menyertakan skema ms-appx: dalam Pengidentifikasi Sumber Daya Seragam (URI) absolut yang Anda gunakan sebagai BitmapImage.UriSource. Dalam kode, Anda tidak mendapatkan pintasan pemrosesan untuk menggabungkan bagian Pengidentifikasi Sumber Daya Seragam (URI) relatif dan skema ms-appx: yang terjadi secara otomatis jika Anda menentukan Sumber sebagai atribut XAML. Sebagai gantinya, Anda harus secara eksplisit membuat Pengidentifikasi Sumber Daya Seragam (URI) absolut dengan skema yang sesuai.
Berikut cara mengatur sumber ke gambar dari paket aplikasi.
Image img = new Image();
BitmapImage bitmapImage = new BitmapImage();
Uri uri = new Uri("ms-appx:///Assets/Logo.png");
bitmapImage.UriSource = uri;
img.Source = bitmapImage;
// OR
Image img = new Image();
img.Source = new BitmapImage(new Uri("ms-appx:///Assets/Logo.png"));
Windows::UI::Xaml::Controls::Image img;
Windows::UI::Xaml::Media::Imaging::BitmapImage bitmapImage;
Windows::Foundation::Uri uri{ L"ms-appx:///Assets/LockScreenLogo.png" };
bitmapImage.UriSource(uri);
img.Source(bitmapImage);
// OR
Windows::UI::Xaml::Controls::Image img;
img.Source(Windows::UI::Xaml::Media::Imaging::BitmapImage{ Windows::Foundation::Uri{ L"ms-appx:///Assets/LockScreenLogo.png" } });
auto img = ref new Image();
auto bitmapImage = ref new Windows::UI::Xaml::Media::Imaging::BitmapImage();
auto uri = ref new Windows::Foundation::Uri("ms-appx:///Assets/Logo.png");
bitmapImage->UriSource = uri;
img->Source = bitmapImage;
// OR
auto img = ref new Image();
img->Source = ref new BitmapImage(ref new Windows::Foundation::Uri("ms-appx:///Assets/Logo.png"));
Jika Anda perlu memastikan bahwa kontrol Gambar siap sebelum mencoba menggunakannya dalam kode, tangani peristiwa Dimuat , dan atur properti Sumber di penanganan aktivitas.
Catatan
Peristiwa FrameworkElement.Loaded terjadi saat kontrol Gambar dimuat ke halaman XAML. Peristiwa ImageOpened terjadi ketika file gambar dibuka di kontrol Gambar .
Berikut adalah contoh pengaturan Image.Source di handler untuk peristiwa Dimuat . 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;
if (img != null)
{
BitmapImage bitmapImage = new BitmapImage();
img.Width = bitmapImage.DecodePixelWidth = 280;
bitmapImage.UriSource = new Uri("ms-appx:///Assets/Logo.png");
img.Source = bitmapImage;
}
}
void MainPage::Image_Loaded(winrt::Windows::Foundation::IInspectable const& sender, winrt::Windows::UI::Xaml::RoutedEventArgs const& /* e */)
{
auto img{ sender.as<Windows::UI::Xaml::Controls::Image>() }; // throws if QI fails, so no need for null-check afterwards.
Windows::UI::Xaml::Media::Imaging::BitmapImage bitmapImage;
img.Width(280);
bitmapImage.DecodePixelWidth(280);
bitmapImage.UriSource(Windows::Foundation::Uri{ L"ms-appx:///Assets/LockScreenLogo.png" });
img.Source(bitmapImage);
}
void App1::MainPage::Image_Loaded(Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e)
{
auto img = dynamic_cast<Image^>(sender);
if (img != nullptr)
{
auto bitmapImage = ref new BitmapImage();
img->Width = 280; bitmapImage->DecodePixelWidth = 280;
bitmapImage->UriSource = ref new Uri("ms-appx:///Assets/Logo.png");
img->Source = bitmapImage;
}
}
Anda dapat menangani peristiwa ImageOpened jika ada masalah waktu dengan mengambil atau mendekode sumber gambar, di mana Anda mungkin memerlukan konten alternatif untuk ditampilkan hingga sumber gambar tersedia. Lihat sampel gambar XAML misalnya kode.
Menggunakan URI relatif dalam kode
Kami melihat sebelumnya bahwa pengurai XAML menginterpretasikan Pengidentifikasi Sumber Daya Seragam (URI) relatif menggunakan Pengidentifikasi Sumber Daya Seragam (URI) dasar dari halaman XAML yang sedang diurai. Untuk mencapai hasil kode yang sama, Anda dapat membuat Uri menggunakan salah satu konstruktor yang membuat Pengidentifikasi Sumber Daya Seragam (URI) dengan menggabungkan basis absolut dan kemudian jalur relatif dalam lokasi tersebut. Untuk parameter pertama, panggil BaseUri di Halaman tempat Gambar dimuat. (Anda juga dapat memanggil BaseUri pada instans Gambar tempat Anda mengatur sumber, atau elemen lain di halaman. Lihat Peringatan di bawah ini.) Ini membuat Pengidentifikasi Sumber Daya Seragam (URI) dengan skema ms-appx: dan menambahkan jalur yang merupakan bagian dari lokasi halaman XAML. Untuk parameter kedua, lewati string Pengidentifikasi Sumber Daya Seragam (URI) relatif yang menjelaskan lokasi gambar sumber.
Dalam C# atau Microsoft Visual Basic, jenis Uri diproyeksikan sebagai System.Uri, jadi gunakan konstruktor System.Uri(Uri, String) yang mengambil string sebagai parameter kedua. Di ekstensi komponen Visual C++ (C++/CX) gunakan Uri(String,String).
<Image x:Name="capturedPhoto"/>
BitmapImage bitmapImage = new BitmapImage();
// Call BaseUri on the root Page element and combine it with a relative path
// to consruct an absolute URI.
bitmapImage.UriSource = new Uri(this.BaseUri, "Assets/placeholder.png");
capturedPhoto.Source = bitmapImage;
auto bitmapImage = winrt::Windows::UI::Xaml::Media::Imaging::BitmapImage();
// Call BaseUri on the root Page element and combine it with a relative path
// to consruct an absolute URI.
bitmapImage.UriSource(winrt::Windows::Foundation::Uri(BaseUri().AbsoluteUri(), L"Assets/placeholder.png"));
capturedPhoto.Source(bitmapImage);
auto bitmapImage = ref new Windows::UI::Xaml::Media::Imaging::BitmapImage();
// Call BaseUri on the root Page element and combine it with a relative path
// to consruct an absolute URI.
bitmapImage->UriSource = ref new Windows::Foundation::Uri(BaseUri->AbsoluteUri, "Assets/placeholder.png");
capturedPhoto->Source = bitmapImage;
Catatan
Jika Anda membuat contoh Gambar baru dalam kode, properti BaseUrinull hingga Gambar ditambahkan ke pohon visual halaman. Misalnya, kode berikut melempar pengecualian ArgumentNull . Untuk menghindari pengecualian, tambahkan Gambar ke pohon visual sebelum mengatur properti Sumber.
Contoh ini memberikan pengecualian karena memanggil BaseUri pada Gambar sebelum Gambar ditambahkan ke halaman. Diasumsikan bahwa 'stackPanel1' adalah elemen StackPanel yang dideklarasikan dalam XAML.
Image img = new Image();
BitmapImage bitmapImage = new BitmapImage();
// AN EXCEPTION IS THROWN BECAUSE img.BaseUri IS NULL AT THIS POINT.
Uri uri = new Uri(img.BaseUri, "Assets/Logo.png");
bitmapImage.UriSource = uri;
img.Source = bitmapImage;
stackPanel1.Children.Add(img);
Image img;
BitmapImage bitmapImage;
// AN EXCEPTION IS THROWN BECAUSE img.BaseUri IS NULL AT THIS POINT.
Uri uri(img.BaseUri(), L"Assets/Logo.png");
bitmapImage.UriSource(uri);
img.Source(bitmapImage);
stackPanel1.Children().Add(img);
auto img = ref new Image();
auto bitmapImage = ref new Windows::UI::Xaml::Media::Imaging::BitmapImage();
// AN EXCEPTION IS THROWN BECAUSE img->BaseUri IS NULL AT THIS POINT.
auto uri = ref new Windows::Foundation::Uri(img->BaseUri->AbsoluteUri, "Assets/Logo.png");
bitmapImage->UriSource = uri;
img->Source = bitmapImage;
stackPanel1->Children->Append(img);
Untuk menghindari kesalahan ini, Anda dapat memanggil BaseUri di Halaman itu sendiri, seperti yang ditunjukkan sebelumnya, atau menambahkan Gambar ke halaman sebelum memanggil BaseUri, seperti yang ditunjukkan di sini.
Dalam contoh ini, Gambar ditambahkan ke halaman sebelum panggilan ke BaseUri, sehingga BaseUri tidak null. Diasumsikan bahwa 'stackPanel1' adalah elemen StackPanel yang dideklarasikan dalam XAML.
Image img = new Image();
// Add the image to the page.
stackPanel1.Children.Add(img);
BitmapImage bitmapImage = new BitmapImage();
// img.BaseUri in not null because img has been added to the page.
Uri uri = new Uri(img.BaseUri, "Assets/Logo.png");
bitmapImage.UriSource = uri;
img.Source = bitmapImage;
Image img;
// Add the image to the page.
stackPanel1.Children().Add(img);
BitmapImage bitmapImage;
// img.BaseUri in not null because img has been added to the page.
Uri uri(img.BaseUri(), L"Assets/Logo.png");
bitmapImage.UriSource(uri);
img.Source(bitmapImage);
auto img = ref new Image();
// Add the image to the page.
stackPanel1->Children->Append(img);
auto bitmapImage = ref new Windows::UI::Xaml::Media::Imaging::BitmapImage();
// img->BaseUri in not null because img has been added to the page.
auto uri = ref new Windows::Foundation::Uri(img->BaseUri->AbsoluteUri, "Assets/Logo.png");
bitmapImage->UriSource = uri;
img->Source = bitmapImage;
Menggunakan file dari jaringan
Untuk menggunakan file dari lokasi jaringan sebagai sumber gambar, gunakan skema http: atau https: seperti yang ditunjukkan di sini. Tentukan Pengidentifikasi Sumber Daya Seragam (URI) absolut. Untuk informasi selengkapnya, lihat Cara memuat sumber daya file.
<Image Source="http://www.contoso.com/images/logo.png"/>
Image img = new Image();
img.Source = new BitmapImage(new Uri("http://www.contoso.com/images/logo.png"));
Image img;
img.Source(BitmapImage(Uri(L"http://www.contoso.com/images/logo.png")));
auto img = ref new Image();
img->Source = ref new BitmapImage(ref new Windows::Foundation::Uri("http://www.contoso.com/images/logo.png"));
Menggunakan file dari penyimpanan lokal
Untuk menggunakan file yang ditempatkan di penyimpanan lokal aplikasi Anda sebagai sumber gambar, gunakan ms-appdata: skema, seperti yang ditunjukkan di sini. Tentukan Pengidentifikasi Sumber Daya Seragam (URI) absolut. Untuk informasi selengkapnya, lihat Cara memuat sumber daya file.
<!-- Access an image file stored in the local folder -->
<Image Source="ms-appdata:///local/images/logo.png"/>
<!-- Access an image file stored in the roaming folder -->
<Image Source="ms-appdata:///roaming/images/logo.png"/>
<!-- Access an image file stored in the temp folder -->
<Image Source="ms-appdata:///temp/images/logo.png"/>
var uri = new System.Uri("ms-appdata:///local/images/logo.png");
var file = await Windows.Storage.StorageFile.GetFileFromApplicationUriAsync(uri);
Image img = new Image();
img.Source = file;
Menggunakan sumber aliran untuk menampilkan gambar dari pustaka Gambar
Penggunaan umum elemen Gambar dalam aplikasi adalah menampilkan gambar dari pustaka Gambar pengguna. Gambar-gambar ini mungkin diakses secara terprogram atau melalui FileOpenPicker. Dalam kedua kasus, objek StorageFile yang Anda dapatkan dapat dibuka sebagai aliran, tetapi tidak memberikan referensi Pengidentifikasi Sumber Daya Seragam (URI) ke file gambar. Untuk menggunakan aliran sebagai sumber gambar, Anda harus menulis kode yang mengatur instans Gambar Anda untuk menggunakan aliran. Ini tidak dapat dilakukan di XAML saja.
Untuk menampilkan gambar individual, gunakan objek StorageFile dari menghitung pustaka dan memanggil OpenAsync untuk mendapatkan aliran. Gunakan aliran ini untuk mengatur sumber gambar, dengan membuat BitmapImage baru, lalu memanggil SetSourceAsync dan meneruskan aliran untuk digunakan sebagai parameter streamSource .
Contoh ini memperlihatkan cara menggunakan FileOpenPicker untuk mengakses file gambar dari pustaka Gambar dan mengaturnya sebagai Sumber kontrol Gambar . Kode sudah dapat ditunggu karena menunggu pengguna memilih file dan hanya berjalan setelah itu terjadi. Aliran yang akan digunakan berasal dari StorageFile.OpenAsync setelah instans StorageFile dikembalikan dari tindakan pemilih asinkron. Untuk informasi selengkapnya tentang menggunakan pemilih file, lihat Membuka file dan folder dengan pemilih.
<Button Content="Get photo" Click="GetPhotoButton_Click"/>
<Image x:Name="image1" Width="300"/>
private async void GetPhotoButton_Click(object sender, RoutedEventArgs e)
{
// Set up the file picker.
Windows.Storage.Pickers.FileOpenPicker openPicker =
new Windows.Storage.Pickers.FileOpenPicker();
openPicker.SuggestedStartLocation =
Windows.Storage.Pickers.PickerLocationId.PicturesLibrary;
openPicker.ViewMode =
Windows.Storage.Pickers.PickerViewMode.Thumbnail;
// Filter to include a sample subset of file types.
openPicker.FileTypeFilter.Clear();
openPicker.FileTypeFilter.Add(".bmp");
openPicker.FileTypeFilter.Add(".png");
openPicker.FileTypeFilter.Add(".jpeg");
openPicker.FileTypeFilter.Add(".jpg");
// Open the file picker.
Windows.Storage.StorageFile file =
await openPicker.PickSingleFileAsync();
// 'file' is null if user cancels the file picker.
if (file != null)
{
// Open a stream for the selected file.
// The 'using' block ensures the stream is disposed
// after the image is loaded.
using (Windows.Storage.Streams.IRandomAccessStream fileStream =
await file.OpenAsync(Windows.Storage.FileAccessMode.Read))
{
// Set the image source to the selected bitmap.
Windows.UI.Xaml.Media.Imaging.BitmapImage bitmapImage =
new Windows.UI.Xaml.Media.Imaging.BitmapImage();
bitmapImage.SetSource(fileStream);
image1.Source = bitmapImage;
}
}
}
Contoh ini menunjukkan cara mengakses file gambar secara terprogram dari pustaka Gambar dan mengaturnya sebagai Sumber kontrol Gambar . Untuk mengakses konten pustaka Gambar secara terprogram, panggil StorageFolder.GetFilesAsync. Ingatlah bahwa Anda perlu menentukan kemampuan untuk mengakses pustaka Gambar secara terprogram.
protected async override void OnNavigatedTo(NavigationEventArgs e)
{
// Get the Pictures library
Windows.Storage.StorageFolder picturesFolder =
Windows.Storage.KnownFolders.PicturesLibrary;
IReadOnlyList<StorageFolder> folders =
await picturesFolder.GetFoldersAsync();
// Process file folders
foreach (StorageFolder folder in folders)
{
// Get and process files in folder
IReadOnlyList<StorageFile> fileList = await folder.GetFilesAsync();
foreach (StorageFile file in fileList)
{
Windows.UI.Xaml.Media.Imaging.BitmapImage bitmapImage =
new Windows.UI.Xaml.Media.Imaging.BitmapImage();
// Open a stream for the selected file.
// The 'using' block ensures the stream is disposed
// after the image is loaded.
using (Windows.Storage.Streams.IRandomAccessStream fileStream =
await file.OpenAsync(Windows.Storage.FileAccessMode.Read))
{
// Set the image source to the selected bitmap.
Windows.UI.Xaml.Media.Imaging.BitmapImage bitmapImage =
new Windows.UI.Xaml.Media.Imaging.BitmapImage();
bitmapImage.SetSource(fileStream);
// Create an Image control.
Image img = new Image();
img.Height = 50;
img.Source = bitmapImage;
// Add the Image control to the UI. 'imageGrid' is a
// VariableSizedWrapGrid declared in the XAML page.
imageGrid.Children.Add(img);
}
}
}
}
Sumber dan penskalakan gambar
Jika Anda mereferensikan gambar yang dipaketkan di aplikasi, Anda harus membuat sumber gambar pada beberapa ukuran yang direkomendasikan, untuk memastikan bahwa aplikasi Anda terlihat hebat saat Windows Runtime menskalakannya. Saat menentukan Sumber untuk Gambar sebagai Pengidentifikasi Sumber Daya Seragam (URI), Anda dapat menggunakan konvensi penamaan yang akan secara otomatis mereferensikan sumber daya gambar yang benar untuk penskalaan saat ini seperti yang terdeteksi oleh sistem pada run-time. Untuk detail konvensi penamaan dan info selengkapnya, lihat Mulai Cepat: Menggunakan sumber daya file atau gambar.
Untuk informasi selengkapnya tentang cara mendesain penskalaan, lihat Ukuran layar dan titik henti atau Keterangan dalam Gambar.
Sumber gambar dan kualifikasi sumber daya
Anda dapat menggunakan penanganan otomatis untuk mengakses sumber daya yang tidak memenuhi syarat dengan kualifikasi skala dan budaya saat ini, atau Anda dapat menggunakan ResourceManager dan ResourceMap dengan kualifikasi untuk budaya dan skala untuk mendapatkan sumber daya secara langsung. Untuk informasi selengkapnya, lihat Sistem manajemen sumber daya atau Keterangan dalam Gambar. Untuk informasi selengkapnya tentang sumber daya aplikasi dan cara mengemas sumber gambar di aplikasi, lihat Menentukan sumber daya aplikasi.
Berlaku untuk
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk