ScrollBar QML Type
Barre de défilement interactive verticale ou horizontale. Plus d'informations...
| Import Statement: | import QtQuick.Controls |
| Inherits: |
Propriétés
- 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))
Propriétés rattachées
- horizontal : ScrollBar
- vertical : ScrollBar
Méthodes
Description détaillée
ScrollBar est une barre interactive qui peut être utilisée pour défiler jusqu'à une position spécifique. Une barre de défilement peut être vertical ou horizontal, et peut être attachée à n'importe quel Flickable, comme ListView et GridView. Elle peut également être utilisée avec ScrollView.
Flickable { // ... ScrollBar.vertical: ScrollBar { } }
Attacher une barre de défilement à un Flickable
Lorsqu'une barre de défilement est attachée vertically ou horizontally à un Flickable, sa géométrie et les propriétés suivantes sont automatiquement définies et mises à jour en fonction des besoins :
Une barre de défilement attachée se réoriente vers le Flickable cible. Une barre de défilement attachée verticalement se redimensionne à la hauteur du Flickable et se positionne d'un côté ou de l'autre de celui-ci en fonction de layout direction. Une barre de défilement attachée horizontalement se redimensionne à la largeur du Flickable et se positionne en bas. La gestion automatique de la géométrie peut être désactivée en spécifiant un autre parent pour la barre de défilement attachée. Cela peut s'avérer utile, par exemple, si la barre de défilement doit être placée en dehors d'un Flickable qui s'écrase. L'exemple suivant le démontre :
Flickable { id: flickable clip: true // ... ScrollBar.vertical: ScrollBar { parent: flickable.parent anchors.top: flickable.top anchors.left: flickable.right anchors.bottom: flickable.bottom } }
Remarquez que la barre de défilement ne filtre pas les événements de touche du Flickable auquel elle est attachée. L'exemple suivant illustre comment mettre en œuvre le défilement avec les touches haut et bas :
Flickable { focus: true Keys.onUpPressed: scrollBar.decrease() Keys.onDownPressed: scrollBar.increase() ScrollBar.vertical: ScrollBar { id: scrollBar } }
Lier l'état actif des barres de défilement horizontales et verticales
Par défaut, les barres de défilement horizontales et verticales ne partagent pas l'état active. Pour que les deux barres restent visibles lors d'un défilement dans l'une ou l'autre direction, il convient d'établir une liaison bidirectionnelle entre les états actifs, comme le montre l'exemple suivant :
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 } }
Barres de défilement non attachées
Il est possible de créer une instance de ScrollBar sans utiliser l'API des propriétés attachées. Cela est utile lorsque le comportement de la barre de défilement attachée n'est pas suffisant ou qu'une page Flickable n'est pas utilisée. Dans l'exemple suivant, des barres de défilement horizontales et verticales sont utilisées pour faire défiler le texte sans utiliser 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 } }

Lors de l'utilisation d'une barre de défilement non attachée, les opérations suivantes doivent être effectuées manuellement :
- Disposer la barre de défilement (avec les propriétés x et y ou anchors, par exemple).
- Définir les propriétés size et position pour déterminer la taille et la position de la barre de défilement par rapport à l'élément à faire défiler.
- La propriété active permet de déterminer quand la barre de défilement sera visible.
Variations de la taille des délégués
Des délégués de taille variable peuvent conduire la barre de défilement à "sauter" lorsque de nouveaux délégués sont chargés dans la vue. Pour cette raison, il est recommandé d'avoir des délégués de taille égale. Voir Variable Delegate Size and Section Labels pour plus d'informations.
Voir également ScrollIndicator, ScrollView, Personnaliser la barre de défilement et les contrôles d'indicateur.
Propriété Documentation
active : bool |
Cette propriété indique si la barre de défilement est active, c'est-à-dire si elle est pressed ou si le Flickable associé est moving.
Il est possible de conserver both horizontal and vertical bars visible tout en faisant défiler dans l'une ou l'autre direction.
Cette propriété est automatiquement définie lorsque la barre de défilement est attached to a flickable.
horizontal : bool |
Cette propriété indique si la barre de défilement est horizontale.
Cette propriété a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).
Voir également orientation.
interactive : bool |
Cette propriété indique si la barre de défilement est interactive. La valeur par défaut est true.
Une barre de défilement non interactive est visuellement et comportementalement similaire à ScrollIndicator. Cette propriété est utile pour passer d'une interface utilisateur typique orientée vers la souris à une interface orientée vers le toucher avec des barres de défilement interactives et non interactives, respectivement.
Cette propriété a été introduite dans QtQuick.Controls 2.2 (Qt 5.9).
minimumSize : real |
Cette propriété indique la taille minimale de la barre de défilement, mise à l'échelle sur 0.0 - 1.0.
Cette propriété a été introduite dans QtQuick.Controls 2.4 (Qt 5.11).
Voir aussi size, visualSize, et visualPosition.
orientation : enumeration |
Cette propriété définit l'orientation de la barre de défilement.
Valeurs possibles :
| Constante | Description |
|---|---|
Qt.Horizontal | Horizontale |
Qt.Vertical | Verticale (par défaut) |
Cette propriété est automatiquement définie lorsque la barre de défilement est attached to a flickable.
Voir également horizontal et vertical.
policy : enumeration |
Cette propriété définit la politique de la barre de défilement. La politique par défaut est ScrollBar.AsNeeded.
Valeurs possibles :
| Constant | Description |
|---|---|
ScrollBar.AsNeeded | La barre de défilement n'est affichée que lorsque le contenu est trop volumineux. |
ScrollBar.AlwaysOff | La barre de défilement n'est jamais affichée. |
ScrollBar.AlwaysOn | La barre de défilement est toujours affichée. |
Dans l'exemple suivant, la barre de défilement verticale est toujours visible :
Flickable { contentHeight: 2000 ScrollBar.vertical: ScrollBar { policy: ScrollBar.AlwaysOn } }
Les styles peuvent utiliser cette propriété en combinaison avec la propriété active afin d'implémenter des barres de défilement transitoires. Les barres de défilement transitoires sont masquées peu après le dernier événement d'interaction (survol ou pression). Pour ce faire, l'opacité de la barre de défilement est généralement animée. Pour remplacer ce comportement, définissez la politique sur ScrollBar.AlwaysOn ou ScrollBar.AlwaysOff, en fonction de la taille du contenu par rapport à sa vue. Par exemple, pour un contenu vertical ListView:
policy: listView.contentHeight > listView.height ? ScrollBar.AlwaysOn : ScrollBar.AlwaysOff
Cette propriété a été introduite dans QtQuick.Controls 2.2 (Qt 5.9).
position : real |
Cette propriété contient la position de la barre de défilement, mise à l'échelle sur 0.0 - 1.0.
La plus grande position valide de la barre de défilement est (1.0 - size). Cela permet d'obtenir un comportement correct dans le cas le plus fréquent où le déplacement de la barre de défilement jusqu'à la fin place la fin du document à l'extrémité inférieure de la zone visible du Flickable connecté.
Cette propriété est automatiquement définie lorsque la barre de défilement est attached to a flickable.
Voir également Flickable::visibleArea et visualPosition.
pressed : bool |
Cette propriété indique si la barre de défilement est enfoncée.
size : real |
Cette propriété indique la taille de la barre de défilement, mise à l'échelle sur 0.0 - 1.0.
Cette propriété est automatiquement définie lorsque la barre de défilement est attached to a flickable.
Voir également Flickable::visibleArea, minimumSize, et visualSize.
snapMode : enumeration |
Cette propriété définit le mode d'accrochage.
Valeurs possibles :
| Constant | Description : La barre de défilement ne s'enclenche pas (par défaut). |
|---|---|
ScrollBar.NoSnap | La barre de défilement ne s'accroche pas (valeur par défaut). |
ScrollBar.SnapAlways | La barre de défilement s'enclenche lorsqu'on la fait glisser. |
ScrollBar.SnapOnRelease | La barre de défilement ne s'enclenche pas lorsqu'on la fait glisser, mais seulement lorsqu'on la relâche. |
Dans le tableau suivant, les différents modes sont illustrés par des animations. Le mouvement et le site stepSize (0.25) sont identiques dans chaque animation.
| Valeur | Exemple |
ScrollBar.NoSnap | |
ScrollBar.SnapAlways | |
ScrollBar.SnapOnRelease |
Cette propriété a été introduite dans QtQuick.Controls 2.2 (Qt 5.9).
Voir également stepSize.
stepSize : real |
vertical : bool |
Cette propriété indique si la barre de défilement est verticale.
Cette propriété a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).
Voir également orientation.
visualPosition : real |
Cette propriété indique la position visuelle effective de la barre de défilement, qui peut être limitée par le site minimum size.
Cette propriété a été introduite dans QtQuick.Controls 2.4 (Qt 5.11).
Voir également position et minimumSize.
visualSize : real |
Cette propriété définit la taille visuelle effective de la barre de défilement, qui peut être limitée par le paramètre minimum size.
Cette propriété a été introduite dans QtQuick.Controls 2.4 (Qt 5.11).
Voir également size et minimumSize.
Documentation de la propriété Attached
ScrollBar.horizontal : ScrollBar |
Cette propriété permet d'attacher une barre de défilement horizontale à une page Flickable.
Flickable { contentWidth: 2000 ScrollBar.horizontal: ScrollBar { } }
Voir également Attaching ScrollBar to a Flickable.
ScrollBar.vertical : ScrollBar |
Cette propriété permet d'attacher une barre de défilement verticale à une page Flickable.
Flickable { contentHeight: 2000 ScrollBar.vertical: ScrollBar { } }
Voir aussi Attaching ScrollBar to a Flickable.
Méthode Documentation
© 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.