在 CollectionView 中控制滚动

项目
09/30/2024

.NET Multi-platform App UI (.NET MAUI) CollectionView 定义了两个 ScrollTo 方法，用于将项滚动到视图中。其中一个重载将指定索引处的项滚动到视图中，而另一个重载将指定的项滚动到视图中。这两个重载都有额外的参数，可以指定这些参数来指示项所属的组，滚动完成后项的确切位置，以及是否对滚动进行动画处理。

CollectionView 定义在调用 ScrollTo 方法之一时触发的 ScrollToRequested 事件。 ScrollToRequested 事件附带的 ScrollToRequestedEventArgs 对象具有许多属性，包括 IsAnimated、Index、Item 和 ScrollToPosition。这些属性是通过 ScrollTo 方法调用中指定的参数设置的。

此外，CollectionView 还定义一个 Scrolled 事件，该事件被触发可指示发生了滚动。 Scrolled 事件附带的 ItemsViewScrolledEventArgs 对象有许多属性。有关详细信息，请参阅检测滚动。

CollectionView 还定义一个 ItemsUpdatingScrollMode 属性，该属性表示向 CollectionView 添加新项时的滚动行为。有关此属性的详细信息，请参阅添加新项时控制滚动位置。

当用户轻扫以启动滚动时，可以控制滚动的结束位置，以便完全显示项。此功能称为对齐，因为当滚动停止时，项将按位置对齐。有关详细信息，请参阅对齐点。

CollectionView 还可以在用户滚动时以增量方式加载数据。有关详细信息，请参阅以增量方式加载数据。

提示

将 CollectionView 放置在 VerticalStackLayout 中可以停止 CollectionView 滚动，并可以限制显示的项目数量。在这种情况下，将 VerticalStackLayout 替换为 Grid。

检测滚动

CollectionView 定义一个 Scrolled 事件，该事件被触发可指示发生了滚动。 ItemsViewScrolledEventArgs 类表示 Scrolled 事件随附的对象，它定义下列属性：

HorizontalDelta，类型为 double，表示水平滚动量的变化。向左滚动时此为负值，向右滚动时为正值。
VerticalDelta，类型为 double，表示垂直滚动量的变化。向上滚动时此为负值，向下滚动时为正值。
HorizontalOffset，类型为 double，定义列表从其原点水平偏移的量。
VerticalOffset，类型为 double，定义列表从其原点垂直偏移的量。
FirstVisibleItemIndex，类型为 int，是列表中第一个可见项的索引。
CenterItemIndex，类型为 int，是列表中可见的中心项的索引。
LastVisibleItemIndex，类型为 int，是列表中最后一个可见项的索引。

下面的 XAML 示例显示了为 Scrolled 事件设置事件处理程序的 CollectionView：

<CollectionView Scrolled="OnCollectionViewScrolled">
    ...
</CollectionView>

等效 C# 代码如下：

CollectionView collectionView = new CollectionView();
collectionView.Scrolled += OnCollectionViewScrolled;

在此代码示例中，OnCollectionViewScrolled 事件处理程序在 Scrolled 事件触发时执行：

void OnCollectionViewScrolled(object sender, ItemsViewScrolledEventArgs e)
{
    // Custom logic
}

重要

针对用户启动的滚动和编程滚动触发 Scrolled 事件。

将索引处的项滚动到视图中

一个 ScrollTo 方法重载将指定索引处的项滚动到视图中。给定一个名为 CollectionView 的 CollectionView 对象，下面的示例显示如何将索引 12 处的项滚动到视图中：

collectionView.ScrollTo(12);

或者通过指定项和组索引，可以将已分组数据中的项滚动到视图中。以下示例说明如何将第二组中的第三项滚动到视图中：

// Items and groups are indexed from zero.
collectionView.ScrollTo(2, 1);

注意

调用 ScrollTo 方法时，将触发 ScrollToRequested 事件。

将项滚动到视图中

另一个 ScrollTo 方法重载将指定项滚动到视图中。给定一个名为 CollectionView 的 CollectionView 对象，以下示例显示如何将“长鼻猴”项滚动到视图中：

MonkeysViewModel viewModel = BindingContext as MonkeysViewModel;
Monkey monkey = viewModel.Monkeys.FirstOrDefault(m => m.Name == "Proboscis Monkey");
collectionView.ScrollTo(monkey);

或者，可以通过指定项和组将分组数据中的项滚动到视图中。以下示例演示如何将“猴子”组中的“长鼻猴”项滚动到视图中：

GroupedAnimalsViewModel viewModel = BindingContext as GroupedAnimalsViewModel;
AnimalGroup group = viewModel.Animals.FirstOrDefault(a => a.Name == "Monkeys");
Animal monkey = group.FirstOrDefault(m => m.Name == "Proboscis Monkey");
collectionView.ScrollTo(monkey, group);

注意

调用 ScrollTo 方法时，将触发 ScrollToRequested 事件。

禁用滚动动画

将项滚动到视图中时，将显示滚动动画。但是，通过将 ScrollTo 方法的 animate 参数设置为 false 可以禁用此动画：

collectionView.ScrollTo(monkey, animate: false);

控制滚动位置

将项滚动到视图中时，可以使用 ScrollTo 方法的 position 参数指定项在滚动完成后的确切位置。此参数接受 ScrollToPosition 枚举成员。

MakeVisible

ScrollToPosition.MakeVisible 成员指示应滚动该项，直到它在视图中可见：

collectionView.ScrollTo(monkey, position: ScrollToPosition.MakeVisible);

此示例代码导致将项滚动到视图中所需的最小滚动：

Screenshot of a CollectionView vertical list with ScrollToPosition.MakeVisible.

注意

如果调用 ScrollTo 方法时未指定 position 参数，则默认情况下使用 ScrollToPosition.MakeVisible 成员。

开始

ScrollToPosition.Start 成员指示应将项滚动到视图的开头：

collectionView.ScrollTo(monkey, position: ScrollToPosition.Start);

此示例代码导致项滚动到视图的开头：

Screenshot of a CollectionView vertical list with ScrollToPosition.Start.

中心

ScrollToPosition.Center 成员指示应将项滚动到视图的中心：

collectionView.ScrollTo(monkey, position: ScrollToPosition.Center);

此示例代码导致项滚动到视图的中心：

Screenshot of a CollectionView vertical list with ScrollToPosition.Center.

结束

ScrollToPosition.End 成员指示应将项滚动到视图的末尾：

collectionView.ScrollTo(monkey, position: ScrollToPosition.End);

此示例代码导致项滚动到视图的末尾：

Screenshot of a CollectionView vertical list with ScrollToPosition.End.

添加新项时控制滚动位置

CollectionView 定义 ItemsUpdatingScrollMode 属性，由可绑定属性提供支持。此属性获取或设置 ItemsUpdatingScrollMode 枚举值，以表示向其中添加新项时 CollectionView 的滚动行为。 ItemsUpdatingScrollMode 枚举定义下列成员：

添加新项时，KeepItemsInView 将保留列表中显示的第一个项。
KeepScrollOffset 确保在添加新项时保持当前滚动位置。
KeepLastItemInView 会调整滚动偏移，以便在添加新项时保持显示列表中的最后一个项。

ItemsUpdatingScrollMode 属性的默认值是 KeepItemsInView。因此，将新项添加到 CollectionView 时，列表中的第一个项将保持显示状态。若要确保在添加新项时显示列表中的最后一项，应将 ItemsUpdatingScrollMode 属性设置为 KeepLastItemInView：

<CollectionView ItemsUpdatingScrollMode="KeepLastItemInView">
    ...
</CollectionView>

等效 C# 代码如下：

CollectionView collectionView = new CollectionView
{
    ItemsUpdatingScrollMode = ItemsUpdatingScrollMode.KeepLastItemInView
};

滚动条可见性

CollectionView 定义 HorizontalScrollBarVisibility 和 VerticalScrollBarVisibility 属性，由可绑定属性提供支持。这些属性会获取或设置一个 ScrollBarVisibility 枚举值，指示水平滚动条或垂直滚动条何时可见。 ScrollBarVisibility 枚举定义下列成员：

Default 指示平台的默认滚动条行为，并且是 HorizontalScrollBarVisibility 和 VerticalScrollBarVisibility 属性的默认值。
Always 指示滚动条将可见，即使内容适合视图也是如此。
Never 指示滚动条将不可见，即使内容不适合视图也是如此。

贴靠点

当用户轻扫以启动滚动时，可以控制滚动的结束位置，以便完全显示项。此功能称为“对齐”，因为项在滚动停止时会对齐位置，并且由 ItemsLayout 类中的以下属性控制：

SnapPointsType，属于 SnapPointsType 类型，用于指定滚动时对齐点的行为。
SnapPointsAlignment，属于 SnapPointsAlignment 类型，用于指定对齐点与项的对齐方式。

所有这些属性都由 BindableProperty 对象提供支持，这意味着这些属性可以作为数据绑定的目标。

注意

当对齐发生时，它将发生在产生最小运动量的方向上。

对齐点类型

SnapPointsType 枚举定义下列成员：

None 指示滚动不会对齐到项。
Mandatory 表示内容总是沿惯性方向对齐到最接近滚动自然停止位置的对齐点。
MandatorySingle 表示与 Mandatory 相同的行为，但一次只滚动一个项。

默认情况下，SnapPointsType 属性设置为 SnapPointsType.None，这可确保滚动不会对齐项，如下面的屏幕截图所示：

Screenshot of a CollectionView vertical list without snap points.

对齐点对齐

SnapPointsAlignment 枚举定义 Start、Center 和 End 成员。

重要

仅当 SnapPointsType 属性被设置为 Mandatory 或 MandatorySingle 时，才会考虑 SnapPointsAlignment 属性的值。

开始

SnapPointsAlignment.Start 成员指示对齐点与项的前边缘对齐。

默认情况下，SnapPointsAlignment 属性设置为 SnapPointsAlignment.Start。但是，为完整起见，下面的 XAML 示例展示了如何设置此枚举成员：

<CollectionView ItemsSource="{Binding Monkeys}">
    <CollectionView.ItemsLayout>
        <LinearItemsLayout Orientation="Vertical"
                           SnapPointsType="MandatorySingle"
                           SnapPointsAlignment="Start" />
    </CollectionView.ItemsLayout>
    ...
</CollectionView>

等效 C# 代码如下：

CollectionView collectionView = new CollectionView
{
    ItemsLayout = new LinearItemsLayout(ItemsLayoutOrientation.Vertical)
    {
        SnapPointsType = SnapPointsType.MandatorySingle,
        SnapPointsAlignment = SnapPointsAlignment.Start
    },
    // ...
};

当用户轻扫以启动滚动时，顶部项将与视图的顶部对齐：

Screenshot of a CollectionView vertical list with start snap points.

中心

SnapPointsAlignment.Center 成员指示对齐点与项的中心对齐。以下 XAML 示例展示了如何设置此枚举成员：

<CollectionView ItemsSource="{Binding Monkeys}">
    <CollectionView.ItemsLayout>
        <LinearItemsLayout Orientation="Vertical"
                           SnapPointsType="MandatorySingle"
                           SnapPointsAlignment="Center" />
    </CollectionView.ItemsLayout>
    ...
</CollectionView>

等效 C# 代码如下：

CollectionView collectionView = new CollectionView
{
    ItemsLayout = new LinearItemsLayout(ItemsLayoutOrientation.Vertical)
    {
        SnapPointsType = SnapPointsType.MandatorySingle,
        SnapPointsAlignment = SnapPointsAlignment.Center
    },
    // ...
};

当用户轻扫以启动滚动时，顶部项将在视图顶部居中对齐：

Screenshot of a CollectionView vertical list with center snap points.

结束

SnapPointsAlignment.End 成员指示对齐点与项的尾部对齐。以下 XAML 示例展示了如何设置此枚举成员：

<CollectionView ItemsSource="{Binding Monkeys}">
    <CollectionView.ItemsLayout>
        <LinearItemsLayout Orientation="Vertical"
                           SnapPointsType="MandatorySingle"
                           SnapPointsAlignment="End" />
    </CollectionView.ItemsLayout>
    ...
</CollectionView>

等效 C# 代码如下：

CollectionView collectionView = new CollectionView
{
    ItemsLayout = new LinearItemsLayout(ItemsLayoutOrientation.Vertical)
    {
        SnapPointsType = SnapPointsType.MandatorySingle,
        SnapPointsAlignment = SnapPointsAlignment.End
    },
    // ...
};

当用户轻扫以启动滚动时，底部项将与视图的底部对齐：

Screenshot of a CollectionView vertical list with end snap points.

通过

在 CollectionView 中控制滚动

检测滚动

将索引处的项滚动到视图中

将项滚动到视图中

禁用滚动动画

控制滚动位置

MakeVisible

开始

中心

结束

添加新项时控制滚动位置

滚动条可见性

贴靠点

对齐点类型

对齐点对齐

开始

中心

结束

其他资源