Bagikan melalui

Popup

  • Artikel

Popup adalah cara yang sangat umum untuk menyajikan informasi kepada pengguna yang berkaitan dengan tugas mereka saat ini. Sistem operasi menyediakan cara untuk menampilkan pesan dan memerlukan respons dari pengguna, pemberitahuan ini biasanya membatasi dalam hal konten yang dapat disediakan pengembang dan juga tata letak dan tampilan.

Catatan

Jika Anda ingin menyajikan sesuatu kepada pengguna yang lebih halang maka lihat opsi Toast dan Snackbar kami.

Tampilan ini Popup memungkinkan pengembang untuk membangun UI kustom mereka sendiri dan menyajikannya kepada pengguna mereka.

Membangun Popup

Popup Dapat dibuat di XAML atau C#:

XAML

Menyertakan namespace XAML

Untuk menggunakan toolkit di XAML, hal berikut xmlns perlu ditambahkan ke halaman atau tampilan Anda:

xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"

Oleh karena itu hal-hal berikut:

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml">

</ContentPage>

Akan dimodifikasi untuk menyertakan xmlns sebagai berikut:

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit">

</ContentPage>

Menentukan Popup Anda

Harap dicatat bahwa jika Popup dibuat di XAML, ia harus memiliki kode C# di belakang file juga. Untuk memahami mengapa ini diperlukan, silakan lihat halaman dokumentasi .NET MAUI ini.

Cara term mudah untuk membuat adalah Popup menambahkan yang baru .NET MAUI ContentView (XAML) ke proyek Anda lalu mengubah setiap file menjadi yang berikut:

<toolkit:Popup xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
               xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
               xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
               x:Class="MyProject.SimplePopup">

    <VerticalStackLayout>
        <Label Text="This is a very important message!" />
    </VerticalStackLayout>
    
</toolkit:Popup>

public partial class SimplePopup : Popup
{
    public SimplePopup()
    {
        InitializeComponent();
    }
}

Penting

Jika kode di belakang file tidak dibuat bersama dengan panggilan ke InitializeComponent maka pengecualian akan dilemparkan saat mencoba menampilkan Popup.

C#

using CommunityToolkit.Maui.Views;

var popup = new Popup
{
    Content = new VerticalStackLayout
    {
        Children = 
        {
            new Label
            {
                Text = "This is a very important message!"
            }
        }
    }
};

Menyajikan Popup

Popup Setelah dibangun, maka dapat disajikan melalui penggunaan metode ekstensi kami Popup atau melalui IPopupService implementasi dari toolkit ini.

Penting

Popup hanya dapat ditampilkan dari Page atau implementasi yang mewarisi dari Page.

using CommunityToolkit.Maui.Views;

public class MyPage : ContentPage
{
    public void DisplayPopup()
    {
        var popup = new SimplePopup();

        this.ShowPopup(popup);
    }
}

Menutup Popup

Ada 2 cara berbeda yang Popup dapat ditutup; secara terprogram atau dengan mengetuk di luar popup.

Menutup Popup secara terprogram

Untuk menutup Popup pengembang harus memanggil Close atau CloseAsync pada dirinya Popup sendiri. Ini biasanya dilakukan dengan merespons penekanan tombol dari pengguna.

Kita dapat meningkatkan contoh XAML sebelumnya dengan menambahkan OKButton:

<toolkit:Popup xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
               xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
               xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
               x:Class="MyProject.SimplePopup">

    <VerticalStackLayout>
        <Label Text="This is a very important message!" />
        <Button Text="OK" 
                Clicked="OnOKButtonClicked" />
    </VerticalStackLayout>
    
</toolkit:Popup>

Dalam penanganan aktivitas yang dihasilkan, kami memanggil Close, ini akan secara terprogram menutup Popup.

Catatan

Close() adalah metode fire-and-forget. Ini akan selesai dan kembali ke utas panggilan sebelum sistem operasi menutup Popup dari layar. Jika Anda perlu menjeda eksekusi kode Anda sampai sistem operasi telah menutup Popup dari layar, gunakan sebagai gantinya CloseAsync().

public partial class MySimplePopup : Popup
{
    // ...

    void OnOKButtonClicked(object? sender, EventArgs e) => Close();
}

Dalam penanganan aktivitas yang dihasilkan, kami memanggil CloseAsync, ini akan secara terprogram menutup Popup yang memungkinkan pemanggil ke await metode sampai sistem operasi telah menutup Popup dari layar.

public partial class MySimplePopup : Popup
{
    // ...

    async void OnOKButtonClicked(object? sender, EventArgs e) 
    {
        var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));

         await CloseAsync(token: cts.Token);
         await Toast.Make("Popup Dismissed By Button").Show();
    }
}

Mengetuk di luar Popup

Secara default, pengguna dapat mengetuk di luar Popup untuk menutupnya. Ini dapat dikontrol melalui penggunaan CanBeDismissedByTappingOutsideOfPopup properti. Mengatur properti ini ke false akan mencegah pengguna menutup Popup dengan mengetuk di luarnya.

Mengembalikan hasil

Pengembang akan cukup sering mencari respons dari pengguna mereka, tampilan memungkinkan Popup pengembang untuk mengembalikan hasil yang dapat ditunggu dan ditindaklanjuti.

Kami dapat meningkatkan contoh XAML asli kami untuk menunjukkan bagaimana hal ini dapat dicapai:

XAML

Dengan menambahkan 2 tombol baru ke XAML:

<toolkit:Popup xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
               xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
               xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
               x:Class="MyProject.SimplePopup">

    <VerticalStackLayout>
        <Label Text="This is a very important message! Do you agree?" />
        <Button Text="Yes" 
                Clicked="OnYesButtonClicked" />
        <Button Text="No"
                Clicked="OnNoButtonClicked" />
    </VerticalStackLayout>
    
</toolkit:Popup>

Kemudian tambahkan penanganan aktivitas berikut di C#:

async void OnYesButtonClicked(object? sender, EventArgs e)
{
    var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
    await CloseAsync(true, cts.Token);
}

async void OnNoButtonClicked(object? sender, EventArgs e)
{
    var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
    await CloseAsync(false, cts.Token);
}

Metode ini Close memungkinkan object nilai disediakan, ini akan menjadi nilai pengembalian yang dihasilkan. Untuk menunggu hasilnya ShowPopupAsync , metode harus digunakan sebagai berikut:

using CommunityToolkit.Maui.Views;

public class MyPage : ContentPage
{
    public async Task DisplayPopup()
    {
        var popup = new SimplePopup();

        var result = await this.ShowPopupAsync(popup, CancellationToken.None);

        if (result is bool boolResult)
        {
            if (boolResult)
            {
                // Yes was tapped
            }
            else
            {
                // No was tapped
            }
        }
    }
}

Catatan

Untuk menangani penyadapan di luar Popup saat juga menunggu hasilnya, Anda dapat mengubah nilai yang dikembalikan melalui ResultWhenUserTapsOutsideOfPopup properti .

Tata Gaya

Kelas ini Popup memungkinkan penggunaan Gaya MAUI .NET untuk mempermudah berbagi pengaturan visual umum di beberapa popup.

Contoh berikut menunjukkan cara menentukan gaya yang berlaku untuk SimplePopup contoh dari bagian sebelumnya.

<toolkit:Popup xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
               xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
               xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
               xmlns:popups="clr-namespace:CommunityToolkit.Maui.Sample.Views.Popups"
               x:Class="MyProject.SimplePopup">

    <toolkit:Popup.Resources>
        <Style TargetType="{x:Type popups:SimplePopup}">
            <Setter Property="Size" Value="100,200" />
            <Setter Property="Color" Value="Green" />
            <Setter Property="HorizontalOptions" Value="Center" />
            <Setter Property="VerticalOptions" Value="Start" />
            <Setter Property="CanBeDismissedByTappingOutsideOfPopup" Value="True" />
        </Style>
    </toolkit:Popup.Resources>

    <VerticalStackLayout>
        <Label Text="This is a very important message! Do you agree?" />
        <Button Text="Yes" 
                Clicked="OnYesButtonClicked" />
        <Button Text="No"
                Clicked="OnNoButtonClicked" />
    </VerticalStackLayout>
    
</toolkit:Popup>

Catatan

Saat membuat Style target Popup tersebut dan Anda ingin membuatnya berlaku untuk popup kustom seperti SimplePopup contoh, pastikan untuk mengatur ApplyToDerivedTypes properti pada Style definisi.

Properti

Properti Tipe Deskripsi
Anchor View Mendapatkan atau mengatur View jangkar. Jangkar adalah tempat Popup akan dirender paling dekat. Ketika Jangkar dikonfigurasi, popup akan muncul berpusat di atas kontrol tersebut atau sedekat mungkin.
CanBeDismissedByTappingOutsideOfPopup bool Mendapatkan atau menetapkan nilai yang menunjukkan apakah popup dapat ditutup dengan mengetuk di luar Popup. Di Android - ketika salah tombol kembali perangkat keras dinonaktifkan.
Color Color Mendapatkan atau mengatur Color Popup. Warna ini mengatur warna latar belakang asli dari Popup, yang independen dari warna latar belakang apa pun yang dikonfigurasi dalam aktual Content.
Content View Mendapatkan atau mengatur konten yang View akan dirender di Popup.
HorizontalOptions LayoutAlignment Mendapatkan atau mengatur LayoutAlignment untuk memposisikan Popup horizontal pada layar.
Result Task<object?> Mendapatkan hasil akhir dari yang diberhentikan Popup.
Size Size Mendapatkan atau mengatur Size Tampilan Popup. Popup akan selalu mencoba membatasi ukuran aktual hingga Popup ukuran Tampilan kecuali Size ditentukan. Popup Jika menggunakan HorizontalOptions properti atau VerticalOptions yang bukan default, maka properti ini Size diperlukan.
VerticalOptions LayoutAlignment Mendapatkan atau mengatur LayoutAlignment untuk memposisikan Popup secara vertikal di layar.

Acara

Kejadian Deskripsi
Closed Terjadi ketika Popup ditutup.
Opened Terjadi ketika Popup dibuka.

Contoh

Anda dapat menemukan contoh fitur ini dalam tindakan di Aplikasi Sampel Toolkit Komunitas .NET MAUI.

API

Anda dapat menemukan kode sumber untuk Popup lebih pada repositori GitHub .NET MAUI Community Toolkit.