Back to Qt.io
Contact Us Blog Download Qt

ScrollIndicator QML Type

垂直或水平非交互式滚动指示器。更多

Import Statement: import QtQuick.Controls
Inherits:

Control

属性

附属物业

详细说明

ScrollIndicator 是一个非交互式指示器，用于指示当前滚动位置。滚动指示器可以是vertical 或horizontal ，也可以附加到任何Flickable 上，如ListView 和GridView 。

Flickable {
    // ...
    ScrollIndicator.vertical: ScrollIndicator { }
}

将 ScrollIndicator 附加到可弹动窗口

注： 将 ScrollIndicator 附加到 Flickable 的vertically 或horizontally 时，其几何形状和以下属性会自动设置并根据情况更新：

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

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

绑定水平和垂直滚动指示器的活动状态

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

Flickable {
    anchors.fill: parent

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

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

非绑定滚动指示器

不使用附加属性 API 也可以创建 ScrollIndicator 的实例。当附加滚动指示器的行为不够充分或未使用Flickable 时，这种方法非常有用。在下面的示例中，水平和垂直滚动指示器用于显示用户滚动文本的距离（使用MouseArea 代替Flickable ）：

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

    Text {
        id: content
        text: "ABC"
        font.pixelSize: 169

        MouseArea {
            id: mouseArea
            drag.target: content
            drag.minimumX: frame.width - width
            drag.minimumY: frame.height - height
            drag.maximumX: 0
            drag.maximumY: 0
            anchors.fill: content
        }
    }

    ScrollIndicator {
        id: verticalIndicator
        active: mouseArea.pressed
        orientation: Qt.Vertical
        size: frame.height / content.height
        position: -content.y / content.height
        anchors { top: parent.top; right: parent.right; bottom: parent.bottom }
    }

    ScrollIndicator {
        id: horizontalIndicator
        active: mouseArea.pressed
        orientation: Qt.Horizontal
        size: frame.width / content.width
        position: -content.x / content.width
        anchors { left: parent.left; right: parent.right; bottom: parent.bottom }
    }
}

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

属性文档

active : bool

该属性表示指示器是否处于活动状态，即当附加的 Flickable 为moving 时。

可以在向任一方向滚动时保持both horizontal and vertical indicators 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 。


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 。


position : real

该属性用于保存指示器的位置，缩放比例为0.0 - 1.0 。

当滚动指标为attached to a flickable 时，该属性将自动设置。

另请参见 Flickable::visibleArea 和visualPosition 。


size : real

该属性表示指标的大小，按比例缩放至0.0 - 1.0 。

当滚动指标为attached to a flickable 时，该属性将自动设置。

另请参阅 Flickable::visibleArea,minimumSize, 和visualSize 。


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

该属性表示滚动条是否垂直。

该属性在 QtQuick.Controls 2.3 (Qt 5.10) 中引入。

另请参阅 orientation 。


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

该属性保存指示器的有效视觉位置，该位置可能受限于minimum size 。

该属性在 QtQuick.Controls 2.4 (Qt 5.11) 中引入。

另请参阅 position 和minimumSize 。


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

该属性保留了指示器的有效可视化尺寸，该尺寸可能受到minimum size 的限制。

该属性在 QtQuick.Controls 2.4 (Qt 5.11) 中引入。

另请参阅 size 和minimumSize 。


附加属性文档

ScrollIndicator.horizontal : ScrollIndicator

该属性将水平滚动指示器附加到Flickable 。

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

另请参阅 Attaching ScrollIndicator to a Flickable 。


ScrollIndicator.vertical : ScrollIndicator

该属性将垂直滚动指示器附加到Flickable 。

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

另请参见 Attaching ScrollIndicator to a Flickable 。


© 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.