注釈付きスクロール バー コントロール

注釈付きスクロール バーは、ユーザーが項目の大きなコレクション内を簡単に移動するのに役立ちます。 この機能は、既定のスクロール バーに代わるもので、スクロール可能なコンテナーと組み合わせて使用できます。 この垂直スクロール バーを使うと、ユーザーはコレクション内の項目間を上下にスクロールできます。 ユーザーは、スクロール バー領域に表示されるカテゴリ ラベルを見ることで、自分が今コレクション内のどこにいるのかが視覚的にわかります。 パン インジケーター (アクセント カラーで示された線) は、コレクション内のユーザーの現在位置を示します。 ユーザーがスクロール バー領域をポイントすると、ヒントが表示されます。 このヒントには、コレクション内の現在位置に関する詳細情報をユーザーに提供するラベルが含まれます。 スクロール矢印は、スクロール バー領域の上端と下端にあります。 これらを使って、現在位置を少しずつ移動できます

注釈付きスクロール バーを ItemsView コントロールと組み合わせて使って、フォト ギャラリー エクスペリエンスを作り直すことができます。 カテゴリ ラベルをさまざまな年に設定すると、ユーザーが写真コレクション内の特定の場所に移動するのに役立ちます。

インタラクション

カーソルを合わせると、ツールチップが表示され、その場所のプレビューが見ることができます。 それから、ユーザーはクリックして特定の場所に移動できます。 ユーザーは、スクロール バー領域の任意の場所をクリックしてドラッグすることで、コレクション内の新しい位置に移動することもできます。 ドラッグすると、パン インジケーターはマウス カーソルに張り付いたままになり、コンテンツはスクロールして新しい位置を反映します。 ユーザーは、マウス ホイールを使ってコレクション内をスクロールすることもできます。 マウス ホイールで上下にスクロールすると、コレクション内の位置が移動し、対応するパン インジケーターが一定の量ずつ上下に移動します。

ラベルの動作

• タッチ入力用に最適化されたエクスペリエンスの場合、ユーザーはスクロール バー領域を長押ししてヒントを表示できます。 ツールチップは、タッチ操作を行うユーザーが読みやすいように少しだけ高くなります。 スクロール バー領域のどこかをタップしてドラッグすると、マウスをクリックしてドラッグするのと同様に機能します。
• ヒントのラベルは、説明のテキストを表示することが目的であるため、切り捨てられることはありません。 ツールチップの最大幅である 360px を超えた場合、テキストは折り返されます。
• カテゴリ ラベルは、テキストがスクロール バーの領域の幅より長い場合、クリップされます。
• 2 つのカテゴリ ラベルの間に競合がある場合 (たとえば、ウィンドウのサイズが小さくなって、2 つのラベルが重なる場合)、上側のラベルが削除されます。 この規則の例外として、コレクションの最初のラベルは、コレクションの範囲をユーザーに示すのに役立つため、常に表示されます。 カテゴリ ラベルの間は常に 4px (上 2px、下 2px) 以上離れている必要があり、そうでない場合は、ラベルの競合がトリガーされます。

これは適切なコントロールですか?

項目の大きなコレクションを処理する場合、または大量のスクロールが予想される場合は、既定のスクロール バーではなく、注釈付きスクロール バーを使うことをお勧めします。 注釈付きスクロール バーを使うと、ユーザーはコレクション内で自分がいる場所を簡単に特定し、コレクション内を移動できます。

項目が少ないコレクションや、わずかなスクロールしか必要としないコレクションの場合は、既定のスクロール バーを使うことをお勧めします。

推奨事項

• ユーザーに役立つ情報を提供する場合にのみ、カテゴリ ラベルを追加します
• カテゴリ ラベルとヒントに使われる文字列は、できるだけ簡潔に保ちます
• 注釈付きスクロール バーは、縦方向に十分なスペースがある場合に最適です。 縦方向のスペースが限られている場合に注釈付きスクロール バーを使うと、表示されるラベルの数が減ります
• ユーザーがコレクション内で自分の位置を特定するための唯一の方法として、注釈付きスクロール バーを使わないでください。 注釈付きスクロール バーを補完するため、コレクション全体で固定ヘッダーまたはカテゴリ ラベルを使うことをお勧めします。

注釈付きスクロール バーを作成する

WinUI 3 ギャラリー アプリには、WinUI コントロールと機能の対話型の例が含まれています。 Microsoft Store からアプリを取得するか、GitHub でソース コードを参照します。

AnnotatedScrollBar を使うには、いくつかのステップを実行する必要があります。

• AnnotatedScrollBar をスクロール コンテナーに接続します。
• ラベルをスクロール バーに追加します。
• 詳細ラベル (ヒント) を追加します。

AnnotatedScrollBar をスクロール コンテナーに接続する

AnnotatedScrollBar を使うには、IScrollController インターフェイスを介してそれをスクロール可能なコンテナーに接続します。 AnnotatedScrollBar は ScrollController のプロパティを通じて IScrollController の実装を提供するのに対し、ScrollView は ScrollPresenter のプロパティ (具体的には ScrollPresenter.VerticalScrollController) を通じてそれを使います。

ここでは、ItemsView の VerticalScrollController プロパティは、AnnotatedScrollBar の ScrollController にバインドされています。 (ItemsView.VerticalScrollPresenter プロパティは、ItemsView の内部 ScrollView の ScrollPresenter.VerticalScrollController 値に渡されます。)

<Grid ColumnDefinitions="*,Auto">
    <ItemsView VerticalScrollController="{x:Bind annotatedScrollBar.ScrollController}"/>
    <AnnotatedScrollBar x:Name="annotatedScrollBar" Grid.Column="1"/>
</Grid>

次に示すように、コードでそれらを接続することもできます。 この例では、ScrollView が ItemsRepeater をラップするために使われ、それにスクロール機能を提供します。 AnnotatedScrollBar は、ScrollView の既定のスクロール バーを置き換えます。

<Grid ColumnDefinitions="*, Auto">
    <ScrollView x:Name="scrollView"
                Background="LightGray" 
                MaxWidth="800" MaxHeight="500"
                VerticalScrollBarVisibility="Hidden">
        <ItemsRepeater x:Name="itemsRepeater"
                ItemsSource="{x:Bind ColorCollection}"
                Margin="2"
                SizeChanged="ItemsRepeater_SizeChanged">
            <ItemsRepeater.Layout>
                <UniformGridLayout/>
            </ItemsRepeater.Layout>
            <ItemsRepeater.ItemTemplate>
                <DataTemplate x:DataType="media:SolidColorBrush">
                    <Grid Background="{x:Bind}" Width="112" Height="82" 
                          CornerRadius="4" Margin="4"/>
                </DataTemplate>
            </ItemsRepeater.ItemTemplate>
        </ItemsRepeater>
    </ScrollView>
                
    <AnnotatedScrollBar x:Name="annotatedScrollBar" Grid.Column="1"
        Margin="4,0,48,0" MaxHeight="500" HorizontalAlignment="Right"
        DetailLabelRequested="AnnotatedScrollBar_DetailLabelRequested"/>
</Grid>

private void AnnotatedScrollBarPage_Loaded(object sender, Microsoft.UI.Xaml.RoutedEventArgs e)
{
    scrollView.ScrollPresenter.VerticalScrollController = annotatedScrollBar.ScrollController;
}

ラベル

AnnotatedScrollBar では 2 種類のラベルを表示でき、どちらも省略可能です。

カテゴリ ラベル

Labels コレクションに値を設定することで、ラベルを追加します。 各 Label は AnnotatedScrollBarLabel クラスで表され、次の 2 つの情報が必要です。

• Content: スクロール バーに表示される内容。
• ScrollOffset: ラベルの内容が表示されるオフセット値。

ラベル (指定した場合) は、他のラベルと競合したり、レールの境界を越えて広がったりしない限り、常にスクロール バーに表示されます。 (詳しくは、「ラベルの動作」をご覧ください。)

ラベルのオフセット値の計算は、アプリとそのデータの詳細に依存します。 オフセットの計算方法の 1 つの例については、GitHub の WinUI 3 ギャラリーの例を参照してください。

詳細ラベル

詳細ラベルは、カーソルがスクロール バーの上にあるときに表示されるヒント要素です。 詳細ラベルを作成するには、DetailLabelRequested イベントを処理します。 イベント引数によって、ヒント ラベルが表示される ScrollOffset が提供されます。 この値を使って、その位置に表示する正しいラベルを決定し、イベント引数の Content プロパティとしてラベルを設定します。

スクロール

ユーザーは、スクロール バーの上端と下端にある矢印ボタンをクリックして、AnnotatedScrollBar をスクロールできます。 SmallChange プロパティを設定して、矢印ボタンで内容をスクロールする量を指定できます。

Scrolling イベントを処理して、実行されているスクロールの方法を特定したり、スクロールが発生したときにアクションを実行したり、スクロール操作をキャンセルしたりできます。

サンプル コードを取得する

• WinUI 3 Gallery サンプル - 対話型形式ですべての XAML コントロールを表示します。

関連トピック

• ScrollView クラス