XAML condicionalConditional XAML

A XAML condicional fornece uma forma de usar o método ApiInformation.IsApiContractPresent na marcação XAML.Conditional XAML provides a way to use the ApiInformation.IsApiContractPresent method in XAML markup. Com isso, você pode definir propriedades e instanciar objetos na marcação com base na presença de uma API sem a necessidade de usar code-behind.This lets you set properties and instantiate objects in markup based on the presence of an API without needing to use code behind. Analisa seletivamente elementos ou atributos para determinar se eles estarão disponíveis no momento da execução.It selectively parses elements or attributes to determine whether they will be available at runtime. Instruções condicionais são avaliadas no momento da execução, e os elementos qualificados com uma marca XAML condicional são analisados se forem avaliados como true; caso contrário, são ignorados.Conditional statements are evaluated at runtime, and elements qualified with a conditional XAML tag are parsed if they evaluate to true; otherwise, they are ignored.

A XAML condicional estará disponível a partir da Atualização para Criadores (versão 1703, compilação 15063).Conditional XAML is available starting with the Creators Update (version 1703, build 15063). Para usar a XAML condicional, a Versão Mínima do seu projeto do Visual Studio deve ser definida como compilação 15063 (Atualização para Criadores) ou posterior, e a Versão de Destino deve ser definida como uma versão mais recente que a Mínima.To use conditional XAML, the Minimum Version of your Visual Studio project must be set to build 15063 (Creators Update) or later, and the Target Version be set to a later version than the Minimum. Confira Aplicativos adaptáveis de versão para obter informações sobre como configurar seu projeto do Visual Studio.See Version adaptive apps for more info about configuring your Visual Studio project.

Observação

Para criar um aplicativo adaptável de versão, uma Versão Mínima inferior à compilação 15063, você deve usar o código adaptável de versão, não a XAML.To create a version adaptive app with a Minimum Version less than build 15063, you must use version adaptive code, not XAML.

Para obter informações de apoio importantes sobre ApiInformation e contratos de API, confira Aplicativos adaptáveis de versão.For important background info about ApiInformation and API contracts, see Version adaptive apps.

Namespaces condicionaisConditional namespaces

Para usar um método condicional em XAML, primeiro é preciso declarar um Namespace XAML condicional na parte superior da sua página.To use a conditional method in XAML, you must first declare a conditional XAML namespace at the top of your page. Veja um exemplo de pseudo-código de um namespace condicional:Here's a psuedo-code example of a conditional namespace:

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

Um namespace condicional pode ser dividido em duas partes pelo delimitador "?".A conditional namespace can be broken down into two parts separated by the '?' delimiter.

  • O conteúdo que precede o delimitador indica o namespace ou o esquema que contém a API sendo referenciada.The content preceding the delimiter indicates the namespace or schema that contains the API being referenced.
  • O conteúdo após o delimitador "?" representa o método condicional que determina se o namespace condicional avalia como true ou false.The content after the '?' delimiter represents the conditional method that determines whether the conditional namespace evaluates to true or false.

Na maioria dos casos, o esquema será o namespace XAML padrão:In most cases, the schema will be the default XAML namespace:

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

A XAML condicional é compatível com os seguintes métodos condicionais:Conditional XAML supports the following conditional methods:

MétodoMethod InverseInverse
IsApiContractPresent(ContractName, VersionNumber)IsApiContractPresent(ContractName, VersionNumber) IsApiContractNotPresent(ContractName, VersionNumber)IsApiContractNotPresent(ContractName, VersionNumber)
IsTypePresent(ControlType)IsTypePresent(ControlType) IsTypeNotPresent(ControlType)IsTypeNotPresent(ControlType)
IsPropertyPresent(ControlType, PropertyName)IsPropertyPresent(ControlType, PropertyName) IsPropertyNotPresent(ControlType, PropertyName)IsPropertyNotPresent(ControlType, PropertyName)

Vamos discutir esses métodos em outras seções deste artigo.We discuss these methods further in later sections of this article.

Observação

Recomendamos o uso de IsApiContractPresent e IsApiContractNotPresent.We recommend you use IsApiContractPresent and IsApiContractNotPresent. Outras condicionais não são compatíveis com a experiência de design do Visual Studio.Other conditionals are not fully supported in the Visual Studio design experience.

Criar um namespace e definir uma propriedadeCreate a namespace and set a property

Neste exemplo, será exibido "Olá, XAML Condicional", como o conteúdo de um bloco de texto se o aplicativo for executado no Fall Creators Update ou versões posteriores, e padrão para nenhum conteúdo se estiver em uma versão anterior.In this example, you display, "Hello, Conditional XAML", as the content of a text block if the app runs on the Fall Creators Update or later, and default to no content if it's on a previous version.

Primeiro, defina um namespace personalizado com o prefixo 'contract5Present' e use o namespace XAML padrão (https://schemas.microsoft.com/winfx/2006/xaml/presentation) como o esquema contendo a propriedade TextBlock.Text.First, define a custom namespace with the prefix 'contract5Present' and use the default XAML namespace (https://schemas.microsoft.com/winfx/2006/xaml/presentation) as the schema containing the TextBlock.Text property. Para torná-lo um namespace condicional, adicione o delimitador "?"To make this a conditional namespace, add the ‘?’ após o esquema.delimiter after the schema.

Depois, defina uma condicional que retorne true nos dispositivos que estão executando o Fall Creators Update ou posterior.You then define a conditional that returns true on devices that are running the Fall Creators Update or later. Use o IsApiContractPresent do método ApiInformation para verificar a 5ª versão do UniversalApiContract.You use the ApiInformation method IsApiContractPresent to check for the 5th version of the UniversalApiContract. A versão 5 do UniversalApiContract foi lançada com o Fall Creators Update (SDK 16299).Version 5 of the UniversalApiContract was released with the Fall Creators Update (SDK 16299).

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

Após a definição do namespace, você coloca o prefixo do namespace na propriedade Text do seu TextBox para qualificá-lo como uma propriedade que deve ser definida de forma condicional no momento da execução.After the namespace is defined, you prepend the namespace prefix to the Text property of your TextBox to qualify it as a property that should be set conditionally at runtime.

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

Veja a XAML completa.Here's the complete 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:contract5Present="http://schemas.microsoft.com/winfx/2006/xaml/presentation?IsApiContractPresent(Windows.Foundation.UniversalApiContract,5)">

    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <TextBlock contract5Present:Text="Hello, Conditional XAML"/>
    </Grid>
</Page>

Ao executar esse exemplo no Fall Creators Update, o texto “Olá, XAML Condicional” é exibido; ao executá-lo na Atualização para Criadores, nenhum texto é exibido.When you run this example on the Fall Creators Update, the text, "Hello, Conditional XAML" is shown; when you run it on the Creators Update, no text is shown.

A XAML condicional permite realizar as verificações de API que, em vez disso, você pode fazer no código da marcação.Conditional XAML lets you perform the API checks you can do in code in your markup instead. Aqui está o código equivalente para essa verificação.Here's the equivalent code for this check.

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

Observe que, embora o método IsApiContractPresent use uma cadeia de caracteres para o parâmetro contractName, você não o coloca entre aspas (" ") na declaração de namespace de XAML.Notice that even though the IsApiContractPresent method takes a string for the contractName parameter, you don't put it in quotes (" ") in the XAML namespace declaration.

Usar as condições if/elseUse if/else conditions

No exemplo anterior, a propriedade Text é definida apenas quando o aplicativo é executado no Fall Creators Update.In the previous example, the Text property is set only when the app runs on the Fall Creators Update. Mas e se você quiser mostrar um texto diferente quando ele é executado na Atualização para Criadores?But what if you want to show different text when it runs on the Creators Update? Você poderia tentar definir a propriedade Text sem um qualificador condicional, como este.You could try to set the Text property without a conditional qualifier, like this.

<!-- DO NOT USE -->
<TextBlock Text="Hello, World" contract5Present:Text="Hello, Conditional XAML"/>

Ela funcionará quando for executada na Atualização para Criadores, mas, quando for executada no Fall Creators Update, ocorrerá um erro informando que a propriedade Text foi definida mais de uma vez.This will work when it runs on the Creators Update, but when it runs on the Fall Creators Update, you get an error saying that the Text property is set more than once.

Para definir um texto diferente quando o aplicativo é executado em versões diferentes do Windows 10, outra condição é necessária.To set different text when the app runs on different versions of Windows 10, you need another condition. Uma XAML condicional fornece o inverso de cada método ApiInformation compatível para permitir que você crie cenários condicionais if/else como este.Conditional XAML provides an inverse of each supported ApiInformation method to let you create if/else conditional scenarios like this.

O método IsApiContractPresent retorna true se o dispositivo atual contiver o contrato especificado e o número de versão.The IsApiContractPresent method returns true if the current device contains the specified contract and version number. Por exemplo, suponha que seu aplicativo está sendo executado na Atualização para Criadores, que tem a 4ª versão do contrato de API universal.For example, assume your app is running on the Creators Update, which has the 4th version of the universal API Contract.

Várias chamadas para IsApiContractPresent apresentariam estes resultados:Various calls to IsApiContractPresent would have these results:

  • IsApiContractPresent(Windows.Foundation.UniversalApiContract, 5) = falseIsApiContractPresent(Windows.Foundation.UniversalApiContract, 5) = false
  • IsApiContractPresent(Windows.Foundation.UniversalApiContract, 4) = trueIsApiContractPresent(Windows.Foundation.UniversalApiContract, 4) = true
  • IsApiContractPresent(Windows.Foundation.UniversalApiContract, 3) = trueIsApiContractPresent(Windows.Foundation.UniversalApiContract, 3) = true
  • IsApiContractPresent(Windows.Foundation.UniversalApiContract, 2) = trueIsApiContractPresent(Windows.Foundation.UniversalApiContract, 2) = true
  • IsApiContractPresent(Windows.Foundation.UniversalApiContract, 1) = true.IsApiContractPresent(Windows.Foundation.UniversalApiContract, 1) = true.

IsApiContractNotPresent retorna o inverso de IsApiContractPresent.IsApiContractNotPresent returns the inverse of IsApiContractPresent. Várias chamadas para IsApiContractPresent apresentariam estes resultados:Calls to IsApiContractNotPresent would have these results:

  • IsApiContractNotPresent(Windows.Foundation.UniversalApiContract, 5) = trueIsApiContractNotPresent(Windows.Foundation.UniversalApiContract, 5) = true
  • IsApiContractNotPresent(Windows.Foundation.UniversalApiContract, 4) = falseIsApiContractNotPresent(Windows.Foundation.UniversalApiContract, 4) = false
  • IsApiContractNotPresent(Windows.Foundation.UniversalApiContract, 3) = falseIsApiContractNotPresent(Windows.Foundation.UniversalApiContract, 3) = false
  • IsApiContractNotPresent(Windows.Foundation.UniversalApiContract, 2) = falseIsApiContractNotPresent(Windows.Foundation.UniversalApiContract, 2) = false
  • IsApiContractNotPresent(Windows.Foundation.UniversalApiContract, 1) = falseIsApiContractNotPresent(Windows.Foundation.UniversalApiContract, 1) = false

Para usar a condição inversa, crie um segundo namespace de XAML condicional que usa o condicional IsApiContractNotPresent.To use the inverse condition, you create a second conditional XAML namespace that uses the IsApiContractNotPresent conditional. Neste exemplo, temos o prefixo "contract5NotPresent".Here, it has the prefix 'contract5NotPresent'.

xmlns:contract5NotPresent="http://schemas.microsoft.com/winfx/2006/xaml/presentation?IsApiContractNotPresent(Windows.Foundation.UniversalApiContract,5)"

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

Com os namespaces definidos, você pode definir a propriedade Text duas vezes, contanto que sejam prefixados com qualificadores que garantam que apenas uma configuração de propriedade seja usada no momento da execução, como a seguir:With both namespaces defined, you can set the Text property twice as long as you prefix them with qualifiers that ensure only one property setting is used at runtime, like this:

<TextBlock contract5NotPresent:Text="Hello, World"
           contract5Present:Text="Hello, Fall Creators Update"/>

Veja outro exemplo que define o plano de fundo de um botão.Here's another example that sets the background of a button. O recurso Material acrílico estará disponível a partir do Fall Creators Update. Assim, você usará o acrílico para o plano de fundo quando o aplicativo for executado no Fall Creators Update.The Acrylic material feature is available starting with the Fall Creators Update, so you’ll use Acrylic for the background when the app runs on the Fall Creators Update. Não estará disponível em versões anteriores. Por isso, nesses casos, você define o plano de fundo como vermelho.It's not available on earlier versions, so in those cases, you set the background to red.

<Button Content="Button"
        contract5NotPresent:Background="Red"
        contract5Present:Background="{ThemeResource SystemControlAcrylicElementBrush}"/>

Criar controles e propriedades de associaçãoCreate controls and bind properties

Até o momento, você já viu como definir as propriedades usando a XAML condicional, mas também é possível instanciar controles de forma condicional com base no contrato de API disponível no momento da execução.So far, you’ve seen how to set properties using conditional XAML, but you can also conditionally instantiate controls based on the API contract available at runtime.

Neste exemplo, um ColorPicker é instanciado quando o aplicativo é executado no Fall Creators Update em que o controle está disponível.Here, a ColorPicker is instantiated when the app runs on the Fall Creators Update where the control is available. O ColorPicker não estará disponível antes do Fall Creators Update. Portanto, quando o aplicativo é executado em versões anteriores, use um ComboBox para fornecer opções de cor simplificadas para o usuário.The ColorPicker isn't available prior to the Fall Creators Update, so when the app runs on earlier versions, you use a ComboBox to provide simplified color choices to the user.

<contract5Present:ColorPicker x:Name="colorPicker"
                              Grid.Column="1"
                              VerticalAlignment="Center"/>

<contract5NotPresent:ComboBox x:Name="colorComboBox"
                              PlaceholderText="Pick a color"
                              Grid.Column="1"
                              VerticalAlignment="Center">

É possível usar qualificadores condicionais com formas diferentes de Sintaxe da propriedade XAML.You can use conditional qualifiers with different forms of XAML property syntax. Neste exemplo, a propriedade Fill do retângulo é definida usando a sintaxe de elemento de propriedade para o Fall Creators Update e uma sintaxe de atributo para versões anteriores.Here, the rectangle’s Fill property is set using property element syntax for the Fall Creators Update, and using attribute syntax for previous versions.

<Rectangle x:Name="colorRectangle" Width="200" Height="200"
           contract5NotPresent:Fill="{x:Bind ((SolidColorBrush)((FrameworkElement)colorComboBox.SelectedItem).Tag), Mode=OneWay}">
    <contract5Present:Rectangle.Fill>
        <SolidColorBrush contract5Present:Color="{x:Bind colorPicker.Color, Mode=OneWay}"/>
    </contract5Present:Rectangle.Fill>
</Rectangle>

Ao associar uma propriedade com outra que depende de um namespace condicional, é preciso usar a mesma condição em ambas as propriedades.When you bind a property to another property that depends on a conditional namespace, you must use the same condition on both properties. Neste exemplo, colorPicker.Color depende do namespace condicional "contract5Present". Por isso, também é preciso colocar o prefixo "contract5Present" na propriedade SolidColorBrush.Color.Here, colorPicker.Color depends on the 'contract5Present' conditional namespace, so you must also place the 'contract5Present' prefix on the SolidColorBrush.Color property. (Ou é possível colocar o prefixo "contract5Present" na propriedade SolidColorBrush em vez da propriedade Color.) Caso contrário, você obterá um erro de tempo de compilação.(Or, you can place the 'contract5Present' prefix on the SolidColorBrush instead of on the Color property.) If you don’t, you’ll get a compile-time error.

<SolidColorBrush contract5Present:Color="{x:Bind colorPicker.Color, Mode=OneWay}"/>

Esta é a XAML completa que demonstra esses cenários.Here's the complete XAML that demonstrates these scenarios. Este exemplo contém um retângulo e uma interface de usuário que permite definir a cor do retângulo.This example contains a rectangle and a UI that lets you set the color of the rectangle.

Quando o aplicativo é executado no Fall Creators Update, use ColorPicker para que o usuário possa definir a cor.When the app runs on the Fall Creators Update, you use a ColorPicker to let the user set the color. O ColorPicker não estará disponível antes do Fall Creators Update. Portanto, quando o aplicativo é executado em versões anteriores, use uma caixa de combinação para fornecer opções de cor simplificadas para o usuário.The ColorPicker isn't available prior to the Fall Creators Update, so when the app runs on earlier versions, you use a combo box to provide simplified color choices to the user.

<Page
    x:Class="ConditionalTest.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:contract5Present="http://schemas.microsoft.com/winfx/2006/xaml/presentation?IsApiContractPresent(Windows.Foundation.UniversalApiContract,5)"
    xmlns:contract5NotPresent="http://schemas.microsoft.com/winfx/2006/xaml/presentation?IsApiContractNotPresent(Windows.Foundation.UniversalApiContract,5)">

    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <Grid.ColumnDefinitions>
            <ColumnDefinition/>
            <ColumnDefinition/>
        </Grid.ColumnDefinitions>

        <Rectangle x:Name="colorRectangle" Width="200" Height="200"
                   contract5NotPresent:Fill="{x:Bind ((SolidColorBrush)((FrameworkElement)colorComboBox.SelectedItem).Tag), Mode=OneWay}">
            <contract5Present:Rectangle.Fill>
                <SolidColorBrush contract5Present:Color="{x:Bind colorPicker.Color, Mode=OneWay}"/>
            </contract5Present:Rectangle.Fill>
        </Rectangle>

        <contract5Present:ColorPicker x:Name="colorPicker"
                                      Grid.Column="1"
                                      VerticalAlignment="Center"/>

        <contract5NotPresent:ComboBox x:Name="colorComboBox"
                                      PlaceholderText="Pick a color"
                                      Grid.Column="1"
                                      VerticalAlignment="Center">
            <ComboBoxItem>Red
                <ComboBoxItem.Tag>
                    <SolidColorBrush Color="Red"/>
                </ComboBoxItem.Tag>
            </ComboBoxItem>
            <ComboBoxItem>Blue
                <ComboBoxItem.Tag>
                    <SolidColorBrush Color="Blue"/>
                </ComboBoxItem.Tag>
            </ComboBoxItem>
            <ComboBoxItem>Green
                <ComboBoxItem.Tag>
                    <SolidColorBrush Color="Green"/>
                </ComboBoxItem.Tag>
            </ComboBoxItem>
        </contract5NotPresent:ComboBox>
    </Grid>
</Page>