滚动条 QML 类型

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

导入语句	import QtQuick.Controls
继承	Control

包括继承成员的所有成员列表

属性

active : bool
horizontal : bool (自 QtQuick.Controls 2.3 (Qt 5.10) 起有效)
interactive : bool (自 QtQuick.Controls 2.2 (Qt 5.9) 起有效)
minimumSize : real (自 QtQuick.Controls 2.4 (Qt 5.11) 起有效)
orientation : 枚举
policy : 枚举 (自 QtQuick.Controls 2.2 (Qt 5.9) 起有效)
position : real
pressed : bool
size : real
snapMode : 枚举 (自 QtQuick.Controls 2.2 (Qt 5.9) 起有效)
stepSize : real
vertical : bool (自 QtQuick.Controls 2.3 (Qt 5.10) 起有效)
visualPosition : real (自 QtQuick.Controls 2.4 (Qt 5.11) 起有效)
visualSize : real (自 QtQuick.Controls 2.4 (Qt 5.11) 起有效)

附加属性

horizontal : ScrollBar
vertical : ScrollBar

方法

void decrease()
void increase()

详细描述

滚动条是一种交互式栏，可以用于滚动到特定位置。滚动条可以是垂直的或水平居中，可以附加到任何可滚动的组件，例如ListView和GridView，还可以与ScrollView一起使用。

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

将滚动条附加到Flickable

当滚动条垂直或水平附加到Flickable上时，其几何形状和下列属性会自动设置并更新

附加的滚动条会将其自身重新定位到目标Flickable。垂直附加的滚动条会调整其大小以匹配Flickable的高度，并根据布局方向将其定位在其两侧。水平附加的滚动条会调整其大小以匹配Flickable的宽度，并位于其底部。可以通过指定另一个父级来禁用自动几何形状管理。例如，如果滚动条需要放置在剪裁Flickable之外，这会很有用。以下示例演示了这一点：

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

请注意，滚动条不会过滤其附加的Flickable的关键事件。以下示例说明了如何使用上下键实现滚动

Flickable {
    focus: true

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

    ScrollBar.vertical: ScrollBar { id: scrollBar }
}

绑定水平和垂直滚动条的活动状态

默认情况下，水平和垂直滚动条不共享活动状态。为了在向任何方向滚动时保持两个条都可见，可以建立活动状态之间的双向绑定，如下例所示

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的情况下创建滚动条的实例。当附加滚动条的行为不足以满足需求或未使用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或锚点属性，例如）。
将大小和位置属性设置为确定滚动条相对于滚动项的大小和位置。
设置活动属性以确定滚动条何时可见。

另请参阅 ScrollIndicator、ScrollView、自定义滚动条和指示控件。

属性文档

活动 : 布尔值

该属性存储滚动条是否被激活，即当它被按下或者附加的Flickable正在移动时。

可以在滚动时同时保持水平和垂直滚动条可见。

该属性在滚动条附加到可摇动控件上时自动设置。

horizontal : bool [只读，自 QtQuick.Controls 2.3 (Qt 5.10) 开始]

该属性表示是否为水平滚动条。

该属性从 QtQuick.Controls 2.3 (Qt 5.10) 开始引入。

另请参阅orientation。

interactive : bool [自 QtQuick.Controls 2.2 (Qt 5.9) 开始]

该属性表示滚动条是否可交互。默认值是 true。

非交互式的滚动条在外观和行为上与 ScrollIndicator 相似。此属性可以用于在交互式和非交互式滚动条之间切换，从而实现鼠标和触摸操作系统界面。

该属性从 QtQuick.Controls 2.2 (Qt 5.9) 开始引入。

minimumSize : real [自 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`	垂直方向 (默认)

该属性在滚动条附加到可摇动控件上时自动设置。

另请参阅horizontal 和 vertical。

policy : enumeration [自 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::visibleArea 和 visualPosition。

pressed : bool

此属性表示是否按下了滚动条。

size : real

此属性表示滚动条的尺寸，已缩放至 0.0 - 1.0。

该属性在滚动条附加到可摇动控件上时自动设置。

另请参阅 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 { }
}

另请参阅 将 ScrollBar 附加到 Flickable。

ScrollBar.vertical : ScrollBar

此属性在 Flickable 中附加一个垂直滚动条。

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

另请参阅 将 ScrollBar 附加到 Flickable。

方法文档

void decrease()

通过 stepSize 或 0.1 减少位置，如果 stepSize 是 0.0，则按 0.1 减少位置。

另请参阅 stepSize。

void increase()

通过步进大小或 0.1 增加位置，如果步进大小是 0.0。

另请参阅 stepSize。