주석이 추가된 스크롤바 컨트롤

2024-03-22

주석이 달린 스크롤바를 사용하면 사용자가 대량의 항목 컬렉션을 쉽게 탐색할 수 있습니다. 이는 스크롤바를 대체하며 스크롤 가능한 컨테이너와 함께 사용할 수 있습니다. 이 세로 스크롤바를 사용하면 컬렉션의 항목을 위아래로 사용자가 스크롤할 수 있습니다. 컬렉션 내에 있는 위치에 대한 시각적 참조를 제공하는 스크롤바 영역을 따라 사용자가 범주 레이블을 확인할 수 있습니다. 이동 표시기(색깔 있는 선으로 강조)는 컬렉션에서 사용자의 현재 위치를 나타냅니다. 사용자가 스크롤바 영역을 마우스로 가리키면 툴팁이 표시됩니다. 툴팁에는 컬렉션의 현재 위치에 대한 자세한 정보를 사용자에게 제공하는 레이블이 포함되어 있습니다. 스크롤 화살표는 스크롤바 영역의 위쪽과 아래쪽에 있습니다. 현재 위치를 작은 단위로 이동하는 데 사용할 수 있습니다.

사진 앱에서 주석이 추가된 스크롤 막대를 보여 주는 스크린샷

주석이 달린 스크롤바를 ItemsView 컨트롤과 함께 사용하면 사진 갤러리 경험을 다시 만들 수 있습니다. 범주 레이블은 다른 연도로의 설정을 통해 사용자가 사진 컬렉션 내의 특정 위치로 쉽게 이동할 수 있게 해줍니다.

상호 작용

마우스로 가리키면, 툴팁이 표시되어 해당 위치의 미리 보기가 표시됩니다. 그런 다음 사용자가 클릭하면 해당 특정 위치로 이동할 수 있습니다. 사용자는 스크롤바 영역의 아무 곳이나 클릭하고 드래그하여 컬렉션 내의 새 위치로 이동할 수도 있습니다. 드래그를 하면, 이동 표시기가 마우스 커서에 연결되고 콘텐츠가 스크롤되어 새 위치가 반영됩니다. 사용자는 마우스 휠을 사용하여 컬렉션을 스크롤할 수도 있습니다. 마우스 휠을 상하 방향으로 스크롤하면 컬렉션의 위치와 해당 이동 표시기가 고정된 양만큼 상하 방향으로 이동합니다.

참고 항목

이 ScrollBar 컨트롤에서와는 달리, 썸을 클릭과 드래그할 수 없습니다. 썸은 현재 뷰포트 위치를 시각화하기 위한 비대화형 요소입니다. 썸에는 뷰포트 높이를 대표하지 않는 고정 높이가 있습니다.

레이블 동작

터치 입력에 최적화된 환경의 경우, 사용자는 스크롤바 영역을 길게 탭하여 툴팁을 볼 수 있습니다. 터치 사용자가 더 쉽게 읽을 수 있도록 툴팁을 약간 더 높게 위치시킵니다. 스크롤바 영역의 아무 곳이나 탭하고 드래그하면 마우스로 클릭하고 드래그하는 것과 유사하게 작동합니다.
툴팁 레이블은 설명이 포함된 텍스트를 표시하기 위한 목적이므로 잘리지 않습니다. 대신, 텍스트가 툴팁의 최대 너비인 360px를 넘어가면 래핑됩니다.
텍스트가 스크롤바 영역의 너비보다 긴 경우 범주 레이블이 잘립니다.
두 범주 레이블이 충돌하는 경우(예: 창 크기가 감소하고 두 레이블이 서로 겹치는 경우) 위쪽 레이블이 제거됩니다. 이 규칙의 예외로, 컬렉션의 첫 번째 레이블은 사용자에게 컬렉션 범위를 나타내는 데 도움이 되므로 항상 유지됩니다. 범주 레이블은 최소 4px(위 2px, 아래 2px)가 사이사이에 있어야 합니다. 그렇지 않으면 레이블 충돌을 발생시킵니다.

올바른 컨트롤인가요?

큰 항목 컬렉션을 처리하거나 많은 양의 스크롤이 예상되는 경우 기본 스크롤바 대신 주석이 달린 스크롤바를 사용하는 것이 좋습니다. 주석이 달린 스크롤바를 통해 사용자가 컬렉션에서 자신을 쉽게 찾고 트래버스할 수 있습니다.

항목이 몇 개만 있거나 스크롤이 적게 필요한 컬렉션의 경우, 기본 스크롤바를 사용하는 것이 좋습니다.

권장 사항

사용자에게 유용한 정보를 제공하는 경우에만 범주 레이블을 추가합니다.
범주 레이블 및 툴팁에 사용되는 문자열을 가능한 한 간결하게 유지
주석이 달린 스크롤바는 세로 공간이 충분한 경우에 가장 적합합니다. 제한된 세로 공간에서 주석이 달린 스크롤바를 사용하면 표시되는 레이블 수가 줄어듭니다.
주석이 추가된 스크롤바를 컬렉션 내에서 사용자가 자신을 찾을 수 있는 유일한 방법으로 사용하지 마세요. 컬렉션 전체에서 고정 헤더 또는 범주 레이블을 사용하여 주석이 추가된 스크롤바를 보완하는 것이 좋습니다.

주석이 추가된 스크롤바 만들기

중요 API: AnnotatedScrollBar 클래스, ScrollView 클래스, IScrollController 인터페이스

WinUI 3 갤러리 앱을 열고 작동 중인 AnnotatedScrollBar를 확인합니다.

WinUI 3 갤러리 앱에는 대부분의 WinUI 3 컨트롤, 특징, 기능의 대화형 예제가 포함되어 있습니다. 앱을 Microsoft Store 에서 다운로드하거나 GitHub에서 소스 코드를 가져오세요.

다음 몇 단계를 완료해야 AnnotatedScrollBar를 사용할 수 있습니다.

AnnotatedScrollBar를 스크롤 컨테이너에 연결합니다.
스크롤바에 레이블을 추가합니다.
세부 정보 레이블(툴팁)을 추가합니다.

AnnotatedScrollBar를 스크롤 컨테이너에 연결

이 AnnotatedScrollBar를 사용하려면, 스크롤 가능한 컨테이너에 IScrollController 인터페이스를 통해 연결합니다. AnnotatedScrollBar는 ScrollController 속성을 통해 IScrollController를 구현하는 한편, ScrollView는 ScrollPresenter 속성(특히, ScrollPresenter.VerticalScrollController)을 통해 사용합니다.

참고 항목

ScrollView 컨트롤은 IScrollController 인터페이스를 사용하는 것을 지원하도록 빌드되었습니다. ScrollViewer와 같은 다른 스크롤 컨테이너의 경우 IScrollController용 어댑터를 작성해야 합니다. 이 문서의 뒷부분에 있는 예제를 참조하세요.

여기서 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는 두 종류의 레이블을 표시할 수 있으며 둘 다 선택 사항입니다.

범주 레이블

레이블을 추가하기 위해 Labels 컬렉션을 채웁니다. 각 레이블은 AnnotatedScrollBarLabel 클래스로 표현되며 다음의 두 가지 정보가 필요합니다.

콘텐츠: 스크롤바에 표시되는 콘텐츠입니다.
ScrollOffset: 레이블 콘텐츠가 표시되는 오프셋 값입니다.

다른 레이블과 충돌하거나 레일 경계를 지나 확장하지 않는 한, 레이블(지정된 경우)은 항상 스크롤바에 표시됩니다. (자세한 내용은 레이블 동작 섹션을 참조하세요.)

레이블 오프셋 값의 계산은 앱 및 해당 데이터의 세부 정보에 따라 달라집니다. 오프셋을 계산하는 방법의 한 가지 예는 GitHub의 WinUI 갤러리 예제를 참조하세요.

세부 정보 레이블

세부 정보 레이블은 커서가 스크롤바 위에 있을 때 표시되는 툴팁 요소입니다. 세부 정보 레이블을 만들려면 DetailLabelRequested 이벤트를 처리합니다. 이벤트 인수는 툴팁 레이블이 표시되는 ScrollOffset 을 제공합니다. 이 값을 사용하여 해당 위치에 대해 표시할 올바른 레이블을 결정하고, 레이블을 이벤트 인수의 Content 속성으로 설정합니다.

스크롤

사용자는 스크롤바의 위쪽과 아래쪽에 있는 화살표 단추를 클릭하여 AnnotatedScrollBar를 스크롤할 수 있습니다. 화살표 버튼이 콘텐츠를 스크롤하는 크기를 지정하려면 SmallChange 속성을 설정하세요.

이 Scrolling 이벤트를 처리하여 스크롤이 수행되는 방식을 확인하거나, 스크롤이 발생할 때 작업을 수행하거나 또는 스크롤 액션을 취소 할 수 있습니다.

샘플 코드 가져오기

WinUI 갤러리 샘플 - 대화형 형식으로 모든 XAML 컨트롤을 보여줍니다.

ScrollView 클래스