Memuat gambar dan aset yang disesuaikan untuk skala, tema, kontras tinggi, dan banyak lagi

Artikel
08/17/2023

Aplikasi Anda dapat memuat file sumber daya gambar (atau file aset lainnya) yang disesuaikan untuk faktor skala tampilan, tema, kontras tinggi, dan konteks runtime lainnya. Gambar-gambar ini dapat dirujuk dari kode imperatif atau dari markup XAML, misalnya sebagai properti Sumber gambar. Mereka juga dapat muncul di file sumber manifes paket aplikasi Anda ( Package.appxmanifest file)—misalnya, sebagai nilai untuk Ikon Aplikasi pada tab Aset Visual dari Visual Studio Manifest Designer—atau pada petak peta dan roti panggang Anda. Dengan menggunakan kualifikasi dalam nama file gambar Anda, dan secara opsional memuatnya secara dinamis dengan bantuan ResourceContext, Anda dapat menyebabkan file gambar yang paling tepat dimuat yang paling sesuai dengan pengaturan runtime pengguna untuk skala tampilan, tema, kontras tinggi, bahasa, dan konteks lainnya.

Sumber daya gambar terkandung dalam file sumber daya gambar. Anda juga dapat menganggap gambar sebagai aset, dan file yang berisinya sebagai file aset; dan Anda dapat menemukan jenis file sumber daya ini di folder \Aset proyek Anda. Untuk latar belakang tentang cara menggunakan kualifikasi dalam nama file sumber daya gambar Anda, lihat Menyesuaikan sumber daya Anda untuk bahasa, skala, dan kualifikasi lainnya.

Beberapa kualifikasi umum untuk gambar adalah skala, tema, kontras, dan targetsize.

Memenuhi syarat sumber daya gambar untuk skala, tema, dan kontras

Nilai default untuk kualifikasi scale adalah scale-100. Jadi, kedua varian ini setara (keduanya menyediakan gambar dalam skala 100, atau faktor skala 1).

\Assets\Images\logo.png
\Assets\Images\logo.scale-100.png

Anda dapat menggunakan kualifikasi dalam nama folder alih-alih nama file. Itu akan menjadi strategi yang lebih baik jika Anda memiliki beberapa file aset per kualifikasi. Untuk tujuan ilustrasi, kedua varian ini setara dengan dua di atas.

\Assets\Images\logo.png
\Assets\Images\scale-100\logo.png

Selanjutnya adalah contoh bagaimana Anda dapat menyediakan varian sumber daya gambar—bernama /Assets/Images/logo.png—untuk pengaturan skala tampilan, tema, dan kontras tinggi yang berbeda. Contoh ini menggunakan penamaan folder.

\Assets\Images\contrast-standard\theme-dark
	\scale-100\logo.png
	\scale-200\logo.png
\Assets\Images\contrast-standard\theme-light
	\scale-100\logo.png
	\scale-200\logo.png
\Assets\Images\contrast-high
	\scale-100\logo.png
	\scale-200\logo.png

Mereferensikan gambar atau aset lain dari markup dan kode XAML

Nama—atau pengidentifikasi—dari sumber daya gambar adalah jalur dan nama filenya dengan salah satu dan semua kualifikasi yang dihapus. Jika Anda menamai folder dan/atau file seperti dalam salah satu contoh di bagian sebelumnya, maka Anda memiliki satu sumber daya gambar dan namanya (sebagai jalur absolut) adalah /Assets/Images/logo.png. Berikut adalah cara Anda menggunakan nama tersebut di markup XAML.

<Image x:Name="myXAMLImageElement" Source="ms-appx:///Assets/Images/logo.png"/>

Perhatikan bahwa Anda menggunakan ms-appx skema URI karena Anda merujuk ke file yang berasal dari paket aplikasi Anda. Lihat skema URI. Dan berikut adalah cara Anda merujuk ke sumber daya gambar yang sama dalam kode imperatif.

this.myXAMLImageElement.Source = new BitmapImage(new Uri("ms-appx:///Assets/Images/logo.png"));

Anda dapat menggunakan ms-appx untuk memuat file arbitrer apa pun dari paket aplikasi Anda.

var uri = new System.Uri("ms-appx:///Assets/anyAsset.ext");
var storagefile = await Windows.Storage.StorageFile.GetFileFromApplicationUriAsync(uri);

ms-appx-web Skema mengakses file yang sama dengan ms-appx, tetapi di kompartemen web.

<WebView x:Name="myXAMLWebViewElement" Source="ms-appx-web:///Pages/default.html"/>

this.myXAMLWebViewElement.Source = new Uri("ms-appx-web:///Pages/default.html");

Untuk salah satu skenario yang ditunjukkan dalam contoh ini, gunakan kelebihan beban konstruktor Uri yang menyimpulkan UriKind. Tentukan URI absolut yang valid termasuk skema dan otoritas, atau biarkan otoritas default ke paket aplikasi seperti dalam contoh di atas.

Perhatikan bagaimana dalam contoh ini URI skema ("ms-appx" atau "ms-appx-web") diikuti oleh "://" yang diikuti oleh jalur absolut. Dalam jalur absolut, "/" terkemuka menyebabkan jalur ditafsirkan dari akar paket.

Catatan

ms-resource Skema URI (untuk sumber daya string) dan ms-appx(-web) (untuk gambar dan aset lainnya) melakukan pencocokan kualifikasi otomatis untuk menemukan sumber daya yang paling sesuai untuk konteks saat ini. Skema ms-appdata URI (yang digunakan untuk memuat data aplikasi) tidak melakukan pencocokan otomatis seperti itu, tetapi Anda dapat menanggapi konten ResourceContext.QualifierValues dan secara eksplisit memuat aset yang sesuai dari data aplikasi menggunakan nama file fisik lengkapnya di URI. Untuk informasi tentang data aplikasi, lihat Menyimpan dan mengambil pengaturan dan data aplikasi lainnya. Skema URI web (misalnya, , http, httpsdan ftp) juga tidak melakukan pencocokan otomatis. Untuk informasi tentang apa yang harus dilakukan dalam hal ini, lihat Menghosting dan memuat gambar di cloud.

Jalur absolut adalah pilihan yang baik jika file gambar Anda tetap berada di tempatnya berada dalam struktur proyek. Jika Anda ingin dapat memindahkan file gambar, tetapi Anda berhati-hati bahwa file tersebut tetap berada di lokasi yang sama relatif terhadap file markup XAML yang mereferensikannya, maka alih-alih jalur absolut, Anda mungkin ingin menggunakan jalur yang relatif terhadap file markup yang berisi. Jika Anda melakukan itu, maka Anda tidak perlu menggunakan skema URI. Anda masih akan mendapat manfaat dari pencocokan kualifikasi otomatis dalam kasus ini, tetapi hanya karena Anda menggunakan jalur relatif dalam markup XAML.

<Image Source="Assets/Images/logo.png"/>

Lihat juga Dukungan petak peta dan roti panggang untuk bahasa, skala, dan kontras tinggi.

Memenuhi syarat sumber daya gambar untuk targetsize

Anda dapat menggunakan scale targetsize dan kualifikasi pada varian yang berbeda dari sumber daya gambar yang sama; tetapi Anda tidak dapat menggunakannya pada satu varian sumber daya. Selain itu, Anda perlu menentukan setidaknya satu varian tanpa TargetSize kualifikasi. Varian tersebut harus menentukan nilai untuk scale, atau membiarkannya default ke scale-100. Jadi, kedua varian sumber daya ini /Assets/Square44x44Logo.png valid.

\Assets\Square44x44Logo.scale-200.png
\Assets\Square44x44Logo.targetsize-24.png

Dan kedua varian ini valid.

\Assets\Square44x44Logo.png // defaults to scale-100
\Assets\Square44x44Logo.targetsize-24.png

Tetapi varian ini tidak valid.

\Assets\Square44x44Logo.scale-200_targetsize-24.png

Lihat file gambar dari manifes paket aplikasi Anda

Jika Anda menamai folder dan/atau file seperti di salah satu dari dua contoh yang valid di bagian sebelumnya, maka Anda memiliki satu sumber daya gambar ikon aplikasi dan namanya (sebagai jalur relatif) adalah Assets\Square44x44Logo.png. Dalam manifes paket aplikasi Anda, cukup lihat sumber daya berdasarkan nama. Tidak perlu menggunakan skema URI apa pun.

Itu saja yang perlu Anda lakukan, dan OS akan melakukan pencocokan kualifikasi otomatis untuk menemukan sumber daya yang paling sesuai untuk konteks saat ini. Untuk daftar semua item dalam manifes paket aplikasi yang dapat Anda lokalkan atau memenuhi syarat dengan cara ini, lihat Item manifes yang dapat dilokalkan.

Memenuhi syarat sumber daya gambar untuk pengalihan tata letak

Lihat Mencerminkan gambar.

Memuat gambar untuk bahasa tertentu atau konteks lainnya

Untuk informasi selengkapnya tentang proposisi nilai pelokalan aplikasi Anda, lihat Globalisasi dan pelokalan.

ResourceContext default (diperoleh dari ResourceContext.GetForCurrentView) berisi nilai kualifikasi untuk setiap nama kualifikasi, yang mewakili konteks runtime default (dengan kata lain, pengaturan untuk pengguna dan komputer saat ini). File gambar dicocokkan—berdasarkan kualifikasi dalam namanya—terhadap nilai kualifikasi dalam konteks runtime tersebut.

Tetapi mungkin ada kalanya Anda ingin aplikasi Anda mengambil alih pengaturan sistem dan secara eksplisit tentang bahasa, skala, atau nilai kualifikasi lainnya untuk digunakan saat mencari gambar yang cocok untuk dimuat. Misalnya, Anda mungkin ingin mengontrol kapan dan gambar kontras tinggi mana yang dimuat.

Anda dapat melakukannya dengan membuat ResourceContext baru (alih-alih menggunakan yang default), mengganti nilainya, lalu menggunakan objek konteks tersebut dalam pencarian gambar Anda.

var resourceContext = new Windows.ApplicationModel.Resources.Core.ResourceContext(); // not using ResourceContext.GetForCurrentView 
resourceContext.QualifierValues["Contrast"] = "high";
var namedResource = Windows.ApplicationModel.Resources.Core.ResourceManager.Current.MainResourceMap[@"Files/Assets/Logo.png"];
var resourceCandidate = namedResource.Resolve(resourceContext);
var imageFileStream = resourceCandidate.GetValueAsStreamAsync().GetResults();
var bitmapImage = new Windows.UI.Xaml.Media.Imaging.BitmapImage();
bitmapImage.SetSourceAsync(imageFileStream);
this.myXAMLImageElement.Source = bitmapImage;

Untuk mencapai efek yang sama di tingkat global, Anda dapat mengambil alih nilai kualifikasi di ResourceContext default. Tetapi sebagai gantinya, kami menyarankan Anda untuk memanggil ResourceContext.SetGlobalQualifierValue. Anda mengatur nilai satu kali dengan panggilan ke SetGlobalQualifierValue lalu nilai tersebut berlaku pada ResourceContext default setiap kali Anda menggunakannya untuk pencarian. Secara default, kelas ResourceManager menggunakan ResourceContext default.

Windows.ApplicationModel.Resources.Core.ResourceContext.SetGlobalQualifierValue("Contrast", "high");
var namedResource = Windows.ApplicationModel.Resources.Core.ResourceManager.Current.MainResourceMap[@"Files/Assets/Logo.png"];
this.myXAMLImageElement.Source = new Windows.UI.Xaml.Media.Imaging.BitmapImage(namedResource.Uri);

Memperbarui gambar sebagai respons terhadap peristiwa perubahan nilai kualifikasi

Aplikasi yang sedang berjalan dapat merespons perubahan pengaturan sistem yang memengaruhi nilai kualifikasi dalam konteks sumber daya default. Salah satu pengaturan sistem ini memanggil peristiwa MapChanged di ResourceContext.QualifierValues.

Sebagai respons terhadap peristiwa ini, Anda dapat memuat ulang gambar Anda dengan bantuan ResourceContext default, yang digunakan ResourceManager secara default.

public MainPage()
{
    this.InitializeComponent();

    ...

    // Subscribe to the event that's raised when a qualifier value changes.
    var qualifierValues = Windows.ApplicationModel.Resources.Core.ResourceContext.GetForCurrentView().QualifierValues;
    qualifierValues.MapChanged += new Windows.Foundation.Collections.MapChangedEventHandler<string, string>(QualifierValues_MapChanged);
}

private async void QualifierValues_MapChanged(IObservableMap<string, string> sender, IMapChangedEventArgs<string> @event)
{
    var dispatcher = this.myImageXAMLElement.Dispatcher;
    if (dispatcher.HasThreadAccess)
    {
        this.RefreshUIImages();
    }
    else
    {
        await dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () => this.RefreshUIImages());
    }
}

private void RefreshUIImages()
{
    var namedResource = Windows.ApplicationModel.Resources.Core.ResourceManager.Current.MainResourceMap[@"Files/Assets/Logo.png"];
    this.myImageXAMLElement.Source = new Windows.UI.Xaml.Media.Imaging.BitmapImage(namedResource.Uri);
}

Bagikan melalui

Memuat gambar dan aset yang disesuaikan untuk skala, tema, kontras tinggi, dan banyak lagi

Memenuhi syarat sumber daya gambar untuk skala, tema, dan kontras

Mereferensikan gambar atau aset lain dari markup dan kode XAML

Memenuhi syarat sumber daya gambar untuk targetsize

Lihat file gambar dari manifes paket aplikasi Anda

Memenuhi syarat sumber daya gambar untuk pengalihan tata letak

Memuat gambar untuk bahasa tertentu atau konteks lainnya

Memperbarui gambar sebagai respons terhadap peristiwa perubahan nilai kualifikasi

API penting

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Memuat gambar dan aset yang disesuaikan untuk skala, tema, kontras tinggi, dan banyak lagi

Memenuhi syarat sumber daya gambar untuk skala, tema, dan kontras

Mereferensikan gambar atau aset lain dari markup dan kode XAML

Memenuhi syarat sumber daya gambar untuk targetsize

Lihat file gambar dari manifes paket aplikasi Anda

Memenuhi syarat sumber daya gambar untuk pengalihan tata letak

Memuat gambar untuk bahasa tertentu atau konteks lainnya

Memperbarui gambar sebagai respons terhadap peristiwa perubahan nilai kualifikasi

API penting

Topik terkait

Saran dan Komentar

Sumber Daya Tambahan: