MAUI横屏模式下Grid布局及ListView兼容问题排查

一、先确保横屏模式的正确强制配置 #

MAUI的横屏设置和Xamarin略有差异，需从全局和页面级双重确认：

• 全局配置：在MauiProgram.cs中针对各平台设置默认方向：

  builder.ConfigureMauiHandlers(handlers =>
  {
      #if ANDROID
      handlers.AddHandler<Microsoft.Maui.Controls.Page, AndroidPageHandler>();
      #elif IOS
      handlers.AddHandler<Microsoft.Maui.Controls.Page, IOSPageHandler>();
      #endif
  });
  
  // Android平台Handler示例
  public class AndroidPageHandler : PageHandler
  {
      protected override void ConnectHandler(MauiAndroid.Views.ContentView platformView)
      {
          base.ConnectHandler(platformView);
          ((Activity)Context).RequestedOrientation = Android.Content.PM.ScreenOrientation.Landscape;
      }
  }
  

• 页面级配置：在目标页面XAML中设置Orientation="Landscape"，或后台代码强制：

  protected override void OnAppearing()
  {
      base.OnAppearing();
      DeviceDisplay.Current.MainDisplayInfo = new DisplayInfo(
          DeviceDisplay.Current.MainDisplayInfo.Width,
          DeviceDisplay.Current.MainDisplayInfo.Height,
          DeviceDisplay.Current.MainDisplayInfo.Density,
          DisplayOrientation.Landscape
      );
  }
  

二、Grid 2:1宽高比例的正确实现 #

要让Grid严格保持宽高2:1，用MAUI的Aspect属性替代Xamarin的旧逻辑：

<Grid Aspect="AspectRatio" AspectRatio="2"
      HorizontalOptions="Center" VerticalOptions="Center"
      Padding="0" Margin="0">
    <!-- 明确列定义，避免默认行为异常 -->
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="*"/>
        <ColumnDefinition Width="*"/>
        <ColumnDefinition Width="*"/>
    </Grid.ColumnDefinitions>
    <Grid.RowDefinitions>
        <RowDefinition Height="*"/>
    </Grid.RowDefinitions>

    <!-- 子控件必须显式设置Column="0"，确保从第0列起始 -->
    <Label Text="第一列" Grid.Column="0" BackgroundColor="LightBlue"/>
    <Label Text="第二列" Grid.Column="1" BackgroundColor="LightGreen"/>
</Grid>

注意：如果Grid的父容器是ContentPage，需将ContentPage的Padding设为0，避免视觉上Grid偏移。

三、添加ListView后布局错乱的核心修复 #

MAUI的ListView布局优先级和Xamarin不同，默认会抢占空间导致Grid列比例失效，解决要点：

1. 给ListView所在列设置明确比例：
   比如Grid有3列，要让ListView占固定份额，列定义写死比例：

   <Grid.ColumnDefinitions>
       <ColumnDefinition Width="2*"/>
       <ColumnDefinition Width="2*"/>
       <ColumnDefinition Width="1*"/> <!-- ListView占1份 -->
   </Grid.ColumnDefinitions>
   

2. 约束ListView的尺寸：
   给ListView添加明确的布局选项，避免无限制扩展：

   <ListView Grid.Column="2" BackgroundColor="LightGray"
             VerticalOptions="Fill" HorizontalOptions="Fill">
       <ListView.ItemTemplate>
           <DataTemplate>
               <ViewCell>
                   <Label Text="{Binding .}" Padding="10"/>
               </ViewCell>
           </DataTemplate>
       </ListView.ItemTemplate>
   </ListView>
   

3. 热重载失效的处理：
   MAUI热重载对布局缓存的处理更激进，涉及ListView这类复杂控件时，移除控件后缓存未清空会导致布局残留。此时必须重启应用，不要仅依赖热重载。

四、Xamarin移植的差异点 #

MAUI的布局引擎重构了部分逻辑，和Xamarin.Forms的核心差异：

• Star比例计算优先级：MAUI中控件的WidthRequest/HeightRequest优先级高于Grid的Star比例，Xamarin则相反；
• ListView默认布局：MAUI中ListView默认尝试填充父容器所有可用空间，Xamarin中会根据内容自适应；
• 约束生效时机：MAUI的布局约束在页面加载时的计算顺序不同，复杂嵌套布局需显式设置HorizontalOptions/VerticalOptions。

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