Sesuaikan sumber daya Anda untuk bahasa, skala, kontras tinggi, dan kualifikasi lainnya

  • Artikel

Topik ini menjelaskan konsep umum kualifikasi sumber daya, cara menggunakannya, dan tujuan masing-masing nama kualifikasi. Lihat ResourceContext.QualifierValues untuk tabel referensi semua nilai kualifikasi yang mungkin.

Aplikasi Anda dapat memuat aset dan sumber daya yang disesuaikan dengan konteks runtime seperti bahasa tampilan, kontras tinggi, faktor skala tampilan, dan banyak lainnya. Cara Anda melakukan ini adalah dengan memberi nama folder atau file sumber daya Anda agar sesuai dengan nama kualifikasi dan nilai kualifikasi yang sesuai dengan konteks tersebut. Misalnya, Anda mungkin ingin aplikasi memuat sekumpulan aset gambar yang berbeda dalam mode kontras tinggi.

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

Nama kualifikasi, nilai kualifikasi, dan kualifikasi

Nama kualifikasi adalah kunci yang memetakan ke sekumpulan nilai kualifikasi. Berikut adalah nama kualifikasi dan nilai kualifikasi untuk kontras.

Konteks Nama kualifikasi Nilai kualifikasi
Pengaturan kontras tinggi Kontras standar, tinggi, hitam, putih

Anda menggabungkan nama kualifikasi dengan nilai kualifikasi untuk membentuk kualifikasi. <qualifier name>-<qualifier value> adalah format kualifikasi. contrast-standard adalah contoh kualifikasi.

Jadi, untuk kontras tinggi, set kualifikasi adalah contrast-standard, , contrast-highcontrast-black, dan contrast-white. Nama kualifikasi dan nilai kualifikasi tidak peka huruf besar/kecil. Misalnya, contrast-standard dan Contrast-Standard merupakan kualifikasi yang sama.

Gunakan kualifikasi dalam nama folder

Berikut adalah contoh penggunaan kualifikasi untuk memberi nama folder yang berisi file aset. Gunakan kualifikasi dalam nama folder jika Anda memiliki beberapa file aset per kualifikasi. Dengan begitu, Anda mengatur kualifikasi sekali di tingkat folder, dan kualifikasi berlaku untuk semua yang ada di dalam folder.

\Assets\Images\contrast-standard\<logo.png, and other image files>
\Assets\Images\contrast-high\<logo.png, and other image files>
\Assets\Images\contrast-black\<logo.png, and other image files>
\Assets\Images\contrast-white\<logo.png, and other image files>

Jika Anda memberi nama folder seperti pada contoh di atas, maka aplikasi Anda menggunakan pengaturan kontras tinggi untuk memuat file sumber daya dari folder bernama untuk kualifikasi yang sesuai. Jadi, jika pengaturannya adalah High Contrast Black, maka file sumber daya di folder dimuat \Assets\Images\contrast-black . Jika pengaturannya tidak ada (yaitu, komputer tidak dalam mode kontras tinggi), maka file sumber daya dalam \Assets\Images\contrast-standard folder dimuat.

Gunakan kualifikasi dalam nama file

Alih-alih membuat dan menamai folder, Anda dapat menggunakan kualifikasi untuk memberi nama file sumber daya itu sendiri. Anda mungkin lebih suka melakukan ini jika Anda hanya memiliki satu file sumber daya per kualifikasi. Berikut adalah contohnya.

\Assets\Images\logo.contrast-standard.png
\Assets\Images\logo.contrast-high.png
\Assets\Images\logo.contrast-black.png
\Assets\Images\logo.contrast-white.png

File yang namanya berisi kualifikasi yang paling tepat untuk pengaturan adalah file yang dimuat. Logika yang cocok ini berfungsi dengan cara yang sama untuk nama file seperti untuk nama folder.

Mereferensikan string atau sumber daya gambar menurut nama

Lihat Merujuk ke pengidentifikasi sumber daya string dari markup XAML, Lihat pengidentifikasi sumber daya string dari kode, dan Mereferensikan gambar atau aset lain dari markup dan kode XAML.

Kecocokan kualifikasi aktual dan netral

Anda tidak perlu menyediakan file sumber daya untuk setiap nilai kualifikasi. Misalnya, jika Anda menemukan bahwa Anda hanya memerlukan satu aset visual untuk kontras tinggi dan satu untuk kontras standar, maka Anda dapat memberi nama aset tersebut seperti ini.

\Assets\Images\logo.contrast-high.png
\Assets\Images\logo.png

Nama file pertama berisi kualifikasi contrast-high . Kualifikasi tersebut adalah kecocokan aktual untuk pengaturan kontras tinggi saat kontras tinggi aktif. Dengan kata lain, ini adalah kecocokan yang dekat sehingga lebih disukai. Kecocokan aktual hanya dapat terjadi jika kualifikasi berisi nilai aktual , seperti yang satu ini. Dalam hal ini, high adalah nilai aktual untuk contrast.

File bernama logo.png tidak memiliki kualifikasi kontras di atasnya sama sekali. Tidak adanya kualifikasi adalah nilai netral . Jika tidak ada kecocokan pilihan yang dapat ditemukan, maka nilai netral berfungsi sebagai kecocokan fallback. Dalam contoh ini, jika kontras tinggi nonaktif, maka tidak ada kecocokan aktual. Kecocokan netral adalah kecocokan terbaik yang dapat ditemukan, sehingga aset logo.png dimuat.

Jika Anda mengubah nama logo.png menjadi logo.contrast-standard.png, maka nama file akan berisi nilai kualifikasi aktual. Dengan kontras tinggi, akan ada kecocokan aktual dengan logo.contrast-standard.png, dan itulah file aset yang akan dimuat. Jadi, file yang sama akan dimuat, dalam kondisi yang sama, tetapi karena kecocokan yang berbeda.

Jika Anda hanya memerlukan satu set aset untuk kontras tinggi dan satu set untuk kontras standar, maka Anda dapat menggunakan nama folder alih-alih nama file. Dalam hal ini, menghilangkan nama folder sepenuhnya memberi Anda kecocokan netral.

\Assets\Images\contrast-high\<logo.png, and other images to load when high contrast theme is not None>
\Assets\Images\<logo.png, and other images to load when high contrast theme is None>

Untuk detail selengkapnya tentang cara kerja pencocokan kualifikasi, lihat Sistem Manajemen Sumber Daya.

Beberapa kualifikasi

Anda dapat menggabungkan kualifikasi dalam nama folder dan file. Misalnya, Anda mungkin ingin aplikasi memuat aset gambar saat mode kontras tinggi aktif dan faktor skala tampilan adalah 400. Salah satu cara untuk melakukan ini adalah dengan folder berlapis.

\Assets\Images\contrast-high\scale-400\<logo.png, and other image files>

Agar logo.png dan file lain yang akan dimuat, pengaturan harus cocok dengan kedua kualifikasi.

Opsi lain adalah menggabungkan beberapa kualifikasi dalam satu nama folder.

\Assets\Images\contrast-high_scale-400\<logo.png, and other image files>

Dalam nama folder, Anda menggabungkan beberapa kualifikasi yang dipisahkan dengan garis bawah. <qualifier1>[_<qualifier2>...] adalah formatnya.

Anda dapat menggabungkan beberapa kualifikasi dalam nama file dalam format yang sama.

\Assets\Images\logo.contrast-high_scale-400.png

Bergantung pada alat dan alur kerja yang Anda gunakan untuk pembuatan aset, atau pada apa yang paling mudah dibaca dan/atau dikelola, Anda dapat memilih satu strategi penamaan untuk semua kualifikasi, atau Anda dapat menggabungkannya untuk kualifikasi yang berbeda.

AlternateForm

Kualifikasi alternateform digunakan untuk menyediakan bentuk alternatif sumber daya untuk beberapa tujuan khusus. Ini biasanya hanya digunakan oleh pengembang aplikasi Jepang untuk menyediakan string furigana yang nilainya msft-phonetic dicadangkan (lihat bagian "Mendukung Furigana untuk string Jepang yang dapat diurutkan" di Cara mempersiapkan pelokalan).

Baik sistem target atau aplikasi Anda harus memberikan nilai yang cocok dengan alternateform kualifikasi. Jangan gunakan awalan msft- untuk nilai kualifikasi kustom alternateform Anda sendiri.

Konfigurasi

Tidak mungkin Anda memerlukan configuration nama kualifikasi. Ini dapat digunakan untuk menentukan sumber daya yang hanya berlaku untuk lingkungan waktu penulisan tertentu, seperti sumber daya khusus pengujian.

Kualifikasi configuration digunakan untuk memuat sumber daya yang paling cocok dengan nilai MS_CONFIGURATION_ATTRIBUTE_VALUE variabel lingkungan. Jadi, Anda dapat mengatur variabel ke nilai string yang telah ditetapkan ke sumber daya yang relevan, misalnya designer, atau test.

Kontras

Kualifikasi contrast digunakan untuk menyediakan sumber daya yang paling cocok dengan pengaturan kontras tinggi.

Kustom

Aplikasi Anda dapat menetapkan nilai untuk kualifikasi, lalu sumber daya dimuat yang paling cocok dengan nilai tersebut custom . Misalnya, Anda mungkin ingin memuat sumber daya berdasarkan lisensi aplikasi Anda. Saat aplikasi Anda diluncurkan, aplikasi memeriksa lisensinya dan menggunakannya sebagai nilai untuk custom kualifikasi dengan memanggil SetGlobalQualifierValue, seperti yang ditunjukkan dalam contoh kode.

public void SetLicenseLevel(BrandID brand)
{
    if (brand == BrandID.Premium)
    {
        ResourceContext.SetGlobalQualifierValue("Custom", "Premium", ResourceQualifierPersistence.LocalMachine);
    }
    else if (brand == BrandID.Standard)
    {
        ResourceContext.SetGlobalQualifierValue("Custom", " Standard", ResourceQualifierPersistence.LocalMachine);
    }
    else
    {
        ResourceContext.SetGlobalQualifierValue("Custom", "Trial", ResourceQualifierPersistence.LocalMachine);
    }
}

Dalam skenario ini, Anda kemudian akan memberikan nama sumber daya Anda yang menyertakan kualifikasi custom-premium, , custom-standarddan custom-trial.

DeviceFamily

Tidak mungkin Anda memerlukan devicefamily nama kualifikasi. Anda dapat dan harus menghindari penggunaannya jika memungkinkan karena ada teknik yang dapat Anda gunakan sebagai gantinya yang jauh lebih nyaman dan kuat. Teknik tersebut dijelaskan dalam Mendeteksi platform yang dijalankan aplikasi Anda dan Kode adaptif versi.

Tetapi sebagai upaya terakhir, dimungkinkan untuk menggunakan kualifikasi devicefamily untuk memberi nama folder yang berisi tampilan XAML Anda (tampilan XAML adalah file XAML yang berisi tata letak dan kontrol UI).

\devicefamily-desktop\<MainPage.xaml, and other markup files to load when running on a desktop computer>
\devicefamily-mobile\<MainPage.xaml, and other markup files to load when running on a phone>

Atau Anda dapat memberi nama file.

\MainPage.devicefamily-desktop.xaml
\MainPage.devicefamily-mobile.xaml

Dalam kedua kasus, setiap salinan MainPage.[<qualifier>].xaml berbagi umum MainPage.xaml.cs, yang tetap tidak berubah dalam proyek Anda dalam hal nama, lokasi, dan konten.

Anda juga dapat menggunakan kualifikasi devicefamily untuk memberi nama File Sumber Daya (.resw), atau folder. Misalnya, saat aplikasi Anda berjalan di keluarga perangkat seluler, elemen <TextBlock x:Uid="DeviceFriendlyName"/> UI akan menggunakan teks dan sumber daya latar depan yang ditentukan dalam file Anda Resources.devicefamily-mobile.resw jika berisi

<data name="DeviceFriendlyName.Foreground">
    <value>Red</value>
</data>
<data name="DeviceFriendlyName.Text">
    <value>Mobile device</value>
</data>

Untuk informasi selengkapnya tentang menggunakan File Sumber Daya, lihat Melokalkan string UI Anda.

DXFeatureLevel

Tidak mungkin Anda memerlukan dxfeaturelevel nama kualifikasi. Ini dirancang untuk digunakan dengan aset game Direct3D, untuk menyebabkan sumber daya tingkat bawah dimuat agar sesuai dengan konfigurasi perangkat keras tingkat bawah tertentu pada saat itu. Tetapi prevalensi konfigurasi perangkat keras tersebut sekarang sangat rendah sehingga kami sarankan Anda tidak menggunakan kualifikasi ini.

HomeRegion

Kualifikasi homeregion sesuai dengan pengaturan pengguna untuk negara atau wilayah. Ini mewakili lokasi beranda pengguna. Nilai mencakup tag wilayah BCP-47 yang valid. Artinya, kode wilayah dua huruf ISO 3166-1 alpha-2 , ditambah set kode geografis tiga digit numerik ISO 3166-1 untuk wilayah yang disusun (lihat Komposisi kode wilayah Divisi Statistik PBB M49). Kode untuk "Pengelompokan ekonomi dan lainnya yang dipilih" tidak valid.

Bahasa

Kualifikasi language sesuai dengan pengaturan bahasa tampilan. Nilai mencakup tag bahasa BCP-47 yang valid. Untuk daftar bahasa, lihat registri subtag bahasa IANA.

Jika Anda ingin aplikasi mendukung bahasa tampilan yang berbeda, dan Anda memiliki literal string dalam kode atau di markup XAML, maka pindahkan string tersebut keluar dari kode/markup dan ke File Sumber Daya (.resw). Anda kemudian dapat membuat salinan terjemahan File Sumber Daya tersebut untuk setiap bahasa yang didukung aplikasi Anda.

Anda biasanya menggunakan language kualifikasi untuk memberi nama folder yang berisi File Sumber Daya Anda (.resw).

\Strings\language-en\Resources.resw
\Strings\language-ja\Resources.resw

Anda dapat menghilangkan language- bagian dari language kualifikasi (yaitu, nama kualifikasi). Anda tidak dapat melakukan ini dengan jenis kualifikasi lainnya; dan Anda hanya dapat melakukannya dalam nama folder.

\Strings\en\Resources.resw
\Strings\ja\Resources.resw

Alih-alih menamai folder, Anda dapat menggunakan language kualifikasi untuk memberi nama File Sumber Daya itu sendiri.

\Strings\Resources.language-en.resw
\Strings\Resources.language-ja.resw

Lihat Melokalkan string UI Anda untuk informasi selengkapnya tentang membuat aplikasi Anda dapat dilokalkan dengan menggunakan sumber daya string, dan cara mereferensikan sumber daya string di aplikasi Anda.

LayoutDirection

Kualifikasi layoutdirection sesuai dengan arah tata letak pengaturan bahasa tampilan. Misalnya, gambar mungkin perlu dicerminkan untuk bahasa kanan-ke-kiri seperti Arab atau Ibrani. Panel tata letak dan gambar di UI Anda akan merespons arah tata letak dengan tepat jika Anda mengatur properti FlowDirection mereka (lihat Menyesuaikan tata letak dan font, dan mendukung RTL). Namun, layoutdirection kualifikasi adalah untuk kasus-kasus di mana membalik sederhana tidak memadai, dan memungkinkan Anda untuk menanggapi arah urutan membaca dan perataan teks tertentu dengan cara yang lebih umum.

Skala

Windows secara otomatis memilih faktor skala untuk setiap tampilan berdasarkan DPI-nya (titik-per-inci) dan jarak tampilan perangkat. Lihat Piksel dan faktor skala yang efektif. Anda harus membuat gambar Anda pada beberapa ukuran yang direkomendasikan (setidaknya 100, 200, dan 400) sehingga Windows dapat memilih ukuran yang sempurna atau dapat menggunakan ukuran terdekat dan menskalakannya. Sehingga Windows dapat mengidentifikasi file fisik mana yang berisi ukuran gambar yang benar untuk faktor skala tampilan, Anda menggunakan scale kualifikasi. Skala sumber daya cocok dengan nilai DisplayInformation.ResolutionScale, atau sumber daya berskala terbesar berikutnya.

Berikut adalah contoh pengaturan kualifikasi di tingkat folder.

\Assets\Images\scale-100\<logo.png, and other image files>
\Assets\Images\scale-200\<logo.png, and other image files>
\Assets\Images\scale-400\<logo.png, and other image files>

Dan contoh ini mengaturnya di tingkat file.

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

Untuk informasi tentang memenuhi syarat sumber daya untuk dan scaletargetsize, lihat Memenuhi syarat sumber daya gambar untuk targetsize.

TargetSize

Kualifikasi targetsize terutama digunakan untuk menentukan ikon asosiasi jenis file atau ikon protokol yang akan ditampilkan dalam File Explorer. Nilai kualifikasi mewakili panjang samping gambar persegi dalam piksel mentah (fisik). Sumber daya yang nilainya cocok dengan pengaturan Tampilan di File Explorer dimuat; atau sumber daya dengan nilai terbesar berikutnya dengan tidak adanya kecocokan yang tepat.

Anda dapat menentukan aset yang mewakili beberapa ukuran targetsize nilai kualifikasi untuk Ikon Aplikasi (/Assets/Square44x44Logo.png) di tab Aset Visual dari perancang manifes paket aplikasi.

Untuk informasi tentang memenuhi syarat sumber daya untuk dan scaletargetsize, lihat Memenuhi syarat sumber daya gambar untuk targetsize.

Tema

Kualifikasi theme digunakan untuk menyediakan sumber daya yang paling cocok dengan pengaturan mode aplikasi default, atau penimpaan aplikasi Anda menggunakan Application.RequestedTheme.

Tema cahaya shell dan sumber daya yang tidak diplika

Pembaruan Windows 10 Mei 2019 memperkenalkan tema "ringan" baru untuk Windows Shell. Akibatnya, beberapa aset aplikasi yang sebelumnya ditampilkan pada latar belakang gelap sekarang akan ditampilkan pada latar belakang terang. Untuk aplikasi yang menyediakan aset altform-unplated untuk taskbar dan pengalih jendela (Alt+Tab, Tampilan Tugas, dll), Anda harus memverifikasi bahwa mereka memiliki kontras yang dapat diterima pada latar belakang yang ringan.

Menyediakan aset spesifik tema ringan

Aplikasi yang ingin menyediakan sumber daya yang disesuaikan untuk tema cahaya shell dapat menggunakan kualifikasi sumber daya bentuk alternatif baru: altform-lightunplated. Kualifikasi ini mencerminkan kualifikasi altform-unplated yang ada.

Pertimbangan tingkat bawah

Aplikasi tidak boleh menggunakan theme-light kualifikasi dengan altform-unplated kualifikasi. Ini akan menyebabkan perilaku yang tidak dapat diprediksi pada RS5 dan versi Windows yang lebih lama karena cara sumber daya dimuat untuk Taskbar. Pada versi windows yang lebih lama, versi tema-ringan mungkin salah digunakan. Kualifikasi altform-lightunplated menghindari masalah ini.

Perilaku kompatibilitas

Untuk kompatibilitas mundur, Windows menyertakan logika untuk mendeteksi ikon monokromatik dan memeriksa apakah kontras dengan latar belakang yang dimaksudkan. Jika ikon gagal memenuhi persyaratan kontras, Windows akan mencari versi aset kontras-putih. Jika itu tidak tersedia, Windows akan kembali menggunakan versi aset berlapis.

API penting