En esta página

SplitView QML Type

Muestra los elementos con un separador arrastrable entre cada uno de ellos. Más...

Import Statement: import QtQuick.Controls
Inherits:

Container

Propiedades

Propiedades adjuntas

Métodos

Descripción detallada

SplitView es un control que distribuye los elementos de forma horizontal o vertical con un separador arrastrable entre cada elemento.

SplitView admite las siguientes propiedades asociadas en los elementos que gestiona:

Además, cada controlador tiene las siguientes propiedades asociadas de solo lectura:

Nota: Los controladores deben ser puramente visuales y no gestionar eventos, ya que esto puede interferir con sus estados de paso del cursor y de pulsación.

El tamaño preferido de los elementos en un SplitView se puede especificar mediante implicitWidth y implicitHeight o SplitView.preferredWidth y SplitView.preferredHeight:

SplitView {
    anchors.fill: parent

    Item {
        SplitView.preferredWidth: 50
    }

    // ...
}

En el caso de una SplitView horizontal, no es necesario especificar la altura preferida de cada elemento, ya que se redimensionarán a la altura de la vista. Esto se aplica a la inversa en las vistas verticales.

Al arrastrar un controlador de división, se sobrescribe la propiedad « SplitView.preferredWidth » o « SplitView.preferredHeight », dependiendo de la propiedad « orientation » de la vista.

Para limitar el tamaño de los elementos en una vista horizontal, utilice las siguientes propiedades:

SplitView {
    anchors.fill: parent

    Item {
        SplitView.minimumWidth: 25
        SplitView.preferredWidth: 50
        SplitView.maximumWidth: 100
    }

    // ...
}

Para limitar el tamaño de los elementos en una vista vertical, utiliza las siguientes propiedades:

SplitView {
    anchors.fill: parent
    orientation: Qt.Vertical

    Item {
        SplitView.minimumHeight: 25
        SplitView.preferredHeight: 50
        SplitView.maximumHeight: 100
    }

    // ...
}

Siempre habrá un elemento (el elemento de relleno) en la SplitView que tenga SplitView.fillWidth establecido en true (o SplitView.fillHeight, si orientation es Qt.Vertical). Esto significa que el elemento ocupará todo el espacio restante una vez que se hayan distribuido los demás elementos. De forma predeterminada, el último elemento secundario visible de la SplitView tendrá esta propiedad establecida, pero se puede cambiar estableciendo explícitamente fillWidth en true en otro elemento.

Un controlador puede pertenecer al elemento situado a la izquierda o en la parte superior, o bien al situado a la derecha o en la parte inferior:

  • Si el elemento de relleno está a la derecha: el controlador pertenece al elemento de la izquierda.
  • Si el elemento de relleno está a la izquierda: el controlador pertenece al elemento de la derecha.

Para crear una SplitView con tres elementos y hacer que el elemento central ocupe el espacio sobrante, se podría hacer lo siguiente:

SplitView {
    anchors.fill: parent
    orientation: Qt.Horizontal

    Rectangle {
        implicitWidth: 200
        SplitView.maximumWidth: 400
        color: "lightblue"
        Label {
            text: "View 1"
            anchors.centerIn: parent
        }
    }
    Rectangle {
        id: centerItem
        SplitView.minimumWidth: 50
        SplitView.fillWidth: true
        color: "lightgray"
        Label {
            text: "View 2"
            anchors.centerIn: parent
        }
    }
    Rectangle {
        implicitWidth: 200
        color: "lightgreen"
        Label {
            text: "View 3"
            anchors.centerIn: parent
        }
    }
}

Serialización del estado de SplitView

El objetivo principal de SplitView es permitir a los usuarios configurar fácilmente el tamaño de diversos elementos de la interfaz de usuario. Además, los tamaños preferidos por el usuario deben recordarse de una sesión a otra. Para lograrlo, los valores de las propiedades SplitView.preferredWidth y SplitView.preferredHeight pueden serializarse utilizando las funciones saveState() y restoreState():

import QtCore
import QtQuick.Controls

ApplicationWindow {
    // ...

    Component.onCompleted: splitView.restoreState(settings.splitView)
    Component.onDestruction: settings.splitView = splitView.saveState()

    Settings {
        id: settings
        property var splitView
    }

    SplitView {
        id: splitView
        // ...
    }
}

Como alternativa, se pueden utilizar las funciones value() y setValue() de Settings:

import QtCore
import QtQuick.Controls

ApplicationWindow {
    // ...

    Component.onCompleted: splitView.restoreState(settings.value("ui/splitview"))
    Component.onDestruction: settings.setValue("ui/splitview", splitView.saveState())

    Settings {
        id: settings
    }

    SplitView {
        id: splitView
        // ...
    }
}

Véase también SplitHandle, Personalización de SplitView y Controles de contenedor.

Documentación sobre propiedades

handle : Component

Esta propiedad contiene el componente «handle».

Se creará una instancia de este componente un count - 1, siempre y cuando count sea mayor que 1.

La siguiente tabla explica cómo se redimensionará cada controlador en función de la orientación de la vista dividida:

OrientaciónAncho del controladorAltura del controlador
Qt.HorizontalimplicitWidthEl height del SplitView.
Qt.Verticalwidth e de SplitView.implicitHeight

Para cambiar el tamaño del controlador para eventos de ratón y táctiles sin modificar su tamaño visual, utiliza un controlador de tamaño variable ( containmentMask):

SplitView {
    id: splitView
    anchors.fill: parent

    handle: Rectangle {
        id: handleDelegate
        implicitWidth: 4
        implicitHeight: 4
        color: SplitHandle.pressed ? "#81e889"
            : (SplitHandle.hovered ? Qt.lighter("#c2f4c6", 1.1) : "#c2f4c6")

        containmentMask: Item {
            x: (handleDelegate.width - width) / 2
            width: 64
            height: splitView.height
        }
    }

    Rectangle {
        implicitWidth: 150
        color: "#444"
    }
    Rectangle {
        implicitWidth: 50
        color: "#666"
    }
}

Véase también Personalización deSplitView.

orientation : enumeration

Esta propiedad define la orientación de la « SplitView ».

La orientación determina cómo se distribuyen los elementos divididos:

Valores posibles:

ConstanteDescripción
Qt.HorizontalLos elementos se disponen horizontalmente (por defecto).
Qt.VerticalLos elementos se disponen verticalmente.

resizing : bool [read-only]

Esta propiedad tiene el valor « true » cuando el usuario cambia el tamaño de los elementos divididos arrastrando los controladores de división.

Documentación de la propiedad adjunta

SplitView.fillHeight : bool [attached]

Esta propiedad adjunta determina si el elemento ocupa el espacio restante en la vista dividida una vez que se han distribuido todos los demás elementos.

Por defecto, el último elemento secundario visible de la vista dividida ocupará toda la vista, pero esto se puede modificar estableciendo explícitamente la propiedad « fillHeight » en « true » en otro elemento. Si varios elementos tienen la propiedad « fillHeight » establecida en « true », el elemento situado más arriba ocupará toda la vista.

La altura de un elemento dividido cuyo valor de « fillHeight » esté establecido en « true » sigue estando limitada por sus valores de « minimumHeight » y « maximumHeight ».

Véase también minimumHeight, preferredHeight, maximumHeight y fillWidth.

SplitView.fillWidth : bool [attached]

Esta propiedad adjunta determina si el elemento ocupa el espacio restante en la vista dividida una vez que se han distribuido todos los demás elementos.

Por defecto, el último elemento secundario visible de la vista dividida ocupará toda la vista, pero esto se puede modificar estableciendo explícitamente « fillWidth » en « true » en otro elemento. Si varios elementos tienen « fillWidth » establecido en « true », el elemento situado más a la izquierda ocupará toda la vista.

El ancho de un elemento dividido cuyo valor « fillWidth » esté establecido en « true » sigue estando limitado por sus valores « minimumWidth » y « maximumWidth ».

Véase también « minimumWidth », « preferredWidth », « maximumWidth » y « fillHeight ».

SplitView.maximumHeight : real [attached]

Esta propiedad adjunta controla la altura máxima del elemento dividido. El valor de « preferredHeight » está limitado por los valores de « minimumHeight » y «maximumHeight». No es posible arrastrar un elemento dividido para que supere su « maximumHeight ».

El valor por defecto es « Infinity ». Para restablecer esta propiedad a su valor por defecto, establécela en « undefined ».

Véase también minimumHeight, preferredHeight, fillHeight y maximumWidth.

SplitView.maximumWidth : real [attached]

Esta propiedad adjunta controla la anchura máxima del elemento dividido. La propiedad « preferredWidth » está limitada por los valores de « minimumWidth » y «maximumWidth». No es posible arrastrar un elemento dividido para que ocupe más espacio que su « maximumWidth ».

El valor por defecto es Infinity. Para restablecer esta propiedad a su valor por defecto, configúrala en undefined.

Véase también minimumWidth, preferredWidth, fillWidth y maximumHeight.

SplitView.minimumHeight : real [attached]

Esta propiedad adjunta controla la altura mínima del elemento dividido. El valor de « preferredHeight » está limitado por «minimumHeight» y « maximumHeight ». No es posible arrastrar un elemento dividido para que su altura sea inferior a su « minimumHeight ».

El valor por defecto es « 0 ». Para restablecer esta propiedad a su valor por defecto, establécela en « undefined ».

Véase también maximumHeight, preferredHeight, fillHeight y minimumWidth.

SplitView.minimumWidth : real [attached]

Esta propiedad adjunta controla la anchura mínima del elemento dividido. El valor de « preferredWidth » está limitado por «minimumWidth» y « maximumWidth ». No es posible arrastrar un elemento dividido para que su anchura sea inferior a su « minimumWidth ».

El valor por defecto es 0. Para restablecer esta propiedad a su valor por defecto, establécela en undefined.

Véase también maximumWidth, preferredWidth, fillWidth y minimumHeight.

SplitView.preferredHeight : real [attached]

Esta propiedad adjunta controla la altura preferida del elemento dividido. La altura preferida se utilizará como tamaño del elemento y estará limitada por los valores de « minimumHeight » y « maximumHeight ». Si no se establece la altura preferida, se utilizará la altura « implicitHeight » del elemento.

Cuando se cambia el tamaño de un elemento dividido, se establecerá la propiedad «preferredHeight» para reflejar el nuevo tamaño.

Por defecto, esta propiedad no está definida, por lo que se utilizará en su lugar implicitHeight. Para restablecer esta propiedad a su valor por defecto, establécela en undefined.

Nota: No establezcas la propiedad « height » de un elemento dividido, ya que se sobrescribirá con cada diseño de « SplitView ».

Véase también minimumHeight, maximumHeight, fillHeight y preferredWidth.

SplitView.preferredWidth : real [attached]

Esta propiedad adjunta controla el ancho preferido del elemento dividido. El ancho preferido se utilizará como tamaño del elemento y estará comprendido entre los valores de « minimumWidth » y « maximumWidth ». Si no se establece el ancho preferido, se utilizará el ancho « implicitWidth » del elemento.

Cuando se cambia el tamaño de un elemento dividido, se establecerá la propiedad «preferredWidth» para reflejar el nuevo tamaño.

Por defecto, esta propiedad no está definida, por lo que se utilizará en su lugar implicitWidth. Para restablecer esta propiedad a su valor por defecto, configúrala en undefined.

Nota: No establezcas la propiedad « width » de un elemento dividido, ya que se sobrescribirá con cada diseño de « SplitView ».

Véase también minimumWidth, maximumWidth, fillWidth y preferredHeight.

SplitView.view : SplitView [attached]

Esta propiedad adjunta contiene la vista dividida del elemento al que está asociada, o bien un objeto de tipo « null » si el elemento no se encuentra en una vista dividida.

Documentación del método

bool restoreState(state)

Lee los tamaños preferidos de state y los aplica a los elementos divididos.

Devuelve ` true ` si el estado se ha restaurado correctamente; en caso contrario, devuelve ` false`.

Véase también Serializing SplitView's State y saveState().

var saveState()

Guarda los tamaños preferidos de los elementos divididos en una matriz de bytes y la devuelve.

Véase también Serializing SplitView's State y restoreState().

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