Slovníky prostředků

Multiplatformní uživatelské rozhraní aplikace .NET (.NET MAUI) ResourceDictionary je úložiště pro prostředky, které používají aplikace .NET MAUI. Typické prostředky, které jsou uložené v ResourceDictionary zahrnutí stylů, řídicích šablon, datových šablon, převaděčů a barev.

Na prostředky XAML, které jsou uložené v objektu, ResourceDictionary lze odkazovat a použít u prvků pomocí StaticResource rozšíření nebo DynamicResource rozšíření značek. V jazyce C# je možné prostředky také definovat v ResourceDictionary indexeru založeném na řetězci a pak na ni odkazovat a použít na prvky. Použití souboru v jazyce C# ale nemá malou výhodu ResourceDictionary , protože sdílené objekty se dají uložit jako pole nebo vlastnosti a přistupovat k nim přímo, aniž byste je museli nejdřív načíst ze slovníku.

Tip

V Visual Studio lze do projektu přidat soubor založený na XAML, ResourceDictionary který je zálohovaný souborem kódu za kódem, šablonou položky .NET MAUI ResourceDictionary (XAML).

Vytvoření prostředků

Každý VisualElement odvozený objekt má Resources vlastnost, což je vlastnost ResourceDictionary , která může obsahovat prostředky. Application Podobně odvozený objekt má Resources vlastnost, což je ResourceDictionary to, že může obsahovat prostředky.

Aplikace .NET MAUI může obsahovat pouze jednu třídu, která je odvozena od Application, ale často používá mnoho tříd odvozených z VisualElement, včetně stránek, rozložení a zobrazení. Kterýkoli z těchto objektů může mít vlastnost Resources nastavenou ResourceDictionary na obsahující prostředky. Volba místa, kam se mají konkrétní ResourceDictionary dopady použít:

• Prostředky v ResourceDictionary připojeném k zobrazení, jako je například Button nebo Label, lze použít pouze u tohoto konkrétního objektu.
• Prostředky v ResourceDictionary připojeném k rozložení, jako StackLayout je například nebo Grid, se dají použít na rozložení a všechny podřízené položky tohoto rozložení.
• Prostředky definované ResourceDictionary na úrovni stránky lze použít na stránku a pro všechny její podřízené položky.
• Prostředky definované ResourceDictionary na úrovni aplikace je možné použít v celé aplikaci.

S výjimkou implicitních stylů musí mít každý prostředek ve slovníku prostředků jedinečný řetězcový klíč, který je definovaný s atributem x:Key .

Následující kód XAML zobrazuje prostředky definované na úrovni ResourceDictionary aplikace v souboru 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>

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

V tomto příkladu slovník prostředků definuje Thickness prostředek, více Color prostředků a dva implicitní Style prostředky.

Důležité

Vkládání prostředků přímo mezi Resources značky elementů vlastností automaticky vytvoří ResourceDictionary objekt. Je ale také platné umístit všechny prostředky mezi volitelné ResourceDictionary značky.

Využívání prostředků

Každý prostředek má klíč zadaný pomocí atributu x:Key , který se stane jeho klíčem slovníku v souboru ResourceDictionary. Klíč se používá k odkazování na prostředek z ResourceDictionaryStaticResource rozšíření z DynamicResource revizí XAML nebo značek XAML.

Rozšíření StaticResource značek je podobné DynamicResource rozšíření značek v tom, že oba používají klíč slovníku k odkazování na hodnotu ze slovníku prostředků. Zatímco StaticResource rozšíření značek provádí jedno vyhledávání slovníku, DynamicResource rozšíření značek ale udržuje odkaz na klíč slovníku. Proto pokud je položka slovníku přidružená ke klíči nahrazena, změna se použije u vizuálního prvku. To umožňuje provádět změny prostředků modulu runtime v aplikaci. Další informace o rozšířeních značek najdete v tématu Rozšíření značek XAML.

Následující příklad XAML ukazuje, jak využívat prostředky a také definovat další prostředek v 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>

V tomto příkladu ContentPage objekt využívá implicitní styl definovaný ve slovníku prostředků na úrovni aplikace. Objekt StackLayout využívá PageMargin prostředek definovaný ve slovníku prostředků na úrovni aplikace, zatímco Button objekt využívá implicitní styl definovaný ve slovníku StackLayout prostředků. Výsledkem je vzhled zobrazený na následujícím snímku obrazovky:

Důležité

Prostředky, které jsou specifické pro jednu stránku, by neměly být zahrnuty do slovníku prostředků na úrovni aplikace, protože takové prostředky se pak budou analyzovat při spuštění aplikace místo toho, když to vyžaduje stránka.

Chování vyhledávání prostředků

K následujícímu procesu vyhledávání dochází, když se na prostředek odkazuje s rozšířením nebo DynamicResource rozšířením StaticResource značek:

• Požadovaný klíč se kontroluje ve slovníku prostředků, pokud existuje, pro element, který nastaví vlastnost. Pokud se požadovaný klíč najde, vrátí se jeho hodnota a proces vyhledávání se ukončí.
• Pokud se shoda nenajde, vyhledávací proces vyhledá vizuální strom směrem nahoru a zkontroluje slovník prostředků každého nadřazeného prvku. Pokud se požadovaný klíč najde, vrátí se jeho hodnota a proces vyhledávání se ukončí. V opačném případě proces pokračuje směrem nahoru, dokud nebude dosaženo kořenového prvku.
• Pokud se v kořenovém prvku nenajde shoda, prověří se slovník prostředků na úrovni aplikace.
• Pokud se shoda stále nenašla, vyvolá XamlParseException se.

Proto když analyzátor XAML narazí na StaticResource rozšíření nebo DynamicResource rozšíření značek, vyhledá odpovídající klíč tak, že přejde nahoru přes vizuální strom a použije první shodu, kterou najde. Pokud toto hledání končí na stránce a klíč stále nebyl nalezen, parser XAML prohledá ResourceDictionary připojený k objektu App . Pokud klíč stále není nalezen, vyvolá se výjimka.

Přepsání prostředků

Když prostředky sdílejí klíče, budou mít prostředky definované ve stromu vizuálu přednost před prostředky, které jsou definované výš. Například nastavení AppBackgroundColor prostředku na AliceBlue úrovni aplikace bude přepsáno prostředkem na úrovni AppBackgroundColor stránky nastaveným na Teal. Podobně bude prostředek na úrovni AppBackgroundColor stránky přepsán rozložením nebo prostředkem na úrovni AppBackgroundColor zobrazení.

Slovníky samostatných prostředků

Lze ResourceDictionary také vytvořit jako samostatný soubor XAML, který není zálohovaný souborem kódu. Pokud chcete vytvořit samostatný ResourceDictionarysoubor, přidejte do projektu nový ResourceDictionary soubor pomocí šablony položky .NET MAUI ResourceDictionary (XAML) a odstraňte jeho soubor kódu za kódem. Potom v souboru XAML odeberte x:Class atribut ze ResourceDictionary značky poblíž začátku souboru. Kromě toho přidejte <?xaml-comp compile="true" ?> za hlavičku XML, abyste zajistili, že se XAML zkompiluje.

Poznámka

Samostatný ResourceDictionary musí mít akci sestavení MauiXaml.

Následující příklad XAML ukazuje samostatný ResourceDictionary název MyResourceDictionary.xaml:

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

V tomto příkladu ResourceDictionary obsahuje jeden prostředek, což je objekt typu DataTemplate. Soubor MyResourceDictionary.xaml lze použít jeho sloučením do jiného slovníku prostředků.

Sloučení slovníků prostředků

Slovníky zdrojů lze kombinovat sloučením jednoho nebo více ResourceDictionary objektů do jiného ResourceDictionary.

Sloučení slovníků místních prostředků

Místní ResourceDictionary soubor lze sloučit do jiného ResourceDictionary vytvořením objektu ResourceDictionary , jehož Source vlastnost je nastavena na název souboru XAML s prostředky:

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

Tato syntaxe nevytáčí MyResourceDictionary instanci třídy. Místo toho odkazuje na soubor XAML. Z tohoto důvodu se při nastavování Source vlastnosti nevyžaduje soubor s kódem a x:Class atribut lze odebrat z kořenové značky souboru MyResourceDictionary.xaml .

Důležité

Vlastnost ResourceDictionary.Source lze nastavit pouze z XAML.

Sloučení slovníků prostředků z jiných sestavení

A ResourceDictionary lze také sloučit do jiné ResourceDictionary přidáním do MergedDictionaries vlastnosti ResourceDictionary. Tato technika umožňuje sloučení slovníků prostředků bez ohledu na sestavení, ve kterém se nacházejí. Sloučení slovníků prostředků z externích sestavení vyžaduje ResourceDictionary , aby byla akce sestavení nastavená na MauiXaml, aby měl soubor s kódem a definoval x:Class atribut v kořenové značce souboru.

Upozornění

Třída ResourceDictionary také definuje MergedWith vlastnost. Tato vlastnost je však zastaralá a již by neměla být použita.

Následující příklad kódu ukazuje dva slovníky prostředků, které se přidají do MergedDictionaries kolekce úrovně ResourceDictionarystránky:

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

V tomto příkladu se slovník prostředků ze stejného sestavení a slovník prostředků z externího sestavení sloučí do slovníku prostředků na úrovni stránky. Kromě toho můžete přidat i další ResourceDictionary objekty v rámci MergedDictionaries značek elementů vlastností a dalších prostředků mimo tyto značky.

Důležité

V objektu ResourceDictionarymůže být pouze jedna MergedDictionaries značka elementu vlastnosti, ale do ní můžete umístit tolik ResourceDictionary objektů, kolik je potřeba.

Když sloučené ResourceDictionary prostředky sdílejí stejné x:Key hodnoty atributů, používá rozhraní .NET MAUI následující prioritu prostředku:

1. Prostředky místní do slovníku prostředků.
2. Prostředky obsažené ve slovníkech prostředků, které byly sloučeny prostřednictvím MergedDictionaries kolekce, v obráceném pořadí, jsou uvedeny ve MergedDictionaries vlastnosti.

Tip

Vyhledávání slovníků prostředků může být výpočetně náročný úkol, pokud aplikace obsahuje více velkých slovníků prostředků. Abyste se tedy vyhnuli zbytečnému vyhledávání, měli byste zajistit, aby každá stránka v aplikaci používala pouze slovníky prostředků, které jsou pro stránku vhodné.