XAML Bersyarah

Artikel
08/25/2023

XAML bersyarat menyediakan cara untuk menggunakan metode ApiInformation.IsApiContractPresent dalam markup XAML. Hal ini memungkinkan Anda mengatur properti dan menginstansiasi objek dalam markup berdasarkan keberadaan API tanpa perlu menggunakan kode di belakang. Ini secara selektif mengurai elemen atau atribut untuk menentukan apakah elemen atau atribut tersebut akan tersedia saat runtime. Pernyataan bersyarat dievaluasi pada runtime, dan elemen yang memenuhi syarat dengan tag XAML bersyarat diurai jika dievaluasi ke true; jika tidak, elemen tersebut diabaikan.

XAML bersyar tersedia dimulai dengan Pembaruan Pembuat (versi 1703, build 15063). Untuk menggunakan XAML bersyarah, Versi Minimum proyek Visual Studio Anda harus diatur ke build 15063 (Pembaruan Kreator) atau yang lebih baru, dan Versi Target diatur ke versi yang lebih baru dari Minimum. Lihat Aplikasi adaptif versi untuk informasi selengkapnya tentang mengonfigurasi proyek Visual Studio Anda.

Catatan

Untuk membuat aplikasi adaptif versi dengan Versi Minimum kurang dari build 15063, Anda harus menggunakan kode adaptif versi, bukan XAML.

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

Namespace bersyarah

Untuk menggunakan metode bersyarah di XAML, Anda harus terlebih dahulu mendeklarasikan namespace XAML bersyar di bagian atas halaman Anda. Berikut adalah contoh pseudo-code dari namespace layanan bersyarah:

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

Namespace bersyarkat dapat dipecah menjadi dua bagian yang dipisahkan oleh pemisah '?'.

Konten yang mendahului pemisah menunjukkan namespace atau skema yang berisi API yang direferensikan.
Konten setelah pemisah '?' mewakili metode kondisional yang menentukan apakah namespace bersyarkat mengevaluasi ke true atau false.

Dalam kebanyakan kasus, skema akan menjadi namespace XAML default:

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

XAML bersyarah mendukung metode bersyarah berikut:

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

Kami membahas metode ini lebih lanjut di bagian selanjutnya dari artikel ini.

Catatan

Sebaiknya gunakan IsApiContractPresent dan IsApiContractNotPresent. Kondisi lainnya tidak sepenuhnya didukung dalam pengalaman desain Visual Studio.

Membuat namespace dan mengatur properti

Dalam contoh ini, Anda menampilkan, "Hello, Conditional XAML", sebagai konten blok teks jika aplikasi berjalan pada Fall Creators Update atau yang lebih baru, dan default ke tidak ada konten jika ada di versi sebelumnya.

Pertama, tentukan namespace kustom dengan awalan 'contract5Present' dan gunakan namespace XAML default (https://schemas.microsoft.com/winfx/2006/xaml/presentation) sebagai skema yang berisi properti TextBlock.Text . Untuk menjadikan ini sebagai namespace kondisi, tambahkan '?' pemisah setelah skema.

Anda kemudian menentukan kondisional yang mengembalikan true pada perangkat yang menjalankan Fall Creators Update atau yang lebih baru. Anda menggunakan metode ApiInformation IsApiContractPresent untuk memeriksa versi ke-5 UniversalApiContract. Versi 5 dari UniversalApiContract dirilis dengan Fall Creators Update (SDK 16299).

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

Setelah namespace didefinisikan, Anda menambahkan awalan namespace ke properti Teks TextBox Anda untuk memenuhi syarat sebagai properti yang harus diatur secara kondisional pada runtime.

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

Berikut XAML 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: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>

Saat Anda menjalankan contoh ini pada Fall Creators Update, teks, "Hello, Conditional XAML" ditampilkan; saat Anda menjalankannya di Pembaruan Pembuat, tidak ada teks yang ditampilkan.

XAML Bersyarahkan memungkinkan Anda melakukan pemeriksaan API yang dapat Anda lakukan dalam kode di markup Anda sebagai gantinya. Berikut adalah kode yang setara untuk pemeriksaan ini.

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

Perhatikan bahwa meskipun metode IsApiContractPresent mengambil string untuk parameter contractName , Anda tidak memasukkannya dalam tanda kutip (" ") dalam deklarasi namespace XAML.

Gunakan kondisi jika/lainnya

Dalam contoh sebelumnya, properti Teks hanya diatur saat aplikasi berjalan pada Fall Creators Update. Tetapi bagaimana jika Anda ingin menampilkan teks yang berbeda saat dijalankan pada Pembaruan Kreator? Anda dapat mencoba mengatur properti Teks tanpa kualifikasi bersyarah, seperti ini.

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

Ini akan berfungsi ketika berjalan pada Pembaruan Pembuat, tetapi ketika berjalan pada Fall Creators Update, Anda mendapatkan kesalahan yang mengatakan bahwa properti Teks diatur lebih dari sekali.

Untuk mengatur teks yang berbeda saat aplikasi berjalan pada versi Windows 10 yang berbeda, Anda memerlukan kondisi lain. XAML bersyarat menyediakan inversi dari setiap metode ApiInformation yang didukung untuk memungkinkan Anda membuat skenario bersyarat if/else seperti ini.

Metode IsApiContractPresent mengembalikan true jika perangkat saat ini berisi nomor kontrak dan versi yang ditentukan. Misalnya, asumsikan aplikasi Anda berjalan pada Pembaruan Pembuat, yang memiliki versi ke-4 dari Kontrak API universal.

Berbagai panggilan ke IsApiContractPresent akan memiliki hasil ini:

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

IsApiContractNotPresent mengembalikan inversi IsApiContractPresent. Panggilan ke IsApiContractNotPresent akan memiliki hasil ini:

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

Untuk menggunakan kondisi terbalik, Anda membuat namespace XAML bersyarat kedua yang menggunakan kondisional IsApiContractNotPresent . Di sini, ia memiliki awalan '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)"

Dengan kedua namespace yang ditentukan, Anda dapat mengatur properti Teks dua kali selama Anda mengawalinya dengan kualifikasi yang memastikan hanya satu pengaturan properti yang digunakan pada runtime, seperti ini:

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

Berikut adalah contoh lain yang mengatur latar belakang tombol. Fitur bahan Acrylic tersedia dimulai dengan Fall Creators Update, sehingga Anda akan menggunakan Acrylic untuk latar belakang saat aplikasi berjalan pada Fall Creators Update. Ini tidak tersedia pada versi sebelumnya, jadi dalam kasus tersebut, Anda mengatur latar belakang menjadi merah.

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

Membuat kontrol dan properti pengikatan

Sejauh ini, Anda telah melihat cara mengatur properti menggunakan XAML kondisional, tetapi Anda juga dapat membuat instans kontrol secara kondisional berdasarkan kontrak API yang tersedia pada runtime.

Di sini, ColorPicker dibuat saat aplikasi berjalan pada Fall Creators Update tempat kontrol tersedia. ColorPicker tidak tersedia sebelum Fall Creators Update, jadi saat aplikasi berjalan pada versi sebelumnya, Anda menggunakan ComboBox untuk memberikan pilihan warna yang disederhanakan kepada pengguna.

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

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

Anda dapat menggunakan kualifikasi kondisi dengan berbagai bentuk sintaks properti XAML. Di sini, properti Isian persegi panjang diatur menggunakan sintaks elemen properti untuk Fall Creators Update, dan menggunakan sintaks atribut untuk versi sebelumnya.

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

Saat Anda mengikat properti ke properti lain yang bergantung pada namespace kondisional, Anda harus menggunakan kondisi yang sama pada kedua properti. Di sini, colorPicker.Color tergantung pada namespace kondisional 'contract5Present', jadi Anda juga harus menempatkan awalan 'contract5Present' pada properti SolidColorBrush.Color. (Atau, Anda dapat menempatkan awalan 'contract5Present' pada SolidColorBrush alih-alih pada properti Warna.) Jika tidak, Anda akan mendapatkan kesalahan waktu kompilasi.

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

Berikut adalah XAML lengkap yang menunjukkan skenario ini. Contoh ini berisi persegi panjang dan UI yang memungkinkan Anda mengatur warna persegi panjang.

Saat aplikasi berjalan pada Fall Creators Update, Anda menggunakan ColorPicker untuk membiarkan pengguna mengatur warna. ColorPicker tidak tersedia sebelum Pembaruan Fall Creators, jadi saat aplikasi berjalan pada versi sebelumnya, Anda menggunakan kotak kombo untuk memberikan pilihan warna yang disederhanakan kepada pengguna.

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

Bagikan melalui

XAML Bersyarah

Namespace bersyarah

Membuat namespace dan mengatur properti

Gunakan kondisi jika/lainnya

Membuat kontrol dan properti pengikatan

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

XAML Bersyarah

Namespace bersyarah

Membuat namespace dan mengatur properti

Gunakan kondisi jika/lainnya

Membuat kontrol dan properti pengikatan

Artikel terkait

Saran dan Komentar

Sumber Daya Tambahan: