Back to Qt.io
Contact Us Blog Download Qt

ScrollBar QML Type

세로 또는 가로 대화형 스크롤 막대. 더 보기...

Import Statement: import QtQuick.Controls
Inherits:

Control

속성

첨부 속성

방법

상세 설명

스크롤바는 특정 위치로 스크롤하는 데 사용할 수 있는 대화형 바입니다. 스크롤 막대는 vertical 또는 horizontal 일 수 있으며, ListView 및 GridView 와 같은 Flickable 에 첨부할 수 있습니다. 또한 ScrollView 와 함께 사용할 수도 있습니다.

Flickable {
    // ...
    ScrollBar.vertical: ScrollBar { }
}

스크롤바를 플릭커블에 부착하기

ScrollBar를 vertically 또는 horizontally 플릭커블에 부착하면 지오메트리와 다음 프로퍼티가 자동으로 설정되고 적절하게 업데이트됩니다:

부착된 스크롤바는 대상 플릭커블에 다시 부모가 됩니다. 세로로 부착된 스크롤바는 플릭커블의 높이에 맞게 크기가 조정되고 layout direction 을 기준으로 양쪽에 위치하며, 가로로 부착된 스크롤바는 플릭커블의 폭에 맞게 크기가 조정되고 아래쪽에 위치합니다. 첨부된 스크롤바에 다른 부모를 지정하여 자동 지오메트리 관리를 비활성화할 수 있습니다. 이 기능은 예를 들어 스크롤바를 클리핑 플릭커블 외부에 배치해야 하는 경우에 유용할 수 있습니다. 다음 예시를 통해 이를 확인할 수 있습니다:

Flickable {
    id: flickable
    clip: true
    // ...
    ScrollBar.vertical: ScrollBar {
        parent: flickable.parent
        anchors.top: flickable.top
        anchors.left: flickable.right
        anchors.bottom: flickable.bottom
    }
}

스크롤바는 연결된 플릭커블의 주요 이벤트를 필터링하지 않는다는 것을 알 수 있습니다. 다음 예시는 위쪽 및 아래쪽 키로 스크롤을 구현하는 방법을 보여줍니다:

Flickable {
    focus: true

    Keys.onUpPressed: scrollBar.decrease()
    Keys.onDownPressed: scrollBar.increase()

    ScrollBar.vertical: ScrollBar { id: scrollBar }
}

가로 및 세로 스크롤 막대의 활성 상태 바인딩하기

가로 및 세로 스크롤 막대는 기본적으로 active 상태를 서로 공유하지 않습니다. 어느 한 방향으로 스크롤하는 동안 두 막대를 모두 표시하려면 다음 예시와 같이 활성 상태 간에 양방향 바인딩을 설정하세요:

Flickable {
    anchors.fill: parent

    contentWidth: parent.width * 2
    contentHeight: parent.height * 2

    ScrollBar.horizontal: ScrollBar { id: hbar; active: vbar.active }
    ScrollBar.vertical: ScrollBar { id: vbar; active: hbar.active }
}

연결되지 않은 스크롤 막대

연결된 속성 API를 사용하지 않고도 ScrollBar의 인스턴스를 만들 수 있습니다. 이는 첨부된 스크롤 막대의 동작이 충분하지 않거나 Flickable 이 사용되지 않을 때 유용합니다. 다음 예에서는 Flickable 을 사용하지 않고 가로 및 세로 스크롤 막대를 사용하여 텍스트를 스크롤합니다:

Rectangle {
    id: frame
    clip: true
    width: 160
    height: 160
    border.color: "black"
    anchors.centerIn: parent

    Text {
        id: content
        text: "ABC"
        font.pixelSize: 160
        x: -hbar.position * width
        y: -vbar.position * height
    }

    ScrollBar {
        id: vbar
        hoverEnabled: true
        active: hovered || pressed
        orientation: Qt.Vertical
        size: frame.height / content.height
        anchors.top: parent.top
        anchors.right: parent.right
        anchors.bottom: parent.bottom
    }

    ScrollBar {
        id: hbar
        hoverEnabled: true
        active: hovered || pressed
        orientation: Qt.Horizontal
        size: frame.width / content.width
        anchors.left: parent.left
        anchors.right: parent.right
        anchors.bottom: parent.bottom
    }
}

첨부되지 않은 스크롤바를 사용하는 경우 다음을 수동으로 수행해야 합니다:

  • 스크롤 막대를 레이아웃합니다(예: x 및 y 또는 anchors 속성 사용).
  • size 및 position 속성을 설정하여 스크롤된 항목과 관련된 스크롤 막대의 크기와 위치를 결정합니다.
  • active 속성을 설정하여 스크롤 막대가 표시되는 시기를 결정합니다.

ScrollIndicator, ScrollView, 스크롤 막대 사용자 지정하기 및 표시기 컨트롤을참조하세요 .

속성 문서

active : bool

이 속성은 스크롤 막대가 활성화되어 있는지 여부(예: pressed 또는 연결된 플릭 가능이 moving 인 경우)를 보유합니다.

어느 방향으로 스크롤하는 동안 both horizontal and vertical bars visible 을 유지할 수 있습니다.

이 속성은 스크롤 막대가 attached to a flickable 일 때 자동으로 설정됩니다.


horizontal : bool [read-only, since QtQuick.Controls 2.3 (Qt 5.10)]

이 속성은 스크롤 막대가 수평인지 여부를 보유합니다.

이 프로퍼티는 QtQuick.Controls 2.3(Qt 5.10)에서 도입되었습니다.

orientation 를참조하십시오 .


interactive : bool [since QtQuick.Controls 2.2 (Qt 5.9)]

이 속성은 스크롤 막대가 대화형인지 여부를 저장합니다. 기본값은 true 입니다.

비대화형 스크롤 막대는 ScrollIndicator 와 시각적 및 동작적으로 유사합니다. 이 속성은 각각 대화형 및 비대화형 스크롤 막대가 있는 일반적인 마우스 및 터치 지향 UI를 전환하는 데 유용합니다.

이 프로퍼티는 QtQuick.Controls 2.2(Qt 5.9)에 도입되었습니다.


minimumSize : real [since QtQuick.Controls 2.4 (Qt 5.11)]

이 프로퍼티는 스크롤 막대의 최소 크기를 0.0 - 1.0 로 스케일링합니다.

이 프로퍼티는 QtQuick.Controls 2.4 (Qt 5.11)에 도입되었습니다.

size, visualSize, visualPosition 를참조하십시오 .


orientation : enumeration

이 속성은 스크롤 막대의 방향을 유지합니다.

가능한 값은 다음과 같습니다:

Constant설명
Qt.HorizontalHorizontal
Qt.Vertical세로(기본값)

이 속성은 스크롤 막대가 attached to a flickable 일 때 자동으로 설정됩니다.

horizontal 및 vertical 을참조하세요 .


policy : enumeration [since QtQuick.Controls 2.2 (Qt 5.9)]

이 속성은 스크롤 막대의 정책을 보유합니다. 기본 정책은 ScrollBar.AsNeeded 입니다.

사용 가능한 값

Constant설명
ScrollBar.AsNeeded스크롤 막대는 콘텐츠가 너무 커서 맞지 않을 때만 표시됩니다.
ScrollBar.AlwaysOff스크롤 막대는 표시되지 않습니다.
ScrollBar.AlwaysOn스크롤 막대는 항상 표시됩니다.

다음 예제에서는 세로 스크롤 막대를 항상 표시합니다:

Flickable {
    contentHeight: 2000
    ScrollBar.vertical: ScrollBar {
        policy: ScrollBar.AlwaysOn
    }
}

스타일은 이 속성을 active 속성과 함께 사용하여 일시적인 스크롤 막대를 구현할 수 있습니다. 일시적 스크롤 막대는 마지막 상호 작용 이벤트(마우스오버 또는 누름) 직후에 숨겨집니다. 이는 일반적으로 스크롤 막대의 불투명도를 애니메이션하여 수행됩니다. 이 동작을 재정의하려면 보기에 비해 콘텐츠의 크기에 따라 정책을 ScrollBar.AlwaysOn 또는 ScrollBar.AlwaysOff 으로 설정합니다. 예를 들어 세로형 ListView 입니다:

policy: listView.contentHeight > listView.height ? ScrollBar.AlwaysOn : ScrollBar.AlwaysOff

이 프로퍼티는 QtQuick.Controls 2.2(Qt 5.9)에 도입되었습니다.


position : real

이 속성은 0.0 - 1.0 로 스케일링된 스크롤 막대의 위치를 유지합니다.

가장 큰 유효한 스크롤바 위치는 (1.0 - size) 입니다. 이렇게 하면 스크롤바를 끝까지 이동하면 문서의 끝이 연결된 플릭 가능 영역의 보이는 영역 하단에 위치하는 가장 많이 사용되는 경우에 올바른 동작을 제공합니다.

이 속성은 스크롤 막대가 attached to a flickable 일 때 자동으로 설정됩니다.

Flickable::visibleArea 및 visualPosition 을참조하세요 .


pressed : bool

이 속성은 스크롤 막대가 눌렸는지 여부를 보유합니다.


size : real

이 속성은 스크롤 막대의 크기를 0.0 - 1.0 로 스케일링합니다.

이 속성은 스크롤 막대가 attached to a flickable 일 때 자동으로 설정됩니다.

Flickable::visibleArea, minimumSize, visualSize 를참조하세요 .


snapMode : enumeration [since QtQuick.Controls 2.2 (Qt 5.9)]

이 속성은 스냅 모드를 유지합니다.

가능한 값은 다음과 같습니다:

Constant설명
ScrollBar.NoSnap스크롤바가 스냅되지 않습니다(기본값).
ScrollBar.SnapAlways스크롤바를 드래그하는 동안 스크롤바가 스냅됩니다.
ScrollBar.SnapOnRelease드래그하는 동안에는 스크롤바가 스냅되지 않고, 드래그에서 손을 뗀 후에만 스냅됩니다.

다음 표에서는 다양한 모드를 애니메이션으로 설명합니다. 움직임과 stepSize (0.25)은 각 애니메이션에서 동일합니다.
값예제
ScrollBar.NoSnap

ScrollBar.SnapAlways

ScrollBar.SnapOnRelease

이 프로퍼티는 QtQuick.Controls 2.2(Qt 5.9)에 도입되었습니다.

stepSize 를참조하십시오 .


stepSize : real

이 속성은 스텝 크기를 보유합니다. 기본값은 0.0 입니다.

snapMode, increase() 및 decrease()도 참조하십시오 .


vertical : bool [read-only, since QtQuick.Controls 2.3 (Qt 5.10)]

이 속성은 스크롤 막대가 세로인지 여부를 저장합니다.

이 프로퍼티는 QtQuick.Controls 2.3(Qt 5.10)에 도입되었습니다.

orientation 를참조하십시오 .


visualPosition : real [read-only, since QtQuick.Controls 2.4 (Qt 5.11)]

이 속성은 minimum size 에 의해 제한될 수 있는 스크롤 막대의 유효 시각적 위치를 보유합니다.

이 프로퍼티는 QtQuick.Controls 2.4 (Qt 5.11)에 도입되었습니다.

position 와 minimumSize 를참조하십시오 .


visualSize : real [read-only, since QtQuick.Controls 2.4 (Qt 5.11)]

이 프로퍼티는 스크롤 막대의 유효 시각적 크기를 보유하며, minimum size 에 의해 제한될 수 있습니다.

이 프로퍼티는 QtQuick.Controls 2.4 (Qt 5.11)에 도입되었습니다.

size 와 minimumSize 를참조하십시오 .


첨부된 속성 문서

ScrollBar.horizontal : ScrollBar

이 프로퍼티는 Flickable 에 가로 스크롤 바를 첨부합니다.

Flickable {
    contentWidth: 2000
    ScrollBar.horizontal: ScrollBar { }
}

Attaching ScrollBar to a Flickable도 참조하십시오 .


ScrollBar.vertical : ScrollBar

이 프로퍼티는 Flickable 에 세로 스크롤 바를 첨부합니다.

Flickable {
    contentHeight: 2000
    ScrollBar.vertical: ScrollBar { }
}

Attaching ScrollBar to a Flickable도 참조하십시오 .


메서드 문서

void decrease()

stepSize 이 0.0 인 경우 stepSize 또는 0.1 만큼 위치를 줄입니다.

stepSize참조 .


void increase()

stepSize 이 0.0 인 경우 stepSize 또는 0.1 으로 위치를 늘립니다.

stepSize도 참조하세요 .


© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.