Voorwaardelijke XAML

Voorwaardelijk XAML biedt een manier om de methode ApiInformation.IsApiContractPresent rechtstreeks in XAML-opmaak te gebruiken. U kunt eigenschappen instellen op basis van de aanwezigheid van een API-contract op besturingssysteemniveau zonder code achter te schrijven. Voorwaardelijke instructies worden tijdens de uitvoering geëvalueerd — elementen die van een voorwaardelijke XAML-tag zijn voorzien, worden geparseerd als deze wordt geëvalueerd als true en anders genegeerd.

Voor voorwaardelijke XAML is Windows 10 versie 1809 (build 17763) of hoger vereist. Dit is de minimale versie van het besturingssysteem voor Windows App SDK-apps.

Prerequisites

Important

Voorwaardelijke XAML maakt gebruik ApiInformation van methoden, die controleren op de aanwezigheid van Windows Runtime (Windows.*) API-contracten en -typen die door het besturingssysteem worden geleverd. Deze controles zijn niet van toepassing op WinUI 3(Microsoft.UI.Xaml.*)-besturingselementen, omdat WinUI 3 wordt geleverd met uw app via het Windows App SDK in plaats van met het besturingssysteem. Elke WinUI 3-besturing waarop uw app is gebouwd, is altijd aanwezig tijdens runtime, ongeacht de Windows 10/11-build waarop het apparaat wordt uitgevoerd. #ifpreprocessorrichtlijnen helpen hier ook niet: ze worden geëvalueerd tijdens het compileren op basis van het doelframework, niet tijdens runtime op basis van het besturingssysteem of Windows App SDK versie die daadwerkelijk is geïnstalleerd. Als u een functie wilt gateen op de Windows App SDK versie waarop uw app wordt uitgevoerd, controleert u de SDK-versie tijdens de build of gebruikt u een try/catch rond de API-aanroep. Zie Adaptieve versiecode voor meer informatie.

Zie ApiInformation voor achtergrondinformatie over en API-contracten.

Voorwaardelijke naamruimten

Als u een voorwaardelijke methode in XAML wilt gebruiken, declareert u een voorwaardelijke XAML-naamruimte boven aan de pagina:

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

De inhoud vóór het ? scheidingsteken is de naamruimte of het schema. De inhoud na ? is de conditionele methode die bepaalt of de naamruimte resulteert in true of false.

In de meeste gevallen is het schema de standaard XAML-naamruimte:

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

Voorwaardelijke XAML ondersteunt deze voorwaardelijke methoden:

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

Note

Gebruik IsApiContractPresent en IsApiContractNotPresent voor de beste ontwerptijdervaring. Andere voorwaarden worden niet volledig ondersteund in de ontwerpervaring van Visual Studio.

Een eigenschap voorwaardelijk instellen

In dit voorbeeld wordt tekst in een TextBlock alleen weergegeven wanneer de app wordt uitgevoerd op Windows 10 versie 1903 (update van mei 2019, build 18362) of nieuwer — een contractcontrole die zinvol is omdat deze nieuwer is dan de 1809-ondergrens van de Windows App SDK.

Definieer eerst een voorwaardelijke naamruimte:

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

Voeg vervolgens de eigenschap toe aan de voorwaardelijke naamruimte:

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

Dit is de volledige markering:

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

De equivalente incheckcode achter:

TextBlock textBlock = new TextBlock();

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

Note

IsApiContractPresent Hoewel u een tekenreeks gebruikt voor de parameter contractnaam, plaatst u deze niet tussen aanhalingstekens in de XAML-naamruimtedeclaratie.

Omdat de minimaal ondersteunde OS-versie van de Windows App SDK 1809 (UniversalApiContract versie 7) is, komt een controle op een contractversie van 7 of lager in een Windows App SDK-app altijd uit op true en levert die geen nuttige informatie op. Controleer alleen op contractversies die hoger zijn dan 7.

If/else-voorwaarden gebruiken

Als u verschillende waarden wilt instellen, afhankelijk van het API-contract, definieert u zowel de positieve als negatieve voorwaardelijke naamruimten:

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

Stel vervolgens de eigenschap twee keer in, elk met een ander voorwaardelijk voorvoegsel. Er wordt slechts één toegepast tijdens runtime:

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

Besturingselementen voorwaardelijk instantiëren

Note

Het voorwaardelijk instantiëren van een element op basis van een OS API-contract , in tegenstelling tot het voorwaardelijk instellen van een eigenschap , is een UWP-specifiek patroon. Dit is niet van toepassing op WinUI 3-besturingselementen.

In UWP kon u met dit patroon terugvallen op een ouder Windows.UI.Xaml.Controls-besturingselement wanneer een nieuwer besturingselement niet beschikbaar was in het besturingssysteem. In een Windows App SDK-app worden WinUI 3-besturingselementen (Microsoft.UI.Xaml.Controls.*) samen met uw app meegeleverd via de Windows App SDK, niet via het besturingssysteem. Elk besturingselement waarvoor uw app is gebouwd — inclusief ColorPicker — is gegarandeerd aanwezig tijdens uitvoering, dus u hoeft de versie van het besturingssysteem niet te controleren voordat u het instantieert.

Als u een WinUI 3-besturingselement of API moet afschermen op basis van de versie van de Windows App SDK waarop uw app is gericht, voer die controle dan uit tijdens het bouwen (door een minimale pakketversie van de Windows App SDK als doel te nemen) of verpak de runtime-aanroep in een try/catch — niet met conditionele XAML.

Verwante onderwerpen

  • Last updated on