.NET MAUI中CommunityToolkit Popup的PageOverlayColor失效问题

1. 修正Popup的继承结构 #

新版CommunityToolkit.Maui的Popup需直接继承CommunityToolkit.Maui.Views.Popup，而非ContentView。你的弹窗根元素使用ContentView会导致遮罩逻辑未正确触发，修改XAML结构如下：

<ct:Popup xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
          xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
          xmlns:ct="clr-namespace:CommunityToolkit.Maui.Views;assembly=CommunityToolkit.Maui"
          x:Class="SmartecConnect.Views.Popups.SimplePopup"
          BackgroundColor="White">
    <ContentView>
        <Label Text="This is a very important message!" />
    </ContentView>
</ct:Popup>

后台代码同步修改继承关系：

using CommunityToolkit.Maui.Views;

namespace SmartecConnect.Views.Popups;

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

2. 给ControlTemplate根Grid设置背景色 #

你的ControlTemplate根Grid未指定背景色，在.NET 9 MAUI中，未设置背景的容器会继承系统深色主题的默认黑色。添加背景色：

<ControlTemplate x:Key="OurLayoutTemplate">
    <Grid RowDefinitions="Auto,*,Auto" Background="White">
        <!-- 原有布局内容 -->
    </Grid>
</ControlTemplate>

3. 调整Popup遮罩颜色的设置方式 #

尝试直接设置Popup自身的OverlayColor，部分场景下其优先级高于PopupOptions中的PageOverlayColor：

var popup = new SimplePopup();
popup.OverlayColor = Colors.Orange;
await CurrentPage.ShowPopupAsync(popup);

4. 检查全局主题设置 #

若应用默认启用深色主题，会导致未明确设置背景的区域显示黑色。在App.xaml中添加全局背景色资源：

<Application.Resources>
    <ResourceDictionary>
        <Color x:Key="GlobalPageBackground">White</Color>
        <!-- 其他资源 -->
    </ResourceDictionary>
</Application.Resources>

然后在ContentPage中绑定该颜色：

<ContentPage BackgroundColor="{StaticResource GlobalPageBackground}" ...>

5. 排查平台特定渲染问题 #

Android平台 #

在Platforms/Android/Resources/values/styles.xml中确保AppTheme背景为浅色：

<style name="MainTheme" parent="MainTheme.Base">
    <item name="android:windowBackground">@android:color/white</item>
</style>

iOS平台 #

在Platforms/iOS/Info.plist中强制关闭深色模式（如果不需要）：

<key>UIUserInterfaceStyle</key>
<string>Light</string>

内容的提问来源于stack exchange，提问作者Carr O'Connor