SplitView QML Type
Muestra los elementos con un separador arrastrable entre cada uno de ellos. Más...
| Import Statement: | import QtQuick.Controls |
| Inherits: |
Propiedades
- handle : Component
- orientation : enumeration
- resizing : bool
Propiedades adjuntas
- fillHeight : bool
- fillWidth : bool
- maximumHeight : real
- maximumWidth : real
- minimumHeight : real
- minimumWidth : real
- preferredHeight : real
- preferredWidth : real
- view : SplitView
Métodos
- bool restoreState(state)
- var saveState()
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:
- SplitView.minimumWidth
- SplitView.minimumHeight
- SplitView.preferredWidth
- SplitView.preferredHeight
- SplitView.maximumWidth
- SplitView.maximumHeight
- SplitView.fillWidth (verdadero si solo hay un elemento secundario)
- SplitView.fillHeight (verdadero si solo hay un elemento secundario)
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:
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ón | Ancho del controlador | Altura del controlador |
|---|---|---|
Qt.Horizontal | implicitWidth | El height del SplitView. |
Qt.Vertical | width 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:
| Constante | Descripción |
|---|---|
Qt.Horizontal | Los elementos se disponen horizontalmente (por defecto). |
Qt.Vertical | Los 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.