Consumir extensões de marcação XAML

Explorar o de exemplo

As extensões de marcação XAML da interface do usuário do aplicativo multiplataforma .NET (.NET MAUI) ajudam a aumentar o poder e a flexibilidade do XAML, permitindo que os atributos de elemento sejam definidos a partir de uma variedade de fontes.

Por exemplo, você normalmente define a propriedade Color de BoxView assim:

<BoxView Color="Blue" />

No entanto, você pode preferir definir o atributo Color a partir de um valor armazenado em um dicionário de recursos, ou do valor de uma propriedade estática de uma classe que você criou, ou de uma propriedade do tipo Color de outro elemento na página, ou construída a partir de valores separados de matiz, saturação e luminosidade. Todas essas opções são possíveis usando extensões de marcação XAML.

Uma extensão de marcação é uma maneira diferente de expressar um atributo de um elemento. As extensões de marcação .NET MAUI XAML geralmente são identificáveis por um valor de atributo que está incluído em chaves curvas:

<BoxView Color="{StaticResource themeColor}" />

Qualquer valor de atributo em chaves é sempre uma extensão de marcação XAML. No entanto, as extensões de marcação XAML também podem ser referenciadas sem o uso de chaves encaracoladas.

Observação

Várias extensões de marcação XAML fazem parte da especificação XAML 2009. Eles aparecem em arquivos XAML com o prefixo de namespace x habitual e são comumente referidos com esse prefixo.

Além das extensões de marcação discutidas neste artigo, as seguintes extensões de marcação são incluídas no .NET MAUI e discutidas em outros artigos:

• AppThemeBinding - Especifica um recurso a ser consumido com base no tema do sistema atual. Para obter mais informações, consulte extensão de marcação AppThemeBinding.
• Binding - estabelece uma ligação entre as propriedades de dois objetos. Para obter mais informações, consulte Vinculação de dados.
• DynamicResource - responde a alterações em objetos em um dicionário de recursos. Para obter mais informações, consulte Estilos dinâmicos.
• FontImage - exibe um ícone de fonte em qualquer visualização que possa exibir um ImageSource. Para obter mais informações, consulte Carregar um ícone de fonte.
• OnIdiom - personaliza a aparência da interface do usuário com base no idioma do dispositivo em que o aplicativo está sendo executado. Para obter mais informações, consulte Personalizar a aparência da interface do usuário com base no idioma do dispositivo.
• OnPlatform - personaliza a aparência da interface do usuário por plataforma. Para obter mais informações, consulte Personalizar a aparência da interface do usuário com base na plataforma.
• RelativeSource - define a origem da ligação relativa à posição do destino da ligação. Para obter mais informações, consulte Ligações relativas.
• StaticResource - faz referência a objetos de um dicionário de recursos. Para obter mais informações, consulte Dicionários de recursos.
• TemplateBinding - executa a vinculação de dados a partir de um modelo de controle. Para obter mais informações, consulte Modelos de controle .

x:Extensão de marcação estática

A extensão de marcação x:Static é suportada pela classe StaticExtension. A classe tem uma única propriedade chamada Member do tipo string que você define como o nome de uma constante pública, propriedade estática, campo estático ou membro de enumeração.

Uma maneira de usar x:Static é primeiro definir uma classe com algumas constantes ou variáveis estáticas, como esta classe AppConstants:

static class AppConstants
{
    public static double NormalFontSize = 18;
}

O XAML a seguir demonstra a abordagem mais detalhada para instanciar a classe StaticExtension entre as etiquetas de elemento de propriedade Label.FontSize:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:sys="clr-namespace:System;assembly=netstandard"
             xmlns:local="clr-namespace:MarkupExtensions"
             x:Class="MarkupExtensions.StaticDemoPage"
             Title="x:Static Demo">
    <StackLayout Margin="10, 0">
        <Label Text="Label No. 1">
            <Label.FontSize>
                <x:StaticExtension Member="local:AppConstants.NormalFontSize" />
            </Label.FontSize>
        </Label>
        ···
    </StackLayout>
</ContentPage>

O analisador XAML também permite que a classe StaticExtension seja abreviada como x:Static:

<Label Text="Label No. 2">
    <Label.FontSize>
        <x:Static Member="local:AppConstants.NormalFontSize" />
    </Label.FontSize>
</Label>

Esta sintaxe pode ser ainda mais simplificada colocando a classe StaticExtension e a definição do membro entre chaves. A expressão resultante é definida diretamente para o atributo FontSize:

<Label Text="Label No. 3"
       FontSize="{x:StaticExtension Member=local:AppConstants.NormalFontSize}" />

Neste exemplo, não há aspas dentro das chaves encaracoladas. A propriedade Member de StaticExtension não é mais um atributo XML. Em vez disso, é parte da expressão para a extensão de marcação.

Assim como você pode abreviar x:StaticExtension para x:Static quando você usá-lo como um elemento de objeto, você também pode abreviar na expressão dentro de chaves encaracoladas:

<Label Text="Label No. 4"
       FontSize="{x:Static Member=local:AppConstants.NormalFontSize}" />

A classe StaticExtension tem um atributo ContentProperty que faz referência à propriedade Member, que marca essa propriedade como a propriedade de conteúdo padrão da classe. Para extensões de marcação XAML expressas com chaves curvas, pode-se eliminar a parte Member= da expressão:

<Label Text="Label No. 5"
       FontSize="{x:Static local:AppConstants.NormalFontSize}" />

Esta é a forma mais comum da extensão de marcação x:Static.

A marca raiz do exemplo XAML também contém uma declaração de namespace XML para o namespace .NET System. Isso permite que o tamanho da fonte Label seja definido como o campo estático Math.PI. Isso resulta em um texto bastante pequeno, de modo que a propriedade Scale é definida como Math.E:

<Label Text="&#x03C0; &#x00D7; E sized text"
       FontSize="{x:Static sys:Math.PI}"
       Scale="{x:Static sys:Math.E}"
       HorizontalOptions="Center" />

A captura de tela a seguir mostra a saída XAML:

x:Extensão de marcação de referência

A extensão de marcação x:Reference é suportada pela classe ReferenceExtension. A classe tem uma única propriedade chamada Name do tipo string que você define como o nome de um elemento na página que recebeu um nome com x:Name. Esta propriedade Name é a propriedade de conteúdo de ReferenceExtension, portanto, Name= não é necessária quando x:Reference aparece entre chavetas. A extensão de marcação x:Reference é usada exclusivamente com associações de dados. Para obter mais informações sobre associação de dados, consulte Vinculação de Dados.

O exemplo XAML a seguir mostra dois usos de x:Reference com associações de dados, o primeiro onde ele é usado para definir a propriedade Source do objeto Binding e o segundo onde ele é usado para definir a propriedade BindingContext para duas associações de dados:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MarkupExtensions.ReferenceDemoPage"
             x:Name="page"
             Title="x:Reference Demo">    
    <StackLayout Margin="10, 0">        
        <Label x:DataType="ContentPage"
               Text="{Binding Source={x:Reference page},
                              StringFormat='The type of this page is {0}'}"
               FontSize="18"
               VerticalOptions="Center"
               HorizontalTextAlignment="Center" />
        <Slider x:Name="slider"
                Maximum="360"
                VerticalOptions="Center" />
        <Label x:DataType="Slider"
               BindingContext="{x:Reference slider}"
               Text="{Binding Value, StringFormat='{0:F0}&#x00B0; rotation'}"
               Rotation="{Binding Value}"
               FontSize="24"
               HorizontalOptions="Center"
               VerticalOptions="Center" />        
    </StackLayout>
</ContentPage>

Neste exemplo, ambas as expressões x:Reference usam a versão abreviada do nome da classe ReferenceExtension e eliminam a parte Name= da expressão. No primeiro exemplo, a extensão de marcação x:Reference é incorporada na extensão de marcação Binding e as propriedades Source e StringFormat são separadas por vírgulas.

A captura de tela a seguir mostra a saída XAML:

x:Extensão de marcação de tipo

A extensão de marcação x:Type é o equivalente XAML da palavra-chave C# typeof. Ele é suportado pela classe TypeExtension, que define uma propriedade chamada TypeName do tipo string que deve ser definida como um nome de classe ou estrutura. A extensão de marcação x:Type retorna o objeto Type dessa classe ou estrutura. TypeName é a propriedade de conteúdo de TypeExtension, portanto, TypeName= não é necessário quando x:Type aparece com chaves encaracoladas.

A extensão de marcação x:Type é comumente usada com a extensão de marcação x:Array. Para obter mais informações, consulte extensão de marcação x:Array.

O exemplo XAML a seguir demonstra o uso da extensão de marcação x:Type para instanciar objetos MAUI do .NET e adicioná-los a um StackLayout. O XAML consiste em três elementos Button com suas propriedades Command definidas como um Binding e as propriedades CommandParameter definidas como tipos de três modos de exibição MAUI do .NET:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:MarkupExtensions"
             x:Class="MarkupExtensions.TypeDemoPage"
             Title="x:Type Demo"
             x:DataType="local:TypeDemoPage">
    <StackLayout x:Name="stackLayout"
                 Padding="10, 0">
        <Button Text="Create a Slider"
                HorizontalOptions="Center"
                VerticalOptions="Center"
                Command="{Binding CreateCommand}"
                CommandParameter="{x:Type Slider}" />
        <Button Text="Create a Stepper"
                HorizontalOptions="Center"
                VerticalOptions="Center"
                Command="{Binding CreateCommand}"
                CommandParameter="{x:Type Stepper}" />
        <Button Text="Create a Switch"
                HorizontalOptions="Center"
                VerticalOptions="Center"
                Command="{Binding CreateCommand}"
                CommandParameter="{x:Type Switch}" />
    </StackLayout>
</ContentPage>

O arquivo code-behind define e inicializa a propriedade CreateCommand:

public partial class TypeDemoPage : ContentPage
{
    public ICommand CreateCommand { get; private set; }

    public TypeDemoPage()
    {
        InitializeComponent();

        CreateCommand = new Command<Type>((Type viewType) =>
        {
            View view = (View)Activator.CreateInstance(viewType);
            view.VerticalOptions = LayoutOptions.Center;
            stackLayout.Add(view);
        });

        BindingContext = this;
    }
}

Quando um Button é pressionado, uma nova instância do argumento CommandParameter é criada e adicionada ao StackLayout. Os três objetos Button compartilham a página com modos de exibição criados dinamicamente:

Os tipos genéricos podem ser especificados com a extensão de marcação x:Type especificando a restrição genérica como um argumento de cadeia de caracteres prefixado entre parênteses:

<x:Array Type="{x:Type local:MyType(local:MyObject)}">
    ...
</x:Array>

Vários argumentos de tipo podem ser especificados como argumentos de cadeia de caracteres prefixados, delimitados por uma vírgula:

<x:Array Type="{x:Type local:MyType(local:MyObject,x:Boolean)}">
    ...
</x:Array>

Para obter mais informações sobre genéricos em XAML, consulte Generics.

x:Extensão de marcação de matriz

A extensão de marcação x:Array permite definir uma matriz na marcação. Ele é suportado pela classe ArrayExtension, que define duas propriedades:

• Type do tipo Type, que indica o tipo dos elementos na matriz. Esta propriedade deve ser configurada para uma extensão de marcação x:Type.
• Items do tipo IList, que é uma coleção dos itens em si. Esta é a propriedade de conteúdo do ArrayExtension.

A extensão de marcação x:Array em si nunca aparece em chaves encaracoladas. Em vez disso, x:Array tags de início e fim delimitam a lista de itens.

O exemplo XAML a seguir mostra como usar x:Array para adicionar itens a um ListView definindo a propriedade ItemsSource como uma matriz:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MarkupExtensions.ArrayDemoPage"
             Title="x:Array Demo Page">
    <ListView Margin="10">
        <ListView.ItemsSource>
            <x:Array Type="{x:Type Color}">
                <Color>Aqua</Color>
                <Color>Black</Color>
                <Color>Blue</Color>
                <Color>Fuchsia</Color>
                <Color>Gray</Color>
                <Color>Green</Color>
                <Color>Lime</Color>
                <Color>Maroon</Color>
                <Color>Navy</Color>
                <Color>Olive</Color>
                <Color>Pink</Color>
                <Color>Purple</Color>
                <Color>Red</Color>
                <Color>Silver</Color>
                <Color>Teal</Color>
                <Color>White</Color>
                <Color>Yellow</Color>
            </x:Array>
        </ListView.ItemsSource>
        <ListView.ItemTemplate>
            <DataTemplate x:DataType="Color">
                <ViewCell>
                    <BoxView Color="{Binding}"
                             Margin="3" />
                </ViewCell>
            </DataTemplate>
        </ListView.ItemTemplate>
    </ListView>
</ContentPage>  

Neste exemplo, o ViewCell cria uma BoxView simples para cada entrada de cor:

Observação

Ao definir matrizes de tipos comuns, como cadeias de caracteres ou números, use as marcas primitivas da linguagem XAML listadas em Passar argumentos.

x:Extensão de marcação nula

A extensão de marcação x:Null é suportada pela classe NullExtension. Ele não tem propriedades e é simplesmente o equivalente XAML da palavra-chave C# null.

O exemplo XAML a seguir mostra como usar a extensão de marcação x:Null:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MarkupExtensions.NullDemoPage"
             Title="x:Null Demo">
    <ContentPage.Resources>
        <Style TargetType="Label">
            <Setter Property="FontSize" Value="48" />
            <Setter Property="FontFamily" Value="OpenSansRegular" />
        </Style>
    </ContentPage.Resources>

    <StackLayout Padding="10, 0">
        <Label Text="Text 1" />
        <Label Text="Text 2" />
        <Label Text="Text 3"
               FontFamily="{x:Null}" />
        <Label Text="Text 4" />
        <Label Text="Text 5" />
    </StackLayout>
</ContentPage>      

Neste exemplo, um Style implícito é definido para Label que inclui um Setter que define a propriedade FontFamily para uma fonte específica. No entanto, a terceira Label evita usar a fonte definida no estilo implícito, definindo seu FontFamily para x:Null:

Extensão de marcação DataTemplate

A extensão de marcação DataTemplate permite converter um tipo em DataTemplate. Ele é suportado pela classe DataTemplateExtension, que define uma propriedade TypeName, que é do tipo stringe é definido como o nome do tipo a ser convertido num DataTemplate. A propriedade TypeName é a propriedade de conteúdo de DataTemplateExtension. Portanto, para expressões de marcação XAML expressas com chaves encaracoladas, você pode eliminar a parte TypeName= da expressão.

Observação

O analisador XAML permite que a classe DataTemplateExtension seja abreviada como DataTemplate.

Um uso típico dessa extensão de marcação é em um aplicativo Shell, conforme mostrado no exemplo a seguir:

<ShellContent Title="Monkeys"
              Icon="monkey.png"
              ContentTemplate="{DataTemplate views:MonkeysPage}" />

Neste exemplo, MonkeysPage é convertido de um ContentPage para um DataTemplate, que é definido como o valor da propriedade ShellContent.ContentTemplate. Isso garante que MonkeysPage só seja criado quando a navegação para a página ocorrer, e não na inicialização do aplicativo.

Para obter mais informações sobre aplicativos Shell, consulte Shell.