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
開發人員必須呼叫 Close
或 CloseAsync
Popup
本身。 這通常是透過回應使用者按下按鈕來執行。
我們可以藉由新增 OKButton
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!" />
<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 範例應用程式中找到這項功能的範例。