Back to Qt.io
Contact Us Blog Download Qt

ScrollBar QML Type

Vertikale oder horizontale interaktive Bildlaufleiste. Mehr...

Import Statement: import QtQuick.Controls
Inherits:

Control

Eigenschaften

Beigefügte Eigenschaften

Methoden

Detaillierte Beschreibung

ScrollBar ist eine interaktive Leiste, mit der man zu einer bestimmten Position blättern kann. Eine Bildlaufleiste kann entweder vertical oder horizontal sein und kann mit jedem Flickable verbunden werden, wie ListView und GridView. Sie kann auch mit ScrollView verwendet werden.

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

Anhängen von ScrollBar an ein Flickable

Wenn ScrollBar vertically oder horizontally an ein Flickable angehängt wird, werden seine Geometrie und die folgenden Eigenschaften automatisch eingestellt und entsprechend aktualisiert:

Eine angehängte ScrollBar wird erneut an das Ziel-Flickable angehängt. Eine vertikal angehängte ScrollBar passt ihre Größe an die Höhe des Flickable an und positioniert sich auf der Grundlage von layout direction auf beiden Seiten des Flickable. Eine horizontal angehängte ScrollBar passt ihre Größe an die Breite des Flickable an und positioniert sich am unteren Rand. Die automatische Geometrieverwaltung kann deaktiviert werden, indem ein anderes übergeordnetes Element für die angehängte ScrollBar angegeben wird. Dies kann z.B. nützlich sein, wenn die ScrollBar außerhalb eines Clipping Flickable platziert werden soll. Dies wird durch das folgende Beispiel veranschaulicht:

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

Beachten Sie, dass ScrollBar keine Tastenereignisse des Flickable filtert, an das es angehängt ist. Das folgende Beispiel veranschaulicht, wie man das Scrollen mit Auf- und Ab-Tasten implementiert:

Flickable {
    focus: true

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

    ScrollBar.vertical: ScrollBar { id: scrollBar }
}

Binden des aktiven Zustands von horizontalen und vertikalen Bildlaufleisten

Horizontale und vertikale Bildlaufleisten teilen standardmäßig nicht den Status active miteinander. Um beide Leisten beim Scrollen in eine der beiden Richtungen sichtbar zu halten, müssen Sie eine wechselseitige Bindung zwischen den aktiven Zuständen herstellen, wie im folgenden Beispiel dargestellt:

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 }
}

Nicht verbundene Bildlaufleisten

Es ist möglich, eine Instanz von ScrollBar zu erstellen, ohne die API für angehängte Eigenschaften zu verwenden. Dies ist nützlich, wenn das Verhalten der angehängten Bildlaufleiste nicht ausreicht oder eine Flickable nicht verwendet wird. Im folgenden Beispiel werden horizontale und vertikale Bildlaufleisten verwendet, um über den Text zu blättern, ohne Flickable zu verwenden:

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
    }
}

Bei der Verwendung einer nicht angehängten Bildlaufleiste muss Folgendes von Hand gemacht werden:

  • Layouten Sie die Bildlaufleiste (z. B. mit den Eigenschaften x und y oder anchors ).
  • Legen Sie die Eigenschaften size und position fest, um die Größe und Position der Bildlaufleiste in Bezug auf das gescrollte Element zu bestimmen.
  • Legen Sie die Eigenschaft active fest, um zu bestimmen, wann die Bildlaufleiste sichtbar sein soll.

Siehe auch ScrollIndicator, ScrollView, ScrollBar anpassen und Indicator Controls.

Eigenschaft Dokumentation

active : bool

Diese Eigenschaft legt fest, ob die Bildlaufleiste aktiv ist, d.h. wenn sie pressed ist oder das angehängte Flickable moving ist.

Es ist möglich, both horizontal and vertical bars visible beim Scrollen in beide Richtungen beizubehalten.

Diese Eigenschaft wird automatisch gesetzt, wenn die Bildlaufleiste attached to a flickable ist.


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

Diese Eigenschaft gibt an, ob die Bildlaufleiste horizontal ist.

Diese Eigenschaft wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

Siehe auch orientation.


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

Diese Eigenschaft gibt an, ob die Bildlaufleiste interaktiv ist. Der Standardwert ist true.

Eine nicht-interaktive Bildlaufleiste ist visuell und vom Verhalten her ähnlich wie ScrollIndicator. Diese Eigenschaft ist nützlich, um zwischen typischen maus- und berührungsorientierten UIs mit interaktiven bzw. nicht-interaktiven Bildlaufleisten zu wechseln.

Diese Eigenschaft wurde in QtQuick.Controls 2.2 (Qt 5.9) eingeführt.


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

Diese Eigenschaft enthält die minimale Größe der Bildlaufleiste, skaliert auf 0.0 - 1.0.

Diese Eigenschaft wurde in QtQuick.Controls 2.4 (Qt 5.11) eingeführt.

Siehe auch size, visualSize, und visualPosition.


orientation : enumeration

Diese Eigenschaft legt die Ausrichtung der Bildlaufleiste fest.

Mögliche Werte:

KonstantBeschreibung
Qt.HorizontalHorizontal
Qt.VerticalVertikal (Standard)

Diese Eigenschaft wird automatisch gesetzt, wenn die Bildlaufleiste attached to a flickable ist.

Siehe auch horizontal und vertical.


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

Diese Eigenschaft enthält die Richtlinie für die Bildlaufleiste. Die Standardeinstellung ist ScrollBar.AsNeeded.

Mögliche Werte:

KonstantBeschreibung
ScrollBar.AsNeededDie Bildlaufleiste wird nur angezeigt, wenn der Inhalt zu groß ist, um hineinzupassen.
ScrollBar.AlwaysOffDie Bildlaufleiste wird nie angezeigt.
ScrollBar.AlwaysOnDie Bildlaufleiste wird immer eingeblendet.

Im folgenden Beispiel ist die vertikale Bildlaufleiste immer sichtbar:

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

Stile können diese Eigenschaft in Kombination mit der Eigenschaft active verwenden, um transiente Bildlaufleisten zu implementieren. Transiente Bildlaufleisten werden kurz nach dem letzten Interaktionsereignis (Hover oder Press) ausgeblendet. Dies geschieht in der Regel durch Animieren der Deckkraft der Bildlaufleiste. Um dieses Verhalten außer Kraft zu setzen, setzen Sie die Richtlinie auf ScrollBar.AlwaysOn oder ScrollBar.AlwaysOff, abhängig von der Größe des Inhalts im Vergleich zu seiner Ansicht. Zum Beispiel für eine vertikale ListView:

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

Diese Eigenschaft wurde in QtQuick.Controls 2.2 (Qt 5.9) eingeführt.


position : real

Diese Eigenschaft enthält die Position der Bildlaufleiste, skaliert auf 0.0 - 1.0.

Die größte gültige Scrollbar-Position ist (1.0 - size). Dies führt zu einem korrekten Verhalten für den am häufigsten verwendeten Fall, in dem das Ende des Dokuments am unteren Ende des sichtbaren Bereichs des verbundenen Flickable liegt, wenn der Scrollbalken zum Ende bewegt wird.

Diese Eigenschaft wird automatisch gesetzt, wenn die Bildlaufleiste attached to a flickable ist.

Siehe auch Flickable::visibleArea und visualPosition.


pressed : bool

Diese Eigenschaft gibt an, ob die Bildlaufleiste gedrückt ist.


size : real

Diese Eigenschaft enthält die Größe der Bildlaufleiste, skaliert auf 0.0 - 1.0.

Diese Eigenschaft wird automatisch gesetzt, wenn die Bildlaufleiste auf attached to a flickable steht.

Siehe auch Flickable::visibleArea, minimumSize, und visualSize.


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

Diese Eigenschaft gibt den Fangmodus an.

Mögliche Werte:

KonstantBeschreibung
ScrollBar.NoSnapDie Bildlaufleiste rastet nicht ein (Standard).
ScrollBar.SnapAlwaysDer Rollbalken rastet beim Ziehen ein.
ScrollBar.SnapOnReleaseDer Rollbalken rastet nicht ein, während er gezogen wird, sondern erst nach dem Loslassen.

In der folgenden Tabelle sind die verschiedenen Modi mit Animationen dargestellt. Die Bewegung und die stepSize (0.25) sind in jeder Animation identisch.
WertBeispiel
ScrollBar.NoSnap

ScrollBar.SnapAlways

ScrollBar.SnapOnRelease

Diese Eigenschaft wurde in QtQuick.Controls 2.2 (Qt 5.9) eingeführt.

Siehe auch stepSize.


stepSize : real

Diese Eigenschaft enthält die Schrittgröße. Der Standardwert ist 0.0.

Siehe auch snapMode, increase(), und decrease().


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

Diese Eigenschaft gibt an, ob die Bildlaufleiste vertikal ist.

Diese Eigenschaft wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

Siehe auch orientation.


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

Diese Eigenschaft enthält die effektive visuelle Position der Bildlaufleiste, die durch die minimum size begrenzt werden kann.

Diese Eigenschaft wurde in QtQuick.Controls 2.4 (Qt 5.11) eingeführt.

Siehe auch position und minimumSize.


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

Diese Eigenschaft enthält die effektive visuelle Größe der Bildlaufleiste, die durch die minimum size begrenzt werden kann.

Diese Eigenschaft wurde in QtQuick.Controls 2.4 (Qt 5.11) eingeführt.

Siehe auch size und minimumSize.


Dokumentation der Eigenschaft Attached

ScrollBar.horizontal : ScrollBar

Diese Eigenschaft fügt eine horizontale Bildlaufleiste an ein Flickable an.

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

Siehe auch Attaching ScrollBar to a Flickable.


ScrollBar.vertical : ScrollBar

Diese Eigenschaft fügt eine vertikale Bildlaufleiste an ein Flickable an.

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

Siehe auch Attaching ScrollBar to a Flickable.


Methode Dokumentation

void decrease()

Verringert die Position um stepSize oder 0.1, wenn stepSize gleich 0.0 ist.

Siehe auch stepSize.


void erhöhen()

Erhöht die Position um stepSize oder 0.1, wenn stepSize gleich 0.0 ist.

Siehe auch 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.