XAML condizionale

XAML condizionale consente di usare il metodo ApiInformation.IsApiContractPresent direttamente nel markup XAML. È possibile impostare le proprietà in base alla presenza di un contratto API a livello di sistema operativo senza scrivere code-behind. Le istruzioni condizionali vengono valutate in fase di esecuzione: gli elementi qualificati con un tag XAML condizionale vengono analizzati se restituiscono true e ignorati in caso contrario.

XAML condizionale richiede Windows 10 versione 1809 (build 17763) o successiva, ovvero la versione minima del sistema operativo per le app SDK per app di Windows.

Prerequisiti

Importante

XAML condizionale usa ApiInformation metodi che controllano la presenza di contratti e tipi API Windows Runtime (Windows.*) forniti dal sistema operativo. Questi controlli non si applicano ai controlli WinUI 3 (Microsoft.UI.Xaml.*), perché WinUI 3 viene fornito con l'app tramite il SDK per app di Windows anziché con il sistema operativo. Ogni controllo WinUI 3 su cui viene compilata l'app è sempre presente in fase di esecuzione, indipendentemente dal Windows 10/11 in cui è in esecuzione il dispositivo. #ifLe direttive del preprocessore non sono utili in questo caso: vengono valutate in fase di compilazione in base al framework di destinazione, non in fase di esecuzione in base al sistema operativo o alla versione SDK per app di Windows effettivamente installata. Per subordinare una funzionalità alla versione di SDK per app di Windows con cui l'app è in esecuzione, verificare la versione dell'SDK in fase di compilazione oppure racchiudere la chiamata API in un blocco try/catch. Per informazioni dettagliate, vedere Codice adattivo della versione .

Per informazioni di base su ApiInformation e i contratti API, vedere App adattive alla versione.

Namespace condizionali

Per usare un metodo condizionale in XAML, dichiarare uno spazio dei nomi XAML condizionale nella parte superiore della pagina:

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

Il contenuto prima del ? delimitatore è lo spazio dei nomi o lo schema. Il contenuto dopo ? è il metodo condizionale che determina se lo spazio dei nomi restituisce true o false.

Nella maggior parte dei casi, lo schema è lo spazio dei nomi XAML predefinito:

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

XAML condizionale supporta questi metodi condizionali:

Method Inverso
IsApiContractPresent(ContractName, VersionNumber) IsApiContractNotPresent(ContractName, VersionNumber)
IsTypePresent(ControlType) IsTypeNotPresent(ControlType)
IsPropertyPresent(ControlType, PropertyName) IsPropertyNotPresent(ControlType, PropertyName)

Note

Usare IsApiContractPresent e IsApiContractNotPresent per un'esperienza ottimale in fase di progettazione. Altre condizionali non sono completamente supportate nell'esperienza di progettazione Visual Studio.

Impostare una proprietà in modo condizionale

Questo esempio visualizza il testo in un TextBlock solo quando l'app viene eseguita su Windows 10 versione 1903 (Aggiornamento di maggio 2019, build 18362) o versioni successive, ovvero una verifica del contratto che ha senso perché è più recente della versione minima 1809 di SDK per app di Windows.

Prima di tutto, definire uno spazio dei nomi condizionale:

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

Quindi anteporre alla proprietà lo spazio dei nomi condizionale:

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

Ecco il markup completo:

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

Il controllo equivalente nel code-behind:

TextBlock textBlock = new TextBlock();

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

Note

Anche se IsApiContractPresent accetta una stringa per il parametro nome contratto, non viene inserita tra virgolette nella dichiarazione dello spazio dei nomi XAML.

Poiché la versione minima del sistema operativo supportata da SDK per app di Windows è 1809 (UniversalApiContract versione 7), verificare una versione di contratto uguale o inferiore a 7 restituisce sempre true in un'app SDK per app di Windows e non fornisce alcuna informazione utile. Controllare solo le versioni del contratto superiori a 7.

Usare condizioni if/else

Per impostare valori diversi a seconda del contratto dell'API, definire sia i namespace condizionali positivi sia quelli negativi:

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

Impostare quindi la proprietà due volte, ognuna con un prefisso condizionale diverso. Solo uno viene applicato in fase di esecuzione:

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

Istanziare i controlli condizionalmente

Note

Creare un'istanza condizionale di un elemento basato su un contratto API del sistema operativo, anziché impostare in modo condizionale una proprietà , è un modello specifico della piattaforma UWP. Non si applica ai controlli WinUI 3.

In UWP questo modello ti consente di eseguire il fallback a un controllo precedente Windows.UI.Xaml.Controls quando un controllo più recente non era disponibile nel sistema operativo. In un'app SDK per app di Windows, i controlli WinUI 3 (Microsoft.UI.Xaml.Controls.*) vengono forniti con l'app tramite il SDK per app di Windows, non con il sistema operativo. Ogni controllo su cui è basata l'app, incluso ColorPicker, sarà sicuramente presente in fase di esecuzione, quindi non è necessario controllare la versione del sistema operativo prima di istanziarlo.

Se devi subordinare un controllo o un'API WinUI 3 alla versione di SDK per app di Windows a cui è destinata l'app, effettua questa verifica in fase di compilazione (impostando come destinazione una versione minima del pacchetto SDK per app di Windows) oppure racchiudi la chiamata di runtime in un try/catch — non usando XAML condizionale.

Contenuti correlati

  • Last updated on