Kamus sumber daya

Artikel
09/25/2024

UI Aplikasi Multi-platform .NET (.NET MAUI) ResourceDictionary adalah repositori untuk sumber daya yang digunakan oleh aplikasi .NET MAUI. Sumber daya umum yang disimpan dalam ResourceDictionary termasuk gaya, templat kontrol, templat data, pengonversi, dan warna.

Sumber daya XAML yang disimpan dalam ResourceDictionary dapat dirujuk dan diterapkan ke elemen dengan menggunakan StaticResource ekstensi markup atau DynamicResource . Di C#, sumber daya juga dapat didefinisikan dalam lalu ResourceDictionary dirujuk dan diterapkan ke elemen dengan menggunakan pengindeks berbasis string.

Tip

Di Visual Studio, file berbasis ResourceDictionary XAML yang didukung oleh file code-behind dapat ditambahkan ke proyek Anda oleh templat item .NET MAUI ResourceDictionary (XAML).

Membuat sumber daya

Setiap VisualElement objek turunan memiliki Resources properti, yang merupakan ResourceDictionary yang dapat berisi sumber daya. Demikian pula, Application objek turunan memiliki Resources properti, yang merupakan ResourceDictionary yang dapat berisi sumber daya.

Aplikasi MAUI .NET hanya dapat berisi satu kelas yang berasal dari Application, tetapi sering menggunakan banyak kelas yang berasal dari VisualElement, termasuk halaman, tata letak, dan tampilan. Salah satu objek ini dapat mengatur propertinya Resources ke sumber daya yang ResourceDictionary berisi. Memilih tempat untuk menempatkan dampak tertentu ResourceDictionary di mana sumber daya dapat digunakan:

Sumber daya dalam ResourceDictionary yang dilampirkan ke tampilan, seperti Button atau Label, hanya dapat diterapkan ke objek tertentu.
Sumber daya dalam yang ResourceDictionary dilampirkan ke tata letak, seperti StackLayout atau Grid, dapat diterapkan ke tata letak dan semua turunan tata letak tersebut.
Sumber daya dalam yang ResourceDictionary ditentukan di tingkat halaman dapat diterapkan ke halaman dan ke semua turunannya.
Sumber daya dalam yang ResourceDictionary ditentukan di tingkat aplikasi dapat diterapkan di seluruh aplikasi.

Dengan pengecualian gaya implisit, setiap sumber daya dalam kamus sumber daya harus memiliki kunci string unik yang ditentukan dengan x:Key atribut .

XAML berikut menunjukkan sumber daya yang ditentukan dalam tingkat ResourceDictionary aplikasi dalam file App.xaml :

<Application xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="ResourceDictionaryDemo.App">
    <Application.Resources>

        <Thickness x:Key="PageMargin">20</Thickness>

        <!-- Colors -->
        <Color x:Key="AppBackgroundColor">AliceBlue</Color>
        <Color x:Key="NavigationBarColor">#1976D2</Color>
        <Color x:Key="NavigationBarTextColor">White</Color>
        <Color x:Key="NormalTextColor">Black</Color>

        <!-- Images -->
        <x:String x:Key="BackgroundImage">background</x:String>
        <x:String x:Key="MenuIcon">menu.png</x:String>
        <x:String x:Key="SearchIcon">search.png</x:String>

        <!-- Implicit styles -->
        <Style TargetType="NavigationPage">
            <Setter Property="BarBackgroundColor"
                    Value="{StaticResource NavigationBarColor}" />
            <Setter Property="BarTextColor"
                    Value="{StaticResource NavigationBarTextColor}" />
        </Style>

        <Style TargetType="ContentPage"
               ApplyToDerivedTypes="True">
            <Setter Property="BackgroundColor"
                    Value="{StaticResource AppBackgroundColor}" />
        </Style>

    </Application.Resources>
</Application>

Dalam contoh ini, kamus sumber daya mendefinisikan sumber daya, beberapa Color sumber daya, dan dua sumber daya implisit.Thickness Style

Penting

Menyisipkan sumber daya langsung di Resources antara tag elemen properti secara otomatis membuat ResourceDictionary objek. Namun, valid juga untuk menempatkan semua sumber daya di antara tag opsional ResourceDictionary .

Mengonsumsi sumber daya

Setiap sumber daya memiliki kunci yang ditentukan menggunakan x:Key atribut , yang menjadi kunci kamusnya di ResourceDictionary. Kunci digunakan untuk mereferensikan ResourceDictionary sumber daya dari dengan StaticResource ekstensi markup atau DynamicResource XAML.

Ekstensi StaticResource markup mirip DynamicResource dengan ekstensi markup karena keduanya menggunakan kunci kamus untuk mereferensikan nilai dari kamus sumber daya. Namun, saat StaticResource ekstensi markup melakukan pencarian kamus tunggal, DynamicResource ekstensi markup mempertahankan tautan ke kunci kamus. Oleh karena itu, jika entri kamus yang terkait dengan kunci diganti, perubahan diterapkan ke elemen visual. Ini memungkinkan perubahan sumber daya runtime dibuat di aplikasi. Untuk informasi selengkapnya tentang ekstensi markup, lihat Ekstensi markup XAML.

Contoh XAML berikut menunjukkan cara menggunakan sumber daya, dan juga menentukan sumber daya tambahan dalam StackLayout:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="ResourceDictionaryDemo.MainPage"
             Title="Main page">
    <StackLayout Margin="{StaticResource PageMargin}"
                 Spacing="6">
        <StackLayout.Resources>
            <!-- Implicit style -->
            <Style TargetType="Button">
                <Setter Property="FontSize" Value="14" />
                <Setter Property="BackgroundColor" Value="#1976D2" />
                <Setter Property="TextColor" Value="White" />
                <Setter Property="CornerRadius" Value="5" />
            </Style>
        </StackLayout.Resources>

        <Label Text="This app demonstrates consuming resources that have been defined in resource dictionaries." />
        <Button Text="Navigate"
                Clicked="OnNavigateButtonClicked" />
    </StackLayout>
</ContentPage>

Dalam contoh ini, ContentPage objek menggunakan gaya implisit yang ditentukan dalam kamus sumber daya tingkat aplikasi. Objek mengonsumsi StackLayout sumber daya yang PageMargin ditentukan dalam kamus sumber daya tingkat aplikasi, sementara Button objek menggunakan gaya implisit yang ditentukan dalam StackLayout kamus sumber daya. Ini menghasilkan tampilan yang ditunjukkan pada cuplikan layar berikut:

Mengonsumsi sumber daya kamus sumber daya.

Penting

Sumber daya yang khusus untuk satu halaman tidak boleh disertakan dalam kamus sumber daya tingkat aplikasi, karena sumber daya tersebut kemudian akan diuraikan pada startup aplikasi alih-alih ketika diperlukan oleh halaman. Untuk informasi selengkapnya, lihat Mengurangi ukuran kamus sumber daya aplikasi.

Perilaku pencarian sumber daya

Proses pencarian berikut terjadi ketika sumber daya dirujuk dengan StaticResource ekstensi atau DynamicResource markup:

Kunci yang diminta diperiksa di kamus sumber daya, jika ada, untuk elemen yang mengatur properti. Jika kunci yang diminta ditemukan, nilainya dikembalikan dan proses pencarian berakhir.
Jika kecocokan tidak ditemukan, proses pencarian mencari pohon visual ke atas, memeriksa kamus sumber daya dari setiap elemen induk. Jika kunci yang diminta ditemukan, nilainya dikembalikan dan proses pencarian berakhir. Jika tidak, proses berlanjut ke atas sampai elemen akar tercapai.
Jika kecocokan tidak ditemukan di elemen root, kamus sumber daya tingkat aplikasi akan diperiksa.
Jika kecocokan masih tidak ditemukan, akan XamlParseException dilemparkan.

Oleh karena itu, ketika pengurai XAML menemukan StaticResource ekstensi atau DynamicResource markup, ia mencari kunci yang cocok dengan melakukan perjalanan melalui pohon visual, menggunakan kecocokan pertama yang ditemukannya. Jika pencarian ini berakhir di halaman dan kunci masih belum ditemukan, pengurai XAML mencari ResourceDictionary yang dilampirkan ke App objek. Jika kunci masih belum ditemukan, pengecualian akan dilemparkan.

Mengambil alih sumber daya

Ketika sumber daya berbagi kunci, sumber daya yang didefinisikan lebih rendah di pohon visual akan lebih diutamakan daripada yang ditentukan lebih tinggi. Misalnya, mengatur AppBackgroundColor sumber daya ke AliceBlue di tingkat aplikasi akan ditimpa oleh sumber daya tingkat AppBackgroundColor halaman yang diatur ke Teal. Demikian pula, sumber daya tingkat AppBackgroundColor halaman akan ditimpa oleh tata letak atau melihat sumber daya tingkat AppBackgroundColor .

Kamus sumber daya yang berdiri sendiri

Juga ResourceDictionary dapat dibuat sebagai file XAML yang berdiri sendiri yang tidak didukung oleh file code-behind. Untuk membuat file mandiri ResourceDictionary, tambahkan file baru ResourceDictionary ke proyek dengan templat item .NET MAUI ResourceDictionary (XAML) dan hapus file code-behind-nya. Kemudian, dalam file XAML hapus x:Class atribut dari ResourceDictionary tag di dekat awal file. Selain itu, tambahkan <?xaml-comp compile="true" ?> setelah header XML untuk memastikan bahwa XAML akan dikompilasi.

Juga ResourceDictionary dapat dibuat sebagai file XAML yang berdiri sendiri yang tidak didukung oleh file code-behind. Untuk membuat file mandiri ResourceDictionary, tambahkan file baru ResourceDictionary ke proyek dengan templat item .NET MAUI ResourceDictionary (XAML) dan hapus file code-behind-nya. Kemudian, dalam file XAML hapus x:Class atribut dari ResourceDictionary tag di dekat awal file. Secara default, berdiri sendiri ResourceDictionary memiliki XAML yang dikompilasi, kecuali <?xaml-comp compile="false" ?> ditentukan setelah header XML.

Catatan

Yang berdiri sendiri ResourceDictionary harus memiliki aksi build MauiXaml.

Contoh XAML berikut menunjukkan yang berdiri sendiri ResourceDictionary bernama MyResourceDictionary.xaml:

<?xml version="1.0" encoding="UTF-8" ?>
<ResourceDictionary xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
                    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml">
    <DataTemplate x:Key="PersonDataTemplate">
        <ViewCell>
            <Grid RowSpacing="6"
                  ColumnSpacing="6">
                <Grid.ColumnDefinitions>
                    <ColumnDefinition Width="0.5*" />
                    <ColumnDefinition Width="0.2*" />
                    <ColumnDefinition Width="0.3*" />
                </Grid.ColumnDefinitions>
                <Label Text="{Binding Name}"
                       TextColor="{StaticResource NormalTextColor}"
                       FontAttributes="Bold" />
                <Label Grid.Column="1"
                       Text="{Binding Age}"
                       TextColor="{StaticResource NormalTextColor}" />
                <Label Grid.Column="2"
                       Text="{Binding Location}"
                       TextColor="{StaticResource NormalTextColor}"
                       HorizontalTextAlignment="End" />
            </Grid>
        </ViewCell>
    </DataTemplate>
</ResourceDictionary>

Dalam contoh ini, ResourceDictionary berisi satu sumber daya, yang merupakan objek jenis DataTemplate. MyResourceDictionary.xaml dapat dikonsumsi dengan menggabungkannya ke dalam kamus sumber daya lain.

Gabungkan kamus sumber daya

Kamus sumber daya dapat dikombinasikan dengan menggabungkan satu atau beberapa ResourceDictionary objek ke objek lain ResourceDictionary.

Menggabungkan kamus sumber daya lokal

File lokal ResourceDictionary dapat digabungkan ke objek lain ResourceDictionary dengan membuat ResourceDictionary objek yang propertinya Source diatur ke nama file file XAML dengan sumber daya:

<ContentPage ...>
    <ContentPage.Resources>
        <!-- Add more resources here -->
        <ResourceDictionary Source="MyResourceDictionary.xaml" />
        <!-- Add more resources here -->
    </ContentPage.Resources>
    ...
</ContentPage>

Sintaks ini tidak membuat instans MyResourceDictionary kelas. Sebagai gantinya, ini mereferensikan file XAML. Untuk alasan itu Source , saat mengatur properti, file code-behind tidak diperlukan, dan x:Class atribut dapat dihapus dari tag akar file MyResourceDictionary.xaml .

Penting

Properti ResourceDictionary.Source hanya dapat diatur dari XAML.

Menggabungkan kamus sumber daya dari rakitan lain

Juga ResourceDictionary dapat digabungkan ke properti lain ResourceDictionary dengan menambahkannya ke MergedDictionaries properti ResourceDictionary. Teknik ini memungkinkan kamus sumber daya digabungkan, terlepas dari assembly tempat mereka berada. Menggabungkan kamus ResourceDictionary sumber daya dari rakitan eksternal mengharuskan tindakan build diatur ke MauiXaml, untuk memiliki file code-behind, dan untuk menentukan x:Class atribut dalam tag akar file.

Peringatan

Kelas ResourceDictionary juga mendefinisikan MergedWith properti. Namun, properti ini telah tidak digunakan lagi dan tidak boleh lagi digunakan.

Contoh kode berikut menunjukkan dua kamus sumber daya yang ditambahkan ke MergedDictionaries kumpulan tingkat ResourceDictionaryhalaman :

<ContentPage ...
             xmlns:local="clr-namespace:ResourceDictionaryDemo"
             xmlns:theme="clr-namespace:MyThemes;assembly=MyThemes">
    <ContentPage.Resources>
        <ResourceDictionary>
            <!-- Add more resources here -->
            <ResourceDictionary.MergedDictionaries>
                <!-- Add more resource dictionaries here -->
                <local:MyResourceDictionary />
                <theme:DefaultTheme />
                <!-- Add more resource dictionaries here -->
            </ResourceDictionary.MergedDictionaries>
            <!-- Add more resources here -->
        </ResourceDictionary>
    </ContentPage.Resources>
    ...
</ContentPage>

Dalam contoh ini, kamus sumber daya dari rakitan yang sama, dan kamus sumber daya dari rakitan eksternal, digabungkan ke dalam kamus sumber daya tingkat halaman. Selain itu, Anda juga dapat menambahkan objek lain ResourceDictionary dalam tag elemen properti, dan sumber daya lain di luar tag tersebut MergedDictionaries .

Penting

Hanya ada satu MergedDictionaries tag elemen properti dalam ResourceDictionary, tetapi Anda dapat menempatkan objek sebanyak ResourceDictionary yang diperlukan di sana.

Saat sumber daya yang digabungkan ResourceDictionary berbagi nilai atribut yang identik x:Key , .NET MAUI menggunakan prioritas sumber daya berikut:

Sumber daya lokal ke kamus sumber daya.
Sumber daya yang terkandung dalam kamus sumber daya yang digabungkan melalui MergedDictionaries koleksi, dalam urutan terbalik yang tercantum dalam MergedDictionaries properti .

Tip

Mencari kamus sumber daya dapat menjadi tugas intensif komputasi jika aplikasi berisi beberapa kamus sumber daya besar. Oleh karena itu, untuk menghindari pencarian yang tidak perlu, Anda harus memastikan bahwa setiap halaman dalam aplikasi hanya menggunakan kamus sumber daya yang sesuai dengan halaman.

Menggunakan kamus sumber daya berbasis XAML dari kode

Kamus sumber daya yang ditentukan dalam XAML dapat digunakan dalam kode, asalkan ResourceDictionary didukung oleh file code-behind. Di Visual Studio, file berbasis ResourceDictionary XAML yang didukung oleh file code-behind dapat ditambahkan ke proyek Anda oleh templat item .NET MAUI ResourceDictionary (XAML):

Cuplikan layar kamus sumber daya yang didukung oleh code-behind.

Kamus sumber daya berbasis XAML yang didukung oleh file code-behind kemudian dapat dikonsumsi dari C# dengan menambahkannya ke MergedDictionaries koleksi kamus sumber daya:

Resources.MergedDictionaries.Add(new MyMauiApp.Resources.Styles.MyColors());
Resources.MergedDictionaries.Add(new MyMauiApp.Resources.Styles.MyStyles());

Mengakses sumber daya menurut kunci dari kode

Anda dapat mengakses sumber daya dalam kamus sumber daya dari kode seperti kamus lainnya.

Contoh berikut menunjukkan cara mengambil dan menerapkan sumber daya dari kamus sumber daya halaman:

// Retrieve the Primary color value which is in the page's resource dictionary
var hasValue = Resources.TryGetValue("Primary", out object primaryColor);

if (hasValue)
{
    myLabel.TextColor = (Color)primaryColor;
}

Ini adalah pendekatan yang direkomendasikan yang memastikan bahwa .NET MAUI tidak akan melempar KeyNotFoundException jika tidak dapat mengambil sumber daya dari kode. Ini dapat terjadi ketika kamus sumber daya gabungan terdiri dari sumber daya yang ditentukan dalam file XAML, dan sumber daya sebaris. Untuk informasi selengkapnya, lihat Masalah GitHub #11214.

Catatan

Untuk mengambil sumber daya di seluruh aplikasi dari kode, akses App.Current.Resources kamus sumber daya.

Bagikan melalui

Kamus sumber daya

Membuat sumber daya

Mengonsumsi sumber daya

Perilaku pencarian sumber daya

Mengambil alih sumber daya

Kamus sumber daya yang berdiri sendiri

Gabungkan kamus sumber daya

Menggabungkan kamus sumber daya lokal

Menggabungkan kamus sumber daya dari rakitan lain

Menggunakan kamus sumber daya berbasis XAML dari kode

Mengakses sumber daya menurut kunci dari kode

Sumber Daya Tambahan: