Xamarin.Forms CarouselView スクロール

CarouselView では、次のようなスクロール関連のプロパティを定義しています。

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

これらのプロパティはすべて、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;

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

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 イベントは 、ユーザーが開始したスクロールとプログラムによるスクロールに対して発生します。

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

最初の ScrollTo メソッド オーバーロードは、指定したインデックス位置にある項目をビューにスクロールします。 次の例は、carouselView という名前の付いた CarouselView オブジェクトを使用して、インデックス 6 の項目をスクロールして表示する方法を示しています。

carouselView.ScrollTo(6);

Note

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

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

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

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 は、プラットフォームの既定のスクロール バーの動作を示し、VerticalScrollBarVisibility および HorizontalScrollBarVisibility プロパティの既定値です。
• 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 でスクロールを開始すると、右側の項目がビューの右側に揃えられます。