CarouselView 操作を構成する

[アーティクル]
02/25/2025

.NET Multi-Platform App UI (.NET MAUI) の CarouselView には、ユーザーによる操作を制御する次のプロパティが定義されています。

CurrentItem (object 型): 現在表示中の項目。このプロパティの既定のバインドモードは TwoWay で、表示するデータがない場合は値が null になります。
CurrentItemChangedCommand (ICommand 型): 現在の項目が変わると実行されます。
CurrentItemChangedCommandParameter: object 型、CurrentItemChangedCommand に渡されるパラメーター。
IsBounceEnabled (bool 型): CarouselView がコンテンツ境界でバウンスするかどうかを指定します。既定値は true です。
IsSwipeEnabled (bool 型): 表示される項目がスワイプジェスチャで変更されるかどうかを指定します。既定値は true です。
Loop (bool 型): CarouselView が項目のコレクションへのループアクセスを提供するかどうかを決定します。既定値は true です。
Position (int 型): 基になるコレクション内の現在の項目のインデックス。このプロパティの既定のバインドモードは TwoWay で、表示するデータがない場合は値が 0 になります。
PositionChangedCommand (ICommand 型): 位置が変わると実行されます。
PositionChangedCommandParameter: object 型、PositionChangedCommand に渡されるパラメーター。
VisibleViews (ObservableCollection<View> 型): 現在表示される項目のオブジェクトを含んだ読み取り専用プロパティ。

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

CarouselView には、ユーザーのスクロールまたはアプリケーションがプロパティを設定する場合に CurrentItem プロパティが変更されると発生する CurrentItemChanged イベントが定義されます。 CurrentItemChanged イベントに付随する CurrentItemChangedEventArgs オブジェクトには、object 型のプロパティが 2 つあります。

PreviousItem: プロパティ変更後の前の項目。
CurrentItem: プロパティ変更後の現在の項目。

また、CarouselView には、ユーザーのスクロールかアプリケーションがプロパティを設定する場合に Position プロパティが変更されると発生する PositionChanged イベントも定義されます。 PositionChanged イベントに付随する PositionChangedEventArgs オブジェクトには、int 型のプロパティが 2 つあります。

PreviousPosition: プロパティ変更後の前の位置。
CurrentPosition: プロパティ変更後の現在の位置。

現在の項目の変更に対応する

現在表示されている項目が変更されると、CurrentItem プロパティはその項目の値に設定されます。このプロパティが変更されると、CurrentItemChangedCommandParameter の値を ICommand に渡して CurrentItemChangedCommand が実行されます。その後、Position プロパティが更新され、CurrentItemChanged イベントが発生します。

重要

CurrentItem プロパティが変更されると、Position プロパティが変更されます。この結果、PositionChangedCommand が実行され、PositionChanged イベントが発生します。

イベント

次の XAML の例は、イベントハンドラーを使用して現在の項目の変更に応答する CarouselView を示します。

<CarouselView ItemsSource="{Binding Monkeys}"
              CurrentItemChanged="OnCurrentItemChanged">
    ...
</CarouselView>

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

CarouselView carouselView = new CarouselView();
carouselView.SetBinding(ItemsView.ItemsSourceProperty, static (MonkeysViewModel vm) => vm.Monkeys);
carouselView.CurrentItemChanged += OnCurrentItemChanged;

この例では、CurrentItemChanged イベントが発生すると、OnCurrentItemChanged イベントハンドラーが実行されます。

void OnCurrentItemChanged(object sender, CurrentItemChangedEventArgs e)
{
    Monkey previousItem = e.PreviousItem as Monkey;
    Monkey currentItem = e.CurrentItem as Monkey;
}

この例では、OnCurrentItemChanged イベントハンドラーは以前の項目と現在の項目を表示します。

Screenshot of a CarouselView with previous and current items.

コマンド

次の XAML の例は、コマンドを使用して現在の項目の変更に応答する CarouselView を示します。

<CarouselView ItemsSource="{Binding Monkeys}"
              CurrentItemChangedCommand="{Binding ItemChangedCommand}"
              CurrentItemChangedCommandParameter="{Binding Source={RelativeSource Self}, Path=CurrentItem}">
    ...
</CarouselView>

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

CarouselView carouselView = new CarouselView();
carouselView.SetBinding(ItemsView.ItemsSourceProperty, static (MonkeysViewModel vm) => vm.Monkeys);
carouselView.SetBinding(CarouselView.CurrentItemChangedCommandProperty, static (MonkeysViewModel vm) => vm.ItemChangedCommand);
carouselView.SetBinding(CarouselView.CurrentItemChangedCommandParameterProperty, Binding.Create(static (CarouselView cv) => cv.CurrentItem, source: RelativeBindingSource.Self));

この例では、CurrentItemChangedCommand プロパティが ItemChangedCommand プロパティにバインドされ、CurrentItem プロパティ値が引数として渡されます。その後、ItemChangedCommand は、必要に応じて、現在の項目の変更に応答できます。

public ICommand ItemChangedCommand => new Command<Monkey>((item) =>
{
    PreviousMonkey = CurrentMonkey;
    CurrentMonkey = item;
});

この例では、ItemChangedCommand は以前の項目と現在の項目を格納するオブジェクトを更新します。

位置の変更に対応する

現在表示されている項目が変更されると、Position プロパティは、基になるコレクションにある現在の項目のインデックスに設定されます。このプロパティが変更されると、PositionChangedCommandParameter の値を ICommand に渡して PositionChangedCommand が実行されます。その後、PositionChanged イベントが発生します。 Position プロパティがプログラムによって変更された場合、CarouselView は Position 値に対応する項目までスクロールされます。

Note

Position プロパティを 0 に設定すると、基になるコレクションの最初の項目が表示されます。

Event

次の XAML の例は、CarouselView がイベントハンドラーを使用して Position プロパティの変更に応答することを示します。

<CarouselView ItemsSource="{Binding Monkeys}"              
              PositionChanged="OnPositionChanged">
    ...
</CarouselView>

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

CarouselView carouselView = new CarouselView();
carouselView.SetBinding(ItemsView.ItemsSourceProperty, static (MonkeysViewModel vm) => vm.Monkeys);
carouselView.PositionChanged += OnPositionChanged;

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

void OnPositionChanged(object sender, PositionChangedEventArgs e)
{
    int previousItemPosition = e.PreviousPosition;
    int currentItemPosition = e.CurrentPosition;
}

この例では、OnCurrentItemChanged イベントハンドラーは前の位置と現在の位置を公開します。

Screenshot of a CarouselView with previous and current positions.

コマンド

次の XAML の例は、CarouselView がコマンドを使用して Position プロパティの変更に応答することを示します。

<CarouselView ItemsSource="{Binding Monkeys}"
              PositionChangedCommand="{Binding PositionChangedCommand}"
              PositionChangedCommandParameter="{Binding Source={RelativeSource Self}, Path=Position}">
    ...
</CarouselView>

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

CarouselView carouselView = new CarouselView();
carouselView.SetBinding(ItemsView.ItemsSourceProperty, static (MonkeysViewModel vm) => vm.Monkeys);
carouselView.SetBinding(CarouselView.PositionChangedCommandProperty, static (MonkeysViewModel vm) => vm.PositionChangedCommand);
carouselView.SetBinding(CarouselView.PositionChangedCommandParameterProperty, Binding.Create(static (CarouselView cv) => cv.Position, source: RelativeBindingSource.Self));

この例では、PositionChangedCommand プロパティは PositionChangedCommand プロパティにバインドされ、Position プロパティ値を引数として渡します。その後、必要に応じて、PositionChangedCommand は位置の変更に応答できます。

public ICommand PositionChangedCommand => new Command<int>((position) =>
{
    PreviousPosition = CurrentPosition;
    CurrentPosition = position;
});

この例では、PositionChangedCommand は前の位置と現在の位置を格納するオブジェクトを更新します。

現在の項目を事前設定する

CurrentItem プロパティを項目に設定することで、CarouselView の現在の項目をプログラムで設定できます。次の XAML の例は、CarouselView が現在の項目を事前に選択していることを示します。

<CarouselView ItemsSource="{Binding Monkeys}"
              CurrentItem="{Binding CurrentItem}">
    ...
</CarouselView>

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

CarouselView carouselView = new CarouselView();
carouselView.SetBinding(ItemsView.ItemsSourceProperty, static (MonkeysViewModel vm) => vm.Monkeys);
carouselView.SetBinding(CarouselView.CurrentItemProperty, static (MonkeysViewModel vm) => vm.CurrentItem);

Note

CurrentItem プロパティの既定のバインドモードは TwoWay です。

CarouselView.CurrentItem プロパティデータは、Monkey 型の接続ビューモデルの CurrentItem プロパティにバインドされます。既定では、TwoWay バインディングが使用され、ユーザーが現在の項目を変更すると、CurrentItem プロパティの値が現在の Monkey オブジェクトに設定されます。 CurrentItem プロパティは MonkeysViewModel クラスで定義されます。

public class MonkeysViewModel : INotifyPropertyChanged
{
    // ...
    public ObservableCollection<Monkey> Monkeys { get; private set; }

    public Monkey CurrentItem { get; set; }

    public MonkeysViewModel()
    {
        // ...
        CurrentItem = Monkeys.Skip(3).FirstOrDefault();
        OnPropertyChanged("CurrentItem");
    }
}

この例では、CurrentItem プロパティは Monkeys コレクション内の 4 番目の項目に設定されます。

Screenshot of a CarouselView with preset item.

位置を事前設定する

CarouselView に表示される項目は、基になるコレクション内の項目のインデックスに Position プロパティを設定することで、プログラムによって設定できます。次の XAML の例は、表示される項目を設定する CarouselView を示します。

<CarouselView ItemsSource="{Binding Monkeys}"
              Position="{Binding Position}">
    ...
</CarouselView>

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

CarouselView carouselView = new CarouselView();
carouselView.SetBinding(ItemsView.ItemsSourceProperty, static (MonkeysViewModel vm) => vm.Monkeys);
carouselView.SetBinding(CarouselView.PositionProperty, static (MonkeysViewModel vm) => vm.Position);

Note

Position プロパティの既定のバインドモードは TwoWay です。

CarouselView.Position プロパティデータは、int 型の接続ビューモデルの Position プロパティにバインドされます。既定では、TwoWay バインディングが使用され、ユーザーが CarouselView をスクロールすると、Position プロパティの値が表示される項目のインデックスに設定されます。 Position プロパティは MonkeysViewModel クラスで定義されます。

public class MonkeysViewModel : INotifyPropertyChanged
{
    // ...
    public int Position { get; set; }

    public MonkeysViewModel()
    {
        // ...
        Position = 3;
        OnPropertyChanged("Position");
    }
}

この例では、Position プロパティは Monkeys コレクション内の 4 番目の項目に設定されます。

Screenshot of a CarouselView with preset position.

表示状態を定義する

CarouselView は、4 つの表示状態を定義します。

CurrentItem は、現在表示されている項目の表示状態を表します。
PreviousItem は、以前に表示された項目の表示状態を表します。
NextItem は、次の項目の表示状態を表します。
DefaultItem は、残りの項目の表示状態を表します。

これらの表示状態を使用して、CarouselView によって表示される項目に対する視覚的な変更を開始できます。

次の XAML の例は、CurrentItem、PreviousItem、NextItem、DefaultItem などの表示状態を定義する方法を示します。

<CarouselView ItemsSource="{Binding Monkeys}"
              PeekAreaInsets="100">
    <CarouselView.ItemTemplate>
        <DataTemplate>
            <StackLayout>
                <VisualStateManager.VisualStateGroups>
                    <VisualStateGroup x:Name="CommonStates">
                        <VisualState x:Name="CurrentItem">
                            <VisualState.Setters>
                                <Setter Property="Scale"
                                        Value="1.1" />
                            </VisualState.Setters>
                        </VisualState>
                        <VisualState x:Name="PreviousItem">
                            <VisualState.Setters>
                                <Setter Property="Opacity"
                                        Value="0.5" />
                            </VisualState.Setters>
                        </VisualState>
                        <VisualState x:Name="NextItem">
                            <VisualState.Setters>
                                <Setter Property="Opacity"
                                        Value="0.5" />
                            </VisualState.Setters>
                        </VisualState>
                        <VisualState x:Name="DefaultItem">
                            <VisualState.Setters>
                                <Setter Property="Opacity"
                                        Value="0.25" />
                            </VisualState.Setters>
                        </VisualState>
                    </VisualStateGroup>
                </VisualStateManager.VisualStateGroups>

                <!-- Item template content -->
                <Border>
                    ...
                </Border>
            </StackLayout>
        </DataTemplate>
    </CarouselView.ItemTemplate>
</CarouselView>

この例では、CurrentItem 表示状態は、CarouselView によって現在表示されている項目の Scale プロパティが既定値の 1 から 1.1 に変更されることを指定します。 PreviousItem 表示状態と NextItem 表示状態では、現在の項目を囲む項目が 0.5 の Opacity 値で表示されることを指定します。 DefaultItem 表示状態は、CarouselView によって表示される残りの項目が 0.25 の Opacity 値で表示されることを指定します。

Note

または、表示状態は、ItemTemplate プロパティ値として設定される、DataTemplate のルート要素の型である TargetType プロパティ値を持つ Style で定義できます。

次のスクリーンショットは、CurrentItem、PreviousItem、NextItem の表示状態を示します。

Screenshot of a CarouselView using visual states.

表示状態の詳細については、「表示状態」をご覧ください。

現在の項目をクリアする

CurrentItem プロパティをクリアするには、そのプロパティまたはバインド先のオブジェクトを null に設定します。

バウンスを無効にする

既定では、CarouselView はコンテンツ境界で項目をバウンスします。 IsBounceEnabled プロパティを false に設定することで、無効にできます。

ループの無効化

既定では、CarouselView で項目のコレクションへのループアクセスが提供されます。したがって、コレクション内の最初の項目から後方にスワイプすると、コレクションの最後の項目が表示されます。同様に、コレクション内の最後の項目から前方にスワイプすると、コレクション内の最初の項目に戻ります。 Loop プロパティを false に設定することで、この動作を無効にできます。

スワイプ操作を無効にする

既定では、CarouselView はユーザーがスワイプジェスチャを使用して項目間を移動できるようにします。このスワイプ操作は、IsSwipeEnabled プロパティを false に設定することで無効にできます。

次の方法で共有

CarouselView 操作を構成する

現在の項目の変更に対応する

イベント

コマンド

位置の変更に対応する

Event

コマンド

現在の項目を事前設定する

位置を事前設定する

表示状態を定義する

現在の項目をクリアする

バウンスを無効にする

ループの無効化

スワイプ操作を無効にする

その他のリソース