快顯 - .NET MAUI 社群工具組 - Community Toolkits for .NET

發行項
12/22/2024

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

注意

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

檢視 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 開發人員必須呼叫 Close 或 CloseAsyncPopup 本身。這通常是透過回應使用者按下按鈕來執行。

我們可以藉由新增 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`	取得或設定在 `View` 中 `Popup`呈現的內容。
`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找到的原始程式碼。

共用方式為

XAML

包含 XAML 命名空間

C#

傳回結果

XAML

設定樣式

屬性

事件

範例

API

其他資源

共用方式為

Popup

建置快顯

XAML

包含 XAML 命名空間

定義您的快顯

C#

呈現快顯

關閉快顯

以程序設計方式關閉快顯

點選快顯外部

傳回結果

XAML

設定樣式

屬性

事件

範例

API

其他資源