XAML Bersyarat

XAML Bersyarat menyediakan cara untuk menggunakan metode ApiInformation.IsApiContractPresent langsung dalam markup XAML. Anda dapat mengatur properti berdasarkan keberadaan kontrak API tingkat OS tanpa menulis kode di belakang. Pernyataan bersyarat dievaluasi saat runtime — elemen yang memenuhi kondisi tag XAML bersyarat diurai jika hasil evaluasinya adalah true dan diabaikan jika tidak.

XAML bersyarat memerlukan Windows 10 versi 1809 (build 17763) atau yang lebih baru, yang merupakan versi OS minimum untuk aplikasi SDK Aplikasi Windows.

Prasyarat

Important

XAML kondisional menggunakan ApiInformation metode, yang memeriksa keberadaan kontrak dan jenis API Windows Runtime (Windows.*) yang disediakan oleh OS. Pemeriksaan ini tidak berlaku untuk kontrol WinUI 3 (Microsoft.UI.Xaml.*), karena WinUI 3 disertakan bersama aplikasi Anda melalui SDK Aplikasi Windows, bukan bersama OS — setiap kontrol WinUI 3 yang menjadi target build aplikasi Anda selalu tersedia saat runtime, apa pun build Windows 10/11 yang dijalankan perangkat tersebut. #if direktif prapemroses juga tidak membantu di sini: direktif ini dievaluasi saat kompilasi berdasarkan kerangka kerja target, bukan saat runtime berdasarkan sistem operasi atau versi SDK Aplikasi Windows yang benar-benar terinstal. Untuk membatasi ketersediaan fitur berdasarkan versi SDK Aplikasi Windows yang digunakan aplikasi Anda, periksa versi SDK saat proses build atau bungkus pemanggilan API dengan try/catch. Lihat Kode adaptif versi untuk detailnya.

Untuk informasi latar belakang tentang ApiInformation dan kontrak API, lihat Aplikasi yang adaptif terhadap versi.

Namespace bersyarat

Untuk menggunakan metode bersyarah di XAML, deklarasikan namespace XAML bersyarkat di bagian atas halaman Anda:

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

Isi sebelum pembatas ? adalah namespace atau skema. Konten setelah ? adalah metode kondisional yang menentukan apakah namespace mengevaluasi ke true atau false.

Dalam kebanyakan kasus, skema adalah namespace XAML default:

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

XAML bersyarat mendukung metode kondisional berikut:

Metode Terbalik
IsApiContractPresent(ContractName, VersionNumber) IsApiContractNotPresent(ContractName, VersionNumber)
IsTypePresent(ControlType) IsTypeNotPresent(ControlType)
IsPropertyPresent(ControlType, PropertyName) IsPropertyNotPresent(ControlType, PropertyName)

Note

Gunakan IsApiContractPresent dan IsApiContractNotPresent untuk pengalaman waktu desain terbaik. Kondisi lainnya tidak sepenuhnya didukung dalam pengalaman desain Visual Studio.

Atur properti secara bersyarat

Contoh ini menampilkan teks dalam TextBlock hanya ketika aplikasi berjalan di Windows 10 versi 1903 (Pembaruan Mei 2019, build 18362) atau yang lebih baru — pemeriksaan kontrak ini bermakna karena versi tersebut lebih baru daripada baseline 1809 SDK Aplikasi Windows.

Pertama, tentukan namespace bersyarah:

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

Kemudian beri awalan pada properti dengan namespace kondisional:

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

Berikut adalah markup lengkapnya:

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

Kode cek masuk yang setara di belakang:

TextBlock textBlock = new TextBlock();

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

Note

Meskipun IsApiContractPresent mengambil string untuk parameter nama kontrak, Anda tidak memasukkannya dalam tanda kutip dalam deklarasi namespace XAML.

Karena versi minimum OS yang didukung oleh SDK Aplikasi Windows adalah 1809 (UniversalApiContract versi 7), memeriksa versi kontrak API pada atau di bawah 7 di aplikasi SDK Aplikasi Windows selalu menghasilkan true dan tidak memberikan informasi yang berguna. Hanya periksa versi kontrak yang lebih tinggi dari 7.

Gunakan kondisi if/else

Untuk mengatur nilai yang berbeda tergantung pada kontrak API, tentukan namespace kondisional positif dan negatif:

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

Kemudian atur properti tersebut dua kali, masing-masing dengan prefiks kondisional yang berbeda. Hanya satu yang diterapkan saat dijalankan:

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

Buat instance kontrol berdasarkan kondisi

Note

Membuat instans elemen secara kondisional berdasarkan kontrak OS API — dibandingkan dengan pengaturan properti secara kondisional — adalah pola khusus UWP. Ini tidak berlaku untuk kontrol WinUI 3.

Di UWP, pola ini memungkinkan Anda kembali ke kontrol yang lebih Windows.UI.Xaml.Controls lama ketika yang lebih baru tidak tersedia di OS. Dalam aplikasi SDK Aplikasi Windows, kontrol WinUI 3 (Microsoft.UI.Xaml.Controls.*) disertakan bersama aplikasi Anda melalui SDK Aplikasi Windows, bukan bersama OS. Setiap kontrol yang menjadi dasar pembuatan aplikasi Anda — termasuk ColorPicker — dijamin tersedia pada saat runtime, jadi Anda tidak perlu memeriksa versi OS sebelum membuat instansnya.

Jika Anda perlu membatasi penggunaan kontrol atau API WinUI 3 berdasarkan versi SDK Aplikasi Windows yang ditargetkan aplikasi Anda, lakukan pemeriksaan tersebut saat build (dengan menargetkan versi paket minimum SDK Aplikasi Windows) atau bungkus pemanggilan runtime dalam try/catch — bukan dengan XAML bersyarat.

Konten terkait

  • Last updated on