Ekstensi markup {ThemeResource}

  • Artikel

Menyediakan nilai untuk atribut XAML apa pun dengan mengevaluasi referensi ke sumber daya, dengan logika sistem tambahan yang mengambil sumber daya yang berbeda tergantung pada tema yang saat ini aktif. Mirip dengan ekstensi markup {StaticResource}, sumber daya ditentukan dalam ResourceDictionary, dan penggunaan ThemeResource mereferensikan kunci sumber daya tersebut di ResourceDictionary.

Penggunaan atribut XAML

<object property="{ThemeResource key}" .../>

Nilai XAML

Istilah Deskripsi
kunci Kunci untuk sumber daya yang diminta. Kunci ini awalnya ditetapkan oleh ResourceDictionary. Kunci sumber daya dapat berupa string apa pun yang ditentukan dalam XamlName Grammar.

Keterangan

ThemeResource adalah teknik untuk mendapatkan nilai untuk atribut XAML yang didefinisikan di tempat lain dalam kamus sumber daya XAML. Ekstensi markup melayani tujuan dasar yang sama dengan ekstensi markup {StaticResource}. Perbedaan perilaku versus ekstensi markup {StaticResource} adalah bahwa referensi ThemeResource dapat secara dinamis menggunakan kamus yang berbeda sebagai lokasi pencarian utama, tergantung pada tema mana yang saat ini digunakan oleh sistem.

Saat aplikasi pertama kali dimulai, referensi sumber daya apa pun yang dibuat oleh referensi ThemeResource dievaluasi berdasarkan tema yang digunakan saat startup. Tetapi jika pengguna kemudian mengubah tema aktif pada run-time, sistem akan mengevaluasi kembali setiap referensi ThemeResource , mengambil sumber daya khusus tema yang mungkin berbeda, dan memutar ulang aplikasi dengan nilai sumber daya baru di semua tempat yang sesuai di pohon visual. StaticResource ditentukan pada waktu pemuatan XAML/startup aplikasi dan tidak akan dievaluasi kembali pada run-time. (Ada teknik lain seperti status visual yang memuat ulang XAML secara dinamis, tetapi teknik tersebut beroperasi pada tingkat yang lebih tinggi sehingga evaluasi sumber daya dasar diaktifkan oleh ekstensi markup {StaticResource}).

ThemeResource mengambil satu argumen, yang menentukan kunci untuk sumber daya yang diminta. Kunci sumber daya selalu merupakan string di Windows Runtime XAML. Untuk informasi selengkapnya tentang bagaimana kunci sumber daya awalnya ditentukan, lihat atribut x:Key.

Untuk informasi selengkapnya tentang cara menentukan sumber daya dan menggunakan ResourceDictionary dengan benar, termasuk kode sampel, lihat Referensi sumber daya ResourceDictionary dan XAML.

Penting Seperti halnya StaticResource, ThemeResource tidak boleh mencoba membuat referensi maju ke sumber daya yang didefinisikan secara leksikal lebih jauh dalam file XAML. Mencoba melakukannya tidak didukung. Bahkan jika referensi maju tidak gagal, mencoba membuatnya membawa penalti performa. Untuk hasil terbaik, sesuaikan komposisi kamus sumber daya Anda sehingga referensi ke depan dihindari.

Mencoba menentukan ThemeResource ke kunci yang tidak dapat menyelesaikan melempar pengecualian penguraian XAML pada durasi. Alat desain juga dapat menawarkan peringatan atau kesalahan.

Dalam implementasi prosesor XAML Windows Runtime, tidak ada representasi kelas backing untuk ThemeResource. Yang paling setara dalam kode adalah menggunakan API pengumpulan ResourceDictionary, misalnya memanggil Contains atau *TryGetValue.

ThemeResource adalah ekstensi markup. Ekstensi markup biasanya diimplementasikan ketika ada persyaratan untuk menghindari nilai atribut agar selain nilai harfiah atau nama handler, dan persyaratannya lebih global daripada hanya menempatkan pengonversi jenis pada jenis atau properti tertentu. Semua ekstensi markup di XAML menggunakan karakter "{" dan "}" dalam sintaks atributnya, yang merupakan konvensi di mana prosesor XAML mengenali bahwa ekstensi markup harus memproses atribut .

Kapan dan bagaimana menggunakan {ThemeResource} daripada {StaticResource}

Aturan di mana ThemeResource diselesaikan ke item dalam kamus sumber daya umumnya sama dengan StaticResource. Pencarian ThemeResource dapat diperluas ke dalam file ResourceDictionary yang direferensikan dalam koleksi ThemeDictionaries , tetapi StaticResource juga dapat melakukannya. Perbedaannya adalah bahwa ThemeResource dapat mengevaluasi kembali pada run-time dan StaticResource tidak dapat.

Kumpulan kunci di setiap kamus tema harus menyediakan set sumber daya kunci yang sama terlepas dari tema mana yang aktif. Jika sumber daya kunci tertentu ada di kamus tema HighContrast , sumber daya lain dengan nama tersebut juga harus ada di Terang dan Default. Jika itu tidak benar, pencarian sumber daya mungkin gagal saat pengguna beralih tema dan aplikasi Anda tidak akan terlihat benar. Dimungkinkan meskipun kamus tema dapat berisi sumber daya kunci yang hanya direferensikan dari dalam cakupan yang sama untuk menyediakan sub-nilai; ini tidak perlu setara di semua tema.

Secara umum Anda harus menempatkan sumber daya dalam kamus tema dan membuat referensi ke sumber daya tersebut menggunakan ThemeResource hanya ketika nilai tersebut dapat berubah di antara tema atau didukung oleh nilai yang berubah. Ini sesuai untuk jenis sumber daya ini:

  • Kuas, khususnya warna untuk SolidColorBrush. Ini membentuk sekitar 80% dari penggunaan ThemeResource dalam templat kontrol XAML default (generic.xaml).
  • Nilai piksel untuk batas, offset, margin dan padding dan sebagainya.
  • Properti font seperti FontFamily atau FontSize.
  • Templat lengkap untuk sejumlah kontrol terbatas yang biasanya bergaya sistem dan digunakan untuk presentasi dinamis, seperti GridViewItem dan ListViewItem.
  • Gaya tampilan teks (biasanya untuk mengubah warna font, latar belakang, dan mungkin ukuran).

Windows Runtime menyediakan sekumpulan sumber daya yang secara khusus dimaksudkan untuk dirujuk oleh ThemeResource. Ini semua terdaftar sebagai bagian dari file XAML themeresources.xaml, yang tersedia di folder include/winrt/xaml/design sebagai bagian dari Windows Software Development Kit (SDK). Untuk dokumentasi tentang kuas tema dan gaya tambahan yang ditentukan dalam themeresources.xaml, lihat sumber daya tema XAML. Kuas didokumentasikan dalam tabel yang memberi tahu Anda nilai warna apa yang dimiliki setiap kuas untuk masing-masing dari tiga tema aktif yang mungkin.

Definisi XAML dari status visual dalam templat kontrol harus menggunakan referensi ThemeResource setiap kali ada sumber daya dasar yang mungkin berubah karena perubahan tema. Perubahan tema sistem biasanya tidak akan menyebabkan perubahan status visual. Sumber daya perlu menggunakan referensi ThemeResource dalam hal ini sehingga nilai dapat dievaluasi kembali untuk status visual yang masih aktif. Misalnya, jika Anda memiliki status visual yang mengubah warna kuas dari bagian UI tertentu dan salah satu propertinya, dan warna kuas itu berbeda per tema, Anda harus menggunakan referensi ThemeResource untuk memberikan nilai properti tersebut dalam templat default dan juga modifikasi status visual ke templat default tersebut.

Penggunaan ThemeResource mungkin terlihat dalam serangkaian nilai dependen. Misalnya, nilai Warna yang digunakan oleh SolidColorBrush yang juga merupakan sumber daya kunci mungkin menggunakan referensi ThemeResource . Tetapi setiap properti UI yang menggunakan sumber daya SolidColorBrush yang dikunci juga akan menggunakan referensi ThemeResource , sehingga khususnya setiap properti jenis Brush yang memungkinkan perubahan nilai dinamis saat tema berubah.

Catatan{ThemeResource} dan evaluasi sumber daya run-time pada pengalihan tema didukung di Windows 8.1 XAML tetapi tidak didukung di XAML untuk aplikasi yang menargetkan Windows 8.

Sumber daya sistem

Beberapa sumber daya tema mereferensikan nilai sumber daya sistem sebagai sub-nilai yang mendasar. Sumber daya sistem adalah nilai sumber daya khusus yang tidak ditemukan dalam kamus sumber daya XAML apa pun. Nilai-nilai ini mengandalkan perilaku dalam dukungan Windows Runtime XAML untuk meneruskan nilai dari sistem itu sendiri, dan mewakilinya dalam bentuk yang dapat direferensikan oleh sumber daya XAML. Misalnya, ada sumber daya sistem bernama "SystemColorButtonFaceColor" yang mewakili warna RGB. Warna ini berasal dari aspek warna dan tema sistem yang tidak hanya spesifik untuk aplikasi Windows Runtime dan Windows Runtime.

Sumber daya sistem sering menjadi nilai yang mendasar untuk tema kontras tinggi. Pengguna memegang kendali atas pilihan warna untuk tema kontras tinggi mereka, dan pengguna membuat pilihan ini menggunakan fitur sistem yang juga tidak spesifik untuk aplikasi Windows Runtime. Dengan mereferensikan sumber daya sistem sebagai referensi ThemeResource , perilaku default tema kontras tinggi untuk aplikasi Windows Runtime dapat menggunakan nilai khusus tema ini yang dikontrol oleh pengguna dan diekspos oleh sistem. Selain itu, referensi sekarang ditandai untuk evaluasi ulang jika sistem mendeteksi perubahan tema run-time.

Contoh penggunaan {ThemeResource}

Berikut adalah beberapa contoh XAML yang diambil dari file generic.xaml dan themeresources.xaml default untuk mengilustrasikan cara menggunakan ThemeResource. Kita hanya akan melihat satu templat ( Tombol default) dan bagaimana dua properti dinyatakan (Latar Belakang dan Latar Depan) responsif terhadap perubahan tema.

    <!-- Default style for Windows.UI.Xaml.Controls.Button -->
    <Style TargetType="Button">
        <Setter Property="Background" Value="{ThemeResource ButtonBackgroundThemeBrush}" />
        <Setter Property="Foreground" Value="{ThemeResource ButtonForegroundThemeBrush}"/>
...

Di sini, properti mengambil nilai Brush , dan referensi ke sumber daya SolidColorBrush bernama ButtonBackgroundThemeBrush dan ButtonForegroundThemeBrush dibuat menggunakan ThemeResource.

Properti yang sama ini juga disesuaikan oleh beberapa status visual untuk Tombol. Terutama, warna latar belakang berubah ketika tombol diklik. Di sini juga, animasi Latar Belakang dan Latar Depan dalam papan cerita status visual menggunakan objek DiscreteObjectKeyFrame dan referensi untuk menyikat dengan ThemeResource sebagai nilai bingkai kunci.

<VisualState x:Name="Pressed">
  <Storyboard>
    <ObjectAnimationUsingKeyFrames Storyboard.TargetName="Border"
        Storyboard.TargetProperty="Background">
      <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource ButtonPressedBackgroundThemeBrush}" />
    </ObjectAnimationUsingKeyFrames>
    <ObjectAnimationUsingKeyFrames Storyboard.TargetName="ContentPresenter"
         Storyboard.TargetProperty="Foreground">
       <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource ButtonPressedForegroundThemeBrush}" />
    </ObjectAnimationUsingKeyFrames>
  </Storyboard>
</VisualState>

Masing-masing kuas ini didefinisikan sebelumnya dalam generic.xaml: mereka harus didefinisikan sebelum templat apa pun yang menggunakannya untuk menghindari referensi penerusan XAML. Berikut adalah definisi tersebut, untuk kamus tema "Default".

    <ResourceDictionary.ThemeDictionaries>
        <ResourceDictionary x:Key="Default">
...
            <SolidColorBrush x:Key="ButtonBackgroundThemeBrush" Color="Transparent" />
            <SolidColorBrush x:Key="ButtonForegroundThemeBrush" Color="#FFFFFFFF" />
...
            <SolidColorBrush x:Key="ButtonPressedBackgroundThemeBrush" Color="#FFFFFFFF" />
            <SolidColorBrush x:Key="ButtonPressedForegroundThemeBrush" Color="#FF000000" />
...

Kemudian masing-masing kamus tema lainnya juga memiliki kuas ini yang ditentukan, misalnya:

        <ResourceDictionary x:Key="HighContrast">
            <!-- High Contrast theme resources -->
...
            <SolidColorBrush x:Key="ButtonBackgroundThemeBrush" Color="{ThemeResource SystemColorButtonFaceColor}" />
            <SolidColorBrush x:Key="ButtonForegroundThemeBrush" Color="{ThemeResource SystemColorButtonTextColor}" />

...
            <SolidColorBrush x:Key="ButtonPressedBackgroundThemeBrush" Color="{ThemeResource SystemColorButtonTextColor}" />
            <SolidColorBrush x:Key="ButtonPressedForegroundThemeBrush" Color="{ThemeResource SystemColorButtonFaceColor}" />

Di sini nilai Warna adalah referensi ThemeResource lain ke sumber daya sistem. Jika Anda mereferensikan sumber daya sistem, dan Anda ingin mengubahnya sebagai respons terhadap perubahan tema, Anda harus menggunakan ThemeResource untuk membuat referensi.

Perilaku Windows 8

Windows 8 tidak mendukung ekstensi markup ThemeResource , tersedia dimulai dengan Windows 8.1. Selain itu, Windows 8 tidak mendukung pengalihan sumber daya terkait tema secara dinamis untuk aplikasi Windows Runtime. Aplikasi harus dimulai ulang untuk mengambil perubahan tema untuk templat dan gaya XAML. Ini bukan pengalaman pengguna yang baik, sehingga aplikasi sangat didorong untuk mengolah ulang dan menargetkan Windows 8.1 sehingga mereka dapat menggunakan gaya dengan penggunaan ThemeResource dan dapat secara dinamis beralih tema ketika pengguna melakukannya. Aplikasi yang dikompilasi untuk Windows 8 tetapi berjalan di Windows 8.1 terus menggunakan perilaku Windows 8.

Dukungan alat waktu desain untuk ekstensi markup {ThemeResource}

Microsoft Visual Studio 2013 dapat menyertakan kemungkinan nilai kunci dalam menu dropdown Microsoft IntelliSense saat Anda menggunakan ekstensi markup {ThemeResource} di halaman XAML. Misalnya, segera setelah Anda mengetik "{ThemeResource", salah satu kunci sumber daya dari sumber daya tema XAML ditampilkan.

Setelah kunci sumber daya ada sebagai bagian dari penggunaan {ThemeResource} , fitur Buka Definisi (F12) dapat menyelesaikan sumber daya tersebut dan menunjukkan kepada Anda generic.xaml untuk waktu desain, tempat sumber daya tema ditentukan. Karena sumber daya tema didefinisikan lebih dari sekali (per tema) Buka Definisi membawa Anda ke definisi pertama yang ditemukan dalam file, yang merupakan definisi untuk Default. Jika Anda menginginkan definisi lain, Anda dapat mencari nama kunci dalam file dan menemukan definisi tema lainnya.