Sdílet prostřednictvím

Slovníky prostředků

  • Článek

Uživatelské rozhraní aplikace .NET s více platformami (.NET MAUI) ResourceDictionary je úložiště pro prostředky, které používají aplikace .NET MAUI. Typické prostředky, které jsou uloženy v ResourceDictionary zahrnutí stylů, ovládacích šablon, datových šablon, převaděčů a barev.

Prostředky XAML, které jsou uloženy v a ResourceDictionary mohou být odkazovány a použity na elementy pomocí StaticResource rozšíření nebo DynamicResource značek. V jazyce C# lze prostředky také definovat v indexeru ResourceDictionary založeném na řetězci a pak na ni odkazovat a použít.

Tip

V sadě Visual Studio je možné do projektu přidat soubor založený na kódu založený na ResourceDictionary XAML pomocí šablony položky .NET MAUI ResourceDictionary (XAML ).

Vytvoření zdrojů

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

Aplikace .NET MAUI může obsahovat pouze jednu třídu, která je odvozena z Application, ale často používá mnoho tříd odvozených z VisualElement, včetně stránek, rozložení a zobrazení. Jakýkoli z těchto objektů může mít vlastnost Resources nastavenou ResourceDictionary na obsahující prostředky. Volba umístění konkrétního ResourceDictionary dopadu na použití prostředků:

  • Prostředky v ResourceDictionary připojeném k zobrazení, jako Button je například 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, lze 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ý pomocí atributu x:Key .

Následující xaml ukazuje 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>

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

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é

Vložení prostředků přímo mezi Resources značky elementu vlastnosti 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 slovníkovým klíčem v souboru ResourceDictionary. Klíč se používá k odkazování na prostředek z ResourceDictionary StaticResource rozšíření kódu XAML nebo značek DynamicResource XAML.

Rozšíření StaticResource značek je podobné DynamicResource rozšíření značek v tom, že obě 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 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:

Využívání prostředků slovníku prostředků

Důležité

Prostředky, které jsou specifické pro jednu stránku, by se neměly zahrnout 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, aby je vyžadovala stránka. Další informace naleznete v tématu Zmenšení velikosti slovníku prostředků aplikace.

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

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

  • Požadovaný klíč je zkontrolován 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 prohledá 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čí. Jinak proces pokračuje vzhůru, dokud se nedosáhne kořenového prvku.
  • Pokud se shoda nenajde v kořenovém prvku, prozkoumá se slovník prostředků na úrovni aplikace.
  • Pokud se shoda stále nenajde, vyvolá XamlParseException se vyvolá.

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, analyzátor XAML prohledá ResourceDictionary připojený k objektu App . Pokud se klíč stále nenajde, vyvolá se výjimka.

Přepsání prostředků

Když prostředky sdílejí klíče, budou mít prostředky definované nižší ve stromu vizuálu přednost před prostředky definovanými výše. 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ě se prostředek na úrovni AppBackgroundColor stránky přepíše rozložením nebo prostředkem na úrovni AppBackgroundColor zobrazení.

Slovníky samostatných prostředků

Můžete 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 s 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.

Můžete 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 s kódem. Potom v souboru XAML odeberte x:Class atribut ze ResourceDictionary značky poblíž začátku souboru. Ve výchozím nastavení má samostatný ResourceDictionary soubor XAML zkompilovaný, pokud <?xaml-comp compile="false" ?> není zadán za hlavičkou XML.

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" ?>
<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 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í místních slovníků 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 instanci MyResourceDictionary třídy. Místo toho odkazuje na soubor XAML. Z tohoto důvodu se při nastavování Source vlastnosti nevyžaduje soubor kódu 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 objektu 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 kódu a definoval x:Class atribut v kořenové značce souboru.

Upozorňující

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řidávají do MergedDictionaries kolekce na úrovni 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 do značek elementů vlastností přidat i další ResourceDictionary objekty MergedDictionaries a další prostředky mimo tyto značky.

Důležité

V objektu ResourceDictionarymůže být pouze jedna MergedDictionaries značka elementu vlastnosti, ale můžete do ní vložit libovolný počet ResourceDictionary objektů.

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

  1. Prostředky místní pro slovník 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 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 vhodné pro danou stránku.

Využívání slovníku prostředků založeného na XAML z kódu

Slovníky prostředků, které jsou definovány v XAML, je možné využívat v kódu za předpokladu, že ResourceDictionary je zálohovaný souborem kódu. V sadě Visual Studio je možné do projektu přidat soubory založené na kódu založené na ResourceDictionary xaml pomocí šablony položky .NET MAUI ResourceDictionary (XAML ):

Snímek obrazovky se slovníky prostředků, které jsou založené na kódu

Slovníky prostředků založené na XAML, které jsou založené na kódu souborů, je pak možné využívat z jazyka C# jejich přidáním do MergedDictionaries kolekce slovníku prostředků:

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

Přístup k prostředkům podle klíče z kódu

K prostředkům ve slovníku prostředků můžete přistupovat z kódu stejně jako k jinému slovníku.

Následující příklad ukazuje, jak načíst a použít prostředek ze slovníku prostředků stránky:

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

Toto je doporučený přístup, který zajistí, že rozhraní .NET MAUI nevyvolá KeyNotFoundException výjimku, pokud nemůže načíst prostředek z kódu. K tomu může dojít, když se sloučený slovník prostředků skládá z prostředků definovaných v souboru XAML a vložených prostředků. Další informace najdete v tématu Problém GitHubu č. 11214.

Poznámka:

Pokud chcete načíst prostředky pro celou aplikaci z kódu, přejděte do slovníku App.Current.Resources prostředků.