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.

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

Important

Le code XAML conditionnel utilise des ApiInformation méthodes qui vérifient la présence de contrats et types d’API Windows RuntimeWindows.* () fournis par le système d’exploitation. Ces vérifications ne s’appliquent pas aux contrôles WinUI 3 (Microsoft.UI.Xaml.*), car WinUI 3 est fourni avec votre application via l’SDK d'application Windows plutôt qu’avec le système d’exploitation. Chaque contrôle WinUI 3 sur lequel votre application est générée est toujours présente lors de l’exécution, quelle que soit la build Windows 10/11 de l’appareil. #ifLes directives de préprocesseur n'aident pas non plus ici : elles sont évaluées au moment de la compilation en fonction du framework cible, et non au moment de l'exécution en fonction du système d'exploitation ou de la version SDK d'application Windows réellement installée. Pour rendre une fonctionnalité conditionnelle à la version du SDK Windows App avec laquelle votre application s’exécute, vérifiez la version du SDK à la compilation ou utilisez un bloc try/catch lors de l’appel à l’API. Pour plus d’informations, consultez le code adaptatif de version .

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 :

Method Inverse
IsApiContractPresent(ContractName, VersionNumber) IsApiContractNotPresent(ContractName, VersionNumber)
IsTypePresent(ControlType) IsTypeNotPresent(ControlType)
IsPropertyPresent(ControlType, PropertyName) IsPropertyNotPresent(ControlType, PropertyName)

Note

Utilisez IsApiContractPresent et IsApiContractNotPresent pour optimiser l’expérience au moment du design. Les autres conditions ne sont pas entièrement prises en charge dans l’expérience de conception Visual Studio.

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";
}

Note

Même si IsApiContractPresent prend une chaîne pour le paramètre de nom de contrat, vous ne le placez pas entre guillemets dans la déclaration d’espace de noms XAML.

Étant donné que la version minimale du système d’exploitation prise en charge par le SDK d’application Windows est 1809 (UniversalApiContract version 7), la vérification d’une version de contrat inférieure ou égale à 7 renvoie toujours true dans une application du SDK d’application Windows et ne fournit aucune information utile. Vérifiez uniquement les versions de contrat supérieures à 7.

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

Note

L’instanciation conditionnelle d’un élément basé sur un contrat d’API de système d’exploitation ( par opposition à la définition conditionnelle d’une propriété ) est un modèle spécifique à UWP. Elle ne s’applique pas aux contrôles WinUI 3.

Dans UWP, ce modèle vous permet de revenir à un contrôle plus ancien Windows.UI.Xaml.Controls lorsqu'un contrôle plus récent n'était pas disponible sur le système d'exploitation. Dans une application SDK d'application Windows, les contrôles WinUI 3 (Microsoft.UI.Xaml.Controls.*) sont fournis avec votre application via le SDK d'application Windows, et non avec le système d’exploitation. Chaque contrôle sur lequel votre application est basée, y compris ColorPicker, est garanti d’être présent au moment de l’exécution ; il n’y a donc aucune version du système d’exploitation à vérifier avant de l’instancier.

Si vous devez faire dépendre un contrôle ou une API WinUI 3 de la version du SDK d'application Windows ciblée par votre application, effectuez cette vérification à la compilation (en ciblant une version minimale du package SDK d'application Windows) ou encapsulez l’appel à l’exécution dans un try/catch — et non avec du XAML conditionnel.

Contenu connexe

  • Last updated on