ScrollBar QML Type

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

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

属性

• active : bool
• horizontal : bool (since QtQuick.Controls 2.3 (Qt 5.10))
• interactive : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• minimumSize : real (since QtQuick.Controls 2.4 (Qt 5.11))
• orientation : enumeration
• policy : enumeration (since QtQuick.Controls 2.2 (Qt 5.9))
• position : real
• pressed : bool
• size : real
• snapMode : enumeration (since QtQuick.Controls 2.2 (Qt 5.9))
• stepSize : real
• vertical : bool (since QtQuick.Controls 2.3 (Qt 5.10))
• visualPosition : real (since QtQuick.Controls 2.4 (Qt 5.11))
• visualSize : real (since QtQuick.Controls 2.4 (Qt 5.11))

关联属性

• horizontal : ScrollBar
• vertical : ScrollBar

方法

• void decrease()
• void increase()

详细说明

滚动条（ScrollBar）是一种交互式控件，可用于滚动至特定位置。滚动条可以是vertical 或horizontal ，并可附加到任何Flickable 上，例如ListView 和GridView 。它还可以与ScrollView 配合使用。

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

将 ScrollBar 附加到 Flickable 上

当将 ScrollBar 通过vertically 或horizontally 附加到 Flickable 时，其几何形状及以下属性会自动设置并适时更新：

• orientation
• position
• size
• active

已附加的 ScrollBar 会将自身重新归属于目标 Flickable。垂直附加的 ScrollBar 会根据 Flickable 的高度调整自身大小，并根据layout direction 定位在 Flickable 的任一侧。水平附加的 ScrollBar 会根据 Flickable 的宽度调整自身大小，并定位在 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
    }
}

使用非附加式 ScrollBar 时，必须手动完成以下操作：

• 布局滚动条（例如，通过x 、y 或anchors 属性）。
• 设置size 和position 属性，以确定滚动条相对于被滚动项的大小和位置。
• 设置active 属性以确定滚动条何时可见。

委托大小不一

委托对象大小的变化可能会导致在将新委托对象加载到视图时，ScrollBar 出现“跳动”现象。因此，建议使用大小一致的委托对象。有关详细信息，请参阅Variable Delegate Size and Section Labels 。

另请参阅 ScrollIndicator 、ScrollView 、自定义 ScrollBar 以及指示器控件。

属性文档

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

该属性用于指定滚动条的方向。

可能的取值：

当滚动条为attached to a flickable 时，此属性会自动设置。

另请参阅 horizontal 和vertical 。

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

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

可能的值：

以下示例使垂直滚动条始终可见：

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)]

该属性用于设置对齐模式。

可能的取值：

在下表中，通过动画演示了各种模式。每段动画中的移动方式和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 [attached]

此属性会在Flickable 上添加一个水平滚动条。

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

另请参阅 Attaching ScrollBar to a Flickable 。

ScrollBar.vertical : ScrollBar [attached]

此属性为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 。