En esta página

Container QML Type

Tipo base abstracto que proporciona funcionalidades comunes a los contenedores. Más...

Import Statement: import QtQuick.Controls
Inherits:

Control

Inherited By:

DialogButtonBox, MenuBar, SplitView, SwipeView, and TabBar

Propiedades

Métodos

Descripción detallada

«Container» es el tipo básico de controles de interfaz de usuario similares a contenedores que permiten insertar y eliminar elementos de forma dinámica.

Uso de los «Container»

Normalmente, los elementos se declaran de forma estática como hijos de Container, pero también es posible añadir elementos de forma dinámica mediante ` add`, ` insert`, ` move ` y ` remove `. Se puede acceder a los elementos de un contenedor mediante ` itemAt()` o ` contentChildren`.

La mayoría de los contenedores cuentan con el concepto de elemento «actual». El elemento actual se especifica mediante la propiedad currentIndex, y se puede acceder a él mediante la propiedad de solo lectura currentItem.

El siguiente ejemplo ilustra la inserción dinámica de elementos en un ` TabBar`, que es una de las implementaciones concretas de `Container`.

Row {
    TabBar {
        id: tabBar

        currentIndex: 0
        width: parent.width - addButton.width

        TabButton { text: "TabButton" }
    }

    Component {
        id: tabButton
        TabButton { text: "TabButton" }
    }

    Button {
        id: addButton
        text: "+"
        flat: true
        onClicked: {
            tabBar.addItem(tabButton.createObject(tabBar))
            console.log("added:", tabBar.itemAt(tabBar.count - 1))
        }
    }
}

Gestión del índice actual

Cuando se utilizan varios contenedores, como TabBar y SwipeView, a la vez, sus propiedades currentIndex pueden vincularse entre sí para mantenerlos sincronizados. Cuando el usuario interactúa con cualquiera de los contenedores, los cambios en su índice actual se propagan automáticamente al otro contenedor.

Sin embargo, hay que tener en cuenta que asignar un valor a currentIndex en JavaScript elimina el enlace correspondiente. Para conservar los enlaces, utiliza los siguientes métodos para modificar el índice actual:

TabBar {
    id: tabBar
    currentIndex: swipeView.currentIndex
}

SwipeView {
    id: swipeView
    currentIndex: tabBar.currentIndex
}

Button {
    text: qsTr("Home")
    onClicked: swipeView.setCurrentIndex(0)
    enabled: swipeView.currentIndex != 0
}

Button {
    text: qsTr("Previous")
    onClicked: swipeView.decrementCurrentIndex()
    enabled: swipeView.currentIndex > 0
}

Button {
    text: qsTr("Next")
    onClicked: swipeView.incrementCurrentIndex()
    enabled: swipeView.currentIndex < swipeView.count - 1
}

Implementación de contenedores

El contenedor no proporciona ninguna visualización por defecto. Se utiliza para implementar contenedores como SwipeView y TabBar. Al implementar un contenedor personalizado, la parte más importante de la API es contentModel, que proporciona los elementos contenidos de tal forma que pueden utilizarse como modelo de objetos para vistas de elementos y repetidores.

Container {
    id: container

    contentItem: ListView {
        model: container.contentModel
        snapMode: ListView.SnapOneItem
        orientation: ListView.Horizontal
    }

    Text {
        text: "Page 1"
        width: container.width
        height: container.height
    }

    Text {
        text: "Page 2"
        width: container.width
        height: container.height
    }
}

Fíjate en cómo se establecen manualmente los tamaños de los elementos de la página. Esto se debe a que el ejemplo utiliza un contenedor simple (Container), que no hace ninguna suposición sobre el diseño visual. Normalmente no es necesario especificar los tamaños de los elementos en implementaciones concretas de contenedores, como SwipeView y TabBar.

Véase también «Controles Container».

Documentación de propiedades

contentChildren : list<Item>

Esta propiedad contiene la lista de elementos hijos de contenido.

La lista contiene todos los elementos que se han declarado en QML como hijos del contenedor, así como los elementos que se han añadido o insertado dinámicamente mediante los métodos addItem() y insertItem(), respectivamente.

Nota: A diferencia de ` contentData`, ` contentChildren ` no incluye objetos QML no visuales. Se reordena cuando se insertan o mueven elementos.

Véase también Item::children y contentData.

contentData : list<QtObject> [default]

Esta propiedad contiene la lista de datos de contenido.

La lista contiene todos los objetos que se han declarado en QML como hijos del contenedor, así como los elementos que se han añadido o insertado dinámicamente mediante los métodos addItem() y insertItem(), respectivamente.

Nota: A diferencia de ` contentChildren`, ` contentData ` sí incluye objetos QML no visuales. No se reordena cuando se insertan o mueven elementos.

Véase también Item::data y contentChildren.

contentHeight : real [since QtQuick.Controls 2.5 (Qt 5.12)]

Esta propiedad almacena la altura del contenido. Se utiliza para calcular la altura implícita total del contenedor.

A menos que se sobrescriba explícitamente, la altura del contenido se calcula automáticamente en función de la altura implícita de los elementos del contenedor.

Esta propiedad se introdujo en QtQuick.Controls 2.5 (Qt 5.12).

Véase también contentWidth.

contentModel : model [read-only]

Esta propiedad contiene el modelo de contenido de los elementos.

El modelo de contenido se proporciona con fines de visualización. Se puede asignar como modelo a un elemento de contenido que presente el contenido del contenedor.

Container {
    id: container
    contentItem: ListView {
        model: container.contentModel
    }
}

Véase también contentData y contentChildren.

contentWidth : real [since QtQuick.Controls 2.5 (Qt 5.12)]

Esta propiedad contiene el ancho del contenido. Se utiliza para calcular el ancho implícito total del contenedor.

A menos que se sobrescriba explícitamente, el ancho del contenido se calcula automáticamente en función del ancho implícito de los elementos del contenedor.

Esta propiedad se introdujo en QtQuick.Controls 2.5 (Qt 5.12).

Véase también contentHeight.

count : int [read-only]

Esta propiedad contiene el número de elementos.

currentIndex : int

Esta propiedad contiene el índice del elemento actual.

Véase también currentItem y Managing the Current Index.

currentItem : Item [read-only]

Esta propiedad contiene el elemento actual.

Véase también currentIndex.

Documentación del método

void addItem(Item item)

Añade un item.

[since QtQuick.Controls 2.1 (Qt 5.8)] void decrementCurrentIndex()

Disminuye el índice actual del contenedor.

Este método se puede invocar para modificar el índice actual sin romper los enlaces existentes de « currentIndex ».

Este método se introdujo en QtQuick.Controls 2.1 (Qt 5.8).

Véase también currentIndex y Managing the Current Index.

[since QtQuick.Controls 2.1 (Qt 5.8)] void incrementCurrentIndex()

Incrementa el índice actual del contenedor.

Este método se puede invocar para modificar el índice actual sin romper los enlaces existentes de currentIndex.

Este método se introdujo en QtQuick.Controls 2.1 (Qt 5.8).

Véase también currentIndex y Managing the Current Index.

void insertItem(int index, Item item)

Inserta un « item » en index.

Item itemAt(int index)

Devuelve el elemento de index, o null si no existe.

void moveItem(int from, int to)

Mueve un elemento from un índice to otro.

[since QtQuick.Controls 2.3 (Qt 5.10)] void removeItem(Item item)

Elimina y destruye el objeto especificado ` item`.

Este método se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

void setCurrentIndex(int index)

Establece el index actual del contenedor.

Este método se puede invocar para establecer un índice actual específico sin romper los enlaces existentes de « currentIndex ».

Véase también « currentIndex » y « Managing the Current Index ».

[since QtQuick.Controls 2.3 (Qt 5.10)] Item takeItem(int index)

Elimina y devuelve el elemento de index.

Nota: La propiedad del elemento se transfiere al llamante.

Este método se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

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