Podmíněný KÓD XAML

Podmíněný XAML umožňuje používat metodu ApiInformation.IsApiContractPresent přímo v kódu XAML. Vlastnosti můžete nastavit na základě přítomnosti kontraktu rozhraní API na úrovni operačního systému, aniž byste museli psát kód. Podmíněné příkazy se vyhodnocují za běhu – prvky označené podmíněnou značkou XAML se zpracují, pokud se vyhodnotí jako true, jinak jsou ignorovány.

Počínaje Windows App SDK 2.0 můžete také definovat vlastní podmínky implementací rozhraní IXamlCondition. Vlastní podmínky umožňují zahrnout nebo vyloučit značkování na základě stavu specifického pro aplikaci, jako jsou příznaky funkcí nebo nastavení konfigurace. Další informace najdete v tématu Vytvoření vlastních podmínek.

Podmíněný XAML vyžaduje Windows 10 verze 1809 (build 17763) nebo novější, což je minimální verze operačního systému pro aplikace Windows App SDK.

Předpoklady

Important

Integrované podmíněné metody používají ApiInformation metody, které kontrolují přítomnost kontraktů rozhraní API prostředí Windows Runtime (Windows.*) a typů poskytovaných operačním systémem. Tyto kontroly se nevztahují na ovládací prvky WinUI 3 (Microsoft.UI.Xaml.*), protože WinUI 3 se dodává s vaší aplikací prostřednictvím Windows App SDK místo operačního systému – každý ovládací prvek WinUI 3, na kterém je vaše aplikace vytvořená, je vždy přítomna za běhu bez ohledu na to, který Windows 10/11 sestavení zařízení běží. #ifDirektivy preprocesoru nepomáhají ani tady: vyhodnocují se v době kompilace na základě cílové architektury, ne za běhu na základě operačního systému nebo Windows App SDK verze, která je skutečně nainstalována. Chcete-li podmínit použití funkce verzí sady Windows App SDK, kterou vaše aplikace používá, ověřte verzi sady SDK při sestavení nebo použijte blok try/catch při volání rozhraní API. Podrobnosti najdete v adaptivním kódu verze .

Základní informace o ApiInformation a kontraktech rozhraní API najdete v tématu Aplikace adaptivní na verze.

Podmíněné obory názvů

Pokud chcete v XAML použít podmíněnou metodu, deklarujte podmíněný obor názvů XAML v horní části stránky:

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

Obsah před oddělovačem ? je obor názvů nebo schéma. Obsah za ? je podmínka, která určuje, zda se obor názvů vyhodnotí jako true nebo false.

Ve většině případů schéma XML představuje výchozí obor názvů XAML:

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

Podmíněný xaml podporuje tyto podmíněné metody:

Metoda Inverzní
IsApiContractPresent(ContractName, VersionNumber) IsApiContractNotPresent(ContractName, VersionNumber)
IsTypePresent(ControlType) IsTypeNotPresent(ControlType)
IsPropertyPresent(ControlType, PropertyName) IsPropertyNotPresent(ControlType, PropertyName)

Můžete také použít podmínku, kterou v aplikaci definujete. Další informace najdete v tématu Vytvoření vlastních podmínek.

Note

Používejte IsApiContractPresent a IsApiContractNotPresent pro zajištění co nejlepšího prostředí v době návrhu. Ostatní podmíněné podmínky nejsou plně podporované v prostředí návrhu Visual Studio.

Nastavení vlastnosti podmíněně

Tento příklad zobrazuje text v TextBlock jen tehdy, když aplikace běží v systému Windows 10 verze 1903 (aktualizace z května 2019, build 18362) nebo novějším — ověření kontraktu, které je smysluplné, protože je novější než minimální verze 1809 sady Windows App SDK.

Nejprve definujte podmíněný obor názvů:

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

Pak předponu vlastnosti pomocí podmíněného oboru názvů:

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

Zde je úplné značkování:

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

Ekvivalentní kontrola v code-behind:

TextBlock textBlock = new TextBlock();

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

Note

I když IsApiContractPresent přijímá řetězec jako parametr názvu kontraktu, v deklaraci oboru názvů XAML ho neuvádíte v uvozovkách.

Vzhledem k tomu, že minimální podporovaná verze operačního systému pro Windows App SDK je 1809 (UniversalApiContract verze 7), kontrola, zda je verze kontraktu rovna 7 nebo nižší, se v aplikaci Windows App SDK vždy vyhodnotí na true a neposkytuje žádné užitečné informace. Zkontrolujte pouze verze kontraktů vyšší než 7.

Použít podmínky if/else

Pokud chcete nastavit různé hodnoty v závislosti na kontraktu rozhraní API, definujte kladné i záporné podmíněné obory názvů:

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

Potom vlastnost nastavte dvakrát, z nichž každá má jinou podmíněnou předponu. Za běhu se použije pouze jeden:

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

Vytvářejte instance ovládacích prvků podmíněně

Note

Podmíněné vytvoření instance elementu založeného na kontraktu rozhraní API operačního systému – na rozdíl od podmíněného nastavení vlastnosti – je vzor specifický pro UPW. Nevztahuje se na ovládací prvky WinUI 3.

V UPW tento model umožňuje vrátit se ke staršímu Windows.UI.Xaml.Controls ovládacímu prvku, když novější ovládací prvek nebyl v operačním systému dostupný. V aplikaci Windows App SDK se ovládací prvkyMicrosoft.UI.Xaml.Controls.* WinUI 3 dodávají s vaší aplikací prostřednictvím Windows App SDK, ne s operačním systémem. Každý ovládací prvek, na který je vaše aplikace sestavená ( včetně ColorPicker ), je zaručeno, že je k dispozici za běhu, takže před vytvořením instance neexistuje žádná verze operačního systému ke kontrole.

Pokud potřebujete podmínit použití ovládacího prvku WinUI 3 nebo rozhraní API verzí Windows App SDK, na kterou vaše aplikace cílí, proveďte tuto kontrolu při sestavení (nastavením minimální verze balíčku Windows App SDK) nebo obalte volání za běhu do try/catch — nikoli pomocí podmíněného XAML.

Pokud chcete zahrnout nebo vyloučit prvky na základě logiky, kterou vaše aplikace definuje, například příznak funkce, použijte vlastní podmínku.

Vytvořit vlastní podmínky

Počínaje Windows App SDK 2.0 můžete definovat vlastní podmínky a používat je se syntaxí podmíněného oboru názvů. Vlastní podmínka umožňuje zahrnout nebo vyloučit značky kódu na základě stavu specifického pro aplikaci, jako jsou příznaky funkcí, nastavení konfigurace nebo možnosti zařízení. Stejně jako předdefinované podmíněné metody se vlastní podmínky vyhodnocují při analýze XAML za běhu.

Otevřete aplikaci Galerie WinUI 3 a podívejte se na vlastní podmíněné výrazy XAML v akci

Ikona galerie WinUI 3 Aplikace Galerie WinUI 3 obsahuje interaktivní příklady ovládacích prvků a funkcí WinUI. Získejte aplikaci z Microsoft Store nebo vyhledejte zdrojový kód na GitHub.

Note

IXamlCondition rozhraní IXamlPredicate nahrazuje rozhraní z experimentálních verzí Windows App SDK 2.0.

Implementujte podmínku

Chcete-li vytvořit podmínku, definujte třídu, která je odvozena z DependencyObject a implementuje IXamlCondition. Analyzátor XAML volá metodu Evaluate a předává text mezi závorkami deklarace podmíněného oboru názvů jako argument parametr. Vraťte true, abyste zahrnuli kvalifikované značky, nebo false, abyste je ignorovali.

Tento příklad z ukázky galerie WinUI 3 vyhodnocuje příznaky funkcí, které aplikace ukládá ve slovníku:

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

Deklarujte podmíněný obor názvů pro podmínku

Nejprve namapujte obor názvů obsahující vaši třídu podmínky pomocí direktivy using:. Potom za ? oddělovačem podmíněného oboru názvů odkazujte se na třídu prostřednictvím této předpony a předejte argument v závorkách:

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

V tomto příkladu analyzátor volá Evaluate("NewExperience") pro značky, které používají předponu newExp, a Evaluate("LegacyMode") pro značky, které používají předponu legacy.

Použijte podmínku u elementů, atributů a setterů

Podmíněnou předponu použijte stejným způsobem jako vestavěné podmíněné obory názvů. Tyto příklady jsou založené na ukázce galerie WinUI 3.

Pokud chcete zahrnout prvek pouze v případě, že podmínka je true, uveďte před prvek:

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

Chcete-li nastavit vlastnost pouze v případě, že podmínka je true, přidejte k atributu předponu:

<!-- 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" />

Chcete-li použít setter stylu pouze v případě, že podmínka je true, přidejte předponu k prvku 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>

Nastavte stav předtím, než se soubor XAML zpracuje

Analyzátor ukládá výsledek Evaluate pro každou kombinaci podmínky a argumentu po dobu životnosti procesu. Pokud změníte stav, který podmínka vyhodnocuje po uložení výsledku do mezipaměti, značky, které už jsou analyzovány, se nezmění a značky, které se parsují později, stále používají výsledek v mezipaměti. Pokud chcete použít jinou hodnotu, restartujte aplikaci.

Nastavte stav, který vaše podmínka čte předtím, než ji analyzátor vyhodnotí, například při spuštění aplikace nebo před voláním InitializeComponent v konstruktoru stránky:

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

  • Dva prvky nemohou mít stejné x:Name, i když je při běhu aplikace zahrnut pouze jeden z nich.
  • Pokud pro stejný atribut použijete více než jednu podmínku, ujistěte se, že se za běhu vyhodnocuje true pouze jedna z nich. Pokud je více než jeden vyhodnocen jako true, parser vyvolá výjimku.
  • Vzhledem k tomu, že se podmínky vyhodnocují za běhu, kompilátor XAML je nemůže zkontrolovat z hlediska logické konzistence. Otestujte každou kombinaci hodnot podmínek, které vaše aplikace podporuje.
  • Vlastní podmínky nefungují s položkami z x: oboru názvů (http://schemas.microsoft.com/winfx/2006/xaml), například x:Uid a x:Key.

Související obsah

  • Poslední aktualizace v