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.

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

Warunkowy kod XAML używa ApiInformation metod, 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)

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.

Treści powiązane

  • Last updated on