스크롤 뷰어 컨트롤

  • 아티클

영역에 맞출 수 있는 것보다 더 많은 UI 콘텐츠가 표시되면 스크롤 뷰어 컨트롤을 사용합니다.

스크롤 뷰어를 사용하면 콘텐츠가 뷰포트(표시 영역)의 경계를 넘어 확장될 수 있습니다. 사용자는 마우스 또는 펜 커서를 사용하여 스크롤 뷰어의 스크롤 막대를 조작하거나 터치, 마우스 휠, 키보드 또는 게임 패드를 통해 스크롤 뷰어 표면을 조작하여 이 콘텐츠에 도달합니다.

상황에 따라 스크롤 뷰어의 스크롤 막대는 이동 표시기(왼쪽)와 기존 스크롤 막대 엄지손가락(오른쪽)의 두 가지 시각화를 사용합니다.

A screenshot that illustrates a panning scrollbar, a 2 pixel wide vertical line at the right edge of the content.

A screenshot that illustrates the standard scrollbar, a 6 pixel wide vertical line with an up arrow button at the top, and a down arrow at the bottom.

Important

WinUI 3에는 ScrollViewer와 ScrollView라는 두 가지 스크롤 뷰어 컨트롤을 사용할 수 있습니다. 스크롤 뷰어 컨트롤에 대해 일반적으로 말할 때마다 정보는 두 컨트롤에 모두 적용됩니다.

스크롤, 이동 및 확대/축소

스크롤 뷰어 컨트롤을 사용하여 콘텐츠의 스크롤, 이동 및 확대/축소를 허용합니다.

  • 스크롤: 스크롤 막대 엄지손가락을 끌거나 마우스에서 스크롤 휠을 사용하여 콘텐츠를 세로 또는 가로로 이동합니다.
  • 이동: 터치 또는 펜 입력을 사용하여 콘텐츠를 세로 또는 가로로 이동합니다.
    • 스크롤 및 이동에 대한 자세한 내용은 이동 지침을 참조 하세요.
  • 확대/축소: 콘텐츠의 크기를 광학적으로 늘리거나 줄입니다.
    • 확대/축소에 대한 자세한 내용은 광학 확대/축소 및 크기 조정을 참조 하세요.

스크롤 막대는 사용자의 입력 방법을 인식하고 이를 사용하여 표시할 시각화를 결정합니다.

  • 스크롤 막대를 직접 조작하지 않고 터치 등으로 영역을 스크롤하는 경우 현재 스크롤 위치 표시와 함께 이동 표시기가 나타납니다.
  • 마우스나 펜 커서가 이동 표시기 위로 이동하면 이동 표시기가 기존 스크롤 막대로 변형됩니다. 스크롤 막대 위치 조정 컨트롤을 끌어 스크롤 영역을 조작합니다.

An animation that shows the scroll bar transform from the narrow panning indicator to the traditional thumb when the cursor moves over it.

참고 항목

스크롤 막대는 ScrollViewer 내의 콘텐츠 맨 위에 16px로 오버레이되어 표시됩니다. 훌륭한 UX 디자인을 만들려면 스크롤 막대가 오버레이되어 대화형 콘텐츠가 잘 보이지 않는 경우가 없도록 합니다. 또한 UX가 겹치지 않도록 하려면 뷰포트의 가장자리에 스크롤 막대를 위한 16px 안쪽 여백을 남겨 둡니다.

뷰포트 및 익스텐트

스크롤 뷰어는 해당 기능을 이해하는 데 중요한 두 개의 기본 영역으로 구성됩니다. 숨겨진 내용과 표시되는 모든 스크롤 가능한 콘텐츠가 포함된 영역은 범위입니다. 콘텐츠가 표시되는 컨트롤의 표시 영역은 뷰포트입니다.

A block of text that extends beyond the viewport, or visible area of the control.

익스텐트 크기와 뷰포트 크기의 차이인 스크롤 가능한 높이와 너비뿐만 아니라 이러한 영역의 높이와 너비를 가져올 수 있는 다양한 API를 사용할 수 있습니다.

권장 사항

  • 가능하면 가로가 아닌 세로 스크롤을 위해 디자인합니다.
  • 하나의 뷰포트 경계(세로 또는 가로)를 넘어 확장되는 콘텐츠 영역에는 1축 이동이 사용됩니다. 두 뷰포트 경계(세로 및 가로)를 넘어 확장되는 콘텐츠 영역에는 2축 이동이 사용됩니다.
  • 항목 보기, 목록 보기, 그리드 보기, 콤보 상자, 목록 상자, 텍스트 입력란 및 허브 컨트롤에서 기본 제공 스크롤 기능을 사용합니다. 이러한 컨트롤을 사용하면 한 번에 표시할 항목이 너무 많으면 사용자가 항목 목록 위로 가로 또는 세로로 스크롤할 수 있습니다.
  • 사용자가 더 큰 영역 주위에서 양방향으로 이동하게 하고 확대/축소할 수 있도록 하려면 예를 들어 사용자가 화면에 맞게 크기가 조정된 이미지가 아닌 전체 크기 이미지를 이동 및 확대/축소하도록 허용하려는 경우 스크롤 뷰어 내에 이미지를 배치합니다.
  • 사용자가 긴 텍스트 구절을 스크롤하는 경우 스크롤 뷰어를 세로로만 스크롤하도록 구성합니다.
  • 스크롤 뷰어를 사용하여 하나의 개체만 포함할 수 있습니다. 하나의 개체는 레이아웃 패널이 될 수 있으며, 이에 따라 자체 개체의 개수를 포함할 수 있습니다.
  • 스크롤 가능한 보기(예: ScrollViewer 또는 ListView)에서 UIElement에 대한 포인터 이벤트를 처리해야 하는 경우 UIElement.CancelDirectManipulation을 호출하여 뷰의 요소에 대한 조작 이벤트에 대한 지원을 명시적으로 사용하지 않도록 설정해야 합니다. 보기에서 조작 이벤트를 다시 사용하도록 설정하려면 UIElement.TryStartDirectManipulation을 호출 합니다.

UWP 및 WinUI 2

참고 항목

컨트롤은 ScrollView WinUI 3에서만 사용할 수 있습니다. UWP 및 WinUI 2의 경우 컨트롤을 ScrollViewer 사용합니다.

Important

이 문서의 정보 및 예제는 Windows 앱 SDK 및 WinUI 3을 사용하는 앱에 최적화되어 있지만 일반적으로 WinUI 2를 사용하는 UWP 앱에 적용됩니다. 플랫폼별 정보 및 예제는 UWP API 참조를 참조하세요.

이 섹션에는 UWP 또는 WinUI 2 앱에서 컨트롤을 사용하는 데 필요한 정보가 포함되어 있습니다.

이 컨트롤에 대한 API는 Windows.UI.Xaml.Controls 네임스페이스에 있습니다.

최신 WinUI 2 를 사용하여 모든 컨트롤에 대한 최신 스타일과 템플릿을 가져오는 것이 좋습니다. WinUI 2.2 이상에는 둥근 모서리를 사용하는 이 컨트롤에 대한 새 템플릿이 포함되어 있습니다. 자세한 내용은 모서리 반경을 참조하세요.

스크롤 뷰어 만들기

WinUI 3 갤러리 앱을 열고 ScrollView의 작동을 확인합니다. WinUI 3 갤러리 앱을 열고 ScrollViewer의 작동을 확인합니다.

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

스크롤 뷰어 컨트롤은 스크롤 뷰어에서 콘텐츠를 명시적으로 래핑하거나 콘텐츠 컨트롤의 컨트롤 템플릿에 스크롤 뷰어를 배치하여 콘텐츠를 스크롤할 수 있도록 하는 데 사용할 수 있습니다.

컨트롤 템플릿의 스크롤 뷰어

스크롤 뷰어 컨트롤이 다른 컨트롤의 복합 부분으로 존재하는 것이 일반적입니다. 스크롤 뷰어 파트는 호스트 컨트롤의 레이아웃 공간이 확장된 콘텐츠 크기보다 작게 제한되는 경우에만 스크롤 막대와 함께 뷰포트를 표시합니다.

ItemsView 는 템플릿에 ScrollView 컨트롤을 포함합니다. 하지만 ItemsView.ScrollView 속성에 액세스할 ScrollView 수 있습니다.

ListView 및 GridView 템플릿에는 항상 .ScrollViewer TextBox 및 RichEditBox 는 템플릿에도 포함 ScrollViewer 됩니다. 기본 제공 부분 ScrollViewer 의 일부 동작 및 속성에 영향을 주려면 스타일에서 ScrollViewer 설정하고 템플릿 바인딩에서 사용할 수 있는 여러 XAML 연결된 속성을 정의합니다. 연결된 속성에 대한 자세한 내용은 연결된 속성 개요를 참조하세요.

스크롤 가능한 콘텐츠 설정

스크롤 뷰어의 뷰포트보다 크면 스크롤 뷰어 내의 콘텐츠를 스크롤할 수 있게 됩니다.

다음은 컨트롤의 내용으로 설정하는 Rectangle 예제입니다 ScrollView . 사용자는 해당 사각형의 500x400 부분만 보고 스크롤하여 나머지 부분을 볼 수 있습니다.

<ScrollView Width="500" Height="400">
    <Rectangle Width="1000" Height="800">
        <Rectangle.Fill>
            <LinearGradientBrush StartPoint="0,0" EndPoint="1,1">
                <GradientStop Color="Yellow" Offset="0.0" />
                <GradientStop Color="Red" Offset="0.25" />
                <GradientStop Color="Blue" Offset="0.75" />
                <GradientStop Color="LimeGreen" Offset="1.0" />
            </LinearGradientBrush>
        </Rectangle.Fill>
    </Rectangle>
</ScrollView>

Layout

이전 예제에서 사각형의 크기는 명시적으로 스크롤 뷰어보다 크도록 설정되었습니다. 목록 또는 텍스트 블록과 같이 스크롤 뷰어 콘텐츠가 자연스럽게 증가할 수 있는 경우 해당 콘텐츠( 범위)가 세로, 가로, 둘 다 또는 둘 다 확장되도록 스크롤 뷰어를 구성할 수 있습니다.

예를 들어 이 텍스트 블록은 부모 컨테이너가 제한될 때까지 가로로 자른 다음 텍스트를 래핑하고 세로로 자랍니다.

<TextBlock Text="{x:Bind someText}" TextWrapping="WrapWholeWords"/>

텍스트 블록이 스크롤 뷰어에 래핑되면 스크롤 뷰어는 가로 및 세로 증가를 제한합니다.

세로 는 콘텐츠가 가로로 제한되지만 뷰포트 범위를 넘어 세로로 증가할 수 있으며 사용자가 콘텐츠를 위아래로 스크롤할 수 있음을 의미합니다.

A block of text that extends vertically beyond the viewport, or visible area of the control, with a vertical scroll bar shown.

가로 는 콘텐츠가 세로로 제한되지만 뷰포트 범위를 넘어 가로로 증가할 수 있으며 사용자가 콘텐츠를 왼쪽과 오른쪽으로 스크롤할 수 있음을 의미합니다.

A block of text that extends horizontally beyond the viewport, or visible area of the control, with a horizontal scroll bar shown.

스크롤 표시 유형

ScrollViewer 및 ScrollView 컨트롤은 약간 다른 방법을 사용하여 콘텐츠의 가로 및 세로 스크롤을 구성합니다.

  • ScrollViewer 컨트롤에서 VerticalScrollBarVisibility 및 HorizontalScrollBarVisibility 속성은 스크롤 막대의 표시 여부와 특정 방향으로 스크롤할 수 있는지 여부를 모두 제어합니다. 속성을 설정하면 사용자 상호 작용을 통해 Disabled해당 방향으로 콘텐츠를 스크롤할 수 없습니다.
    • 기본값은 다음과 VerticalScrollBarVisibility="Auto"같습니다. HorizontalScrollBarVisibility="Disabled"
  • ScrollView 컨트롤에서 VerticalScrollBarVisibility 및 HorizontalScrollBarVisibility 속성은 스크롤 막대의 표시 유형만 제어합니다.
    • 기본값은 다음과 VerticalScrollBarVisibility="Auto"같습니다. HorizontalScrollBarVisibility="Auto"

이 표에서는 이러한 속성에 대한 표시 유형 옵션을 설명합니다.

값 설명
자동 뷰포트에서 모든 콘텐츠를 표시할 수 없는 경우에만 스크롤 막대가 나타납니다.
사용 안 함(ScrollViewer만 해당) 뷰포트에서 모든 콘텐츠를 표시할 수 없는 경우에도 스크롤 막대가 나타나지 않습니다. 사용자 상호 작용을 통해 스크롤할 수 없습니다. 프로그래밍 방식으로 스크롤할 수 있습니다.
숨겨져 있음 뷰포트에서 모든 콘텐츠를 표시할 수 없는 경우에도 스크롤 막대가 나타나지 않습니다. 스크롤은 계속 사용하도록 설정되어 있으며 터치, 키보드 또는 마우스 휠 상호 작용을 통해 발생할 수 있습니다.
표시 스크롤 막대가 항상 나타납니다. (현재 UX 디자인에서 스크롤 막대는 뷰포트가 모든 콘텐츠를 표시할 수 없는 한 마우스 커서가 위에 있을 때만 나타납니다. )

(ScrollViewer는 다음을 사용합니다.ScrollBarVisibility 열거형 ; ScrollView는 ScrollingScrollBarVisibility 열거형 을 사용합니다.)

Orientation

ScrollView 컨트롤에는 콘텐츠 레이아웃을 제어할 수 있는 ContentOrientation 속성이 있습니다. 이 속성은 콘텐츠가 명시적으로 제한되지 않을 때 콘텐츠가 증가하는 방법을 결정합니다. Width 콘텐츠 ContentOrientation 에 명시적으로 설정된 경우 Height 아무런 영향을 주지 않습니다.

이 표에는 ScrollView에 대한 옵션과 ScrollViewer에 대한 해당 설정이 표시됩니다ContentOrientation.

Orientation ScrollView ScrollViewer
Vertical ContentOrientation="Vertical" VerticalScrollBarVisibility="[Auto][Visible][Hidden]"
HorizontalScrollBarVisibility="Disabled"
수평적 크기 조정 ContentOrientation="Horizontal" VerticalScrollBarVisibility="Disabled"
HorizontalScrollBarVisibility="[Auto][Visible][Hidden]"
모두 ContentOrientation="Both" VerticalScrollBarVisibility="[Auto][Visible][Hidden]"
HorizontalScrollBarVisibility="[Auto][Visible][Hidden]"
None ContentOrientation="None"
 VerticalScrollBarVisibility="Disabled"
HorizontalScrollBarVisibility="Disabled"

세로 레이아웃

기본적으로 스크롤 뷰어의 콘텐츠 레이아웃(방향)은 세로입니다.

이 예제에서는 ItemsRepeater 가 ScrollView의 Content.로 사용됩니다. ItemsRepeater에 대한 UniformGridLayout은 공간이 부족할 때까지(이 예제에서는 500px) 항목을 행에 가로로 배치한 다음 다음 행에 다음 항목을 배치합니다. ItemsRepeater는 사용자가 볼 수 있는 400px보다 크지만 사용자는 콘텐츠를 세로로 스크롤할 수 있습니다.

기본값 ContentOrientation 은 VerticalScrollView에서 변경이 필요하지 않습니다.

<ScrollView Width="500" Height="400">
    <ItemsRepeater ItemsSource="{x:Bind Albums}"
                   ItemTemplate="{StaticResource MyTemplate}">
        <ItemsRepeater.Layout>
            <UniformGridLayout RowSpacing="8" ColumnSpacing="8"/>
        </ItemsRepeater.Layout>
    </ItemsRepeater>
</ScrollView>

가로 레이아웃

이 예제에서 콘텐츠는 StackPanel 항목을 가로로 배치하는 것입니다. 스크롤 뷰어 구성이 가로 스크롤을 지원하고 세로 스크롤을 사용하지 않도록 변경됩니다.

ScrollView'의 ContentOrientation 속성은 콘텐츠가 필요한 만큼 가로로 증가할 수 있도록 설정 Horizontal 됩니다.

<ScrollView Width="500" Height="400" ContentOrientation="Horizontal">
    <StackPanel Orientation="Horizontal">
        <Button Width="200" Content="Button 1"/>
        <Button Width="200" Content="Button 2"/>
        <Button Width="200" Content="Button 3"/>
        <Button Width="200" Content="Button 4"/>
        <Button Width="200" Content="Button 5"/>
    </StackPanel>
</ScrollView>

프로그래밍 방식 스크롤

스크롤 뷰어의 오프셋 속성은 읽기 전용이지만 프로그래밍 방식으로 스크롤할 수 있는 메서드가 제공됩니다.

ScrollView 컨트롤의 경우 ScrollTo 메서드를 호출하고 스크롤할 가로 및 세로 오프셋을 전달합니다. 이 경우 스크롤은 세로이므로 현재 HorizontalOffset 값이 사용됩니다. 위쪽 으로 스크롤하려면 VerticalOffset 0이 사용됩니다. 아래쪽 VerticalOffset 으로 스크롤하려면 ScrollableHeight와 동일합니다.

<Button Content="Scroll to top" Click="ScrollTopButton_Click"/>
<Button Content="Scroll to bottom" Click="ScrollBottomButton_Click"/>
<ScrollView x:Name="scrollView" Width="500" Height="400">
    <StackPanel>
        <Button Width="200" Content="Button 1"/>
        <Button Width="200" Content="Button 2"/>
        <Button Width="200" Content="Button 3"/>
        <Button Width="200" Content="Button 4"/>
        <Button Width="200" Content="Button 5"/>
    </StackPanel>
</ScrollView>

private void ScrollTopButton_Click(object sender, RoutedEventArgs e)
{
    scrollView.ScrollTo(
        horizontalOffset: scrollView.HorizontalOffset,
        verticalOffset: 0);
}

private void ScrollBottomButton_Click(object sender, RoutedEventArgs e)
{
    scrollView.ScrollTo(
        horizontalOffset: scrollView.HorizontalOffset,
        verticalOffset: scrollView.ScrollableHeight);
}

또한 ScrollView는 현재 오프셋에서 지정된 델타로 세로 또는 가로로 스크롤할 수 있는 ScrollBy 메서드를 제공합니다.

확대/축소

스크롤 뷰어를 사용하여 사용자가 콘텐츠를 광학적으로 확대 및 축소할 수 있습니다. 광학 확대/축소 조작은 손가락 모으기 및 스트레치 제스처를 통해 수행됩니다(손가락을 더 멀리 이동하고 확대하여 더 가깝게 이동)하거나 마우스 스크롤 휠을 스크롤하는 동안 Ctrl 키를 눌러 수행합니다. 확대/축소에 대한 자세한 내용은 광학 확대/축소 및 크기 조정을 참조 하세요.

사용자 상호 작용에 따라 확대/축소를 ZoomMode 사용하도록 설정하려면 속성을 Enabled 기본적으로 Disabled 설정하세요. 속성에 대한 ZoomMode 변경 내용은 즉시 적용되며 진행 중인 사용자 상호 작용에 영향을 줄 수 있습니다.

이 예제에서는 확대/축소를 허용하도록 구성된 스크롤 뷰어에 래핑된 이미지를 보여줍니다.

<ScrollView Width="500" Height="400"
            ContentOrientation="Both"
            ZoomMode="Enabled">
    <Image Source="Assets/rainier.jpg"/>
</ScrollView>

이 경우 이미지는 스크롤 뷰어에 의해 제한되지 않으므로 처음에는 기본 크기로 표시됩니다. 이미지 원본이 뷰포트보다 큰 경우 사용자는 전체 이미지를 보려면 축소해야 합니다. 이는 의도된 동작이 아닐 수 있습니다.

A picture of a mountain zoomed in so far that only blue sky and clouds in the upper left of the picture are visible.

다음 예제에서는 뷰포트에 이미지를 제한하도록 스크롤 뷰어를 구성하는 방법을 보여 줍니다. 이렇게 하면 처음에 로드된 이미지가 축소되고 원하는 경우 사용자가 확대 및 스크롤할 수 있습니다.

A picture of a mountain zoomed out so that the foreground, mountain, and sky are all visible.

이미지를 ScrollView의 뷰포트로 제한하려면 ContentOrientation 속성을 None.로 설정합니다. 스크롤 막대 표시 유형은 이 제약 조건에 연결되지 않으므로 사용자가 확대할 때 스크롤 막대가 자동으로 표시됩니다.

<ScrollView Width="500" Height="400"
            ContentOrientation="None"
            ZoomMode="Enabled">
    <Image Source="Assets/rainier.jpg"/>
</ScrollView>

확대/축소 비율

MinZoomFactor 및 MaxZoomFactor 속성을 사용하여 사용자가 콘텐츠를 확대/축소할 수 있는 양을 제어합니다. 이러한 속성은 사용자 상호 작용 및 프로그래밍 방식 확대/축소 모두에 효과적입니다.

  • 기본값은 다음과 MinZoomFactor="0.1"같습니다. MaxZoomFactor="10.0"
<ScrollView Width="500" Height="400"
            ContentOrientation="Both"
            ZoomMode="Enabled" 
            MinZoomFactor="1.0" MaxZoomFactor="8.0">
    <Image Source="Assets/rainier.png"/>
</ScrollView>

프로그래밍 방식 확대/축소

이 ZoomFactor 속성은 읽기 전용이지만 프로그래밍 방식으로 확대/축소할 수 있도록 메서드가 제공됩니다. 일반적으로 스크롤 뷰어를 확대/축소 크기를 제어하는 슬라이더에 연결하거나 확대/축소 수준을 다시 설정하는 단추를 사용합니다. (확대/축소 슬라이더의 예를 보려면 WinUI 3 갤러리 앱의 ScrollViewer를 참조하세요.)

ScrollView 컨트롤의 경우 ZoomTo 메서드를 호출하고 새 확대/축소 요소를 첫 번째 매개 변수로 전달합니다.

<Slider Header="Zoom" IsEnabled="True"
        Maximum="{x:Bind scrollControl.MaxZoomFactor, Mode=OneWay}"
        Minimum="{x:Bind scrollControl.MinZoomFactor, Mode=OneWay}"
        StepFrequency="0.1"
        ValueChanged="ZoomSlider_ValueChanged" />
<ScrollView Width="500" Height="400"
            ContentOrientation="None"
            ZoomMode="Enabled">
    <Image Source="Assets/rainier.png"/>
</ScrollView>

private void ZoomSlider_ValueChanged(object sender, RangeBaseValueChangedEventArgs e)
{
    if (scrollControl != null)
    {
        scrollControl.ZoomTo(
            zoomFactor: (float)e.NewValue,
            centerPoint: null)
    }
}

또한 ScrollView는 현재 확대/축소 수준에서 지정된 델타로 확대 및 축소할 수 있는 ZoomBy 메서드를 제공합니다.

샘플 코드 가져오기