共用方式為


Popup

彈出視窗是一種非常常見的方式,將信息呈現給與目前工作相關的使用者。 操作系統提供顯示訊息並要求用戶回應的方式,這些警示通常限制開發人員可以提供的內容,以及版面配置和外觀。

注意

如果您想要向用戶呈現更微妙的內容,請查看我們的 快顯通知小吃店 選項。

檢視 Popup 可讓開發人員建置自己的自定義UI,並將其呈現給使用者。

建置快顯

Popup可以在 XAML 或 C# 中建立 :

XAML

包含 XAML 命名空間

若要在 XAML 中使用工具組,必須將下列專案 xmlns 新增至您的頁面或檢視:

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

因此,下列專案:

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

將修改為包含 xmlns ,如下所示:

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

定義您的快顯

請注意,如果在 Popup XAML 中建立 ,它也必須有 C# 程式代碼後置檔案。 若要了解為何需要此專案,請參閱此 .NET MAUI 檔頁面

建立 Popup 最簡單的方式是將新的 .NET MAUI ContentView (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!" />
    </VerticalStackLayout>
    
</toolkit:Popup>
public partial class SimplePopup : Popup
{
    public SimplePopup()
    {
        InitializeComponent();
    }
}

重要

如果未建立檔案後置程式代碼以及呼叫 , InitializeComponent 則在嘗試顯示 時 Popup,將會擲回例外狀況。

C#

using CommunityToolkit.Maui.Views;

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

呈現快顯

Popup建置之後,即可透過我們的擴充方法,Popup或透過這個工具組的IPopupService實作來呈現。

重要

Popup只能從 顯示 ,Page或 繼承自 Page的實作。

using CommunityToolkit.Maui.Views;

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

        this.ShowPopup(popup);
    }
}

關閉快顯

有 2 種不同的方式 Popup 可以關閉;以程式設計方式或點選快顯外部的方式。

以程序設計方式關閉快顯

若要關閉 Popup 開發人員必須呼叫 CloseCloseAsyncPopup 本身。 這通常是透過回應使用者按下按鈕來執行。

我們可以藉由新增 OKButtonXAML 範例:

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

在產生的事件處理程式中,我們會 Close以程式設計方式關閉 Popup

注意

Close() 是 fire-and-forget 方法。 它會在操作系統 Popup 關閉畫面之前完成並返回呼叫線程。 如果您需要暫停程式代碼的執行,直到作業系統已 Popup 關閉畫面的 ,請改 CloseAsync()用 。

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

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

在所呼叫 CloseAsync的結果事件處理程式中,這會以程式設計方式關閉 Popup 方法的允許呼叫者 await ,直到作業系統從畫面關閉 Popup

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();
    }
}

點選快顯外部

根據預設,用戶可以點選 外部 Popup 將其關閉。 這可透過屬性的使用來控制 CanBeDismissedByTappingOutsideOfPopup 。 將此屬性設定為 false 可防止使用者藉由點選外部關閉 Popup

傳回結果

開發人員通常會從使用者尋求回應,檢視 Popup 可讓開發人員傳回可等候並採取行動的結果。

我們可以增強原始的 XAML 範例,以示範如何完成此作業:

XAML

將 2 個新按鈕新增至 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>

然後在 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);
}

方法 Close 允許 object 提供值,這會是產生的傳回值。 若要等候結果 ShowPopupAsync ,必須使用 方法,如下所示:

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

注意

為了在等候結果時處理 外 Popup 點選,您可以變更透過 ResultWhenUserTapsOutsideOfPopup 屬性傳回的值。

設定樣式

類別 Popup 允許使用 .NET MAUI 樣式 ,讓您更輕鬆地跨多個快顯共用一般視覺設定。

下列範例示範如何定義套用至上一節範例的 SimplePopup 樣式。

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

注意

建立Style該目標Popup並想要將其套用至範例之類的SimplePopup自定義快顯時,請務必在定義上ApplyToDerivedTypes設定 Style 屬性。

屬性

屬性 類型​ 描述
Anchor View 取得或設定 View 錨點。 錨點是快顯最接近的地方。 設定錨點時,彈出視窗會以該控件為中心,或盡可能接近該控件。
CanBeDismissedByTappingOutsideOfPopup bool 取得或設定值,指出快顯是否可以在Popup外部點選來關閉快顯。 在Android上 - 當為 false 時,硬體返回按鈕會停用。
Color Color 取得或設定 Color Popup 的 。 此色彩會設定 的 Popup原生背景色彩,這與實際 Content中設定的任何背景色彩無關。
Content View 取得或設定在 ViewPopup呈現的內容。
HorizontalOptions LayoutAlignment 取得或設定 LayoutAlignment ,用於在畫面上水準放置 Popup
Result Task<object?> 取得已 Popup關閉的最終結果。
Size Size 取得或設定 Size 快顯顯示器的 。 除非指定 ,否則Popup快顯一律會嘗試將 的實際大小Size限製為 View 的大小。 Popup如果 使用 HorizontalOptions 不是預設值的 或 VerticalOptions 屬性,則需要此屬性Size
VerticalOptions LayoutAlignment 取得或設定 LayoutAlignment ,用於在畫面上垂直放置 Popup

事件

活動 描述
Closed 在關閉 時 Popup 發生。
Opened 發生於 開啟 時 Popup

範例

您可以在 .NET MAUI Community Toolkit 範例應用程式中找到這項功能的範例。

API

您可以在 .NET MAUI Community Toolkit GitHub 存放庫Popup找到 的原始程式碼。