Responder às alterações de tema do sistema

Visualizar a amostra

Os dispositivos normalmente incluem temas claros e escuros, que se referem a um amplo conjunto de preferências de aparência que podem ser definidas no nível do sistema operacional. Os aplicativos devem respeitar esses temas do sistema e responder imediatamente quando o tema do sistema for alterado.

O tema do sistema pode ser alterado 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 mudando devido a fatores ambientais, como pouca luz.

Os aplicativos .NET MAUI (interface de usuário multiplataforma do .NET) podem responder às alterações de tema do sistema consumindo recursos com a extensão de marcação AppThemeBinding, e os métodos de extensão SetAppThemeColor e SetAppTheme<T>.

A captura de tela a seguir mostra páginas temáticas para o tema do sistema claro no iOS e o tema do sistema escuro no Android:

Definir e consumir recursos de tema

Recursos para temas claros e escuros podem ser consumidos com a extensão de marcação AppThemeBinding, e os métodos de extensão SetAppThemeColor e SetAppTheme<T>. Com essas abordagens, os recursos são aplicados automaticamente com base no valor do tema atual do sistema. Além disso, os objetos que consomem esses recursos são atualizados automaticamente se o tema do sistema é alterado enquanto um aplicativo está em execução.

Extensão de marcação AppThemeBinding

A AppThemeBinding extensão de marcação permite que você consuma um recurso, como uma imagem ou cor, com base no tema atual do sistema.

A extensão de marcação AppThemeBinding é compatível com a classe AppThemeBindingExtension, que define as seguintes propriedades:

• Default, do tipo object, que você define como o recurso a ser usado por padrão.
• Light, do tipo object, que você define como o recurso a ser usado quando o dispositivo está usando seu tema claro.
• Dark, do tipo object, que você define para o recurso a ser usado quando o dispositivo está usando seu tema escuro.
• Value, do tipo object, que retorna o recurso que está sendo usado atualmente pela extensão de marcação.

A propriedade Default é a propriedade de conteúdo do AppThemeBindingExtension. Portanto, para expressões de marcação XAML expressas com chaves, você pode eliminar a parte Default= da expressão, desde que ela seja o primeiro argumento.

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

<StackLayout>
    <Label Text="This text is green in light mode, and red in dark mode."
           TextColor="{AppThemeBinding Light=Green, Dark=Red}" />
    <Image Source="{AppThemeBinding Light=lightlogo.png, Dark=darklogo.png}" />
</StackLayout>

Neste exemplo, a cor do texto da primeira Label é definida como verde quando o dispositivo está usando seu tema claro e é definida como vermelho quando o dispositivo está usando seu tema escuro. Da mesma forma, o Image exibe um arquivo de imagem diferente com base no tema atual do sistema.

Os recursos definidos em um ResourceDictionary podem ser consumidos em um AppThemeBinding com a extensão de marcação de StaticResource.

<ContentPage ...>
    <ContentPage.Resources>

        <!-- Light colors -->
        <Color x:Key="LightPrimaryColor">WhiteSmoke</Color>
        <Color x:Key="LightSecondaryColor">Black</Color>

        <!-- Dark colors -->
        <Color x:Key="DarkPrimaryColor">Teal</Color>
        <Color x:Key="DarkSecondaryColor">White</Color>

        <Style x:Key="ButtonStyle"
               TargetType="Button">
            <Setter Property="BackgroundColor"
                    Value="{AppThemeBinding Light={StaticResource LightPrimaryColor}, Dark={StaticResource DarkPrimaryColor}}" />
            <Setter Property="TextColor"
                    Value="{AppThemeBinding Light={StaticResource LightSecondaryColor}, Dark={StaticResource DarkSecondaryColor}}" />
        </Style>

    </ContentPage.Resources>

    <Grid BackgroundColor="{AppThemeBinding Light={StaticResource LightPrimaryColor}, Dark={StaticResource DarkPrimaryColor}}">
      <Button Text="MORE INFO"
              Style="{StaticResource ButtonStyle}" />
    </Grid>    
</ContentPage>    

Neste exemplo, a cor de fundo e o estilo do Grid e do Button são alterados com base na utilização do tema claro ou tema escuro pelo dispositivo.

Além disso, os recursos definidos em um ResourceDictionary também podem ser consumidos em uma AppThemeBinding com a extensão de marcação DynamicResource.

<ContentPage ...>
    <ContentPage.Resources>
        <Color x:Key="Primary">DarkGray</Color>
        <Color x:Key="Secondary">HotPink</Color>
        <Color x:Key="Tertiary">Yellow</Color>
        <Style x:Key="labelStyle" TargetType="Label">
            <Setter Property="Padding" Value="5"/>
            <Setter Property="TextColor" Value="{AppThemeBinding Light={StaticResource Secondary}, Dark={StaticResource Primary}}" />
            <Setter Property="BackgroundColor" Value="{AppThemeBinding Light={DynamicResource Primary}, Dark={DynamicResource Secondary}}" />
        </Style>
    </ContentPage.Resources>
    <Label x:Name="myLabel"
           Style="{StaticResource labelStyle}"/>
</ContentPage>

Métodos de extensão

.NET MAUI inclui SetAppThemeColor e SetAppTheme<T> métodos de extensão que permitem que VisualElement objetos respondam às alterações de tema do sistema.

O SetAppThemeColor método permite que Color os objetos sejam especificados que serão definidos em uma propriedade de destino com base no tema atual do sistema:

Label label = new Label();
label.SetAppThemeColor(Label.TextColorProperty, Colors.Green, Colors.Red);

Neste exemplo, a cor do texto do Label é definida como verde quando o dispositivo estiver no tema claro e é definida como vermelho quando estiver no tema escuro.

O SetAppTheme<T> método permite que objetos do tipo T sejam especificados que serão definidos em uma propriedade de destino com base no tema atual do sistema:

Image image = new Image();
image.SetAppTheme<FileImageSource>(Image.SourceProperty, "lightlogo.png", "darklogo.png");

Neste exemplo, o Image exibe lightlogo.png quando o dispositivo está usando seu tema claro, e exibe darklogo.png quando está usando seu tema escuro.

Detectar o tema atual do sistema

O tema atual do sistema pode ser detectado obtendo o valor da Application.RequestedTheme propriedade:

AppTheme currentTheme = Application.Current.RequestedTheme;

A RequestedTheme propriedade retorna um AppTheme membro de enumeração. A enumeração AppTheme define os seguintes membros:

• Unspecified, que indica que o dispositivo está usando um tema não especificado.
• Light, indicando que o dispositivo está usando seu tema claro.
• Dark, que indica que o dispositivo está usando seu tema escuro.

Definir o tema atual do usuário

O tema usado pelo aplicativo pode ser definido com a Application.UserAppTheme propriedade, que é do tipo AppTheme, independentemente de qual tema do sistema esteja atualmente operacional:

Application.Current.UserAppTheme = AppTheme.Dark;

Neste exemplo, o aplicativo está definido para usar o tema definido para o modo escuro do sistema, independentemente de qual tema do sistema esteja operacional no momento.

Reagir às alterações de tema

O tema do sistema em um dispositivo pode ser alterado por vários motivos, dependendo de como o dispositivo está configurado. Os aplicativos MAUI do .NET podem ser notificados quando o tema do sistema é alterado manipulando o Application.RequestedThemeChanged evento:

Application.Current.RequestedThemeChanged += (s, a) =>
{
    // Respond to the theme change
};

O AppThemeChangedEventArgs objeto, que acompanha o RequestedThemeChanged evento, tem uma única propriedade chamada RequestedTheme, do tipo AppTheme. Essa propriedade pode ser examinada para detectar o tema do sistema solicitado.