Rozšíření značek XAML

Článek
09/25/2024

Rozšíření značek XAML pro více platforem .NET Multi-Platform App UI (.NET MAUI) umožňují nastavit vlastnosti na objekty nebo hodnoty, na které se odkazuje nepřímo z jiných zdrojů. Rozšíření značek XAML jsou zvláště důležitá pro sdílení objektů a odkazování na konstanty používané v celé aplikaci, ale jejich největší nástroj v datových vazbách.

Xaml obvykle slouží k nastavení vlastností objektu na explicitní hodnoty, jako je řetězec, číslo, člen výčtu nebo řetězec, který je převeden na hodnotu na pozadí. Někdy však vlastnosti musí místo toho odkazovat na hodnoty definované někde jinde nebo které mohou vyžadovat malé zpracování kódem za běhu. Pro tyto účely jsou k dispozici rozšíření značek XAML.

Rozšíření značek XAML jsou tak pojmenována, protože jsou podporovány kódem ve třídách, které implementují IMarkupExtension. Je také možné napsat vlastní rozšíření značek.

V mnoha případech jsou rozšíření značek XAML okamžitě rozpoznatelná v souborech XAML, protože se zobrazují jako hodnoty atributů oddělené složenými závorkami, { a }, ale někdy se rozšíření značek zobrazují také v kódu jako konvenční prvky.

Důležité

Rozšíření značek můžou mít vlastnosti, ale nejsou nastavené jako atributy XML. V rozšíření značek jsou nastavení vlastností oddělená čárkami a ve složených závorkách se nezobrazují žádné uvozovky.

Sdílené prostředky

Některé stránky XAML obsahují několik zobrazení s vlastnostmi nastavenými na stejné hodnoty. Například mnoho nastavení vlastnosti pro tyto Button objekty je stejné:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamlSamples.SharedResourcesPage"
             Title="Shared Resources Page">
    <StackLayout>
        <Button Text="Do this!"
                HorizontalOptions="Center"
                VerticalOptions="Center"
                BorderWidth="3"
                Rotation="-15"
                TextColor="Red"
                FontSize="24" />
        <Button Text="Do that!"
                HorizontalOptions="Center"
                VerticalOptions="Center"
                BorderWidth="3"
                Rotation="-15"
                TextColor="Red"
                FontSize="24" />
        <Button Text="Do the other thing!"
                HorizontalOptions="Center"
                VerticalOptions="Center"
                BorderWidth="3"
                Rotation="-15"
                TextColor="Red"
                FontSize="24" />
    </StackLayout>
</ContentPage>

Pokud je potřeba některou z těchto vlastností změnit, můžete změnu raději provést jen jednou, a ne třikrát. Pokud by to byl kód, pravděpodobně byste používali konstanty a statické objekty jen pro čtení, které vám pomůžou zachovat takové hodnoty konzistentní a snadno upravit.

Jedním z oblíbených řešení v JAZYCE XAML je uložení takových hodnot nebo objektů ve slovníku prostředků. Třída VisualElement definuje vlastnost s názvem Resources typu ResourceDictionary, což je slovník s klíči typu string a hodnoty typu object. Objekty můžete vložit do tohoto slovníku a pak na ně odkazovat z revizí, a to vše v XAML.

Pokud chcete použít slovník prostředků na stránce, přidejte do horní části stránky dvojici značek elementů Resources vlastností a přidejte prostředky do těchto značek. Objekty a hodnoty různých typů lze přidat do slovníku prostředků. Tyto typy musí být okamžité. Nemůžou být například abstraktními třídami. Tyto typy musí mít také veřejný konstruktor bez parametrů. Každá položka vyžaduje klíč slovníku zadaný atributem x:Key :

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamlSamples.SharedResourcesPage"
             Title="Shared Resources Page">
    <ContentPage.Resources>
        <LayoutOptions x:Key="horzOptions"
                       Alignment="Center" />
        <LayoutOptions x:Key="vertOptions"
                       Alignment="Center" />
    </ContentPage.Resources>
    ...
</ContentPage>

V tomto příkladu jsou dva prostředky hodnotami typu LayoutOptionsstruktury a každý má jedinečný klíč a jednu nebo dvě sady vlastností. V kódu a kódu je mnohem častější používat statická pole LayoutOptions, ale zde je vhodnější nastavit vlastnosti.

Poznámka:

Volitelné ResourceDictionary značky mohou být zahrnuty jako podřízené značky Resources .

Prostředky pak mohou objekty využívat Button pomocí StaticResource rozšíření značek XAML k nastavení jejich HorizontalOptions a VerticalOptions vlastností:

<Button Text="Do this!"
        HorizontalOptions="{StaticResource horzOptions}"
        VerticalOptions="{StaticResource vertOptions}"
        BorderWidth="3"
        Rotation="-15"
        TextColor="Red"
        FontSize="24" />

Rozšíření StaticResource značek je vždy oddělené složenými závorkami a obsahuje klíč slovníku. Název StaticResource ho odlišuje od DynamicResource, který podporuje také .NET MAUI. DynamicResource je určen pro klíče slovníku přidružené k hodnotám, které se můžou změnit za běhu, zatímco StaticResource při vytváření prvků na stránce přistupuje k prvkům ze slovníku jen jednou. Kdykoli analyzátor XAML narazí na StaticResource rozšíření značek, vyhledá strom vizuálu a použije první ResourceDictionary , na které narazí obsahující tento klíč.

Je nutné uložit dvojité položky ve slovníku BorderWidthRotationpro , a FontSize vlastnosti. XAML pohodlně definuje značky pro běžné datové typy jako x:Double a x:Int32:

<ContentPage.Resources>
        <LayoutOptions x:Key="horzOptions"
                       Alignment="Center" />
        <LayoutOptions x:Key="vertOptions"
                       Alignment="Center" />
        <x:Double x:Key="borderWidth">3</x:Double>
        <x:Double x:Key="rotationAngle">-15</x:Double>
        <x:Double x:Key="fontSize">24</x:Double>        
</ContentPage.Resources>

Na tyto další tři prostředky lze odkazovat stejným způsobem jako na LayoutOptions hodnoty:

<Button Text="Do this!"
        HorizontalOptions="{StaticResource horzOptions}"
        VerticalOptions="{StaticResource vertOptions}"
        BorderWidth="{StaticResource borderWidth}"
        Rotation="{StaticResource rotationAngle}"
        TextColor="Red"
        FontSize="{StaticResource fontSize}" />

Pro prostředky typu Colormůžete použít stejné řetězcové reprezentace, které používáte při přímém přiřazování atributů těchto typů. Převaděče typů zahrnuté v rozhraní .NET MAUI jsou vyvolány při vytvoření prostředku. Třídu v rámci slovníku OnPlatform prostředků je také možné použít k definování různých hodnot pro platformy. Následující příklad používá tuto třídu k nastavení různých barev textu:

<OnPlatform x:Key="textColor"
            x:TypeArguments="Color">
    <On Platform="iOS" Value="Red" />
    <On Platform="Android" Value="Aqua" />
</OnPlatform>

Prostředek OnPlatform získá x:Key atribut, protože se jedná o objekt ve slovníku a x:TypeArguments atribut, protože se jedná o obecnou třídu. Atributy iOSa Android atributy jsou převedeny na Color hodnoty při inicializaci objektu.

Následující příklad ukazuje tři tlačítka, která přistupují k šesti sdíleným hodnotám:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamlSamples.SharedResourcesPage"
             Title="Shared Resources Page">
    <ContentPage.Resources>
        <LayoutOptions x:Key="horzOptions"
                       Alignment="Center" />
        <LayoutOptions x:Key="vertOptions"
                       Alignment="Center" />
        <x:Double x:Key="borderWidth">3</x:Double>
        <x:Double x:Key="rotationAngle">-15</x:Double>
        <x:Double x:Key="fontSize">24</x:Double>    
        <OnPlatform x:Key="textColor"
                    x:TypeArguments="Color">
            <On Platform="iOS" Value="Red" />
            <On Platform="Android" Value="Aqua" />
            <On Platform="WinUI" Value="#80FF80" />
        </OnPlatform>
    </ContentPage.Resources>

    <StackLayout>
        <Button Text="Do this!"
                HorizontalOptions="{StaticResource horzOptions}"
                VerticalOptions="{StaticResource vertOptions}"
                BorderWidth="{StaticResource borderWidth}"
                Rotation="{StaticResource rotationAngle}"
                TextColor="{StaticResource textColor}"
                FontSize="{StaticResource fontSize}" />
        <Button Text="Do that!"
                HorizontalOptions="{StaticResource horzOptions}"
                VerticalOptions="{StaticResource vertOptions}"
                BorderWidth="{StaticResource borderWidth}"
                Rotation="{StaticResource rotationAngle}"
                TextColor="{StaticResource textColor}"
                FontSize="{StaticResource fontSize}" />
        <Button Text="Do the other thing!"
                HorizontalOptions="{StaticResource horzOptions}"
                VerticalOptions="{StaticResource vertOptions}"
                BorderWidth="{StaticResource borderWidth}"
                Rotation="{StaticResource rotationAngle}"
                TextColor="{StaticResource textColor}"
                FontSize="{StaticResource fontSize}" />
    </StackLayout>
</ContentPage>

Následující snímek obrazovky ověřuje konzistentní styly:

Snímek obrazovky se stylovanými ovládacími prvky

I když je běžné definovat Resources kolekci v horní části stránky, můžete mít Resources kolekce na jiných prvcích na stránce. Například následující příklad ukazuje prostředky přidané do StackLayout:

<StackLayout>
    <StackLayout.Resources>
        <Color x:Key="textColor">Blue</Color>
    </StackLayout.Resources>
    ...
</StackLayout>

Jedním z nejběžnějších typů objektů uložených ve slovníkech prostředků je .NET MAUI Style, který definuje kolekci nastavení vlastností. Další informace o stylech najdete v tématu Aplikace stylů využívající XAML.

Poznámka:

Účelem slovníku prostředků je sdílet objekty. Proto nemá smysl vložit ovládací prvky, jako Label je slovník prostředků nebo Button do něj. Vizuální prvky nelze sdílet, protože stejná instance se na stránce nezobrazí dvakrát.

x:Static – rozšíření značek

Kromě StaticResource rozšíření značek existuje také x:Static rozšíření značek. Zatímco StaticResource však vrátí objekt ze slovníku prostředků,x:Static přistupuje k veřejnému statickému poli, veřejné statické vlastnosti, veřejnému konstantnímu poli nebo členu výčtu.

Poznámka:

Rozšíření StaticResource značek je podporováno implementacemi XAML, které definují slovník prostředků, zatímco x:Static je vnitřní součástí XAML, jak se předpona x odhalí.

Následující příklad ukazuje, jak x:Static lze explicitně odkazovat na statická pole a členy výčtu:

<Label Text="Hello, XAML!"
       VerticalOptions="{x:Static LayoutOptions.Start}"
       HorizontalTextAlignment="{x:Static TextAlignment.Center}"
       TextColor="{x:Static Colors.Aqua}" />

Hlavním použitím rozšíření značek je odkazování na statická pole nebo vlastnosti z vlastního x:Static kódu. Tady je AppConstants například třída, která obsahuje některá statická pole, která můžete chtít použít na více stránkách v celé aplikaci:

namespace XamlSamples
{
    static class AppConstants
    {
        public static readonly Color BackgroundColor = Colors.Aqua;
        public static readonly Color ForegroundColor = Colors.Brown;
    }
}

Chcete-li odkazovat na statická pole této třídy v souboru XAML, musíte použít deklaraci oboru názvů XML k označení umístění tohoto souboru. Každá další deklarace oboru názvů XML definuje novou předponu. Pro přístup ke třídám místnímu k oboru názvů kořenové aplikace, například AppConstants, můžete použít předponu local. Deklarace oboru názvů musí obsahovat název oboru názvů CLR (Common Language Runtime), označovaný také jako název oboru názvů .NET, což je název, který se zobrazuje v definici jazyka C# namespace nebo v direktivě using :

xmlns:local="clr-namespace:XamlSamples"

Můžete také definovat deklarace oboru názvů XML pro obory názvů .NET. Tady je například sys předpona standardního oboru názvů .NET System , který je v netstandard sestavení. Vzhledem k tomu, že se jedná o jiné sestavení, musíte také zadat název sestavení, v tomto případě netstandard:

xmlns:sys="clr-namespace:System;assembly=netstandard"

Poznámka:

Za klíčovým slovem clr-namespace následuje dvojtečka a potom název oboru názvů .NET, za kterým následuje středník, klíčové slovo assembly, znaménko rovná se a název sestavení.

Po deklarování oboru názvů XML je pak možné použít statická pole:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:XamlSamples"
             xmlns:sys="clr-namespace:System;assembly=netstandard"
             x:Class="XamlSamples.StaticConstantsPage"
             Title="Static Constants Page"
             Padding="5,25,5,0">
    <StackLayout>
       <Label Text="Hello, XAML!"
              TextColor="{x:Static local:AppConstants.BackgroundColor}"
              BackgroundColor="{x:Static local:AppConstants.ForegroundColor}"
              FontAttributes="Bold"
              FontSize="30"
              HorizontalOptions="Center" />
      <BoxView WidthRequest="{x:Static sys:Math.PI}"
               HeightRequest="{x:Static sys:Math.E}"
               Color="{x:Static local:AppConstants.ForegroundColor}"
               HorizontalOptions="Center"
               VerticalOptions="CenterAndExpand"
               Scale="100" />
    </StackLayout>
</ContentPage>

V tomto příkladu BoxView jsou dimenze nastaveny na Math.PI a Math.E, ale škálovány faktorem 100:

Snímek obrazovky s ovládacími prvky používajícími rozšíření x:Static markup

Další rozšíření značek

Několik rozšíření značek jsou vnitřní pro XAML a podporují se v .NET MAUI XAML. Některé z nich se velmi často nepoužívají, ale jsou nezbytné, pokud je potřebujete:

Pokud vlastnost má ve výchozím nastavení jinou hodnotu null , ale chcete ji nastavit na null, nastavte ji na {x:Null} rozšíření značek.
Pokud je vlastnost typu Type, můžete ji přiřadit k objektu Type pomocí rozšíření {x:Type someClass}značek .
Pole v XAML můžete definovat pomocí x:Array rozšíření značek. Toto rozšíření značek má požadovaný atribut, Type který označuje typ prvků v poli.

Další informace o rozšířeních značek XAML naleznete v tématu Využití rozšíření značek XAML.

Další kroky

Datové vazby .NET MAUI umožňují propojení vlastností dvou objektů tak, aby změna v jednom způsobí změnu v druhém objektu.

Základy datových vazeb

Sdílet prostřednictvím

Rozšíření značek XAML

Sdílené prostředky

x:Static – rozšíření značek

Další rozšíření značek

Další kroky

Další materiály