XAML condicional

O XAML condicional fornece uma maneira de usar o método ApiInformation.IsApiContractPresent diretamente na marcação XAML. Você pode definir propriedades com base na presença de um contrato de API no nível do sistema operacional sem escrever código atrás. Declarações condicionais são avaliadas em tempo de execução — elementos qualificados com uma tag XAML condicional são analisados se forem avaliados como true e ignorados caso contrário.

O XAML condicional requer Windows 10 versão 1809 (build 17763) ou posterior, que é a versão mínima do sistema operacional para aplicativos SDK do Aplicativo Windows.

Pré-requisitos

Importante

O XAML condicional usa métodos, que verificam a presença de ApiInformation de API Windows Runtime (Windows.*) e tipos fornecidos pelo sistema operacional. Essas verificações não se aplicam a controles WinUI 3 (Microsoft.UI.Xaml.*) porque o WinUI 3 é fornecido com seu aplicativo por meio do SDK do Aplicativo Windows em vez de com o sistema operacional — cada controle WinUI 3 no qual seu aplicativo é criado está sempre presente no runtime, independentemente de qual compilação Windows 10/11 o dispositivo está em execução. #ifAs diretivas de pré-processador também não ajudam aqui: elas são avaliadas em tempo de compilação com base na estrutura de destino, não em runtime com base no sistema operacional ou SDK do Aplicativo Windows versão realmente instalada. Para condicionar um recurso à versão do SDK do Aplicativo Windows com a qual seu aplicativo está sendo executado, verifique a versão do SDK em tempo de compilação ou use um bloco try/catch na chamada à API. Consulte o código adaptável de versão para obter detalhes.

Para obter informações básicas sobre ApiInformation e contratos de API, consulte Aplicativos adaptáveis à versão.

Namespaces condicionais

Para usar um método condicional em XAML, declare um namespace XAML condicional na parte superior da página:

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

O conteúdo antes do ? delimitador é o namespace ou esquema. O conteúdo após ? é o método condicional que determina se o namespace é avaliado como true ou false.

Na maioria dos casos, o esquema é o namespace XAML padrão:

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

O XAML condicional dá suporte a esses métodos condicionais:

Método Inverso
IsApiContractPresent(ContractName, VersionNumber) IsApiContractNotPresent(ContractName, VersionNumber)
IsTypePresent(ControlType) IsTypeNotPresent(ControlType)
IsPropertyPresent(ControlType, PropertyName) IsPropertyNotPresent(ControlType, PropertyName)

Note

Use IsApiContractPresent e IsApiContractNotPresent para obter a melhor experiência de tempo de design. Não há suporte total para outras condicionalidades na experiência de design Visual Studio.

Definir uma propriedade condicionalmente

Este exemplo exibe texto TextBlock somente quando o aplicativo é executado no Windows 10 versão 1903 (Atualização de maio de 2019, build 18362) ou posterior – uma verificação de contrato que é significativa porque é mais recente do que o piso 1809 do SDK do Aplicativo Windows.

Primeiro, defina um namespace condicional:

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

Em seguida, prefixe a propriedade com o namespace condicional:

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

Aqui está a marcação completa:

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

O código de check-in equivalente por trás:

TextBlock textBlock = new TextBlock();

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

Note

Embora IsApiContractPresent aceite uma string para o parâmetro de nome do contrato, você não deve colocá-lo entre aspas na declaração de namespace XAML.

Como a versão mínima com suporte do sistema operacional para o SDK do Aplicativo Windows é 1809 (UniversalApiContract versão 7), verificar uma versão de contrato igual ou inferior a 7 em um aplicativo do SDK do Aplicativo Windows sempre é avaliada como true e não fornece nenhuma informação útil. Verifique apenas se há versões de contrato superiores a 7.

Usar condições if/else

Para definir valores diferentes dependendo do contrato de API, defina os namespaces condicionais positivos e negativos:

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

Em seguida, defina a propriedade duas vezes, cada uma com um prefixo condicional diferente. Somente um é aplicado no runtime:

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

Instanciar controles condicionalmente

Note

A instanciação condicional de um elemento com base em um contrato de API do sistema operacional , em vez de definir condicionalmente uma propriedade , é um padrão específico da UWP. Ele não se aplica aos controles WinUI 3.

Na UWP, esse padrão permite que você volte para um controle mais antigo Windows.UI.Xaml.Controls quando um mais novo não estava disponível no sistema operacional. Em um aplicativo SDK do Aplicativo Windows, os controles winui 3 (Microsoft.UI.Xaml.Controls.*) são enviados com seu aplicativo por meio do SDK do Aplicativo Windows, não com o sistema operacional. Todos os controles com os quais seu aplicativo é criado, inclusive ColorPicker , têm a garantia de estar presente no runtime, portanto, não há nenhuma versão do sistema operacional para verificar antes de instanciá-lo.

Se você precisar condicionar um controle ou uma API do WinUI 3 à versão do SDK do Aplicativo Windows que seu aplicativo tem como destino, faça essa verificação em tempo de compilação (definindo como destino uma versão mínima do pacote do SDK do Aplicativo Windows) ou encapsule a chamada em tempo de execução em um try/catch — não com XAML condicional.

Conteúdo relacionado

  • Last updated on