使用CommunityToolkit.Maui v14 Popup时如何解决黑屏问题

将开发环境从VS 2022 + .NET 9升级到VS 2026 + .NET 10时，同步切换到CommunityToolkit v14版本。使用该工具包的Popup组件时遇到弹窗弹出后屏幕变黑的问题——原.NET 9环境中弹窗后方的页面是可见的。

弹窗调用代码 #

var apopup = new PasswordPopup();
var options = new PopupOptions
{
      PageOverlayColor = Colors.Transparent,
      Shape = null
};
var response = (await this.ShowPopupAsync(apopup, options)) as LoginPasswordNotification;

Popup的XAML代码 #

<?xml version="1.0" encoding="utf-8" ?>
<Popup xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
       xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
       xmlns:telerik="http://schemas.telerik.com/2022/xaml/maui"
       xmlns:const="clr-namespace:MyApp.Helpers.Constants"
       xmlns:ctrl="clr-namespace:MyApp.Resources.Controls"
       xmlns:local="clr-namespace:MyApp.Resources.Localization"
       xmlns:selviews="clr-namespace:MyApp.Views.SelectLists"
       xmlns:views="clr-namespace:MyApp.Views"
       xmlns:ret="clr-namespace:MyApp.Helpers.AppMessaging.Messages.Login"
       CanBeDismissedByTappingOutsideOfPopup="False"
       x:TypeArguments="ret:LoginPasswordNotification"
       x:Class="Resource_Requests.Views.Login.PasswordPopup">
    <Border x:Name="PageBorder" Style="{StaticResource PopupBorder}">
        <VerticalStackLayout Spacing="20" WidthRequest="{OnIdiom 275, Phone=275, Tablet=350}">
            <ctrl:TRGLabel Style="{StaticResource PopupTitle}" Text="{local:Translate Title_PleaseEnterPassword}" />
            <Grid ColumnDefinitions="*,Auto">
                <ctrl:TRGEntry x:Name="PasswordEntry"
                               Text="{Binding PasswordValue}"
                               Grid.Column="0" Grid.ColumnSpan="2"
                               IsPassword="{Binding HidePassword}"
                               TextChanged="OnPasswordEnteredTextChanged"
                               Keyboard="Plain"
                               ReturnType="Go"
                               Completed="OnPasswordCompleted" />
                <Image Grid.Column="1" Source="{Binding EyeballSource}"
                       Margin="0,0,10,0"
                       HeightRequest="25" WidthRequest="25">
                    <Image.GestureRecognizers>
                        <TapGestureRecognizer Tapped="OnEyeballTapped"/>
                    </Image.GestureRecognizers>
                </Image>
            </Grid>

            <Grid ColumnDefinitions="*,*" ColumnSpacing="20"
                  WidthRequest="{OnIdiom 230, Phone=230, Tablet=330}"
                  Margin="{OnPlatform '0,0,0,0', Android='0,0,0,0', iOS='0,0,0,20'}">
                <ctrl:TRGButton Grid.Column="0"
                        Text="{local:Translate Button_Cancel}" Clicked="OnCancelClicked" />
                <ctrl:TRGButton Grid.Column="1" Style="{StaticResource AppThemeButton}"
                        Text="{local:Translate Button_OK}" IsEnabled="{Binding OkIsEnabled}" Clicked="OnOkClicked" />
            </Grid>
        </VerticalStackLayout>
    </Border>
</Popup>

• 替换过时的PopupOptions属性：CommunityToolkit v14中PageOverlayColor已被废弃，改用OverlayColor控制遮罩透明度。修改调用代码：

  var options = new PopupOptions
  {
        OverlayColor = Colors.Transparent,
        Shape = null
  };
  

• 设置Popup自身背景透明：在Popup的XAML标签中添加BackgroundColor="Transparent"，避免弹窗自身背景遮挡后方页面：

  <Popup ... BackgroundColor="Transparent">
  

• 检查样式资源：查看PopupBorder静态样式，确认其中的Background属性是否为透明或半透明。如果样式里设置了黑色背景，会导致弹窗区域外的屏幕看起来变黑。

• 排查平台特定渲染逻辑：.NET 10搭配v14在部分平台（比如Android）可能默认强制添加不透明遮罩，可针对平台单独设置OverlayColor验证：

  options.OverlayColor = DeviceInfo.Platform switch
  {
      DevicePlatform.Android => Colors.Transparent,
      DevicePlatform.iOS => Colors.Transparent,
      _ => Colors.Transparent
  };
  

• 确认内部控件背景：检查Popup内部的Border、VerticalStackLayout等控件，确保它们的背景没有设置为不透明黑色，避免覆盖整个弹窗区域外的屏幕。

内容的提问来源于stack exchange，提问作者John Ureke