XAML conditionnel

Le code XAML conditionnel permet d’utiliser la méthode ApiInformation.IsApiContractPresent directement dans le balisage XAML. Vous pouvez définir des propriétés en fonction de la présence d’un contrat d’API au niveau du système d’exploitation sans écrire de code derrière. Les instructions conditionnelles sont évaluées à l’exécution — les éléments marqués par une balise XAML conditionnelle sont analysés si elles sont évaluées à true, et ignorés sinon.

À partir de SDK d'application Windows 2.0, vous pouvez également définir vos propres conditions en implémentant l’interface IXamlCondition. Les conditions personnalisées vous permettent d’inclure ou d’exclure le balisage en fonction de l’état spécifique à l’application, tel que les indicateurs de fonctionnalité ou les paramètres de configuration. Pour plus d’informations, consultez Créer des conditions personnalisées.

Le code XAML conditionnel nécessite Windows 10 version 1809 (build 17763) ou ultérieure, qui est la version minimale du système d’exploitation pour les applications SDK d'application Windows.

Prerequisites

• Un projet SDK d'application Windows. Pour connaître les étapes de configuration, consultez Créer et exécuter un projet WinUI 3.
• Connaissance des applications adaptées aux versions et de la classe ApiInformation.

Pour des informations générales sur ApiInformation et les contrats API, consultez Applications adaptatives aux versions.

Espaces de noms conditionnels

Pour utiliser une méthode conditionnelle en XAML, déclarez un espace de noms XAML conditionnel en haut de votre page :

xmlns:myNamespace="schema?conditionalMethod(parameter)"

Le contenu avant le délimiteur ? est l’espace de noms ou le schéma. Le contenu après ? est la méthode conditionnelle qui détermine si l’espace de noms est évalué à true ou false.

Dans la plupart des cas, le schéma est l’espace de noms XAML par défaut :

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

Le code XAML conditionnel prend en charge ces méthodes conditionnelles :

Vous pouvez également utiliser une condition que vous définissez dans votre application. Pour plus d’informations, consultez Créer des conditions personnalisées.

Définir une propriété de manière conditionnelle

Cet exemple affiche du texte dans un TextBlock uniquement lorsque l’application s’exécute sur Windows 10 version 1903 (mise à jour de mai 2019, build 18362) ou version ultérieure — une vérification de contrat pertinente, car elle est plus récente que la version minimale 1809 du SDK d’application Windows.

Tout d’abord, définissez un espace de noms conditionnel :

xmlns:contract8Present="http://schemas.microsoft.com/winfx/2006/xaml/presentation?IsApiContractPresent(Windows.Foundation.UniversalApiContract,8)"

Préfixez ensuite la propriété avec l’espace de noms conditionnel :

<TextBlock contract8Present:Text="Hello, Conditional XAML"/>

Voici le balisage complet :

<Page
    x:Class="ConditionalTest.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:contract8Present="http://schemas.microsoft.com/winfx/2006/xaml/presentation?IsApiContractPresent(Windows.Foundation.UniversalApiContract,8)">

    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <TextBlock contract8Present:Text="Hello, Conditional XAML"/>
    </Grid>
</Page>

La vérification équivalente dans le code-behind :

TextBlock textBlock = new TextBlock();

if (ApiInformation.IsApiContractPresent("Windows.Foundation.UniversalApiContract", 8))
{
    textBlock.Text = "Hello, Conditional XAML";
}

Utiliser des conditions if/else

Pour définir différentes valeurs en fonction du contrat d’API, définissez à la fois les espaces de noms conditionnels positifs et négatifs :

xmlns:contract8NotPresent="http://schemas.microsoft.com/winfx/2006/xaml/presentation?IsApiContractNotPresent(Windows.Foundation.UniversalApiContract,8)"
xmlns:contract8Present="http://schemas.microsoft.com/winfx/2006/xaml/presentation?IsApiContractPresent(Windows.Foundation.UniversalApiContract,8)"

Définissez ensuite la propriété deux fois, chacune avec un préfixe conditionnel différent. Une seule est appliquée au moment de l’exécution :

<TextBlock contract8NotPresent:Text="Hello, World"
           contract8Present:Text="Hello, May 2019 Update or later"/>

Instancier des contrôles de manière conditionnelle

Pour inclure ou exclure des éléments en fonction de la logique définie par votre application, comme un indicateur de fonctionnalité, utilisez une condition personnalisée.

Créer des conditions personnalisées

À compter de SDK d'application Windows 2.0, vous pouvez définir vos propres conditions et les utiliser avec la syntaxe de l’espace de noms conditionnel. Une condition personnalisée vous permet d’inclure ou d’exclure le balisage en fonction de l’état spécifique à l’application, tel que les indicateurs de fonctionnalité, les paramètres de configuration ou les fonctionnalités de l’appareil. Comme les méthodes conditionnelles intégrées, les conditions personnalisées sont évaluées lorsque le code XAML est analysé au moment de l’exécution.

L’application Galerie WinUI 3 inclut des exemples interactifs de contrôles et de fonctionnalités WinUI. Obtenez l’application à partir du Microsoft Store ou parcourez le code source sur GitHub.

Implémenter une condition

Pour créer une condition, définissez une classe qui dérive de DependencyObject et implémente IXamlCondition. L’analyseur XAML appelle la méthode Evaluate et transmet le texte entre parenthèses de la déclaration d’espace de noms conditionnel en tant que argument paramètre. Retournez true pour inclure le balisage qualifié, ou false pour l’ignorer.

Cet exemple, à partir de l’exemple de galerie WinUI 3, évalue les indicateurs de fonctionnalité que l’application stocke dans un dictionnaire :

using System.Collections.Generic;
using Microsoft.UI.Xaml;
using Microsoft.UI.Xaml.Markup;

namespace MyApp;

public sealed partial class FeatureFlagCondition : DependencyObject, IXamlCondition
{
    public static IDictionary<string, bool> FeatureFlags { get; } = new Dictionary<string, bool>
    {
        ["NewExperience"] = true,
        ["LegacyMode"] = false,
    };

    // The XAML parser calls Evaluate with the text between the parentheses
    // in the conditional namespace declaration, for example "NewExperience".
    public bool Evaluate(string argument)
    {
        return FeatureFlags.TryGetValue(argument, out bool enabled) && enabled;
    }
}

Déclarer un espace de noms conditionnel pour la condition

Tout d’abord, mappez l’espace de noms qui contient votre classe de condition à l’aide d’une using: déclaration. Ensuite, après le ? délimiteur d’un espace de noms conditionnel, référencez la classe via ce préfixe et transmettez l’argument entre parenthèses :

xmlns:cond="using:MyApp"
xmlns:newExp="http://schemas.microsoft.com/winfx/2006/xaml/presentation?cond:FeatureFlagCondition(NewExperience)"
xmlns:legacy="http://schemas.microsoft.com/winfx/2006/xaml/presentation?cond:FeatureFlagCondition(LegacyMode)"

Dans cet exemple, l’analyseur appelle Evaluate("NewExperience") pour le balisage qui utilise le préfixe newExp, et Evaluate("LegacyMode") pour le balisage qui utilise le préfixe legacy.

Utiliser la condition sur les éléments, les attributs et les setters

Utilisez le préfixe conditionnel de la même façon que vous utilisez les espaces de noms conditionnels intégrés. Ces exemples sont basés sur l’exemple de galerie WinUI 3.

Pour inclure un élément uniquement lorsqu’une condition est true, faites précéder l’élément de :

<StackPanel Spacing="8">
    <!-- Included only when FeatureFlagCondition.Evaluate("NewExperience") returns true. -->
    <newExp:InfoBar Title="New experience" IsOpen="True" Severity="Success"
                    Message="This InfoBar is included because the NewExperience flag is true." />

    <!-- Included only when FeatureFlagCondition.Evaluate("LegacyMode") returns true. -->
    <legacy:InfoBar Title="Legacy mode" IsOpen="True" Severity="Warning"
                    Message="This InfoBar is included because the LegacyMode flag is true." />
</StackPanel>

Pour définir une propriété uniquement lorsqu’une condition est true, préfixez l’attribut :

<!-- Make sure that no more than one of these conditions is true at runtime. -->
<Button newExp:Content="Open the new editor"
        legacy:Content="Open the classic editor" />

Pour appliquer un setter de style uniquement lorsqu’une condition est true, préfixez l’élément Setter :

<Page.Resources>
    <Style x:Key="ConditionalHeadingStyle" TargetType="TextBlock">
        <newExp:Setter Property="FontWeight" Value="SemiBold" />
        <newExp:Setter Property="FontSize" Value="28" />
        <legacy:Setter Property="FontWeight" Value="Normal" />
        <legacy:Setter Property="FontSize" Value="18" />
    </Style>
</Page.Resources>

Définissez l’état avant que le XAML soit analysé

L’analyseur met en cache le résultat de Evaluate pour chaque combinaison de condition et d’argument pour la durée de vie du processus. Si vous modifiez l’état dont dépend une condition une fois le résultat mis en cache, le balisage déjà analysé ne change pas et le balisage analysé ultérieurement utilise toujours le résultat mis en cache. Pour utiliser une valeur différente, redémarrez l’application.

Définissez l’état que votre condition vérifie avant que l’analyseur l’évalue, par exemple au démarrage de l’application ou avant d’appeler InitializeComponent dans un constructeur de page :

public sealed partial class MainPage : Page
{
    public MainPage()
    {
        // Set the flags before InitializeComponent so that the XAML parser
        // uses these values when it evaluates the conditions.
        FeatureFlagCondition.FeatureFlags["NewExperience"] = true;
        FeatureFlagCondition.FeatureFlags["LegacyMode"] = false;

        this.InitializeComponent();
    }
}

Limitations

• Deux éléments ne peuvent pas avoir le même x:Name, même si un seul d’entre eux est inclus au moment de l’exécution.
• Si vous appliquez plusieurs conditions au même attribut, assurez-vous qu’une seule d’entre elles s’évalue à true au moment de l’exécution. Si plusieurs éléments s’évaluent à true, l’analyseur lève une exception.
• Étant donné que les conditions sont évaluées au moment de l’exécution, le compilateur XAML ne peut pas les vérifier pour la cohérence logique. Testez chaque combinaison de valeurs de condition que votre application prend en charge.
• Les conditions personnalisées ne fonctionnent pas avec les éléments de l’espace de noms x: (http://schemas.microsoft.com/winfx/2006/xaml), par exemple x:Uid et x:Key.

Contenu connexe

• Applications adaptatives de version
• Code adaptatif de version
• Interface IXamlCondition