Xamarin.Forms CollectionView のスクロール

[アーティクル]
07/13/2023

CollectionView は、項目をビューにスクロールする 2 つの ScrollTo メソッドを定義します。オーバーロードの 1 つは、指定したインデックスの項目をビューにスクロールし、もう 1 つは指定した項目をビューにスクロールします。どちらのオーバーロードにも、項目が属するグループ、スクロールが完了した後の項目の正確な位置、スクロールをアニメーション化するかどうかを示すために指定できる追加の引数があります。

CollectionView は、 ScrollToRequested いずれかのメソッドが呼び出されたときに発生するイベントを ScrollTo 定義します。 ScrollToRequestedEventArgsイベントに付随ScrollToRequestedするオブジェクトには、、IndexItemScrollToPosition、、などIsAnimated、多くのプロパティがあります。これらのプロパティは、メソッド呼び出しで ScrollTo 指定された引数から設定されます。

さらに、はScrolled、CollectionViewスクロールが発生したことを示すために発生するイベントを定義します。 ItemsViewScrolledEventArgsイベントに付随Scrolledするオブジェクトには、多くのプロパティがあります。詳細については、「スクロールの検出」を参照してください。

CollectionView また、 ItemsUpdatingScrollMode 新しい項目が追加されたときの CollectionView のスクロール動作を表すプロパティも定義します。このプロパティの詳細については、「新しい項目が追加されたときにスクロール位置を制御する」を参照してください。

ユーザーがスワイプしてスクロールを開始すると、スクロールの終了位置を制御して、項目が完全に表示されるようにすることができます。スクロールが停止すると項目が位置にスナップするため、この機能はスナップと呼ばれます。詳細については、「ポイントをスナップする」を参照してください。

CollectionView は、ユーザーがスクロールするにつれてデータを増分的に読み込むこともできます。詳細については、「データの増分読み込み」を参照してください。

スクロールを検出する

CollectionView は、 Scrolled スクロールが発生したことを示すために発生するイベントを定義します。イベントに付随Scrolledするオブジェクトを表すクラスはItemsViewScrolledEventArgs、次のプロパティを定義します。

HorizontalDelta型 doubleのは、水平スクロールの量の変化を表します。これは左にスクロールする場合は負の値、右にスクロールする場合は正の値です。
VerticalDelta型 doubleのは、垂直スクロールの量の変化を表します。これは、上方向にスクロールする場合は負の値、下方向にスクロールする場合は正の値です。
HorizontalOffset型 doubleのは、リストが原点から水平方向にオフセットされる量を定義します。
VerticalOffset型 doubleのは、リストが原点から垂直方向にオフセットされる量を定義します。
FirstVisibleItemIndex型 intのは、リストに表示される最初の項目のインデックスです。
CenterItemIndex型 intのは、リストに表示される中央の項目のインデックスです。
LastVisibleItemIndex型 intのは、リストに表示される最後の項目のインデックスです。

次の XAML の例は、 CollectionView イベントのイベントハンドラーを設定するを Scrolled 示しています。

<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);

または、グループ化されたデータ内の項目をスクロールして、項目とグループインデックスを指定することもできます。次の例は、2 番目のグループの 3 番目の項目をスクロールして表示する方法を示しています。

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

注意

メソッドが ScrollToRequested 呼び出されると、 ScrollTo イベントが発生します。

項目をスクロールして表示する

2 番目 ScrollTo のメソッドオーバーロードは、指定した項目をビューにスクロールします。という名前collectionViewのオブジェクトをCollectionView指定すると、Proboscis Monkey 項目をスクロールして表示する方法を次の例に示します。

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

または、グループ化されたデータ内の項目をスクロールして、項目とグループを指定することもできます。次の例は、Monkeys グループの Proboscis 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);

注意

メソッドが ScrollToRequested 呼び出されると、 ScrollTo イベントが発生します。

スクロールアニメーションを無効にする

項目をビューにスクロールすると、スクロールアニメーションが表示されます。ただし、メソッドの引数を animate に設定することで、このアニメーションを ScrollTo 無効に falseできます。

collectionView.ScrollTo(monkey, animate: false);

スクロール位置を制御する

項目をビューにスクロールする場合、スクロールが完了した後の項目の正確な位置は、メソッドの ScrollTo 引数をposition使用して指定できます。この引数は列挙メンバーを ScrollToPosition 受け入れます。

MakeVisible

メンバーは ScrollToPosition.MakeVisible 、ビューに表示されるまで項目をスクロールする必要があることを示します。

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

次のコード例では、項目をビューにスクロールするために必要な最小限のスクロールが行われます。

注意

メソッドのScrollToPosition.MakeVisible呼び出しScrollTo時に引数がposition指定されていない場合、メンバーは既定で使用されます。

[開始]

メンバーは ScrollToPosition.Start 、項目をビューの先頭までスクロールする必要があることを示します。

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

次のコード例では、項目がビューの先頭までスクロールされます。

Center

メンバーは ScrollToPosition.Center 、項目をビューの中央までスクロールする必要があることを示します。

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

次のコード例では、項目がビューの中央までスクロールされます。

垂直リストスクロール項目が含まれる CollectionView 垂直リストのスクリーンショット。スクロールされた項目が含まれる iOS および Android の ScrollToPosition.Center

End

メンバーは ScrollToPosition.End 、項目をビューの末尾までスクロールする必要があることを示します。

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

次のコード例では、項目がビューの末尾までスクロールされます。

スクロール項目が CollectionView の垂直リスト含まれる CollectionView 垂直リストのスクリーンショット。スクロールされた項目が含まれる iOS および Android の

新しい項目が追加されたときにスクロール位置を制御する

CollectionViewItemsUpdatingScrollModeは、バインド可能なプロパティによってサポートされるプロパティを定義します。このプロパティは、 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はプラットフォームの既定のスクロールバーの動作を示し、とプロパティのHorizontalScrollBarVisibilityVerticalScrollBarVisibility既定値です。
Always は、コンテンツがビューに収まる場合でも、スクロールバーが表示されることを示します。
Never は、コンテンツがビューに収まらない場合でも、スクロールバーが表示されないことを示します。

スナップ位置

ユーザーがスワイプしてスクロールを開始すると、スクロールの終了位置を制御して、項目が完全に表示されるようにすることができます。この機能はスナップと呼ばれます。これは、スクロールが停止したときに項目が位置にスナップし、クラスの ItemsLayout 次のプロパティによって制御されるためです。

SnapPointsType型 SnapPointsTypeのは、スクロール時のスナップポイントの動作を指定します。
SnapPointsAlignment型 SnapPointsAlignmentの。は、スナップポイントを項目に合わせる方法を指定します。

これらのプロパティはオブジェクトによって BindableProperty サポートされます。つまり、プロパティはデータバインディングのターゲットにすることができます。

注意

スナップが発生すると、最小のモーション量を生成する方向にスナップが発生します。

スナップポイントの種類

SnapPointsType 列挙体を使って、次のメンバーを定義できます。

None は、スクロールが項目にスナップしないことを示します。
Mandatory は、コンテンツが常に、慣性方向に沿って、スクロールが自然に停止する最も近いスナップポイントにスナップすることを示します。
MandatorySingle はと同じ動作 Mandatoryを示しますが、一度にスクロールする項目は 1 つだけです。

既定では、 SnapPointsType プロパティはに SnapPointsType.None設定されています。これにより、次のスクリーンショットに示すように、スクロールが項目をスナップしないようにします。

スナップポイントの配置

列挙体はSnapPointsAlignment、CenterおよびメンバーをEnd定義しますStart。

重要

プロパティのSnapPointsAlignment値は、プロパティが、または MandatorySingleにMandatory設定されている場合SnapPointsTypeにのみ考慮されます。

[開始]

メンバーは 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
    },
    // ...
};

ユーザーがスワイプしてスクロールを開始すると、上部の項目がビューの上部に揃えられます。

Center

メンバーは 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
    },
    // ...
};

ユーザーがスワイプしてスクロールを開始すると、上部の項目がビューの上部に中央揃えされます。

End

メンバーは 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
    },
    // ...
};

ユーザーがスワイプしてスクロールを開始すると、下部の項目がビューの下部に揃えられます。

CollectionView (サンプル)

Xamarin.Forms CollectionView のスクロール

スクロールを検出する

インデックスの項目をビューにスクロールする

項目をスクロールして表示する

スクロール アニメーションを無効にする

スクロール位置を制御する

MakeVisible

[開始]

Center

End

新しい項目が追加されたときにスクロール位置を制御する

スクロール バーの表示

スナップ位置

スナップ ポイントの種類

スナップ ポイントの配置

[開始]

Center

End

関連リンク

その他のリソース

スクロールアニメーションを無効にする

スクロールバーの表示

スナップポイントの種類

スナップポイントの配置