Reageren op wijzigingen in systeemthema's

Het voorbeeld bekijken.

Apparaten bevatten doorgaans lichte en donkere thema's, die elk verwijzen naar een brede set uiterlijkvoorkeuren die op besturingssysteemniveau kunnen worden ingesteld. Apps moeten deze systeemthema's respecteren en onmiddellijk reageren wanneer het systeemthema wordt gewijzigd.

Het systeemthema kan om verschillende redenen veranderen, afhankelijk van de apparaatconfiguratie. Dit omvat het systeemthema dat expliciet wordt gewijzigd door de gebruiker, het wordt gewijzigd vanwege het tijdstip van de dag en het verandert vanwege omgevingsfactoren zoals weinig licht.

.NET Multi-platform App UI (.NET MAUI)-apps kunnen reageren op wijzigingen in systeemthema's door resources te gebruiken met de AppThemeBinding markup-extensie en de SetAppThemeColor en SetAppTheme<T> uitbreidingsmethoden.

In de volgende schermopname ziet u pagina's met thema's voor het lichte systeemthema op iOS en het donkere systeemthema op Android:

Themabronnen definiëren en gebruiken

Resources voor lichte en donkere thema's kunnen worden gebruikt met de AppThemeBinding markup-extensie en de extensiemethoden SetAppThemeColor en SetAppTheme<T>. Met deze benaderingen worden resources automatisch toegepast op basis van de waarde van het huidige systeemthema. Bovendien worden objecten die deze resources verbruiken automatisch bijgewerkt als het systeemthema verandert terwijl een app wordt uitgevoerd.

AppThemeBinding Markup-extensie

Met de AppThemeBinding markeringsextensie kunt u een resource, zoals een afbeelding of kleur, gebruiken op basis van het huidige systeemthema.

De AppThemeBinding markeringsextensie wordt ondersteund door de AppThemeBindingExtension klasse, waarmee de volgende eigenschappen worden gedefinieerd:

• Default, van type object, die je instelt als de standaardresource.
• Light, van het type object, dat u instelt als de resource die moet worden gebruikt wanneer het apparaat zijn lichte thema gebruikt.
• Dark, van het type object, dat u instelt op de resource die moet worden gebruikt wanneer het apparaat het donkere thema gebruikt.
• Value, van het type object, waarmee de resource wordt geretourneerd die momenteel wordt gebruikt door de markup-extensie.

De Default eigenschap is de inhoudseigenschap van AppThemeBindingExtension. Voor XAML-opmaakexpressies die worden uitgedrukt met accolades, kunt u daarom het Default= deel van de expressie elimineren, mits dit het eerste argument is.

In het volgende XAML-voorbeeld ziet u hoe u de AppThemeBinding markeringsextensie gebruikt:

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

In dit voorbeeld wordt de tekstkleur van de eerste Label ingesteld op groen wanneer het apparaat het lichtthema gebruikt en is ingesteld op rood wanneer het apparaat het donkere thema gebruikt. Op dezelfde manier wordt een ander afbeeldingsbestand Image weergegeven op basis van het huidige systeemthema.

Resources die zijn gedefinieerd in een ResourceDictionary kunnen worden gebruikt in een AppThemeBinding met de StaticResource markeringsextensie:

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

In dit voorbeeld verandert de achtergrondkleur van de Grid en de Button stijl op basis van of het apparaat het lichte thema of het donkere thema gebruikt.

Daarnaast kunnen resources die in een ResourceDictionary zijn gedefinieerd, ook worden gebruikt in een AppThemeBinding met de DynamicResource markeringsextensie:

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

Extensiemethoden

.NET MAUI bevat SetAppThemeColor en SetAppTheme<T> uitbreidingsmethoden waarmee VisualElement objecten kunnen reageren op wijzigingen in systeemthema's.

Met SetAppThemeColor de methode kunnen Color objecten worden opgegeven die worden ingesteld op een doeleigenschap op basis van het huidige systeemthema:

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

In dit voorbeeld is de tekstkleur van de Label tekst ingesteld op groen wanneer het apparaat het lichtthema gebruikt en is ingesteld op rood wanneer het apparaat het donkere thema gebruikt.

Met SetAppTheme<T> de methode kunnen objecten van het type T worden opgegeven die worden ingesteld op een doeleigenschap op basis van het huidige systeemthema:

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

In dit voorbeeld toont het Imagelightlogo.png wanneer het apparaat het lichte thema gebruikt, en darklogo.png wanneer het apparaat het donkere thema gebruikt.

Het huidige systeemthema detecteren

Het huidige systeemthema kan worden gedetecteerd door de waarde van de Application.RequestedTheme eigenschap op te halen:

AppTheme currentTheme = Application.Current.RequestedTheme;

De RequestedTheme eigenschap retourneert een AppTheme opsommingslid. De opsomming AppTheme definieert de volgende leden:

• Unspecified, waarmee wordt aangegeven dat het apparaat een niet-opgegeven thema gebruikt.
• Light, waarmee wordt aangegeven dat het apparaat het lichte thema gebruikt.
• Dark, wat aangeeft dat het apparaat het donkere thema gebruikt.

Het huidige gebruikersthema instellen

Het thema dat door de app wordt gebruikt, kan worden ingesteld met de Application.UserAppTheme eigenschap, wat van het type AppThemeis, ongeacht welk systeemthema momenteel operationeel is:

Application.Current.UserAppTheme = AppTheme.Dark;

In dit voorbeeld is de app ingesteld op het gebruik van het thema dat is gedefinieerd voor de donkere systeemmodus, ongeacht welk systeemthema momenteel operationeel is.

Reageren op themawijzigingen

Het systeemthema op een apparaat kan om verschillende redenen veranderen, afhankelijk van hoe het apparaat is geconfigureerd. .NET MAUI-apps kunnen worden gewaarschuwd wanneer het systeemthema wordt gewijzigd door de Application.RequestedThemeChanged gebeurtenis te verwerken:

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

Het AppThemeChangedEventArgs object, dat met de RequestedThemeChanged gebeurtenis hoort, heeft één eigenschap met de naam RequestedTheme, van het type AppTheme. Deze eigenschap kan worden onderzocht om het aangevraagde systeemthema te detecteren.