Villkorsstyrd XAML

Villkorsstyrd XAML är ett sätt att använda metoden ApiInformation.IsApiContractPresent direkt i XAML-markering. Du kan ange egenskaper baserat på förekomsten av ett API-kontrakt på OS-nivå utan att skriva kod bakom. Villkorssatser utvärderas under körning – element som omfattas av en villkorlig XAML-tagg parsas om de utvärderas till true och ignoreras i annat fall.

Villkorsstyrd XAML kräver Windows 10 version 1809 (version 17763) eller senare, vilket är den lägsta operativsystemversionen för Windows App SDK appar.

Förutsättningar

Important

Villkorsstyrd XAML använder ApiInformation metoder som kontrollerar om det finns Windows Runtime (Windows.*) API-kontrakt och typer som tillhandahålls av operativsystemet. Dessa kontroller gäller inte för WinUI 3-kontroller (Microsoft.UI.Xaml.*) eftersom WinUI 3 levereras med din app via Windows App SDK i stället för med operativsystemet – varje WinUI 3-kontroll som din app skapas mot finns alltid vid körning, oavsett vilken Windows 10/11-version som enheten körs på. #ifpreprocessor-direktiv hjälper inte här heller: de utvärderas vid kompileringstid baserat på målramverket, inte vid körning baserat på operativsystemet eller Windows App SDK version som faktiskt har installerats. Om du vill villkorsstyra en funktion utifrån vilken version av Windows App SDK som appen körs med, kontrollerar du SDK-versionen vid kompilering eller använder try/catch kring API-anropet. Mer information finns i Versionsanpassad kod .

Bakgrundsinformation om ApiInformation och API-kontrakt finns i Versionsanpassade appar.

Villkorsstyrda namnområden

Om du vill använda en villkorsstyrd metod i XAML deklarerar du ett villkorsstyrt XAML-namnområde överst på sidan:

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

Innehållet före avgränsare ? är namnområdet eller schemat. Innehållet efter ? är den villkorsstyrda metoden som avgör om namnområdet utvärderas till true eller false.

I de flesta fall är schemat XAML-standardnamnområdet:

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

Villkorsstyrd XAML stöder följande villkorsstyrda metoder:

Metod Omvänd
IsApiContractPresent(ContractName, VersionNumber) IsApiContractNotPresent(ContractName, VersionNumber)
IsTypePresent(ControlType) IsTypeNotPresent(ControlType)
IsPropertyPresent(ControlType, PropertyName) IsPropertyNotPresent(ControlType, PropertyName)

Note

Använd IsApiContractPresent och IsApiContractNotPresent för bästa möjliga upplevelse vid design. Andra villkor stöds inte fullt ut i Visual Studio designupplevelse.

Ange en egenskap villkorligt

Det här exemplet visar text i en TextBlock endast när appen körs på Windows 10 version 1903 (uppdateringen från maj 2019, build 18362) eller senare – en kontraktskontroll som är meningsfull eftersom den är nyare än Windows App SDK:s minimiversion 1809.

Definiera först ett villkorsstyrt namnområde:

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

Prefixa sedan egenskapen med villkorsstyrd namnrymd:

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

Här är hela koden:

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

Motsvarande incheckningskod bakom:

TextBlock textBlock = new TextBlock();

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

Note

Även om IsApiContractPresent tar emot en sträng för parametern kontraktsnamn anger du den inte inom citationstecken i XAML-namnområdesdeklarationen.

Eftersom Windows App SDK lägsta operativsystemversion som stöds är 1809 (UniversalApiContractversion 7) utvärderas alltid sökning efter en kontraktsversion vid eller under 7 till true i en Windows App SDK-app och ger ingen användbar information. Kontrollera endast kontraktversioner som är högre än 7.

Använd if/else-villkor

Om du vill ange olika värden beroende på API-kontraktet definierar du både de positiva och negativa villkorliga namnrymderna:

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

Ange sedan egenskapen två gånger, var och en med ett annat villkorsprefix. Endast en används under körning:

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

Instansiera kontroller villkorligt

Note

Villkorsstyrd instansiering av ett element baserat på ett OS API-kontrakt – i stället för att villkorligt ange en egenskap – är ett UWP-specifikt mönster. Det gäller inte för WinUI 3-kontroller.

I UWP gör det här mönstret att du kan återgå till en äldre Windows.UI.Xaml.Controls kontroll när en nyare inte var tillgänglig i operativsystemet. I en app som använder Windows App SDK levereras WinUI 3-kontroller (Microsoft.UI.Xaml.Controls.*) med din app genom Windows App SDK, inte med operativsystemet. Varje kontroll som appen är byggd mot – inklusive ColorPicker – är garanterad att finnas vid körning, så det finns ingen os-version att kontrollera innan du instansierar den.

Om du behöver villkora en WinUI 3-kontroll eller ett API utifrån versionen av Windows App SDK som appen riktar sig mot, gör den kontrollen vid kompilering (genom att ange en lägsta paketversion för Windows App SDK) eller omslut anropet vid körning i en try/catch – inte med villkorsstyrd XAML.

Relaterat innehåll

  • Last updated on