カルーセルビューでスクロールを制御する

サンプルを参照する

.NET Multi-platform App UI (.NET MAUI) CarouselView は、次のスクロール関連のプロパティを定義します。

• HorizontalScrollBarVisibility は ScrollBarVisibility 型で、水平スクロール バーが表示されるタイミングを指定します。
• IsDragging は bool 型で、CarouselView がスクロールしているかどうかを示します。 このプロパティは読み取り専用であり、既定値は false です。
• IsScrollAnimated は bool 型で、CarouselView のスクロール時にアニメーションを実行するかどうかを指定します。 既定値は true です。
• ItemsUpdatingScrollMode は ItemsUpdatingScrollMode 型で、CarouselView に新しい項目が追加されたときのスクロール動作を表します。
• VerticalScrollBarVisibility は ScrollBarVisibility 型で、垂直スクロール バーが表示されるタイミングを指定します。

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

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

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

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

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

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

スクロールの検出

IsDragging プロパティを調べて、CarouselView が現在項目をスクロールしているかどうかを判断できます。

さらに、CarouselView は Scrolled イベントを定義しており、これはスクロールが発生したことを知らせるために発生します。 このイベントは、スクロールに関するデータが必要な場合に使用する必要があります。

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

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

同等の C# コードを次に示します。

CarouselView carouselView = new CarouselView();
carouselView.Scrolled += OnCarouselViewScrolled;

このコード例では、OnCarouselViewScrolled イベントハンドラーが、Scrolled イベントが発生したときに実行されます。

void OnCarouselViewScrolled(object sender, ItemsViewScrolledEventArgs e)
{
    Debug.WriteLine("HorizontalDelta: " + e.HorizontalDelta);
    Debug.WriteLine("VerticalDelta: " + e.VerticalDelta);
    Debug.WriteLine("HorizontalOffset: " + e.HorizontalOffset);
    Debug.WriteLine("VerticalOffset: " + e.VerticalOffset);
    Debug.WriteLine("FirstVisibleItemIndex: " + e.FirstVisibleItemIndex);
    Debug.WriteLine("CenterItemIndex: " + e.CenterItemIndex);
    Debug.WriteLine("LastVisibleItemIndex: " + e.LastVisibleItemIndex);
}

この例では、OnCarouselViewScrolled イベントハンドラーは、イベントに付随する ItemsViewScrolledEventArgs オブジェクトの値を出力します。

重要

Scrolled イベントは、ユーザーが開始したスクロールと、プログラムによるスクロールに対して発生します。

インデックスの項目をスクロールして表示する

1 つの ScrollTo メソッドのオーバーロードは、指定されたインデックスのアイテムをスクロールして表示させます。 次の例は、CarouselView という名前の CarouselView オブジェクトがある場合、インデックス 6 のアイテムをスクロールして表示する方法を示しています。

carouselView.ScrollTo(6);

Note

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

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

別の ScrollTo メソッドのオーバーロードは、指定された項目をスクロールして表示します。 次の例では、CarouselView という名前 CarouselView オブジェクトを使用してテングザル (Proboscis Monkey) 項目をスクロールして表示する方法を示します。

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

Note

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

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

CarouselView 内の項目間を移動する際に、スクロールするアニメーションが表示されます。 このアニメーションは、ユーザーが開始したスクロールでも、プログラムによるスクロールでも発生します。 IsScrollAnimated プロパティを false に設定すると、両方のスクロール カテゴリのアニメーションが無効になります。

または、ScrollTo メソッドの animate 引数を false に設定すると、プログラムによるスクロールでスクロール アニメーションを無効にすることもできます。

carouselView.ScrollTo(monkey, animate: false);

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

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

MakeVisible

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

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

このコード例では、項目をビューに表示するために必要なスクロールが最小限に抑えられます。

Note

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

先頭

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

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

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

中央

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

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

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

末尾

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

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

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

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

CarouselView は、バインド可能なプロパティでサポートされる ItemsUpdatingScrollMode プロパティを定義します。 このプロパティは、CarouselView に新しい項目が追加されたときのスクロール動作を表す ItemsUpdatingScrollMode 列挙値を取得または設定します。 ItemsUpdatingScrollMode 列挙体を使って、次のメンバーを定義できます。

• KeepItemsInView は、新しい項目が追加されたときにリスト内の最初の項目を引き続き表示します。
• KeepScrollOffset は、新しい項目が追加されたときに現在のスクロール位置を維持します。
• KeepLastItemInView は、新しい項目が追加されたときにリスト内の最後の項目が引き続き表示されるように、スクロール オフセットを調整します。

ItemsUpdatingScrollMode プロパティの既定値は KeepItemsInView です。 したがって、CarouselView に新しい項目が追加されても、リストの最初の項目が表示されたままになります。 新しい項目が追加されたときにリスト内の最後の項目が表示されるようにするには、ItemsUpdatingScrollMode プロパティを KeepLastItemInView に設定します。

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

同等の C# コードを次に示します。

CarouselView carouselView = new CarouselView
{
    ItemsUpdatingScrollMode = ItemsUpdatingScrollMode.KeepLastItemInView
};

スクロール バーの表示

CarouselView は、バインド可能なプロパティでサポートされる HorizontalScrollBarVisibility プロパティと VerticalScrollBarVisibility プロパティを定義します。 これらのプロパティは、水平スクロール バーまたは垂直スクロール バーが表示されるタイミングを表す ScrollBarVisibility 列挙値を取得または設定します。 ScrollBarVisibility 列挙体を使って、次のメンバーを定義できます。

• Default は、プラットフォームの既定のスクロール バーの動作を示し、HorizontalScrollBarVisibility プロパティおよび VerticalScrollBarVisibility プロパティの既定値です。
• Always は、コンテンツがビューに収まる場合でもスクロール バーが表示されることを示します。
• Never は、コンテンツがビューに収まらない場合でもスクロール バーが表示されないことを示します。

スナップ位置

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

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

これらのプロパティはすべて、BindableProperty オブジェクトを基にしています。つまり、プロパティをデータ バインディングの対象にすることができます。

Note

スナップが発生するとき、最も動きの少ない方向に発生します。

スナップ ポイントのタイプ

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

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

CarouselView の既定では、SnapPointsType プロパティは SnapPointsType.MandatorySingle に設定され、スクロールは一度に1つのアイテムだけをスクロールするようになります。

次のスクリーンショットは、スナップをオフにした CarouselView を示しています。

スナップ位置の調整

SnapPointsAlignment 列挙体は、Start、Center および End 要素を定義します。

重要

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

先頭

SnapPointsAlignment.Start 要素は、スナップ ポイントが項目の上端に揃っていることを示します。 次の XAML の例は、この列挙要素を設定する方法を示しています:

<CarouselView ItemsSource="{Binding Monkeys}"
              PeekAreaInsets="100">
    <CarouselView.ItemsLayout>
        <LinearItemsLayout Orientation="Horizontal"
                           SnapPointsType="MandatorySingle"
                           SnapPointsAlignment="Start" />
    </CarouselView.ItemsLayout>
    ...
</CarouselView>

同等の C# コードを次に示します。

CarouselView carouselView = new CarouselView
{
    ItemsLayout = new LinearItemsLayout(ItemsLayoutOrientation.Horizontal)
    {
        SnapPointsType = SnapPointsType.MandatorySingle,
        SnapPointsAlignment = SnapPointsAlignment.Start
    },
    // ...
};

水平スクロール CarouselView でユーザーがスワイプしてスクロールを開始した場合、左の項目はビューの左側に整列されます。

中央

SnapPointsAlignment.Center は、スナップポイントが項目の中心に配置されていることを示します。

CarouselView の既定では、SnapPointsAlignment プロパティは Center に設定されます。 ただし、念のため、次の XAML の例では、この列挙要素を設定する方法を示します。

<CarouselView ItemsSource="{Binding Monkeys}"
              PeekAreaInsets="100">
    <CarouselView.ItemsLayout>
        <LinearItemsLayout Orientation="Horizontal"
                           SnapPointsType="MandatorySingle"
                           SnapPointsAlignment="Center" />
    </CarouselView.ItemsLayout>
    ...
</CarouselView>

同等の C# コードを次に示します。

CarouselView carouselView = new CarouselView
{
    ItemsLayout = new LinearItemsLayout(ItemsLayoutOrientation.Horizontal)
    {
        SnapPointsType = SnapPointsType.MandatorySingle,
        SnapPointsAlignment = SnapPointsAlignment.Center
    },
    // ...
};

水平スクロール CarouselView でユーザーがスワイプしてスクロールを開始した場合、中央の項目はビューの中央に整列されます。

末尾

SnapPointsAlignment.End は、スナップポイントが項目の後端と一直線上にあることを示します。 次の XAML の例は、この列挙要素を設定する方法を示しています:

<CarouselView ItemsSource="{Binding Monkeys}"
              PeekAreaInsets="100">
    <CarouselView.ItemsLayout>
        <LinearItemsLayout Orientation="Horizontal"
                           SnapPointsType="MandatorySingle"
                           SnapPointsAlignment="End" />
    </CarouselView.ItemsLayout>
    ...
</CarouselView>

同等の C# コードを次に示します。

CarouselView carouselView = new CarouselView
{
    ItemsLayout = new LinearItemsLayout(ItemsLayoutOrientation.Horizontal)
    {
        SnapPointsType = SnapPointsType.MandatorySingle,
        SnapPointsAlignment = SnapPointsAlignment.End
    },
    // ...
};

水平スクロール CarouselView でユーザーがスワイプしてスクロールを開始すると、右の項目がビューの右側に整列されます。