Условный код XAML

Условный КОД XAML предоставляет способ использования метода ApiInformation.IsApiContractPresent непосредственно в разметке XAML. Вы можете задать свойства на основе наличия контракта API на уровне ОС, не записывая код позади. Условные выражения вычисляются во время выполнения — элементы, помеченные условным тегом XAML, обрабатываются, если условие принимает значение true, и игнорируются в противном случае.

Для условного XAML требуется Windows 10 версии 1809 (сборка 17763) или более поздней версии, которая является минимальной версией ОС для приложений Windows App SDK.

Необходимые условия

Important

Условный XAML использует методы ApiInformation, которые проверяют наличие контрактов API и типов среда выполнения Windows (Windows.*), предоставляемых ОС. Эти проверки не применяются к элементам управления WinUI 3 (Microsoft.UI.Xaml.*), поскольку WinUI 3 поставляется вместе с вашим приложением через Windows App SDK, а не с операционной системой — каждый элемент управления WinUI 3, с которым собрано ваше приложение, всегда присутствует во время выполнения, независимо от того, какая сборка Windows 10/11 установлена на устройстве. #if Директивы препроцессора тут тоже не помогают: они обрабатываются во время компиляции на основе целевого фреймворка, а не во время выполнения на основе ОС или фактически установленной версии Windows App SDK. Чтобы включать функцию в зависимости от версии Windows App SDK, с которой работает ваше приложение, проверяйте версию Windows App SDK на этапе сборки или используйте конструкцию try/catch при вызове API. Дополнительные сведения см. в адаптивном коде версии .

Дополнительные сведения о ApiInformation и контрактах API см. в статье Приложения с адаптацией к версии.

Условные пространства имен

Чтобы использовать условный метод в XAML, объявите условное пространство имен XAML в верхней части страницы:

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

Содержимое ? перед разделителем — пространство имен или схема. Содержимое после ? представляет собой условный метод, который определяет, вычисляется ли пространство имён как true или false.

В большинстве случаев схема является пространством имен XAML по умолчанию:

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

Условный КОД XAML поддерживает следующие условные методы:

Метод Обратный
IsApiContractPresent(ContractName, VersionNumber) IsApiContractNotPresent(ContractName, VersionNumber)
IsTypePresent(ControlType) IsTypeNotPresent(ControlType)
IsPropertyPresent(ControlType, PropertyName) IsPropertyNotPresent(ControlType, PropertyName)

Note

Используйте IsApiContractPresent и IsApiContractNotPresent для максимального удобства на этапе разработки. Другие условные условия не полностью поддерживаются в интерфейсе разработки Visual Studio.

Задать свойство условно

В этом примере текст отображается в элементе TextBlock только если приложение работает под Windows 10 версии 1903 (обновление за май 2019 года, сборка 18362) или более поздней версии — такая проверка контракта имеет смысл, поскольку она относится к версии новее, чем минимально поддерживаемая версия 1809 в Windows App SDK.

Сначала определите условное пространство имен:

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

Затем префикс свойства с помощью условного пространства имен:

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

Ниже приведена полная разметка:

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

Эквивалентная проверка в коде программной части:

TextBlock textBlock = new TextBlock();

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

Note

IsApiContractPresent Несмотря на то что принимает строку в качестве параметра имени контракта, её не заключают в кавычки в объявлении пространства имён XAML.

Так как минимальная поддерживаемая версия ОС для Windows App SDK — 1809 (UniversalApiContract версия 7), проверка версии контракта, равной 7 или ниже, в приложении Windows App SDK всегда даёт значение true и не даёт никакой полезной информации. Проверяйте только версии контракта выше 7.

Использование условий if/else

Чтобы задать разные значения в зависимости от контракта API, определите как положительные, так и отрицательные условные пространства имен:

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

Затем задайте свойство дважды, каждый из которых имеет другой условный префикс. Применяется только один во время выполнения:

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

Создание экземпляров элементов управления при определённых условиях

Note

Условное создание экземпляра элемента в зависимости от контракта API ОС — в отличие от условной установки свойства — это шаблон, характерный для UWP. Он не применяется к элементам управления WinUI 3.

В UWP этот шаблон позволяет вернуться к более старому Windows.UI.Xaml.Controls элементу управления, когда он был недоступен в ОС. В приложении Windows App SDK элементы управления WinUI 3 (Microsoft.UI.Xaml.Controls.*) передаются с приложением через Windows App SDK, а не с ОС. Каждый элемент управления, на который рассчитано ваше приложение, включая ColorPicker, гарантированно доступен во время выполнения, поэтому перед созданием его экземпляра не нужно проверять версию ОС.

Если вам нужно сделать использование элемента управления WinUI 3 или API зависимым от версии Windows App SDK, на которую ориентировано ваше приложение, выполняйте эту проверку во время сборки (задав минимальную версию пакета Windows App SDK) или оберните вызов во время выполнения в try/catch, а не используйте условный XAML.

Связанные материалы

  • Last updated on