Mengonsumsi ekstensi markup XAML

Telusuri sampel

Ekstensi markup XAML .NET Multi-platform App UI (.NET MAUI) membantu meningkatkan daya dan fleksibilitas XAML dengan memungkinkan atribut elemen diatur dari berbagai sumber.

Misalnya, Anda biasanya mengatur Color properti BoxView seperti ini:

<BoxView Color="Blue" />

Namun, Anda mungkin lebih suka mengatur Color atribut dari nilai yang disimpan dalam kamus sumber daya, atau dari nilai properti statis kelas yang telah Anda buat, atau dari properti jenis Color elemen lain di halaman, atau dibangun dari warna, saturasi, dan nilai luminositas terpisah. Semua opsi ini dimungkinkan menggunakan ekstensi markup XAML.

Ekstensi markup adalah cara yang berbeda untuk mengekspresikan atribut elemen. Ekstensi markup .NET MAUI XAML biasanya dapat diidentifikasi oleh nilai atribut yang diapit kurung kurawal:

<BoxView Color="{StaticResource themeColor}" />

Nilai atribut apa pun dalam kurung kurawal selalu merupakan ekstensi markup XAML. Namun, ekstensi markup XAML juga dapat direferensikan tanpa menggunakan kurung kurawal.

Catatan

Beberapa ekstensi markup XAML adalah bagian dari spesifikasi XAML 2009. Ini muncul dalam file XAML dengan awalan x namespace kustom, dan biasanya dirujuk dengan awalan ini.

Selain ekstensi markup yang dibahas dalam artikel ini, ekstensi markup berikut disertakan dalam .NET MAUI dan dibahas dalam artikel lain:

• AppThemeBinding - menentukan sumber daya yang akan digunakan berdasarkan tema sistem saat ini. Untuk informasi selengkapnya, lihat Ekstensi markup AppThemeBinding.
• Binding - membangun hubungan antara properti dari dua objek. Untuk informasi selengkapnya, lihat Pengikatan data.
• DynamicResource - menanggapi perubahan objek dalam kamus sumber daya. Untuk informasi selengkapnya, lihat Gaya dinamis.
• FontImage - menampilkan ikon font dalam tampilan apa pun yang dapat menampilkan ImageSource. Untuk informasi selengkapnya, lihat Memuat ikon font.
• OnIdiom - menyesuaikan tampilan UI berdasarkan idiom perangkat yang dijalankan aplikasi. Untuk informasi selengkapnya, lihat Menyesuaikan tampilan UI berdasarkan idiom perangkat.
• OnPlatform - menyesuaikan tampilan UI berdasarkan per platform. Untuk informasi selengkapnya, lihat Menyesuaikan tampilan UI berdasarkan platform.
• RelativeSource - menetapkan sumber pengikatan relatif terhadap posisi target pengikatan. Untuk informasi selengkapnya, lihat Pengikatan relatif.
• StaticResource - mereferensikan objek dari kamus sumber daya. Untuk informasi selengkapnya, lihat Kamus sumber daya.
• TemplateBinding - melakukan pengikatan data dari templat kontrol. Untuk informasi selengkapnya, lihat Templat kontrol.

x:Ekstensi markup statis

Ekstensi x:Static markup didukung oleh StaticExtension kelas . Kelas memiliki satu properti bernama Member jenis string yang Anda atur ke nama konstanta publik, properti statis, bidang statis, atau anggota enumerasi.

Salah satu cara untuk menggunakannya x:Static adalah dengan terlebih dahulu menentukan kelas dengan beberapa konstanta atau variabel statis, seperti kelas ini AppConstants :

static class AppConstants
{
    public static double NormalFontSize = 18;
}

XAML berikut menunjukkan pendekatan paling verbose untuk membuat StaticExtension instans kelas antara Label.FontSize tag elemen properti:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:sys="clr-namespace:System;assembly=netstandard"
             xmlns:local="clr-namespace:MarkupExtensions"
             x:Class="MarkupExtensions.StaticDemoPage"
             Title="x:Static Demo">
    <StackLayout Margin="10, 0">
        <Label Text="Label No. 1">
            <Label.FontSize>
                <x:StaticExtension Member="local:AppConstants.NormalFontSize" />
            </Label.FontSize>
        </Label>
        ···
    </StackLayout>
</ContentPage>

Pengurai XAML juga memungkinkan StaticExtension kelas disingkat sebagai x:Static:

<Label Text="Label No. 2">
    <Label.FontSize>
        <x:Static Member="local:AppConstants.NormalFontSize" />
    </Label.FontSize>
</Label>

Sintaks ini dapat disederhanakan lebih jauh dengan menempatkan StaticExtension kelas dan pengaturan anggota dalam kurung kurawal. Ekspresi yang dihasilkan diatur langsung ke FontSize atribut :

<Label Text="Label No. 3"
       FontSize="{x:StaticExtension Member=local:AppConstants.NormalFontSize}" />

Dalam contoh ini, tidak ada tanda kutip dalam kurung kurawal. Properti Member bukan StaticExtension lagi atribut XML. Ini bukan bagian dari ekspresi untuk ekstensi markup.

Sama seperti yang dapat Anda singkatkan x:StaticExtensionx:Static ketika Anda menggunakannya sebagai elemen objek, Anda juga dapat menyingkatnya dalam ekspresi dalam kurung kurawal:

<Label Text="Label No. 4"
       FontSize="{x:Static Member=local:AppConstants.NormalFontSize}" />

Kelas StaticExtension memiliki atribut yang ContentProperty mereferensikan properti Member, yang menandai properti ini sebagai properti konten default kelas. Untuk ekstensi markup XAML yang dinyatakan dengan kurung kurawal, Anda dapat menghilangkan Member= bagian ekspresi:

<Label Text="Label No. 5"
       FontSize="{x:Static local:AppConstants.NormalFontSize}" />

Ini adalah bentuk paling umum dari x:Static ekstensi markup.

Tag akar contoh XAML juga berisi deklarasi namespace XML untuk namespace layanan .NET System . Ini memungkinkan Label ukuran font diatur ke bidang Math.PIstatis . Itu menghasilkan teks yang agak kecil, sehingga Scale properti diatur ke Math.E:

<Label Text="&#x03C0; &#x00D7; E sized text"
       FontSize="{x:Static sys:Math.PI}"
       Scale="{x:Static sys:Math.E}"
       HorizontalOptions="Center" />

Cuplikan layar berikut menunjukkan output XAML:

x:Ekstensi markup referensi

Ekstensi x:Reference markup didukung oleh ReferenceExtension kelas . Kelas memiliki properti tunggal bernama Name jenis string yang Anda atur ke nama elemen pada halaman yang telah diberi nama dengan x:Name. Properti ini Name adalah properti konten , ReferenceExtensionjadi Name= tidak diperlukan saat x:Reference muncul dalam kurung kurawal. Ekstensi x:Reference markup digunakan secara eksklusif dengan pengikatan data. Untuk informasi selengkapnya tentang pengikatan data, lihat Pengikatan data.

Contoh XAML berikut menunjukkan dua penggunaan x:Reference dengan pengikatan data, yang pertama di mana digunakan untuk mengatur Source properti Binding objek, dan yang kedua di mana ia digunakan untuk mengatur BindingContext properti untuk dua pengikatan data:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MarkupExtensions.ReferenceDemoPage"
             x:Name="page"
             Title="x:Reference Demo">    
    <StackLayout Margin="10, 0">        
        <Label Text="{Binding Source={x:Reference page},
                              StringFormat='The type of this page is {0}'}"
               FontSize="18"
               VerticalOptions="Center"
               HorizontalTextAlignment="Center" />
        <Slider x:Name="slider"
                Maximum="360"
                VerticalOptions="Center" />
        <Label BindingContext="{x:Reference slider}"
               Text="{Binding Value, StringFormat='{0:F0}&#x00B0; rotation'}"
               Rotation="{Binding Value}"
               FontSize="24"
               HorizontalOptions="Center"
               VerticalOptions="Center" />        
    </StackLayout>
</ContentPage>

Dalam contoh ini, kedua x:Reference ekspresi menggunakan versi singkat dari ReferenceExtension nama kelas dan menghilangkan Name= bagian ekspresi. Dalam contoh pertama, x:Reference ekstensi markup disematkan dalam Binding ekstensi markup dan Source properti dan StringFormat dipisahkan oleh koma.

Cuplikan layar berikut menunjukkan output XAML:

x:Jenis ekstensi markup

Ekstensi x:Type markup adalah XAML yang setara dengan kata kunci C# typeof . Ini didukung oleh TypeExtension kelas , yang mendefinisikan properti bernama TypeName jenis string yang harus diatur ke nama kelas atau struktur. Ekstensi x:Type markup mengembalikan objek kelas atau struktur tersebut Type . TypeName adalah properti konten dari TypeExtension, jadi TypeName= tidak diperlukan saat x:Type muncul dengan kurung kurawal.

Ekstensi x:Type markup umumnya digunakan dengan x:Array ekstensi markup. Untuk informasi selengkapnya, lihat ekstensi markup x:Array.

Contoh XAML berikut menunjukkan menggunakan x:Type ekstensi markup untuk membuat instans objek MAUI .NET dan menambahkannya ke StackLayout. XAML terdiri dari tiga Button elemen dengan propertinya Command diatur ke dan BindingCommandParameter properti diatur ke jenis tiga tampilan .NET MAUI:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MarkupExtensions.TypeDemoPage"
             Title="x:Type Demo">    
    <StackLayout x:Name="stackLayout"
                 Padding="10, 0">        
        <Button Text="Create a Slider"
                HorizontalOptions="Center"
                VerticalOptions="Center"
                Command="{Binding CreateCommand}"
                CommandParameter="{x:Type Slider}" />
        <Button Text="Create a Stepper"
                HorizontalOptions="Center"
                VerticalOptions="Center"
                Command="{Binding CreateCommand}"
                CommandParameter="{x:Type Stepper}" />
        <Button Text="Create a Switch"
                HorizontalOptions="Center"
                VerticalOptions="Center"
                Command="{Binding CreateCommand}"
                CommandParameter="{x:Type Switch}" />
    </StackLayout>
</ContentPage>

File code-behind menentukan dan menginisialisasi CreateCommand properti:

public partial class TypeDemoPage : ContentPage
{
    public ICommand CreateCommand { get; private set; }

    public TypeDemoPage()
    {
        InitializeComponent();

        CreateCommand = new Command<Type>((Type viewType) =>
        {
            View view = (View)Activator.CreateInstance(viewType);
            view.VerticalOptions = LayoutOptions.Center;
            stackLayout.Add(view);
        });

        BindingContext = this;
    }
}

Button Ketika ditekan instans baru argumen CommandParameter dibuat dan ditambahkan ke StackLayout. Ketiga Button objek kemudian berbagi halaman dengan tampilan yang dibuat secara dinamis:

x:Ekstensi markup array

Ekstensi x:Array markup memungkinkan Anda menentukan array dalam markup. Ini didukung oleh ArrayExtension kelas , yang mendefinisikan dua properti:

• Type jenis Type, yang menunjukkan jenis elemen dalam array. Properti ini harus diatur ke x:Type ekstensi markup.
• Items jenis IList, yang merupakan kumpulan item itu sendiri. Ini adalah properti konten dari ArrayExtension.

Ekstensi x:Array markup itu sendiri tidak pernah muncul dalam kurung kurawal. Sebagai gantinya, x:Array tag mulai dan akhir memisahkan daftar item.

Contoh XAML berikut menunjukkan cara menggunakan x:Array untuk menambahkan item ke dengan ListView mengatur ItemsSource properti ke array:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MarkupExtensions.ArrayDemoPage"
             Title="x:Array Demo Page">
    <ListView Margin="10">
        <ListView.ItemsSource>
            <x:Array Type="{x:Type Color}">
                <Color>Aqua</Color>
                <Color>Black</Color>
                <Color>Blue</Color>
                <Color>Fuchsia</Color>
                <Color>Gray</Color>
                <Color>Green</Color>
                <Color>Lime</Color>
                <Color>Maroon</Color>
                <Color>Navy</Color>
                <Color>Olive</Color>
                <Color>Pink</Color>
                <Color>Purple</Color>
                <Color>Red</Color>
                <Color>Silver</Color>
                <Color>Teal</Color>
                <Color>White</Color>
                <Color>Yellow</Color>
            </x:Array>
        </ListView.ItemsSource>
        <ListView.ItemTemplate>
            <DataTemplate>
                <ViewCell>
                    <BoxView Color="{Binding}"
                             Margin="3" />
                </ViewCell>
            </DataTemplate>
        </ListView.ItemTemplate>
    </ListView>
</ContentPage>     

Dalam contoh ini, ViewCell membuat sederhana BoxView untuk setiap entri warna:

Catatan

Saat menentukan array jenis umum seperti string atau angka, gunakan tag primitif bahasa XAML yang tercantum dalam argumen Pass.

x:Ekstensi markup null

Ekstensi x:Null markup didukung oleh NullExtension kelas . Ini tidak memiliki properti dan hanya XAML yang setara dengan kata kunci C# null .

Contoh XAML berikut menunjukkan cara menggunakan x:Null ekstensi markup:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MarkupExtensions.NullDemoPage"
             Title="x:Null Demo">
    <ContentPage.Resources>
        <Style TargetType="Label">
            <Setter Property="FontSize" Value="48" />
            <Setter Property="FontFamily" Value="OpenSansRegular" />
        </Style>
    </ContentPage.Resources>

    <StackLayout Padding="10, 0">
        <Label Text="Text 1" />
        <Label Text="Text 2" />
        <Label Text="Text 3"
               FontFamily="{x:Null}" />
        <Label Text="Text 4" />
        <Label Text="Text 5" />
    </StackLayout>
</ContentPage>      

Dalam contoh ini, implisit Style didefinisikan untuk Label yang mencakup Setter yang mengatur FontFamily properti ke font tertentu. Namun, yang ketiga Label menghindari penggunaan font yang ditentukan dalam gaya implisit dengan mengaturnya FontFamily ke x:Null:

Ekstensi markup DataTemplate

Ekstensi DataTemplate markup memungkinkan Anda mengonversi jenis menjadi DataTemplate. Ini didukung oleh DataTemplateExtension kelas , yang mendefinisikan TypeName properti, jenis string, yang diatur ke nama jenis yang akan dikonversi menjadi DataTemplate. Properti TypeName adalah properti konten dari DataTemplateExtension. Oleh karena itu, untuk ekspresi markup XAML yang dinyatakan dengan kurung kurawal, Anda dapat menghilangkan TypeName= bagian ekspresi.

Catatan

Parser XAML memungkinkan DataTemplateExtension kelas disingkat sebagai DataTemplate.

Penggunaan umum ekstensi markup ini ada di aplikasi Shell, seperti yang ditunjukkan dalam contoh berikut:

<ShellContent Title="Monkeys"
              Icon="monkey.png"
              ContentTemplate="{DataTemplate views:MonkeysPage}" />

Dalam contoh ini, MonkeysPage dikonversi dari ke ContentPageDataTemplate, yang ditetapkan sebagai nilai ShellContent.ContentTemplate properti. Ini memastikan bahwa MonkeysPage hanya dibuat ketika navigasi ke halaman terjadi, bukan saat startup aplikasi.

Untuk informasi selengkapnya tentang aplikasi Shell, lihat Shell.