Aracılığıyla paylaş

Kaynak sözlükleri

  • Makale

.NET Çok Platformlu Uygulama Kullanıcı Arabirimi (.NET MAUI), ResourceDictionary .NET MAUI uygulaması tarafından kullanılan kaynaklar için bir depodur. Bir içinde ResourceDictionary depolanan tipik kaynaklar stiller, denetim şablonları, veri şablonları, dönüştürücüler ve renklerdir.

içinde ResourceDictionary depolanan XAML kaynaklarına başvurulabilir ve veya DynamicResource işaretleme uzantısı kullanılarak öğelere StaticResource uygulanabilir. C# dilinde kaynaklar da bir ResourceDictionary içinde tanımlanabilir ve ardından dize tabanlı dizin oluşturucu kullanılarak öğelere başvurulup uygulanabilir.

Bahşiş

Visual Studio'da, arka planda kod dosyası tarafından yedeklenen XAML tabanlı ResourceDictionary bir dosya .NET MAUI ResourceDictionary (XAML) öğe şablonu tarafından projenize eklenebilir.

Kaynak oluşturma

Türetilen her VisualElement nesnenin, kaynak içerebilen bir ResourceDictionary özelliği vardırResources. Benzer şekilde, türetilmiş bir ApplicationResources nesnenin, kaynak içerebilen bir ResourceDictionary özelliği vardır.

.NET MAUI uygulaması yalnızca öğesinden Applicationtüretilen tek bir sınıf içerebilir, ancak genellikle sayfalar, düzenler ve görünümler dahil olmak üzere öğesinden VisualElementtüretilen birçok sınıfı kullanır. Bu nesnelerden herhangi birinin özelliği, içeren kaynaklar ResourceDictionary olarak ayarlanmış olabilirResources. Kaynakların kullanılabilmesi için belirli ResourceDictionary bir etkinin nereye koyulacağını seçme:

  • veya Labelgibi Button bir ResourceDictionary görünüme eklenmiş olan bir içindeki kaynaklar yalnızca belirli bir nesneye uygulanabilir.
  • Veya Gridgibi StackLayout bir ResourceDictionary düzene eklenmiş bir düzendeki kaynaklar düzene ve bu düzenin tüm alt öğelerine uygulanabilir.
  • Sayfa düzeyinde tanımlanan bir ResourceDictionary içindeki kaynaklar sayfaya ve tüm alt öğelerine uygulanabilir.
  • Uygulama düzeyinde tanımlanan bir ResourceDictionary içindeki kaynaklar uygulama genelinde uygulanabilir.

Örtük stiller dışında, kaynak sözlüğündeki her kaynağın özniteliğiyle x:Key tanımlanan benzersiz bir dize anahtarı olmalıdır.

Aşağıdaki XAML, App.xaml dosyasında bir uygulama düzeyinde ResourceDictionarytanımlanan kaynakları gösterir:

<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>

Bu örnekte kaynak sözlüğü bir Thickness kaynağı, birden çok Color kaynağı ve iki örtük Style kaynağı tanımlar.

Önemli

Doğrudan özellik öğesi etiketleri arasına Resources kaynak eklemek otomatik olarak bir ResourceDictionary nesne oluşturur. Ancak, tüm kaynakları isteğe bağlı ResourceDictionary etiketler arasına yerleştirmek de geçerlidir.

Kaynakları kullanma

Her kaynağın özniteliği kullanılarak x:Key belirtilen bir anahtarı vardır ve bu, içinde ResourceDictionarykendi sözlük anahtarı olur. anahtarı, veya DynamicResource XAML işaretleme uzantısı ile StaticResource kaynağından ResourceDictionary bir kaynağa başvurmak için kullanılır.

İşaretlemeyi StaticResource uzantısı, kaynak sözlüğündeki DynamicResource bir değere başvurmak için sözlük anahtarı kullanan işaretleme uzantısına benzer. Ancak, işaretleme uzantısı tek bir sözlük araması gerçekleştirirken StaticResource , DynamicResource işaretleme uzantısı sözlük anahtarına bir bağlantı tutar. Bu nedenle, anahtarla ilişkili sözlük girdisi değiştirilirse, değişiklik görsel öğesine uygulanır. Bu, bir uygulamada çalışma zamanı kaynak değişikliklerinin yapılmasını sağlar. biçimlendirme uzantıları hakkında daha fazla bilgi için bkz . XAML işaretleme uzantıları.

Aşağıdaki XAML örneğinde kaynakların nasıl tüketilip bir içinde StackLayoutek kaynak tanımlanacağı gösterilmektedir:

<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>

Bu örnekte nesnesi, ContentPage uygulama düzeyi kaynak sözlüğünde tanımlanan örtük stili tüketir. StackLayout nesnesi, uygulama düzeyi kaynak sözlüğünde tanımlanan kaynağı kullanırkenPageMargin, Button nesne ise kaynak sözlüğünde StackLayout tanımlanan örtük stili tüketir. Bu, aşağıdaki ekran görüntüsünde gösterilen görünüme neden olur:

Consuming resource dictionary resources.

Önemli

Tek bir sayfaya özgü kaynaklar uygulama düzeyi kaynak sözlüğüne dahil edilmemelidir, çünkü bu tür kaynaklar bir sayfanın gerektirdiği durumlarda değil uygulama başlangıcında ayrıştırılır. Daha fazla bilgi için bkz . Uygulama kaynak sözlüğü boyutunu küçültme.

Kaynak arama davranışı

Veya işaretleme uzantısıyla StaticResourceDynamicResource bir kaynağa başvurulduğunda aşağıdaki arama işlemi gerçekleşir:

  • İstenen anahtar, varsa, özelliği ayarlayan öğe için kaynak sözlüğünde denetlendi. İstenen anahtar bulunursa değeri döndürülür ve arama işlemi sonlandırılır.
  • Eşleşme bulunamazsa, arama işlemi görsel ağacı yukarı doğru arar ve her üst öğenin kaynak sözlüğünü denetler. İstenen anahtar bulunursa değeri döndürülür ve arama işlemi sonlandırılır. Aksi takdirde, kök öğeye ulaşılana kadar işlem yukarı doğru devam eder.
  • Kök öğesinde eşleşme bulunamazsa, uygulama düzeyi kaynak sözlüğü incelenmiş olur.
  • Eşleşme hala bulunamazsa, bir XamlParseException oluşturulur.

Bu nedenle, XAML ayrıştırıcısı bir StaticResource veya DynamicResource işaretleme uzantısıyla karşılaştığında, bulduğu ilk eşleşmeyi kullanarak görsel ağaçta yukarı doğru ilerleyerek eşleşen bir anahtar arar. Bu arama sayfada sona erer ve anahtar hala bulunamazsa, XAML ayrıştırıcısı nesneye eklenen öğesini ResourceDictionaryApp arar. Anahtar hala bulunamazsa bir özel durum oluşturulur.

Kaynakları geçersiz kılma

Kaynaklar anahtarları paylaştığında, görsel ağaçta daha altta tanımlanan kaynaklar daha yüksek tanımlı kaynaklara göre öncelikli olur. Örneğin, bir AppBackgroundColor kaynağın AliceBlue uygulama düzeyinde olarak ayarlanması, olarak ayarlanmış Tealbir sayfa düzeyi AppBackgroundColor kaynağı tarafından geçersiz kılınacaktır. Benzer şekilde, sayfa düzeyi AppBackgroundColor kaynağı bir düzen veya görünüm düzeyi AppBackgroundColor kaynağı tarafından geçersiz kılınacaktır.

Tek başına kaynak sözlükleri

Bir ResourceDictionary , arka planda kod dosyası tarafından desteklenmeyen tek başına bir XAML dosyası olarak da oluşturulabilir. Tek başına ResourceDictionaryoluşturmak için projeye .NET MAUI ResourceDictionary (XAML) öğesi şablonuyla yeni ResourceDictionary bir dosya ekleyin ve arka planda kod dosyasını silin. Ardından, XAML dosyasında özniteliğini dosyanın başlangıcına yakın olan etiketten ResourceDictionary kaldırınx:Class. Ayrıca, XAML'nin derlendiğinden emin olmak için XML üst bilgisinin arkasına ekleyin <?xaml-comp compile="true" ?> .

Dekont

Tek başına ResourceDictionary bir MauiXaml derleme eylemine sahip olmalıdır.

Aşağıdaki XAML örneği MyResourceDictionary.xaml adlı tek başına ResourceDictionary bir örneği gösterir:

<?xml version="1.0" encoding="UTF-8" ?>
<?xaml-comp compile="true" ?>
<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>

Bu örnekte, ResourceDictionary türünde DataTemplatebir nesne olan tek bir kaynak içerir. MyResourceDictionary.xaml , başka bir kaynak sözlüğünde birleştirilerek kullanılabilir.

Kaynak sözlüklerini birleştirme

Kaynak sözlükleri, bir veya daha fazla ResourceDictionary nesne başka bir ile birleştirilerek birleştirilebilir ResourceDictionary.

Yerel kaynak sözlüklerini birleştirme

Yerel ResourceDictionary bir dosya, özelliği XAML dosyasının dosya adına ayarlanmış bir nesne Source oluşturularak başka ResourceDictionary bir ResourceDictionary dosyayla birleştirilebilir:

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

Bu söz dizimi sınıfın örneğini MyResourceDictionary oluşturmaz. Bunun yerine XAML dosyasına başvurur. Bu nedenle özelliği ayarlarken Source arka plan kod dosyası gerekmez ve x:Class özniteliği MyResourceDictionary.xaml dosyasının kök etiketinden kaldırılabilir.

Önemli

ResourceDictionary.Source özelliği yalnızca XAML'den ayarlanabilir.

Diğer derlemelerden kaynak sözlüklerini birleştirme

AResourceDictionary, özelliğine ResourceDictionaryeklenerek başka bir ResourceDictionary taneyle MergedDictionaries de birleştirilebilir. Bu teknik, bulundukları derlemeden bağımsız olarak kaynak sözlüklerinin birleştirilmesini sağlar. Dış derlemelerden kaynak sözlüklerinin birleştirilmesi için, bir derleme eyleminin ResourceDictionary MauiXaml olarak ayarlanması, arka plan kod dosyası olması ve özniteliğinin dosyanın kök etiketinde tanımlanması x:Class gerekir.

Uyarı

ResourceDictionary sınıfı da bir MergedWith özellik tanımlar. Ancak, bu özellik kullanım dışı bırakıldı ve artık kullanılmamalıdır.

Aşağıdaki kod örneği, bir sayfa düzeyi ResourceDictionarykoleksiyonuna MergedDictionaries eklenen iki kaynak sözlüklerini gösterir:

<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>

Bu örnekte, aynı derlemedeki bir kaynak sözlüğü ve bir dış derlemeden kaynak sözlüğü sayfa düzeyinde kaynak sözlüğüyle birleştirilir. Buna ek olarak, özellik öğesi etiketlerinin MergedDictionaries içindeki diğer ResourceDictionary nesneleri ve bu etiketlerin dışındaki diğer kaynakları da ekleyebilirsiniz.

Önemli

içinde yalnızca bir MergedDictionariesResourceDictionaryözellik öğesi etiketi olabilir, ancak bu etikete gerektiği kadar ResourceDictionary nesne yerleştirebilirsiniz.

Birleştirilmiş ResourceDictionary kaynaklar özdeş x:Key öznitelik değerlerini paylaştığında, .NET MAUI aşağıdaki kaynak önceliğini kullanır:

  1. Kaynak sözlüğünde yerel kaynaklar.
  2. Koleksiyon aracılığıyla MergedDictionaries birleştirilen kaynak sözlüklerinde yer alan kaynaklar, özelliğinde MergedDictionaries ters sırada listelenir.

Bahşiş

Bir uygulama birden çok, büyük kaynak sözlükleri içeriyorsa kaynak sözlüklerini aramak işlem açısından yoğun bir görev olabilir. Bu nedenle, gereksiz aramalardan kaçınmak için, bir uygulamadaki her sayfanın yalnızca sayfaya uygun kaynak sözlükleri kullandığından emin olmanız gerekir.

Koddan XAML tabanlı kaynak sözlüğü kullanma

XAML'de tanımlanan kaynak sözlükleri, arka planda kod dosyası tarafından desteklenmeleri koşuluyla ResourceDictionary kodda kullanılabilir. Visual Studio'da arka planda kod dosyaları tarafından desteklenen XAML tabanlı ResourceDictionary dosyalar .NET MAUI ResourceDictionary (XAML) öğe şablonu tarafından projenize eklenebilir:

Screenshot of resource dictionaries backed by code-behind.

Arka planda kod dosyaları tarafından desteklenen XAML tabanlı kaynak sözlükleri daha sonra C# dilinden kaynak sözlüğü koleksiyonuna MergedDictionaries eklenerek kullanılabilir:

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

Koddan anahtara göre kaynaklara erişme

Kaynak sözlüğündeki kaynaklara diğer sözlükler gibi koddan erişebilirsiniz.

Aşağıdaki örnekte, bir sayfanın kaynak sözlüğünden bir kaynağın nasıl alınacağı ve uygulanacağı gösterilmektedir:

// 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;
}

Bu, koddan kaynak alamıyorsa .NET MAUI'nin KeyNotFoundException oluşturmamasını sağlayan önerilen yaklaşımdır. Birleştirilmiş kaynak sözlüğü bir XAML dosyasında tanımlanan kaynaklardan ve satır içi kaynaklardan oluştuğunda bu durum oluşabilir. Daha fazla bilgi için bkz . GitHub sorunu #11214.

Dekont

Koddan uygulama genelindeki kaynakları almak için kaynak sözlüğüne erişin App.Current.Resources .