Mulai menggunakan XAML

Telusuri sampel

Dalam aplikasi .NET Multi-platform App UI (.NET MAUI), XAML sebagian besar digunakan untuk menentukan konten visual halaman dan bekerja bersama dengan file C# code-behind. File code-behind menyediakan dukungan kode untuk markup. Bersama-sama, kedua file ini berkontribusi pada definisi kelas baru yang mencakup tampilan anak dan inisialisasi properti. Dalam file XAML, kelas dan properti direferensikan dengan elemen dan atribut XML, dan tautan antara markup dan kode dibuat.

Anatomi file XAML

Aplikasi MAUI .NET baru berisi tiga file XAML, dan file kode-di belakang terkait:

Pasangan file pertama adalah App.xaml, file XAML, dan App.xaml.cs, file kode C# di belakang yang terkait dengan file XAML. App.xaml dan App.xaml.cs berkontribusi pada kelas bernama App yang berasal dari Application. Pasangan file kedua adalah AppShell.xaml dan AppShell.xaml.cs, yang berkontribusi pada kelas bernama AppShell yang berasal dari Shell. Sebagian besar kelas lain dengan file XAML berkontribusi pada kelas yang berasal dari ContentPage, dan menentukan UI halaman. Ini berlaku untuk file MainPage.xaml dan MainPage.xaml.cs .

File MainPage.xaml memiliki struktur berikut:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MyMauiApp.MainPage">
    ...
</ContentPage>

Dua deklarasi namespace XML (xmlns) mengacu pada URI pada microsoft.com. Namun, tidak ada konten di URI ini, dan pada dasarnya berfungsi sebagai pengidentifikasi versi.

Deklarasi namespace XML pertama berarti bahwa tag yang ditentukan dalam file XAML tanpa awalan mengacu pada kelas di .NET MAUI, misalnya ContentPage. Deklarasi namespace kedua mendefinisikan awalan .x Ini digunakan untuk beberapa elemen dan atribut yang intrinsik untuk XAML itu sendiri dan yang didukung oleh implementasi XAML lainnya. Namun, elemen dan atribut ini sedikit berbeda tergantung pada tahun yang disematkan dalam URI. .NET MAUI mendukung spesifikasi XAML 2009.

Di akhir tag pertama, awalan x digunakan untuk atribut bernama Class. Karena penggunaan awalan ini x hampir universal untuk namespace XAML, atribut XAML seperti Class hampir selalu disebut sebagai x:Class. Atribut x:Class menentukan nama kelas .NET yang sepenuhnya memenuhi syarat: MainPage kelas di MyMauiApp namespace. Ini berarti bahwa file XAML ini mendefinisikan kelas baru bernama MainPage di MyMauiApp namespace layanan yang berasal ( ContentPage tag tempat x:Class atribut muncul).

Atribut x:Class hanya dapat muncul di elemen akar file XAML untuk menentukan kelas C# turunan. Ini adalah satu-satunya kelas baru yang ditentukan dalam file XAML. Segala sesuatu yang muncul dalam file XAML hanya dibuat dari kelas yang ada dan diinisialisasi.

File MainPage.xaml.cs terlihat mirip dengan ini:

namespace MyMauiApp;

public partial class MainPage : ContentPage
{
    public MainPage()
    {
        InitializeComponent();
    }
}

Kelas MainPage ini berasal dari ContentPage, dan merupakan definisi kelas parsial.

Saat Visual Studio membangun proyek, generator sumber menghasilkan sumber C# baru yang berisi definisi InitializeComponent metode yang dipanggil dari MainPage konstruktor dan menambahkannya ke objek kompilasi.

Pada runtime, kode di MauiProgram kelas bootstrap aplikasi dan menjalankan App konstruktor kelas, yang membuat instans AppShell. Kelas AppShell membuat instans halaman pertama aplikasi yang akan ditampilkan, yaitu MainPage. Konstruktor MainPage memanggil InitializeComponent, yang menginisialisasi semua objek yang ditentukan dalam file XAML, menghubungkan semuanya bersama-sama dalam hubungan induk-anak, melampirkan penanganan peristiwa yang ditentukan dalam kode ke peristiwa yang diatur dalam file XAML, dan mengatur pohon objek yang dihasilkan sebagai konten halaman.

Catatan

Kelas AppShell menggunakan .NET MAUI Shell untuk mengatur halaman pertama aplikasi yang akan ditampilkan. Namun, Shell berada di luar cakupan pengenalan XAML ini. Untuk informasi selengkapnya, lihat .NET MAUI Shell.

Mengatur konten halaman

ContentPage Harus berisi satu anak, yang bisa berupa tampilan atau tata letak dengan tampilan turunan. Anak dari ContentPage secara otomatis ditetapkan sebagai nilai ContentPage.Content properti.

Contoh berikut menunjukkan yang ContentPage berisi Label:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamlSamples.HelloXamlPage"
             Title="Hello XAML Page">
    <Label Text="Hello, XAML!"
           VerticalOptions="Center"
           HorizontalTextAlignment="Center"
           Rotation="-15"
           FontSize="18"
           FontAttributes="Bold"
           TextColor="Blue" />
</ContentPage>

Dari contoh di atas hubungan antara kelas, properti, dan XML harus terbukti. Kelas MAUI .NET (seperti ContentPage atau Label) muncul dalam file XAML sebagai elemen XML. Properti kelas tersebut—termasuk Title pada ContentPage dan tujuh properti Label biasanya muncul sebagai atribut XML.

Banyak pintasan yang ada untuk mengatur nilai properti ini. Beberapa properti adalah jenis data dasar. Misalnya, properti dan Text berjenis string, dan Rotation berjenis double.Title Properti HorizontalTextAlignment berjenis TextAlignment, yang merupakan enumerasi. Untuk properti dari jenis enumerasi apa pun, yang perlu Anda berikan adalah nama anggota.

Namun, untuk properti dari jenis yang lebih kompleks, konverter digunakan untuk mengurai XAML. Ini adalah kelas di .NET MAUI yang berasal dari TypeConverter. Untuk contoh di atas, beberapa konverter .NET MAUI secara otomatis diterapkan untuk mengonversi nilai string ke jenis yang benar:

• LayoutOptionsConverterVerticalOptions untuk properti . Pengonversi ini mengonversi nama bidang statis publik dari LayoutOptions struktur menjadi nilai jenis LayoutOptions.
• ColorTypeConverterTextColor untuk properti . Pengonversi ini mengonversi nama bidang statis publik dari Colors nilai RGB kelas atau heksadesimal, dengan atau tanpa saluran alfa.

Navigasi halaman

Saat Anda menjalankan aplikasi .NET MAUI, MainPage biasanya ditampilkan. Untuk melihat halaman lain, Anda dapat mengaturnya sebagai halaman startup baru di file AppShell.xaml , atau menavigasi ke halaman baru dari MainPage.

Untuk menerapkan navigasi, di konstruktor MainPage.xaml.cs , Anda dapat membuat yang sederhana Button dan menggunakan penanganan aktivitas untuk menavigasi ke HelloXamlPage:

public MainPage()
{
    InitializeComponent();

    Button button = new Button
    {
        Text = "Navigate!",
        HorizontalOptions = LayoutOptions.Center,
        VerticalOptions = LayoutOptions.Center
    };

    button.Clicked += async (sender, args) =>
    {
        await Navigation.PushAsync(new HelloXamlPage());
    };

    Content = button;
}

Saat Anda mengkompilasi dan menyebarkan versi baru aplikasi ini, tombol akan muncul di layar. Menekannya menavigasi ke HelloXamlPage:

Anda dapat menavigasi kembali ke MainPage menggunakan bilah navigasi yang muncul di setiap platform.

Catatan

Alternatif untuk model navigasi ini adalah menggunakan .NET MAUI Shell. Untuk informasi selengkapnya, lihat Gambaran umum .NET MAUI Shell.

Interaksi XAML dan kode

Anak dari sebagian besar ContentPage turunan adalah tata letak, seperti StackLayout atau Grid, dan tata letak dapat berisi beberapa anak. Di XAML, hubungan induk-turunan ini dibuat dengan hierarki XML normal:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamlSamples.XamlPlusCodePage"
             Title="XAML + Code Page">
    <StackLayout>
        <Slider VerticalOptions="Center" />
        <Label Text="A simple Label"
               FontSize="18"
               HorizontalOptions="Center"
               VerticalOptions="Center" />
        <Button Text="Click Me!"
                HorizontalOptions="Center"
                VerticalOptions="Center" />
    </StackLayout>
</ContentPage>

File XAML ini secara sintis selesai, dan menghasilkan UI berikut:

Namun, meskipun Anda dapat berinteraksi dengan Slider dan Button, UI tidak diperbarui. Slider harus menyebabkan Label menampilkan nilai saat ini, dan Button harus melakukan sesuatu.

Menampilkan Slider nilai menggunakan Label dapat dicapai sepenuhnya di XAML dengan pengikatan data. Namun, berguna untuk melihat solusi kode terlebih dahulu. Meskipun demikian, menangani Button klik pasti memerlukan kode. Ini berarti bahwa file code-behind untuk XamlPlusCodePage harus berisi handler untuk ValueChanged peristiwa Slider dan Clicked peristiwa Button:

namespace XamlSamples
{
    public partial class XamlPlusCodePage
    {
        public XamlPlusCodePage()
        {
            InitializeComponent();
        }

        void OnSliderValueChanged(object sender, ValueChangedEventArgs args)
        {
            valueLabel.Text = args.NewValue.ToString("F3");
        }

        async void OnButtonClicked(object sender, EventArgs args)
        {
            Button button = (Button)sender;
            await DisplayAlert("Clicked!", "The button labeled '" + button.Text + "' has been clicked", "OK");
        }
    }
}

Kembali ke file XAML, Slider tag dan Button perlu menyertakan atribut untuk ValueChanged peristiwa dan Clicked yang mereferensikan handler ini:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamlSamples.XamlPlusCodePage"
             Title="XAML + Code Page">
    <StackLayout>
        <Slider VerticalOptions="Center"
                ValueChanged="OnSliderValueChanged" />
        <Label x:Name="valueLabel"
               Text="A simple Label"
               FontSize="18"
               HorizontalOptions="Center"
               VerticalOptions="Center" />
        <Button Text="Click Me!"
                HorizontalOptions="Center"
                VerticalOptions="Center"
                Clicked="OnButtonClicked" />
    </StackLayout>
</ContentPage>

Perhatikan bahwa menetapkan handler ke peristiwa memiliki sintaks yang sama dengan menetapkan nilai ke properti. Selain itu, untuk ValueChanged penanganan aktivitas untuk Slider menggunakan Label untuk menampilkan nilai saat ini, handler perlu mereferensikan objek tersebut dari kode. Oleh karena itu, Label kebutuhan nama, yang ditentukan dengan x:Name atribut . Awalan xx:Name atribut menunjukkan bahwa atribut ini intrinsik dengan XAML. Nama yang Anda tetapkan ke x:Name atribut memiliki aturan yang sama dengan nama variabel C#. Misalnya, harus dimulai dengan huruf atau garis bawah dan tidak berisi spasi yang disematkan.

Penanganan ValueChanged aktivitas sekarang dapat mengatur Label untuk menampilkan nilai baru Slider , yang tersedia dari argumen peristiwa:

void OnSliderValueChanged(object sender, ValueChangedEventArgs args)
{
    valueLabel.Text = args.NewValue.ToString("F3");
}

Atau, handler dapat memperoleh Slider objek yang menghasilkan peristiwa ini dari sender argumen dan mendapatkan Value properti dari itu:

void OnSliderValueChanged(object sender, ValueChangedEventArgs args)
{
    valueLabel.Text = ((Slider)sender).Value.ToString("F3");
}

Hasilnya adalah bahwa setiap manipulasi dari Slider penyebab nilainya ditampilkan dalam Label:

Dalam contoh di atas mensimulasikan Button respons terhadap Clicked peristiwa dengan menampilkan pemberitahuan dengan tombol Text . Oleh karena itu, penanganan aktivitas dapat melemparkan sender argumen ke dan Button kemudian mengakses propertinya:

async void OnButtonClicked(object sender, EventArgs args)
{
    Button button = (Button)sender;
    await DisplayAlert("Clicked!", "The button labeled '" + button.Text + "' has been clicked", "OK");
}

Metode OnButtonClicked ini didefinisikan sebagai async karena DisplayAlert metode ini asinkron dan harus diawali dengan await operator, yang kembali ketika metode selesai. Karena metode ini mendapatkan Button peristiwa penembakan dari sender argumen, handler yang sama dapat digunakan untuk beberapa tombol.

Langkah berikutnya

XAML sebagian besar dirancang untuk membuat instans dan menginisialisasi objek. Tetapi seringkali, properti harus diatur ke objek kompleks yang tidak dapat dengan mudah direpresentasikan sebagai string XML, dan terkadang properti yang ditentukan oleh satu kelas harus diatur pada kelas anak. Kedua kebutuhan ini memerlukan fitur sintaks XAML penting dari elemen properti dan properti terlampir.

Sintaks XAML penting