Criar um tema para um aplicativo

Navegar no exemplo

Os aplicativos .NET Multi-platform App UI (.NET MAUI) podem responder a alterações de estilo de forma dinâmica em tempo de execução, usando a extensão de marcação DynamicResource. Esse tipo de extensão de marcação é semelhante à extensão de marcação StaticResource, pois ambas usam uma chave de dicionário para buscar um valor de um ResourceDictionary. No entanto, enquanto a extensão de marcação StaticResource executa uma única pesquisa de dicionário, a extensão de marcação DynamicResource mantém um link para a chave de dicionário. Portanto, se o valor associado à chave for substituído, a alteração será aplicada ao VisualElement. Isso permite que os temas de runtime sejam implementados em aplicativos .NET MAUI.

Para implementar temas de runtime em um aplicativo .NET MAUI você precisa:

1. Definir os recursos para cada tema em um ResourceDictionary. Para mais informações, veja Definir temas.
2. Definir um tema padrão no arquivo App.xaml do aplicativo. Para mais informações, veja Definir um tema padrão.
3. Consumir recursos de tema no aplicativo, usando a extensão de marcação DynamicResource. Para mais informações, consulte Usar recursos de tema.
4. Adicionar código para carregar um tema em runtime. Para obter mais informações, veja Carregar um tema no tempo de execução.

A captura de tela a seguir mostra páginas temáticas, com o aplicativo iOS usando um tema claro e o aplicativo Android usando um tema escuro:

Captura de tela da página principal de um aplicativo temático.

O .NET MAUI também tem a capacidade de responder a alterações de tema do sistema. O tema do sistema pode mudar por vários motivos, dependendo da configuração do dispositivo. Isso inclui o tema do sistema sendo explicitamente alterado pelo usuário, ele mudando devido à hora do dia e ele mudando devido a fatores ambientais, como pouca luz. Para mais informações, consulte Responda a alterações do tema do sistema.

Definir temas

Um tema é definido como uma coleção de objetos de recurso armazenados em um arquivo denominado ResourceDictionaryResourceDictionaryResourceDictionary.

O exemplo a seguir mostra um ResourceDictionary para um tema claro chamado LightTheme:

<ResourceDictionary xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
                    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                    x:Class="ThemingDemo.LightTheme">
    <Color x:Key="PageBackgroundColor">White</Color>
    <Color x:Key="NavigationBarColor">WhiteSmoke</Color>
    <Color x:Key="PrimaryColor">WhiteSmoke</Color>
    <Color x:Key="SecondaryColor">Black</Color>
    <Color x:Key="PrimaryTextColor">Black</Color>
    <Color x:Key="SecondaryTextColor">White</Color>
    <Color x:Key="TertiaryTextColor">Gray</Color>
    <Color x:Key="TransparentColor">Transparent</Color>
</ResourceDictionary>

O exemplo a seguir mostra um ResourceDictionary para um tema escuro chamado DarkTheme:

<ResourceDictionary xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
                    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                    x:Class="ThemingDemo.DarkTheme">
    <Color x:Key="PageBackgroundColor">Black</Color>
    <Color x:Key="NavigationBarColor">Teal</Color>
    <Color x:Key="PrimaryColor">Teal</Color>
    <Color x:Key="SecondaryColor">White</Color>
    <Color x:Key="PrimaryTextColor">White</Color>
    <Color x:Key="SecondaryTextColor">White</Color>
    <Color x:Key="TertiaryTextColor">WhiteSmoke</Color>
    <Color x:Key="TransparentColor">Transparent</Color>
</ResourceDictionary>

Cada ResourceDictionary contém Color recursos que definem seus respectivos temas, com cada ResourceDictionary usando chaves idênticas. Para mais informações sobre dicionários de recursos, veja Dicionários de Recursos.

Definir um tema padrão

Um aplicativo requer um tema padrão, para que os controles tenham valores para os recursos que consomem. Um tema padrão pode ser definido integrando o ResourceDictionary do tema no ResourceDictionary no nível do aplicativo definido em App.xaml:

<Application xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="ThemingDemo.App">
    <Application.Resources>
        <ResourceDictionary Source="Themes/LightTheme.xaml" />
    </Application.Resources>
</Application>

Para mais informações sobre mesclar dicionários de recursos, consulte Dicionários de recursos mesclados.

Consumir recursos de tema

Quando um aplicativo quer consumir um recurso armazenado em um ResourceDictionary que representa um tema, deve fazê-lo com a DynamicResource extensão de marcação. Isso garante que, se um tema diferente for selecionado no runtime, os valores do novo tema serão aplicados.

O exemplo a seguir mostra três estilos que podem ser aplicados a todos os objetos Label no aplicativo:

<Application xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="ThemingDemo.App">
    <Application.Resources>

        <Style x:Key="LargeLabelStyle"
               TargetType="Label">
            <Setter Property="TextColor"
                    Value="{DynamicResource SecondaryTextColor}" />
            <Setter Property="FontSize"
                    Value="30" />
        </Style>

        <Style x:Key="MediumLabelStyle"
               TargetType="Label">
            <Setter Property="TextColor"
                    Value="{DynamicResource PrimaryTextColor}" />
            <Setter Property="FontSize"
                    Value="25" />
        </Style>

        <Style x:Key="SmallLabelStyle"
               TargetType="Label">
            <Setter Property="TextColor"
                    Value="{DynamicResource TertiaryTextColor}" />
            <Setter Property="FontSize"
                    Value="15" />
        </Style>

    </Application.Resources>
</Application>

Esses estilos são definidos no dicionário de recursos no nível do aplicativo, para que possam ser consumidos por várias páginas. Cada estilo consome recursos de tema com a extensão de marcação DynamicResource.

Esses estilos são então consumidos por páginas:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:ThemingDemo"
             x:Class="ThemingDemo.UserSummaryPage"
             Title="User Summary"
             BackgroundColor="{DynamicResource PageBackgroundColor}">
    ...
    <ScrollView>
        <Grid>
            <Grid.RowDefinitions>
                <RowDefinition Height="200" />
                <RowDefinition Height="120" />
                <RowDefinition Height="70" />
            </Grid.RowDefinitions>
            <Grid BackgroundColor="{DynamicResource PrimaryColor}">
                <Label Text="Face-Palm Monkey"
                       VerticalOptions="Center"
                       Margin="15"
                       Style="{StaticResource MediumLabelStyle}" />
                ...
            </Grid>
            <StackLayout Grid.Row="1"
                         Margin="10">
                <Label Text="This monkey reacts appropriately to ridiculous assertions and actions."
                       Style="{StaticResource SmallLabelStyle}" />
                <Label Text="  &#x2022; Cynical but not unfriendly."
                       Style="{StaticResource SmallLabelStyle}" />
                <Label Text="  &#x2022; Seven varieties of grimaces."
                       Style="{StaticResource SmallLabelStyle}" />
                <Label Text="  &#x2022; Doesn't laugh at your jokes."
                       Style="{StaticResource SmallLabelStyle}" />
            </StackLayout>
            ...
        </Grid>
    </ScrollView>
</ContentPage>

Quando um recurso de tema é consumido diretamente, ele deve ser consumido com a extensão de marcação `DynamicResource`. No entanto, quando um estilo que usa a extensão de marcação DynamicResource é consumido, ele deve ser consumido com a extensão de marcação StaticResource.

Para mais informações sobre como estilizar, consulte Estilo de aplicativos usando XAML. Para mais informações sobre a extensão de marcação DynamicResource, consulte Estilos dinâmicos.

Carregar um tema em runtime

Quando um tema é selecionado em runtime, um aplicativo deve:

1. Remover o tema atual do aplicativo. Isso é feito limpando a propriedade MergedDictionaries do ResourceDictionary no nível do aplicativo.
2. Carregar o tema selecionado. Isso é feito adicionando uma instância do tema selecionado à propriedade MergedDictionaries do ResourceDictionary no nível do aplicativo.

Todos os objetos VisualElement que definem propriedades com a extensão de marcação DynamicResource aplicarão os novos valores de tema. Isso ocorre porque a extensão de marcação DynamicResource mantém um link para chaves de dicionário. Portanto, quando os valores associados às chaves são substituídos, as alterações são aplicadas aos objetos VisualElement.

No aplicativo de exemplo, um tema é selecionado por meio de uma página modal que contém um elemento `Picker`. O código a seguir mostra o método OnPickerSelectionChanged, que é executado quando o tema selecionado é alterado:

O exemplo a seguir mostra a remoção do tema atual e o carregamento de um novo tema:

ICollection<ResourceDictionary> mergedDictionaries = Application.Current.Resources.MergedDictionaries;
if (mergedDictionaries != null)
{
    mergedDictionaries.Clear();
    mergedDictionaries.Add(new DarkTheme());
}