Warunkowy kod XAML

Warunkowy XAML zapewnia możliwość bezpośredniego użycia metody ApiInformation.IsApiContractPresent w znacznikach XAML. Właściwości można ustawić na podstawie obecności kontraktu interfejsu API na poziomie systemu operacyjnego bez konieczności pisania kodu. Instrukcje warunkowe są oceniane w czasie wykonywania — elementy opatrzone warunkowym tagiem XAML są analizowane, jeśli dają w wyniku true, a w przeciwnym razie są ignorowane.

Począwszy od Zestaw SDK do aplikacji systemu Windows 2.0, można również zdefiniować własne warunki, implementując interfejs IXamlCondition. Warunki niestandardowe umożliwiają dołączanie lub wykluczanie znaczników na podstawie stanu specyficznego dla aplikacji, takiego jak flagi funkcji lub ustawienia konfiguracji. Aby uzyskać więcej informacji, zobacz Tworzenie warunków niestandardowych.

Warunkowy kod XAML wymaga Windows 10 w wersji 1809 (kompilacja 17763) lub nowszej, co jest minimalną wersją systemu operacyjnego dla aplikacji Zestaw SDK do aplikacji systemu Windows.

Wymagania wstępne

Ważna

Wbudowane metody warunkowe używają metod ApiInformation, które sprawdzają obecność kontraktów interfejsu API środowisko wykonawcze systemu Windows (Windows.*) i typów dostarczonych przez system operacyjny. Te kontrole nie dotyczą kontrolek WinUI 3 (Microsoft.UI.Xaml.*), ponieważ WinUI 3 jest dostarczany z aplikacją za pośrednictwem pakietu Zestaw SDK do aplikacji systemu Windows, a nie z systemem operacyjnym — każda kontrolka WinUI 3, dla której aplikacja została skompilowana, jest zawsze obecna w czasie działania, niezależnie od tego, której kompilacji systemu Windows 10/11 używa urządzenie. #ifDyrektywy preprocesora nie pomagają w tym miejscu: są one oceniane w czasie kompilacji na podstawie platformy docelowej, a nie w czasie wykonywania na podstawie systemu operacyjnego lub Zestaw SDK do aplikacji systemu Windows wersji rzeczywiście zainstalowanej. Aby uzależnić dostępność funkcji od wersji pakietu Zestaw SDK do aplikacji systemu Windows, z której korzysta aplikacja, sprawdź wersję SDK na etapie kompilacji lub użyj bloku try/catch przy wywołaniu interfejsu API. Aby uzyskać szczegółowe informacje, zobacz Kod adaptacyjny wersji .

Aby uzyskać informacje ogólne na temat ApiInformation i kontraktów interfejsu API, zobacz Aplikacje dostosowujące się do wersji.

Warunkowe przestrzenie nazw

Aby użyć metody warunkowej w języku XAML, zadeklaruj warunkową przestrzeń nazw XAML w górnej części strony:

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

Zawartość przed ? ogranicznikiem jest przestrzenią nazw lub schematem. Zawartość po ? jest metodą warunkową, która określa, czy przestrzeń nazw ma wartość true , czy false.

W większości przypadków schemat jest domyślną przestrzenią nazw XAML:

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

Warunkowy kod XAML obsługuje następujące metody warunkowe:

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

Możesz również użyć warunku zdefiniowanego w aplikacji. Aby uzyskać więcej informacji, zobacz Tworzenie warunków niestandardowych.

Note

Użyj funkcji IsApiContractPresent i IsApiContractNotPresent w celu uzyskania najlepszego środowiska w czasie projektowania. Inne warunki nie są w pełni obsługiwane w środowisku projektowania Visual Studio.

Warunkowe ustawianie właściwości

W tym przykładzie tekst jest wyświetlany w kontrolce TextBlock tylko wtedy, gdy aplikacja działa w systemie Windows 10 w wersji 1903 (aktualizacja z maja 2019 r., kompilacja 18362) lub nowszej — jest to sprawdzenie kontraktu, które ma sens, ponieważ jest on nowszy niż minimalna wersja 1809 wymagana przez Zestaw SDK do aplikacji systemu Windows.

Najpierw zdefiniuj warunkową przestrzeń nazw:

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

Następnie poprzedź właściwość prefiksem z warunkowej przestrzeni nazw:

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

Oto kompletny kod znaczników:

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

Równoważne sprawdzenie w kodzie code-behind:

TextBlock textBlock = new TextBlock();

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

Note

Mimo że IsApiContractPresent przyjmuje ciąg parametru nazwy kontraktu, nie umieszczasz go w cudzysłowie w deklaracji przestrzeni nazw XAML.

Ponieważ minimalna obsługiwana przez Zestaw SDK do aplikacji systemu Windows wersja systemu operacyjnego to 1809 (UniversalApiContract wersja 7), sprawdzanie wersji kontraktu równej 7 lub niższej zawsze daje wynik true w aplikacji Zestaw SDK do aplikacji systemu Windows i nie dostarcza żadnych użytecznych informacji. Sprawdzaj tylko wersje umowy wyższe niż 7.

Użyj warunków if/else

Aby ustawić różne wartości w zależności od kontraktu interfejsu API, zdefiniuj zarówno dodatnie, jak i ujemne przestrzenie nazw warunkowych:

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

Następnie ustaw właściwość dwa razy, z których każda ma inny prefiks warunkowy. Tylko jeden z nich jest używany w czasie wykonywania:

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

Warunkowe tworzenie kontrolek

Note

Warunkowe tworzenie elementu w zależności od kontraktu interfejsu API systemu operacyjnego — w przeciwieństwie do warunkowego ustawiania właściwości — to wzorzec charakterystyczny dla UWP. Nie dotyczy kontrolek WinUI 3.

W systemie UWP ten wzorzec umożliwia powrót do starszej Windows.UI.Xaml.Controls kontrolki, gdy nowsza nie była dostępna w systemie operacyjnym. W aplikacji Zestaw SDK do aplikacji systemu Windows kontrolki WinUI 3 (Microsoft.UI.Xaml.Controls.*) są dostarczane z aplikacją za pośrednictwem Zestaw SDK do aplikacji systemu Windows, a nie z systemem operacyjnym. Każda kontrolka, względem której skompilowano aplikację — w tym ColorPicker — na pewno będzie dostępna w czasie wykonywania, więc przed utworzeniem jej instancji nie trzeba sprawdzać wersji systemu operacyjnego.

Jeśli musisz uzależnić kontrolkę lub interfejs API WinUI 3 od wersji pakietu Zestaw SDK do aplikacji systemu Windows, na którą jest ukierunkowana aplikacja, sprawdź to na etapie kompilacji (ustawiając minimalną wersję pakietu Zestaw SDK do aplikacji systemu Windows) albo opakuj wywołanie wykonywane w czasie działania w try/catch — a nie za pomocą warunkowego kodu XAML.

Aby uwzględnić lub wykluczyć elementy na podstawie logiki zdefiniowanej przez aplikację, takiej jak flaga funkcji, użyj warunku niestandardowego.

Utwórz warunki niestandardowe

Począwszy od Zestaw SDK do aplikacji systemu Windows 2.0, można zdefiniować własne warunki i użyć ich przy użyciu składnią warunkowej przestrzeni nazw. Warunek niestandardowy umożliwia dołączanie lub wykluczanie znaczników na podstawie stanu specyficznego dla aplikacji, takiego jak flagi funkcji, ustawienia konfiguracji lub możliwości urządzenia. Podobnie jak wbudowane metody warunkowe, warunki niestandardowe są oceniane, gdy kod XAML jest analizowany w czasie wykonywania.

Otwórz aplikację Galeria WinUI 3 i zobacz niestandardowe warunkowe XAML w działaniu

Ikona galerii WinUI 3 Aplikacja Galeria WinUI 3 zawiera interaktywne przykłady kontrolek i funkcji WinUI. Pobierz aplikację z Microsoft Store lub przejrzyj kod źródłowy w GitHub.

Note

IXamlCondition zastępuje interfejs IXamlPredicate z eksperymentalnych wersji Zestaw SDK do aplikacji systemu Windows 2.0.

Zaimplementuj warunek

Aby utworzyć warunek, zdefiniuj klasę, która pochodzi z klasy DependencyObject i implementuje IXamlCondition. Analizator XAML wywołuje metodę Evaluate i przekazuje tekst między nawiasami deklaracji warunkowej przestrzeni nazw jako parametr argument. Wróć true, aby dołączyć kwalifikowane znaczniki, lub false, aby je zignorować.

W tym przykładzie z przykładu z galerii WinUI 3 ocenia flagi funkcji przechowywane w słowniku:

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

Deklarować warunkową przestrzeń nazw dla warunku

Najpierw zamapuj przestrzeń nazw zawierającą Twoją klasę warunku przy użyciu deklaracji using:. Następnie po ograniczniku ? warunkowej przestrzeni nazw odwołaj się do klasy za pomocą tego prefiksu i przekaż argument w nawiasach:

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

W tym przykładzie analizator wywołuje Evaluate("NewExperience") dla znaczników używających prefiksu newExp i Evaluate("LegacyMode") dla znaczników używających prefiksu legacy.

Użyj warunku dla elementów, atrybutów i setterów

Użyj prefiksu warunkowego w taki sam sposób, jak w przypadku wbudowanych warunkowych przestrzeni nazw. Te przykłady są oparte na przykładowej aplikacji WinUI 3 Gallery.

Aby uwzględnić element tylko wtedy, gdy warunek to true, poprzedź element prefiksem:

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

Aby ustawić właściwość tylko wtedy, gdy warunek to true, poprzedź atrybut prefiksem:

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

Aby zastosować metodę ustawiającą styl tylko wtedy, gdy warunek to true, dodaj prefiks do elementu 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>

Ustaw stan przed przeanalizowaniem kodu XAML

Parser buforuje wynik Evaluate dla każdej kombinacji warunku i argumentu przez cały czas trwania procesu. Jeśli zmienisz stan, który warunek odczytuje po zapisaniu wyniku w pamięci podręcznej, znaczniki, które zostały już przeanalizowane, nie zmienią się, a znaczniki, które są analizowane później, nadal używają buforowanego wyniku. Aby użyć innej wartości, uruchom ponownie aplikację.

Ustaw stan, który odczytuje warunek, zanim parser go oceni, na przykład podczas uruchamiania aplikacji lub przed wywołaniem InitializeComponent w konstruktorze strony:

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

  • Dwa elementy nie mogą mieć tego samego x:Name, nawet jeśli tylko jeden z nich jest uwzględniony w czasie wykonywania.
  • Jeśli zastosujesz więcej niż jeden warunek do tego samego atrybutu, upewnij się, że tylko jeden z nich ocenia się jako true w czasie wykonywania. Jeśli więcej niż jeden element zwróci wartość true, analizator zgłasza wyjątek.
  • Ponieważ warunki są oceniane w czasie wykonywania, kompilator XAML nie może sprawdzić ich pod kątem spójności logicznej. Przetestuj każdą kombinację wartości warunków, które obsługuje Twoja aplikacja.
  • Warunki niestandardowe nie działają z elementami z x: przestrzeni nazw (http://schemas.microsoft.com/winfx/2006/xaml), takich jak x:Uid i x:Key.

Treści powiązane

  • Ostatnia aktualizacja o