ScrollBar QML Type
Barra de desplazamiento interactiva vertical u horizontal. Más...
| Import Statement: | import QtQuick.Controls |
| Inherits: |
Propiedades
- 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))
Propiedades adjuntas
- horizontal : ScrollBar
- vertical : ScrollBar
Métodos
Descripción detallada
ScrollBar es una barra interactiva que se puede utilizar para desplazarse hasta una posición específica. Una barra de desplazamiento puede ser de tipo vertical o horizontal, y se puede asociar a cualquier Flickable, como ListView y GridView. También se puede utilizar con ScrollView.
Cómo asociar ScrollBar a un Flickable
Cuando se vincula un ScrollBar vertically o horizontally a un Flickable, su geometría y las siguientes propiedades se configuran y actualizan automáticamente según corresponda:
Una barra de desplazamiento adjunta se vincula al Flickable de destino. Una barra de desplazamiento adjunta verticalmente se redimensiona a la altura del Flickable y se coloca a uno de sus lados en función de layout direction. Una barra de desplazamiento adjunta horizontalmente se redimensiona al ancho del Flickable y se coloca en la parte inferior. La gestión automática de la geometría se puede desactivar especificando otro elemento padre para la barra de desplazamiento adjunta. Esto puede resultar útil, por ejemplo, si la barra de desplazamiento debe colocarse fuera de un `Flickable` de recorte. Así se ilustra en el siguiente ejemplo:
Flickable {
id: flickable
clip: true
// ...
ScrollBar.vertical: ScrollBar {
parent: flickable.parent
anchors.top: flickable.top
anchors.left: flickable.right
anchors.bottom: flickable.bottom
}
}Ten en cuenta que la barra de desplazamiento (ScrollBar) no filtra los eventos de teclas del Flickable al que está asociada. El siguiente ejemplo ilustra cómo implementar el desplazamiento con las teclas arriba y abajo:
Flickable {
focus: true
Keys.onUpPressed: scrollBar.decrease()
Keys.onDownPressed: scrollBar.increase()
ScrollBar.vertical: ScrollBar { id: scrollBar }
}Vinculación del estado activo de las barras de desplazamiento horizontales y verticales
Las barras de desplazamiento horizontales y verticales no comparten entre sí el estado « active » de forma predeterminada. Para mantener ambas barras visibles mientras se desplaza en cualquier dirección, establezca un enlace bidireccional entre los estados activos tal y como se muestra en el siguiente ejemplo:
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 }
}Barras de desplazamiento no asociadas
Es posible crear una instancia de `ScrollBar` sin utilizar la API de propiedades adjuntas. Esto resulta útil cuando el comportamiento de la barra de desplazamiento adjunta no es suficiente o no se utiliza un ` Flickable `. En el siguiente ejemplo, se utilizan barras de desplazamiento horizontal y vertical para desplazarse por el texto sin utilizar ` 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
}
}
Al utilizar una barra de desplazamiento no asociada, hay que realizar manualmente lo siguiente:
- Diseñar la barra de desplazamiento (con las propiedades x y y o anchors, por ejemplo).
- Configurar las propiedades « size » y « position » para determinar el tamaño y la posición de la barra de desplazamiento en relación con el elemento desplazado.
- Establece la propiedad « active » para determinar cuándo estará visible la barra de desplazamiento.
Tamaños variables de los delegados
Los tamaños variables de los delegados pueden provocar que ScrollBar «dé saltos» a medida que se cargan nuevos delegados en la vista. Por este motivo, se recomienda que los delegados tengan el mismo tamaño. Consulte Variable Delegate Size and Section Labels para obtener más información.
Véase también « ScrollIndicator» , « ScrollView », «Personalización de ScrollBar» y «Controles indicadores».
Documentación de propiedades
active : bool
Esta propiedad se mantiene independientemente de si la barra de desplazamiento está activa, es decir, tanto si está en « pressed » como si el Flickable asociado está en « moving ».
Es posible mantener la propiedad « both horizontal and vertical bars visible » mientras se desplaza en cualquier dirección.
Esta propiedad se establece automáticamente cuando la barra de desplazamiento está en « attached to a flickable ».
horizontal : bool [read-only, since QtQuick.Controls 2.3 (Qt 5.10)]
Esta propiedad indica si la barra de desplazamiento es horizontal.
Esta propiedad se introdujo en QtQuick.Controls 2.3 (Qt 5.10).
Véase también orientation.
interactive : bool [since QtQuick.Controls 2.2 (Qt 5.9)]
Esta propiedad indica si la barra de desplazamiento es interactiva. El valor predeterminado es « true ».
Una barra de desplazamiento no interactiva es similar, tanto visualmente como en cuanto a su comportamiento, a ScrollIndicator. Esta propiedad resulta útil para alternar entre interfaces de usuario típicas orientadas al ratón y a la interacción táctil, con barras de desplazamiento interactivas y no interactivas, respectivamente.
Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).
minimumSize : real [since QtQuick.Controls 2.4 (Qt 5.11)]
Esta propiedad contiene el tamaño mínimo de la barra de desplazamiento, escalado a 0.0 - 1.0.
Esta propiedad se introdujo en QtQuick.Controls 2.4 (Qt 5.11).
Véase también size, visualSize y visualPosition.
orientation : enumeration
Esta propiedad determina la orientación de la barra de desplazamiento.
Valores posibles:
| Constante | Descripción |
|---|---|
Qt.Horizontal | Horizontal |
Qt.Vertical | Vertical (por defecto) |
Esta propiedad se establece automáticamente cuando la barra de desplazamiento es de tip attached to a flickable.
Véase también horizontal y vertical.
policy : enumeration [since QtQuick.Controls 2.2 (Qt 5.9)]
Esta propiedad define la política de la barra de desplazamiento. La política predeterminada es « ScrollBar.AsNeeded ».
Valores posibles:
| Constante | Descripción |
|---|---|
ScrollBar.AsNeeded | La barra de desplazamiento solo se muestra cuando el contenido es demasiado grande para caber en la pantalla. |
ScrollBar.AlwaysOff | La barra de desplazamiento nunca se muestra. |
ScrollBar.AlwaysOn | La barra de desplazamiento siempre se muestra. |
El siguiente ejemplo mantiene la barra de desplazamiento vertical siempre visible:
Los estilos pueden utilizar esta propiedad en combinación con la propiedad « active » para implementar barras de desplazamiento transitorias. Las barras de desplazamiento transitorias se ocultan poco después del último evento de interacción (paso del cursor o pulsación). Esto se suele hacer animando la opacidad de la barra de desplazamiento. Para anular este comportamiento, establece la política en « ScrollBar.AlwaysOn » o « ScrollBar.AlwaysOff », dependiendo del tamaño del contenido en comparación con su vista. Por ejemplo, para una barra de desplazamiento vertical « ListView »:
policy: listView.contentHeight > listView.height ? ScrollBar.AlwaysOn : ScrollBar.AlwaysOffEsta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).
position : real
Esta propiedad contiene la posición de la barra de desplazamiento, escalada a 0.0 - 1.0.
La posición máxima válida de la barra de desplazamiento es (1.0 - size). Esto garantiza un comportamiento correcto en el caso más habitual, en el que al desplazar la barra de desplazamiento hasta el final, el final del documento quedará situado en el extremo inferior del área visible del Flickable conectado.
Esta propiedad se establece automáticamente cuando la barra de desplazamiento se encuentra en attached to a flickable.
Véase también Flickable::visibleArea y visualPosition.
pressed : bool
Esta propiedad indica si se ha pulsado la barra de desplazamiento.
size : real
Esta propiedad contiene el tamaño de la barra de desplazamiento, escalado a 0.0 - 1.0.
Esta propiedad se establece automáticamente cuando la barra de desplazamiento tiene el valor « attached to a flickable ».
Véase también « Flickable::visibleArea », « minimumSize » y « visualSize ».
snapMode : enumeration [since QtQuick.Controls 2.2 (Qt 5.9)]
Esta propiedad determina el modo de ajuste.
Valores posibles:
| Constante | Descripción |
|---|---|
ScrollBar.NoSnap | La barra de desplazamiento no se ajusta (valor predeterminado). |
ScrollBar.SnapAlways | La barra de desplazamiento se ajusta mientras se arrastra. |
ScrollBar.SnapOnRelease | La barra de desplazamiento no se ajusta mientras se arrastra, sino solo después de soltarla. |
En la siguiente tabla se ilustran los distintos modos mediante animaciones. El movimiento y el « stepSize » (0.25) son idénticos en cada animación.
| Valor | Ejemplo |
ScrollBar.NoSnap | |
ScrollBar.SnapAlways | |
ScrollBar.SnapOnRelease |
Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).
Véase también « stepSize ».
stepSize : real
Esta propiedad indica el tamaño del paso. El valor por defecto es 0.0.
Véase también snapMode, increase() y decrease().
vertical : bool [read-only, since QtQuick.Controls 2.3 (Qt 5.10)]
Esta propiedad indica si la barra de desplazamiento es vertical.
Esta propiedad se introdujo en QtQuick.Controls 2.3 (Qt 5.10).
Véase también orientation.
visualPosition : real [read-only, since QtQuick.Controls 2.4 (Qt 5.11)]
Esta propiedad contiene la posición visual efectiva de la barra de desplazamiento, que puede verse limitada por la propiedad « minimum size ».
Esta propiedad se introdujo en QtQuick.Controls 2.4 (Qt 5.11).
Véanse también « position » y « minimumSize ».
visualSize : real [read-only, since QtQuick.Controls 2.4 (Qt 5.11)]
Esta propiedad contiene el tamaño visual efectivo de la barra de desplazamiento, que puede verse limitado por la propiedad « minimum size ».
Esta propiedad se introdujo en QtQuick.Controls 2.4 (Qt 5.11).
Véase también « size » y « minimumSize ».
Documentación de la propiedad asociada
ScrollBar.horizontal : ScrollBar [attached]
Esta propiedad añade una barra de desplazamiento horizontal a un elemento « Flickable ».
Véase también Attaching ScrollBar to a Flickable.
ScrollBar.vertical : ScrollBar [attached]
Esta propiedad añade una barra de desplazamiento vertical a un elemento ` Flickable`.
Véase también Attaching ScrollBar to a Flickable.
Documentación del método
void decrease()
Disminuye la posición en stepSize o 0.1 si stepSize es 0.0.
Véase también stepSize.
void increase()
Aumenta la posición en stepSize o 0.1 si stepSize es 0.0.
Véase también stepSize.
© 2026 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.