Répondre aux modifications du thème système

Parcourir l’exemple

Les appareils incluent généralement des thèmes clairs et sombres, qui font référence à un large ensemble de préférences d’apparence qui peuvent être définies au niveau du système d’exploitation. Les applications doivent respecter ces thèmes système et répondre immédiatement lorsque le thème système change.

Le thème système peut changer pour diverses raisons, en fonction de la configuration de l’appareil. Cela inclut le thème système étant explicitement modifié par l’utilisateur, il change en raison de l’heure de la journée, et il change en raison de facteurs environnementaux tels que la faible lumière.

Les applications .NET Multiplateforme App UI (.NET MAUI) peuvent répondre aux modifications de thème système en consommant des ressources avec l’extension de AppThemeBinding balisage et les SetAppThemeColor méthodes d’extension.SetAppTheme<T>

Remarque

Les applications .NET MAUI peuvent répondre aux modifications de thème système sur iOS 13 ou version ultérieure, Android 10 (API 29) ou version ultérieure, macOS 10.14 ou version ultérieure, et Windows 10 ou version ultérieure.

La capture d’écran suivante montre les pages à thème, pour le thème système clair sur iOS et le thème système sombre sur Android :

Définir et consommer des ressources de thème

Les ressources pour les thèmes clairs et sombres peuvent être consommées avec l’extension de AppThemeBinding balisage et les SetAppThemeColor méthodes d’extension SetAppTheme<T> . Avec ces approches, les ressources sont automatiquement appliquées en fonction de la valeur du thème système actuel. En outre, les objets qui consomment ces ressources sont automatiquement mis à jour si le thème système change pendant l’exécution d’une application.

Extension de balisage AppThemeBinding

L’extension AppThemeBinding de balisage vous permet de consommer une ressource, telle qu’une image ou une couleur, en fonction du thème système actuel.

L’extension AppThemeBinding de balisage est prise en charge par la AppThemeBindingExtension classe, qui définit les propriétés suivantes :

• Default, de type object, que vous définissez sur la ressource à utiliser par défaut.
• Light, de type object, que vous définissez sur la ressource à utiliser lorsque l’appareil utilise son thème clair.
• Dark, de type object, que vous définissez sur la ressource à utiliser lorsque l’appareil utilise son thème sombre.
• Value, de type object, qui retourne la ressource actuellement utilisée par l’extension de balisage.

Remarque

L’analyseur XAML permet à la AppThemeBindingExtension classe d’être abrégée en tant que AppBindingTheme.

La Default propriété est la propriété de contenu de AppThemeBindingExtension. Par conséquent, pour les expressions de balisage XAML exprimées avec accolades, vous pouvez éliminer la Default= partie de l’expression fournie qu’il s’agit du premier argument.

L’exemple XAML suivant montre comment utiliser l’extension de AppThemeBinding balisage :

<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>

Dans cet exemple, la couleur de texte du premier Label est définie sur verte lorsque l’appareil utilise son thème clair et est défini sur rouge lorsque l’appareil utilise son thème sombre. De même, l’affichage Image d’un fichier image différent basé sur le thème système actuel.

Les ressources définies dans un ResourceDictionary objet peuvent être consommées dans une AppThemeBinding extension de StaticResource balisage :

<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>    

Dans cet exemple, la couleur d’arrière-plan du Grid style change Button selon que l’appareil utilise son thème clair ou son thème sombre.

En outre, les ressources définies dans un peut ResourceDictionary également être consommées dans une AppThemeBinding extension de DynamicResource balisage :

<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éthodes d’extension

.NET MAUI inclut et SetAppTheme<T> des SetAppThemeColor méthodes d’extension qui permettent VisualElement aux objets de répondre aux modifications de thème système.

La SetAppThemeColor méthode permet aux objets d’être spécifiés Color qui seront définis sur une propriété cible en fonction du thème système actuel :

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

Dans cet exemple, la couleur de texte du Label texte est définie sur verte lorsque l’appareil utilise son thème clair et est défini sur rouge lorsque l’appareil utilise son thème sombre.

La SetAppTheme<T> méthode permet aux objets de type T d’être spécifiés qui seront définis sur une propriété cible en fonction du thème système actuel :

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

Dans cet exemple, l’écran Image s’affiche lightlogo.png lorsque l’appareil utilise son thème clair et darklogo.png lorsque l’appareil utilise son thème sombre.

Détecter le thème système actuel

Le thème système actuel peut être détecté en obtenant la valeur de la Application.RequestedTheme propriété :

AppTheme currentTheme = Application.Current.RequestedTheme;

La RequestedTheme propriété retourne un membre d’énumération AppTheme . L’énumération AppTheme définit les membres suivants :

• Unspecified, qui indique que l’appareil utilise un thème non spécifié.
• Light, qui indique que l’appareil utilise son thème clair.
• Dark, qui indique que l’appareil utilise son thème sombre.

Définir le thème utilisateur actuel

Le thème utilisé par l’application peut être défini avec la Application.UserAppTheme propriété, qui est de type AppTheme, quel que soit le thème système actuellement opérationnel :

Application.Current.UserAppTheme = AppTheme.Dark;

Dans cet exemple, l’application est définie pour utiliser le thème défini pour le mode sombre système, quel que soit le thème système actuellement opérationnel.

Remarque

Définissez la UserAppTheme propriété AppTheme.Unspecified sur la valeur par défaut sur le thème du système opérationnel.

Réagir aux modifications de thème

Le thème système sur un appareil peut changer pour diverses raisons, en fonction de la façon dont l’appareil est configuré. Les applications .NET MAUI peuvent être averties lorsque le thème système change en gérant l’événement Application.RequestedThemeChanged :

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

L’objet AppThemeChangedEventArgs , qui accompagne l’événement RequestedThemeChanged , a une propriété unique nommée RequestedTheme, de type AppTheme. Cette propriété peut être examinée pour détecter le thème système demandé.

Important

Pour répondre aux modifications de thème sur Android, votre MainActivity classe doit inclure l’indicateur ConfigChanges.UiMode dans l’attribut Activity . Les applications .NET MAUI créées avec les modèles de projet Visual Studio incluent automatiquement cet indicateur.