Back to Qt.io
Contact Us Blog Download Qt

ScrollBar QML Type

垂直或水平交互式滚动条。更多

Import Statement: import QtQuick.Controls
Inherits:

Control

属性

附属物业

方法

详细说明

ScrollBar 是一个交互式滚动条，可用于滚动到特定位置。滚动条可以是vertical 或horizontal ，也可以附加到任何Flickable 上，如ListView 和GridView 。它还可以与ScrollView 一起使用。

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

将滚动条附加到可闪烁页面

将 ScrollBar 附加到 Flickablevertically 或horizontally 时，会自动设置和更新其几何形状和以下属性：

附加的 ScrollBar 会将自身重新导向目标 Flickable。垂直附加的 ScrollBar 会根据 Flickable 的高度调整自身大小，并根据layout direction 将自身定位在其两侧。水平附加的 ScrollBar 会根据 Flickable 的宽度调整自身大小，并将自身定位在底部。通过为附加的 ScrollBar 指定另一个父级，可以禁用自动几何管理。例如，如果要将 ScrollBar 放置在剪切 Flickable 外，这就非常有用。下面的示例演示了这一点：

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

请注意，ScrollBar 不会过滤其所连接的 Flickable 的按键事件。下面的示例说明了如何使用上下键实现滚动：

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,Customizing ScrollBar 和Indicator Controls。

属性文档

active : bool

该属性用于确定滚动条是否处于活动状态，即当pressed 或附加的 Flickable 为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 相似。该属性对于在典型的鼠标和触摸导向用户界面之间切换交互式和非交互式滚动条非常有用。

该属性在 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

该属性保存滚动条的方向。

可能的值：

常量说明
Qt.Horizontal水平
Qt.Vertical垂直（默认）

该属性在滚动条为attached to a flickable 时自动设置。

另请参阅 horizontal 和vertical 。


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

该属性用于保存滚动条的策略。默认策略为ScrollBar.AsNeeded 。

可能的值：

常量说明
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) 。在最常用的情况下，将滚动条移动到末端会使文档末端位于所连接的 Flickable 可视区域的下端，而这一操作是正确的。

当滚动条为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)]

该属性用于设置抓取模式。

可能的值：

常量说明
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.1 （如果stepSize 是0.0 ）减少位置。

另请参见 stepSize 。


void increase()

通过stepSize 或0.1 （如果stepSize 是0.0 ）增加位置。

另请参见 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.