En esta página

ScrollBar QML Type

Barra de desplazamiento interactiva vertical u horizontal. Más...

Import Statement: import QtQuick.Controls
Inherits:

Control

Propiedades

Propiedades adjuntas

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.

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

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

Barra de desplazamiento utilizada de forma independiente, sin ninguna propiedad asociada

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:

ConstanteDescripción
Qt.HorizontalHorizontal
Qt.VerticalVertical (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:

ConstanteDescripción
ScrollBar.AsNeededLa barra de desplazamiento solo se muestra cuando el contenido es demasiado grande para caber en la pantalla.
ScrollBar.AlwaysOffLa barra de desplazamiento nunca se muestra.
ScrollBar.AlwaysOnLa barra de desplazamiento siempre se muestra.

El siguiente ejemplo mantiene la barra de desplazamiento vertical siempre visible:

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

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

Esta 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:

ConstanteDescripción
ScrollBar.NoSnapLa barra de desplazamiento no se ajusta (valor predeterminado).
ScrollBar.SnapAlwaysLa barra de desplazamiento se ajusta mientras se arrastra.
ScrollBar.SnapOnReleaseLa 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.

ValorEjemplo
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 ».

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

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

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

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.