.NET MAUI中CollectionView滚动UI紊乱（iOS/iPad重叠问题）

在iOS iPad设备上滚动CollectionView时，会出现顶部导航区域与列表内容重叠的UI问题。

相关页面代码（MyPage.xaml） #

<Grid IsVisible="{Binding IsBusy, Converter={StaticResource inverseBooleanConverter}}"
         RowDefinitions="auto, auto, auto, *, auto, auto">

        <StackLayout
                    Padding="0"
                    BackgroundColor="WhiteSmoke"
                    Grid.Row="0">
            <StackLayout
                        Orientation="Horizontal"
                        Margin="10,20">

                <ImageButton
                            HorizontalOptions="Start"
                            HeightRequest="22"
                            WidthRequest="22"
                            Command="{Binding Path=NavigateToRootCommand}"
                            Margin="5,0">
                    <ImageButton.Source>
                        <FontImageSource Glyph="{x:Static helper:MaterialFontHelper.ChevronDown}"
                                         Color="{StaticResource Black}"
                                         Size="22"
                                         FontFamily="MaterialDesignIcons"/>

                    </ImageButton.Source>
                </ImageButton>

                <Label
                      Style="{StaticResource LabelValueStyle}"
                      Text="Retail Food"
                      HorizontalOptions="Start"/>

                <Label
                      Style="{StaticResource LabelValueStyle}"
                      Text="NA"
                      HorizontalOptions="EndAndExpand"/>

            </StackLayout>
            <StackLayout.Shadow>
                <Shadow
                       Brush="Black"
                       Offset="10,5"
                       Opacity="0.3" />
            </StackLayout.Shadow>
        </StackLayout>
        <Label
              Grid.Row="1"
              Padding="10,20,0,20"
              LineBreakMode="TailTruncation"
              Text="{Binding Path=InspectionTitle}"
              Style="{StaticResource LabelTitleStyle}"/>

        <BoxView
                Grid.Row="2"
                HeightRequest="0.3"
                BackgroundColor="#ECECEC"/>

        <CollectionView
            Grid.Row="3"
            HorizontalOptions="FillAndExpand"
            VerticalOptions="FillAndExpand"
            ItemsSource="{Binding HealthViolationCodeRefs}">
                <CollectionView.ItemTemplate>
                    <DataTemplate>
                        <Grid
                             RowDefinitions="auto, auto, 5"
                             RowSpacing="5"
                             ColumnDefinitions="40, *, 5">

                            <CheckBox
                                     Grid.Row="0"
                                     VerticalOptions="CenterAndExpand"
                                     Margin="0,5,0,0"
                                     IsChecked="{Binding Path=IsSelected}"
                                     CheckedChanged="CheckBox_CheckedChanged"
                                     Color="DarkGray"
                                     Grid.Column="0">
                            </CheckBox>

                            <Label
                                  Padding="10,10,0,0"
                                  Text="{Binding Path=CodeNumber}"
                                  Style="{StaticResource LabelTitleStyle}"
                                  Grid.Row="0" Grid.Column="1">
                                <Label.GestureRecognizers>
                                    <TapGestureRecognizer
                                                         Command="{Binding Source={x:Reference _this},
                                                                   Path=BindingContext.ViolationCodeTapCommand}"
                                                                   CommandParameter="{Binding .}"/>
                                </Label.GestureRecognizers>
                            </Label>

                            <Label
                                  Grid.Row="1"
                                  Grid.Column="1"
                                  Padding="10,0"
                                  Margin="{OnPlatform iOS='0,0,20,0'}"
                                  Style="{StaticResource LabelKeyStyle}"
                                  HorizontalOptions="StartAndExpand"
                                  MaxLines="4"
                                  Text="{Binding Path=CodeText}"/>

                            <BoxView
                                    HeightRequest="0.3"
                                    Grid.Row="2"
                                    Grid.Column="0"
                                    Grid.ColumnSpan="3"
                                    BackgroundColor="#ECECEC"/>
                        </Grid>
                    </DataTemplate>

                </CollectionView.ItemTemplate>
        </CollectionView>
      <StackLayout BackgroundColor="WhiteSmoke" Grid.Row="5" VerticalOptions="EndAndExpand" Orientation="Horizontal">
            <Button
                    Margin="0,10,15,10"
                    Command="{Binding Path=NavigateToViolationItemDetailsCommand}"
                    Text="Next"
                    IsEnabled="{Binding Path=IsNextEnabled}"
                    Padding="30,10"
                    HorizontalOptions="EndAndExpand"
                    CornerRadius="5"/>
    </StackLayout>
</Grid>

已尝试的方法 #

曾尝试通过自定义ScrollViewRenderer移除回弹效果，但.NET MAUI的CollectionView并没有Bounce或AlwaysBounceVertical这类直接可用的属性，该方法无效。

解决方法 #

1. 自定义CollectionView Handler（iOS平台） #

在iOS项目中创建针对CollectionView的自定义Handler，修改底层UICollectionView的滚动属性：

using Microsoft.Maui.Handlers;
using UIKit;

namespace YourAppName.iOS.Handlers;

public class CustomCollectionViewHandler : CollectionViewHandler
{
    protected override void ConnectHandler(UICollectionView platformView)
    {
        base.ConnectHandler(platformView);
        
        // 禁用滚动回弹效果
        platformView.Bounces = false;
        // 禁用垂直方向的回弹（可选，根据需求调整）
        platformView.AlwaysBounceVertical = false;
    }
}

2. 注册自定义Handler #

在项目的MauiProgram.cs中注册该Handler，仅针对iOS平台生效：

builder.ConfigureMauiHandlers(handlers =>
{
#if IOS
    handlers.AddHandler<Microsoft.Maui.Controls.CollectionView, YourAppName.iOS.Handlers.CustomCollectionViewHandler>();
#endif
});

3. 布局校验（可选） #

检查页面Grid的布局约束：CollectionView所在的行使用*确保它填充剩余空间，顶部导航区和底部按钮区使用auto固定高度，避免因布局计算错误导致的视图偏移。

原理：.NET MAUI的CollectionView在iOS底层基于UICollectionView实现，禁用其Bounces属性可以消除滚动时的回弹偏移，从而解决UI重叠问题。

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