ResourceDictionary Kelas

Referensi

Definisi

Ruang nama:: Windows.UI.Xaml

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.

Edit

Menentukan repositori untuk sumber daya XAML, seperti gaya, yang digunakan aplikasi Anda. Anda menentukan sumber daya di XAML dan kemudian dapat mengambilnya di XAML menggunakan ekstensi markup {StaticResource} dan ekstensi markup {ThemeResource} . Anda juga dapat mengakses sumber daya dengan kode, tetapi itu kurang umum.

/// [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 ResourceDictionary : DependencyObject, IIterable<IKeyValuePair<IInspectable, IInspectable const&>>, IMap<IInspectable, IInspectable const&>

[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 class ResourceDictionary : DependencyObject, IDictionary<object,object>, IEnumerable<KeyValuePair<object,object>>

Public Class ResourceDictionary
Inherits DependencyObject
Implements IDictionary(Of Object, Object), IEnumerable(Of KeyValuePair(Of Object, Object))

<ResourceDictionary>
  oneOrMoreResources
</ResourceDictionary>
- or -
<frameworkElement>
  <frameworkElement.Resources>
    oneOrMoreResources
  </frameworkElement.Resources>
</frameworkElement>

Warisan: Object IInspectable DependencyObject ResourceDictionary

Turunan: Windows.UI.Xaml.ColorPaletteResources

Atribut: ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Penerapan: IDictionary<Object,Object> IMap<IInspectable,IInspectable> IIterable<IKeyValuePair<K,V>> IEnumerable<KeyValuePair<K,V>> IEnumerable<KeyValuePair<Object,Object>> IIterable<IKeyValuePair<IInspectable,IInspectable>>

Persyaratan Windows

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

Keterangan

Kamus sumber daya adalah repositori untuk sumber daya XAML, seperti gaya, yang digunakan aplikasi Anda. Anda menentukan sumber daya di XAML dan kemudian dapat mengambilnya di XAML menggunakan ekstensi markup {StaticResource} dan ekstensi markup {ThemeResource} . Anda juga dapat mengakses sumber daya dengan kode, tetapi itu kurang umum. Anda dapat menggunakan sumber daya untuk menegakkan bahwa nilai tertentu seperti warna kuas atau pengukuran piksel digunakan secara konsisten di seluruh aplikasi Anda. Untuk informasi selengkapnya tentang menggunakan kamus sumber daya secara efektif, lihat Referensi sumber daya ResourceDictionary dan XAML.

Penggunaan elemen ResourceDictionary

Jenis ResourceDictionary digunakan sebagai nilai dua properti, FrameworkElement.Resources dan Application.Resources, yang penting untuk struktur keseluruhan aplikasi UWP. File XAML yang Anda dapatkan dari templat proyek awal untuk aplikasi akan dimulai dengan nilai awal untuk FrameworkElement.Resources, dan file app.xaml mungkin dimulai dengan nilai awal untuk Application.Resources. Sumber daya apa yang ditentukan di sana tergantung pada templat awal proyek mana yang Anda gunakan.

XAML ini menunjukkan penggunaan properti FrameworkElement.Resources . Dalam hal ini FrameworkElement adalah Halaman. Tidak ada elemen ResourceDictionary bawahan elemen properti Page.Resources, tetapi kehadirannya tersirat; untuk informasi selengkapnya lihat bagian "Catatan tentang sintaks XAML" di bawah ini. XAML menempatkan Gaya ke dalam ResourceDictionary dengan nilai atribut x:Key "TextBlockStyle1". Lebih jauh ke bawah di XAML, ekstensi markup {StaticResource} mereferensikan Gaya dalam kamus sumber daya untuk memberikan nilai untuk properti Gaya elemen TextBlock .

Gaya seperti yang ditampilkan sebenarnya tidak menerapkan gaya apa pun ke TextBlock, tetapi Anda dapat menambahkan properti Gaya di Microsoft Visual Studio. Anda kemudian dapat menggunakan sumber daya Gaya sesering yang Anda suka di halaman untuk menegakkan keseragaman.

Anda dapat menggunakan Microsoft Visual Studio untuk membuat kamus sumber daya. Contoh ini dibuat dengan langkah-langkah ini: letakkan TextBlock di permukaan desain, klik kanan, pilih Edit Gaya / Buat Kosong, lalu "Dokumen ini" untuk menentukan sumber daya baru di Page.Resources.

<Page
    x:Class="ResourceDictionary_example.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:ResourceDictionary_example"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d">
    <Page.Resources>
        <Style x:Key="TextBlockStyle1" TargetType="TextBlock"/>
    </Page.Resources>

    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <TextBlock Style="{StaticResource TextBlockStyle1}" Text="TextBlock"/>
    </Grid>
</Page>

XAML ini, dari file AppPage.xaml dari sampel AtomPub, menunjukkan penggunaan properti Application.Resources . XAML menempatkan dua elemen Gaya ke dalam kamus sumber daya, membuatnya tersedia di seluruh aplikasi.

<Application xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
    x:Class="AtomPub.App"
    RequestedTheme="Light" >
    <Application.Resources>
        <ResourceDictionary>
            <Style x:Key="TitleStyle" TargetType="TextBlock">
                <Setter Property="Foreground" Value="#707070"/>
                <Setter Property="FontFamily" Value="Segoe UI Light"/>
                <Setter Property="FontSize" Value="16"/>
            </Style>
            <Style x:Key="H1Style" TargetType="TextBlock">
                <Setter Property="Foreground" Value="#212121"/>
                <Setter Property="FontFamily" Value="Segoe UI Semilight"/>
                <Setter Property="FontSize" Value="26.667"/>
                <Setter Property="Margin" Value="0,0,0,25"/>
            </Style>
            ...
        </ResourceDictionary>
    </Application.Resources>
</Application>

XAML dari file MainPage.xaml ini menggunakan ekstensi markup {StaticResource} untuk mengakses gaya TitleStyle dan H1Style :

...
<!-- Header -->
<StackPanel x:Name="Header" Grid.Row="0">
    <StackPanel Orientation="Horizontal">
        ...
        <TextBlock Text="Windows SDK Samples" VerticalAlignment="Bottom" Style="{StaticResource TitleStyle}" TextWrapping="Wrap"/>
    </StackPanel>
    <TextBlock x:Name="FeatureName" Text="Add Feature Name" Style="{StaticResource H1Style}" TextWrapping="Wrap"/>
</StackPanel>
 ...

Anda dapat memperhitungkan sumber daya ke dalam file XAML mereka sendiri dengan menggunakan ResourceDictionary sebagai elemen akar file. Anda kemudian dapat menyertakan sumber daya tersebut dalam kamus sumber daya FrameworkElement.Resources atau Application.Resources . Untuk melakukan ini, Anda menggunakan properti ResourceDictionary.MergedDictionaries atau properti ResourceDictionary.ThemeDictionaries dari elemen ResourceDictionary.

File ini, Common/Styles1.xaml, mendefinisikan sumber daya Gaya menggunakan ResourceDictionary sebagai elemen root:

<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Style x:Key="TitleTextStyle" TargetType="TextBlock">
        <Setter Property="FontFamily" Value="Segoe UI Light"/>
        <Setter Property="FontSize" Value="16"/>
    </Style>
    <Style x:Key="HeaderTextStyle" TargetType="TextBlock">
        <Setter Property="FontFamily" Value="Segoe UI Semilight"/>
        <Setter Property="FontSize" Value="26.667"/>
        <Setter Property="Margin" Value="0,0,0,25"/>
    </Style>
    ...
</ResourceDictionary>

Sekarang misalkan ada file lain, Common/Styles2.xaml yang juga mendefinisikan sumber daya Gaya . XAML ini menunjukkan cara menggabungkan sumber daya dalam dua file tersebut menggunakan properti ResourceDictionary.MergedDictionaries untuk membuat kamus sumber daya Application.Resources . XAML juga mendefinisikan dua sumber daya Gaya lebih lanjut dan menggabungkannya dengan sumber daya dari dua file.

<Application
    .... >
    <Application.Resources>
        <ResourceDictionary>
            <Style x:Key="ErrorStyle" TargetType="TextBlock">
                <Setter Property="Foreground" Value="DarkRed"/>
                <Setter Property="FontFamily" Value="Segoe UI Semilight"/>
                <Setter Property="FontSize" Value="15"/>
            </Style>
            <Style x:Key="StatusStyle" TargetType="TextBlock">
                <Setter Property="Foreground" Value="Black"/>
                <Setter Property="FontFamily" Value="Segoe UI Semilight"/>
                <Setter Property="FontSize" Value="15"/>
            </Style>
            <ResourceDictionary.MergedDictionaries>
                <!-- 
                    Styles that define common aspects of the platform look and feel
                 -->
                <ResourceDictionary Source="Common/Styles1.xaml"/>
                <ResourceDictionary Source="Common/Styles2.xaml"/>
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Application.Resources>
</Application>

Untuk informasi tentang bagaimana sumber daya kamus gabungan diselesaikan, lihat bagian "Kamus sumber daya gabungan" dari referensi sumber daya ResourceDictionary dan XAML.

Properti x:Key

Di XAML, kunci untuk ResourceDictionaryitems dinyatakan dengan mengatur atribut x:Keypada elemen yang mewakili sumber daya XAML. Biasanya, jika Anda mencoba menempatkan elemen anak yang tidak memiliki nilai kunci ke dalam ResourceDictionary, ini melemparkan pengecualian penguraian XAML atau Windows Runtimeexception. Kondisi pengecualian mungkin juga dicatat sebagai peringatan oleh permukaan desain XAML. Namun, ada tiga kasus penting di mana elemen ResourceDictionarychild tidak akan memerlukan nilai atribut x:Key:

Sumber daya Gaya dapat menggunakan nilai TargetType-nya sebagai kunci sumber daya implisit. Untuk informasi selengkapnya tentang cara kerja kunci implisit untuk gaya dan templat kontrol, lihat Kontrol gaya.
Elemen ResourceDictionary dengan nilai Sumber yang mewakili nilai ResourceDictionary.MergedDictionaries tidak dapat memiliki atribut x:Key pada ResourceDictionary. Dalam setiap file kamus gabungan, (yang direferensikan oleh URI sebagai Sumbernya) Anda memerlukan kunci untuk setiap sumber daya.
Atribut x:Name dapat digunakan alih-alih atribut x:Key, karena alasan warisan. Namun, atribut x:Name dengan sendirinya tidak mengaktifkan pencarian sumber daya XAML dari item tersebut. Konvensi identifikasi atribut x:Name digunakan untuk skenario tertentu seperti menentukan animasi yang di-storyboard. Untuk informasi selengkapnya, lihat atribut x:Name.

Iterasi melalui ResourceDictionary

Anda dapat melakukan iterasi melalui ResourceDictionary di C# atau Microsoft Visual Basic. Dalam banyak kasus, seperti menggunakan sintaks foreach , pengkompilasi melakukan transmisi ini untuk Anda dan Anda tidak perlu mentransmisikan untuk IEnumerable secara eksplisit. Jika Anda perlu mentransmisikan secara eksplisit, misalnya jika Anda ingin memanggil GetEnumerator, transmisikan ke IEnumerable<T> dengan Objek KeyValuePair<, Batasan objek> .

ResourceDictionary dan Microsoft Visual Studio

Microsoft Visual Studio menyediakan pilihan halaman Tambahkan Item Baru untuk kamus sumber daya. Gunakan opsi ini setiap kali Anda ingin menentukan kamus sumber daya XAML longgar baru, misalnya untuk berfungsi sebagai sumber untuk kamus gabungan. Microsoft Visual Studio juga menambahkan kamus sumber daya XAML yang longgar ke proyek setiap kali Anda menggunakan Tambahkan Item Baru untuk membuat kontrol templat. Kamus sumber daya ini menyediakan templat tema default. Microsoft Visual Studio mungkin membuat ResourceDictionary baru untuk Anda di XAML jika Anda mengedit salinan gaya atau templat dan ResourceDictionary untuk lokasi sumber daya yang Anda pilih (aplikasi, halaman, atau mandiri) belum ada.

Catatan tentang sintaks XAML

Perhatikan bahwa sintaks pengumpulan implisit XAML untuk ResourceDictionary tidak menyertakan elemen objek untuk ResourceDictionary. Ini adalah contoh sintaks pengumpulan implisit XAML; tag yang mewakili elemen koleksi dapat dihilangkan. Elemen yang ditambahkan sebagai item ke koleksi ditentukan sebagai elemen anak dari elemen properti dari properti yang jenis yang mendasarinya mendukung metode Tambahkan kamus / peta.

Untuk kamus sumber daya gabungan, Anda perlu secara eksplisit mendeklarasikan elemen objek ResourceDictionary, sehingga Anda juga dapat mendeklarasikan elemen properti ResourceDictionary.MergedDictionaries dan Sumber. Dengan demikian, ada minimal dua elemen objek ResourceDictionary yang terlibat, dan Anda menggunakan sintaks ini.

<ResourceDictionary>
  <ResourceDictionary.MergedDictionaries>
    <ResourceDictionary Source="uri"/>
    ...
  </ResourceDictionary.MergedDictionaries>
...
</ResourceDictionary>

Dalam sintaks ini, ResourceDictionary luar adalah ResourceDictionary utama. ResourceDictionary dalam adalah ResourceDictionary yang sedang digabungkan.

Untuk penggunaan pengumpulan implisit, tempat penampung yang sesuai untuk properti FrameworkElement.Resources ditampilkan. Anda juga dapat menggunakan penggunaan pengumpulan implisit ini untuk properti Application.Resources , atau berpotensi untuk properti kustom yang menggunakan ResourceDictionary sebagai jenis propertinya.

Jenis yang dapat dibagikan dan jenis UIElement

Kamus sumber daya adalah teknik untuk menentukan jenis dan nilai yang dapat dibagikan dari jenis ini di XAML. Tidak semua jenis atau nilai cocok untuk penggunaan dari ResourceDictionary. Contoh jenis di mana berbagi didukung termasuk Gaya, subkelas FrameworkTemplate apa pun, jenis data intrinsik XAML, kuas, warna, dan transformasi. Untuk informasi selengkapnya tentang jenis mana yang dianggap dapat dibagikan, lihat Referensi sumber daya ResourceDictionary dan XAML. Umumnya, jenis turunan UIElement tidak dapat dibagikan kecuali berasal dari templat dan aplikasi templat pada instans kontrol tertentu. Tidak termasuk kasus templat, UIElement diharapkan hanya ada di satu tempat di pohon objek setelah dibuat, dan memiliki UIElement yang dapat dibagikan akan berpotensi melanggar prinsip ini.

Dalam praktiknya, sebagian besar sumber daya yang ditentukan dalam ResourceDictionary akan menjadi salah satu dari berikut:

Mengontrol templat untuk kontrol, termasuk status visualnya.
Gaya pendukung untuk bagian kontrol
Gaya untuk elemen yang merupakan bagian dari UI aplikasi umum tetapi bukan kontrol, seperti TextBlock
Templat data untuk kontrol dan panel yang menggunakan pengikatan data
Nilai Brush tertentu, sebagian besar SolidColorBrush
String atau konstanta lain yang tidak perlu dilokalkan (string dan konstanta yang perlu dilokalkan tidak boleh berada di ResourceDictionary; untuk informasi selengkapnya lihat Mulai Cepat: Menerjemahkan sumber daya UI)

Mengakses objek ResourceDictionary dalam kode

API yang digunakan kode Anda untuk mengakses sumber daya dalam ResourceDictionary bergantung pada bahasa pemrograman mana yang Anda gunakan:

Untuk C# atau Microsoft Visual Basic, Anda menggunakan API yang mengimplementasikan IDictionary<TKey,TValue> dan IEnumerable<T>. Misalnya, TryGetValue atau pengindeks Item .
Untuk ekstensi komponen Visual C++ (C++/CX) Anda menggunakan API yang mengimplementasikan IMap<K,V> dan IIterable. Misalnya, Pencarian.
API yang bukan bagian dari dukungan pengumpulan, seperti Sumber, sama dalam semua bahasa.

Untuk informasi selengkapnya tentang cara menggunakan ResourceDictionary dalam kode, lihat bagian "Menggunakan ResourceDictionary dari kode" dari referensi sumber daya ResourceDictionary dan XAML.

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.

Catatan untuk versi sebelumnya

Pengoptimalan pemuatan sumber daya di Windows 8.1

Dimulai dengan Windows 8.1, ada pengoptimalan pemuatan sumber daya yang diaktifkan oleh model aplikasi dan parser XAML Windows Runtime. Untuk Windows 8, parser XAML memuat sumber daya dari app.xaml dan membuat masing-masing sebagai objek sebagai bagian dari startup. Itu tidak terlalu efisien jika ada kamus besar di sana. Selain itu, sumber daya tersebut termasuk item yang diperlukan oleh ketiga tema, dan dua dari tiga tema bahkan tidak akan aktif. Dimulai dengan Windows 8.1, pengurai XAML hanya membuat sumber daya saat diminta secara khusus. Permintaan mungkin berasal dari sumber daya lain atau dari aplikasi atau halaman XAML saat masing-masing dimuat. Perilaku pengurai ini meminimalkan waktu yang diperlukan untuk membaca kamus tingkat aplikasi pada waktu mulai, dan memungkinkan halaman aplikasi pertama dimuat lebih cepat dalam banyak kasus. Sumber daya yang diperlukan oleh tema lain yang saat ini tidak aktif hanya dimuat jika tema tersebut dipilih untuk menjadi tema aktif oleh pengguna. Pada saat itu, sumber daya apa pun di mana ekstensi markup {ThemeResource} digunakan untuk permintaan dihitung ulang berdasarkan tema yang baru aktif.

perilaku Windows 8

Windows 8 tidak memiliki pengoptimalan yang dijelaskan di atas. ResourceDictionary Application.Resources untuk harus menyelesaikan penguraian sebelum halaman mana pun selain layar splash dapat dimuat ke Jendela aplikasi. Karena itu, Anda mungkin melihat beberapa perbedaan waktu saat anda menargetkan ulang aplikasi untuk Windows 8.1. Aplikasi harus dimuat lebih cepat, namun mungkin tidak mungkin untuk mengisolasi peningkatan ini versus perubahan lain yang telah Anda buat pada kode aplikasi Anda sebagai bagian dari penargetan ulang. Beberapa tempat di mana Anda mungkin melihat bukti perubahan waktu karena pemuatan sumber daya yang dioptimalkan termasuk ketika konstruktor dipanggil oleh pengurai, untuk objek seperti objek Aplikasi , konverter, atau kelas kustom lainnya. Aplikasi yang dikompilasi untuk Windows 8 tetapi berjalan di Windows 8.1 terus menggunakan perilaku Windows 8.

Untuk informasi selengkapnya tentang performa dan faktor sumber daya XAML, lihat Mengoptimalkan markup XAML Anda.

Konstruktor

ResourceDictionary()

Menginisialisasi instans baru kelas ResourceDictionary .

Properti

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)
MergedDictionaries	Mendapatkan kumpulan kamus ResourceDictionary yang merupakan berbagai kamus sumber daya dalam kamus gabungan.
Size	Mendapatkan jumlah elemen yang terkandung dalam koleksi.
Source	Mendapatkan atau mengatur Pengidentifikasi Sumber Daya Seragam (URI) yang menyediakan lokasi sumber kamus sumber daya gabungan.
ThemeDictionaries	Mendapatkan kumpulan kamus sumber daya yang digabungkan yang secara khusus dikun kunci dan terdiri untuk mengatasi skenario tema, misalnya memasok nilai tema untuk "HighContrast".

Metode

Clear()	Menghapus semua item dari ResourceDictionary ini.
ClearValue(DependencyProperty)	Menghapus nilai lokal properti dependensi. (Diperoleh dari DependencyObject)
First()	Mengembalikan iterator untuk item dalam koleksi.
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)
GetView()	Mengambil tampilan terhadap ResourceDictionary.
HasKey(Object)	Mengembalikan apakah ResourceDictionary memiliki entri dengan kunci yang diminta.
Insert(Object, Object)	Menambahkan entri baru ke ResourceDictionary.
Lookup(Object)	Mengembalikan nilai dari kunci yang diminta, jika ada entri dengan kunci tersebut.
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)
Remove(Object)	Menghapus item tertentu dari ResourceDictionary.
SetValue(DependencyProperty, Object)	Mengatur nilai lokal properti dependensi pada DependencyObject. (Diperoleh dari DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Membatalkan pemberitahuan perubahan yang sebelumnya terdaftar dengan memanggil RegisterPropertyChangedCallback. (Diperoleh dari DependencyObject)

Berlaku untuk