Responder a alterações de tema do sistema

Navegue pelo exemplo

Os dispositivos normalmente incluem temas claros e escuros, cada um deles se refere 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 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.

Os aplicativos .NET Multi-platform App UI (.NET MAUI) podem responder a alterações de tema do sistema consumindo recursos com a AppThemeBinding extensão de marcação e os SetAppThemeColor métodos de extensão e SetAppTheme<T> .

Observação

Os aplicativos .NET MAUI podem responder a alterações de tema do sistema no iOS 13 ou superior, Android 10 (API 29) ou superior, macOS 10.14 ou superior e Windows 10 ou superior.

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 AppThemeBinding extensão de marcação e os SetAppThemeColor métodos de extensão e SetAppTheme<T> . Com essas abordagens, os recursos são aplicados automaticamente com base no valor do tema do sistema atual. Além disso, os objetos que consomem esses recursos são atualizados automaticamente se o tema do sistema for alterado durante a execução de um aplicativo.

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 do sistema atual.

A AppThemeBinding extensão de marcação é suportada AppThemeBindingExtension pela classe, que define as seguintes propriedades:

• Default, do tipo object, que você definiu 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 estiver usando seu tema claro.
• Dark, do tipo object, que você define como o recurso a ser usado quando o dispositivo estiver usando seu tema escuro.
• Value, do tipo object, que retorna o recurso que está sendo usado atualmente pela extensão de marcação.

Observação

O analisador XAML permite que a AppThemeBindingExtension classe seja abreviada como AppBindingTheme.

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

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

<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 do primeiro 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 do sistema atual.

Os recursos definidos em um podem ser consumidos em um ResourceDictionaryAppThemeBinding com a extensão de StaticResource marcação:

<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 do plano de fundo do e o estilo mudam com base no fato de Grid o Button dispositivo estar usando seu tema claro ou escuro.

Além disso, os recursos definidos em um também podem ser consumidos em um ResourceDictionaryAppThemeBinding com a extensão de DynamicResource marcação:

<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

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

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

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 está usando seu tema claro e é definida como vermelho quando o dispositivo está usando seu tema escuro.

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

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

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

Detectar o tema atual do sistema

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

AppTheme currentTheme = Application.Current.RequestedTheme;

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

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

Definir o tema de usuário atual

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

Application.Current.UserAppTheme = AppTheme.Dark;

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

Observação

Defina a UserAppTheme propriedade como AppTheme.Unspecified padrão para o tema do sistema operacional.

Reaja às mudanças de tema

O tema do sistema em um dispositivo pode mudar por vários motivos, dependendo de como o dispositivo está configurado. Os aplicativos .NET MAUI podem ser notificados quando o tema do sistema for 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.

Importante

Para responder a alterações de tema no Android, sua MainActivity classe deve incluir o ConfigChanges.UiModeActivity sinalizador no atributo. Os aplicativos .NET MAUI criados com os modelos de projeto do Visual Studio incluem automaticamente esse sinalizador.