En esta página

TableView QML Type

Ofrece una vista de tabla de elementos para mostrar los datos de un modelo. Más...

Import Statement: import QtQuick
Inherits:

Flickable

Inherited By:

HorizontalHeaderView, TreeView, and VerticalHeaderView

Propiedades

Propiedades adjuntas

Señales

  • columnMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex) (since 6.8)
  • layoutChanged() (since 6.5)
  • rowMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex) (since 6.8)

Señales adjuntas

Métodos

Descripción detallada

Una TableView tiene un model que define los datos que se van a mostrar y un delegate que define cómo deben mostrarse dichos datos.

TableView hereda de ` Flickable`. Esto significa que, aunque el modelo puede tener cualquier número de filas y columnas, normalmente solo una parte de la tabla es visible dentro del área de visualización. En cuanto se desliza el dedo, nuevas filas y columnas entran en el área de visualización, mientras que las antiguas salen y se eliminan de ella. Las filas y columnas que salen se reutilizan para construir las filas y columnas que entran en el área de visualización. De este modo, TableView admite modelos de cualquier tamaño sin que ello afecte al rendimiento.

Una TableView muestra datos de modelos creados a partir de tipos QML integrados, como ListModel y XmlListModel, que solo rellenan la primera columna en una TableView. Para crear modelos con varias columnas, utiliza TableModel o un modelo en C++ que herede de QAbstractItemModel.

Una TableView no incluye encabezados de forma predeterminada. Puedes añadir encabezados utilizando los elementos HorizontalHeaderView y VerticalHeaderView de los controles de Qt Quick.

Nota: TableView solo load tantos elementos delegados como sean necesarios para llenar la vista. No hay garantía de que se carguen los elementos que quedan fuera de la vista, aunque TableView a veces precarga elementos por motivos de optimización. Por lo tanto, es posible que una TableView con anchura o altura cero no cargue ningún elemento delegado.

Ejemplo de uso

Modelos en C++

El siguiente ejemplo muestra cómo crear un modelo desde C++ con varias columnas:

#include <qqml.h>
#include <QAbstractTableModel>

class TableModel : public QAbstractTableModel
{
    Q_OBJECT
    QML_ELEMENT

public:
    int rowCount(const QModelIndex & = QModelIndex()) const override
    {
        return 200;
    }

    int columnCount(const QModelIndex & = QModelIndex()) const override
    {
        return 200;
    }

    QVariant data(const QModelIndex &index, int role) const override
    {
        switch (role) {
            case Qt::DisplayRole:
                return QString("%1, %2").arg(index.column()).arg(index.row());
            default:
                break;
        }

        return QVariant();
    }

    QHash<int, QByteArray> roleNames() const override
    {
        return { {Qt::DisplayRole, "display"} };
    }
};

A continuación, el TableViewDelegate utiliza automáticamente el modelo para establecer y obtener datos del mismo. El TableViewDelegate utiliza el Qt::DisplayRole para mostrar texto y el Qt::EditRole para editar datos en el modelo.

El siguiente fragmento de código muestra cómo utilizar el modelo desde QML en un delegado personalizado:

import QtQuick
import TableModel

TableView {
    anchors.fill: parent
    columnSpacing: 1
    rowSpacing: 1
    clip: true

    model: TableModel {}

    delegate: Rectangle {
        implicitWidth: 100
        implicitHeight: 50
        Text {
            text: display
        }
    }
}

Modelos QML

Para crear prototipos y mostrar datos muy sencillos (procedentes de una API web, por ejemplo), se puede utilizar TableModel:

import QtQuick
import Qt.labs.qmlmodels

TableView {
    anchors.fill: parent
    columnSpacing: 1
    rowSpacing: 1
    clip: true

    model: TableModel {
        TableModelColumn { display: "name" }
        TableModelColumn { display: "color" }

        rows: [
            {
                "name": "cat",
                "color": "black"
            },
            {
                "name": "dog",
                "color": "brown"
            },
            {
                "name": "bird",
                "color": "white"
            }
        ]
    }

    delegate: Rectangle {
        implicitWidth: 100
        implicitHeight: 50
        border.width: 1

        Text {
            text: display
            anchors.centerIn: parent
        }
    }
}

Dado que TableViewDelegate utiliza Qt::EditRole para establecer los datos, es necesario especificar el rol de edición en TableModelColumn cuando el delegado es TableViewDelegate:

model: TableModel {
    TableModelColumn { display: "name", edit: "name" }
    TableModelColumn { display: "color", edit: "color" }

    rows: [
        {
            "name": "cat",
            "color": "black"
        },
        {
            "name": "dog",
            "color": "brown"
        },
        {
            "name": "bird",
            "color": "white"
        }
    ]
 }

Reutilización de elementos

TableView recicla los elementos del delegado de forma predeterminada, en lugar de instanciarlos desde el ` delegate ` cada vez que se muestran nuevas filas y columnas al deslizar el dedo. Este enfoque supone una mejora enorme del rendimiento, dependiendo de la complejidad del delegado.

Cuando un elemento se elimina con un movimiento rápido, pasa al grupo de reutilización, que es una caché interna de elementos no utilizados. Cuando esto ocurre, se emite la señal « TableView::pooled » para informar al elemento de ello. Del mismo modo, cuando el elemento vuelve a recuperarse del grupo, se emite la señal « TableView::reused ».

Cualquier propiedad del elemento que provenga del modelo se actualiza cuando se reutiliza el elemento. Esto incluye « index », « row » y « column », pero también cualquier rol del modelo.

Nota: Evita almacenar cualquier estado dentro de un delegado. Si lo haces, restablece dicho estado manualmente al recibir la señal « TableView::reused ».

Si un elemento tiene temporizadores o animaciones, considera la posibilidad de pausarlos al recibir la señal « TableView::pooled ». De este modo, evitarás utilizar los recursos de la CPU para elementos que no están visibles. Del mismo modo, si un elemento tiene recursos que no se pueden reutilizar, se podrían liberar.

Si no deseas reutilizar elementos o si el « delegate » no lo admite, puedes establecer la propiedad « reuseItems » en « false ».

Nota: Aunque un elemento se encuentre en el grupo, puede seguir activo y responder a las señales y enlaces conectados.

El siguiente ejemplo muestra un delegado que anima un rectángulo giratorio. Cuando se incluye en el grupo, la animación se pausa temporalmente:

Component {
    id: tableViewDelegate
    Rectangle {
        implicitWidth: 100
        implicitHeight: 50

        TableView.onPooled: rotationAnimation.pause()
        TableView.onReused: rotationAnimation.resume()

        Rectangle {
            id: rect
            anchors.centerIn: parent
            width: 40
            height: 5
            color: "green"

            RotationAnimation {
                id: rotationAnimation
                target: rect
                duration: (Math.random() * 2000) + 200
                from: 0
                to: 359
                running: true
                loops: Animation.Infinite
            }
        }
    }
}

Alturas de las filas y anchuras de las columnas

Cuando se muestra una nueva columna al deslizar la vista, TableView determinará su anchura llamando a la función « columnWidthProvider ». Si se ha definido, esta función decidirá por sí sola la anchura de la columna. De lo contrario, comprobará si se ha establecido una anchura explícita mediante « setColumnWidth()». Si no es así, se utilizará « implicitColumnWidth()». El ancho implícito de una columna es igual al mayor valor de « implicit width » encontrado entre los elementos del delegado cargados actualmente en esa columna. Intentar establecer un valor explícito de « width » directamente en un delegado no tiene ningún efecto, y será ignorado y sobrescrito. La misma lógica se aplica también a las alturas de las filas.

Una implementación de un ` columnWidthProvider ` equivalente a la lógica predeterminada sería:

columnWidthProvider: function(column) {
    let w = explicitColumnWidth(column)
    if (w >= 0)
        return w;
    return implicitColumnWidth(column)
}

Una vez resuelta la anchura de la columna, todos los demás elementos de la misma columna se redimensionan a esta anchura, incluidos aquellos que se introduzcan en la vista más adelante.

Nota: El ancho determinado de una columna se descarta cuando toda la columna se desplaza fuera de la vista, y se vuelve a calcular si se vuelve a introducir en ella. Esto significa que, si el ancho depende de ` implicitColumnWidth()`, el cálculo puede variar cada vez, dependiendo de en qué fila te encuentres cuando la columna entre en la vista (ya que ` implicitColumnWidth()` solo tiene en cuenta los elementos delegados que están actualmente en ` loaded`). Para evitarlo, debes utilizar un ` columnWidthProvider` o asegurarte de que todos los elementos delegados de la misma columna tengan el mismo ` implicitWidth`.

Si se modifican los valores que devuelven rowHeightProvider o columnWidthProvider para las filas y columnas dentro del área de visualización, se debe llamar a forceLayout. Esto indica a TableView que debe volver a utilizar las funciones del proveedor para recalcular y actualizar el diseño.

Desde Qt 5.13, si deseas ocultar una columna específica, puedes devolver ` 0 ` desde ` columnWidthProvider ` para esa columna. Del mismo modo, puedes devolver 0 desde ` rowHeightProvider ` para ocultar una fila. Si devuelves un número negativo o ` undefined`, TableView recurrirá a calcular el tamaño basándose en los elementos del delegado.

Nota: El tamaño de una fila o columna debe ser un número entero para evitar la alineación de elementos a nivel de subpíxeles.

El siguiente ejemplo muestra cómo definir una « columnWidthProvider » sencilla junto con un temporizador que modifica los valores que devuelve la función. Cuando se modifica la matriz, se llama a « forceLayout » para que los cambios surtan efecto:

TableView {
    id: tableView

    property var columnWidths: [100, 50, 80, 150]
    columnWidthProvider: function (column) { return columnWidths[column] }

    Timer {
        running: true
        interval: 2000
        onTriggered: {
            tableView.columnWidths[2] = 150
            tableView.forceLayout();
        }
    }
}

Edición de celdas

Puedes permitir que el usuario edite las celdas de la tabla proporcionando un delegado de edición. El delegado de edición se instanciará según el evento « editTriggers », que por defecto se produce cuando el usuario pulsa dos veces sobre una celda o pulsa, por ejemplo, « Qt::Key_Enter » o « Qt::Key_Return ». El delegado de edición se configura mediante « TableView::editDelegate », que es una propiedad adjunta que se establece en « delegate ». El siguiente fragmento de código muestra cómo hacerlo:

    TableView {
        id: tableView
        anchors.fill: parent
        clip: true

        model: TableModel {
            TableModelColumn { display: "name" }
            rows: [ { "name": "Harry" }, { "name": "Hedwig" } ]
        }

        selectionModel: ItemSelectionModel {}

        delegate: Rectangle {
            implicitWidth: 100
            implicitHeight: 50

            Text {
                anchors.centerIn: parent
                text: display
            }

            TableView.editDelegate: TextField {
                anchors.fill: parent
                text: display
                horizontalAlignment: TextInput.AlignHCenter
                verticalAlignment: TextInput.AlignVCenter
                Component.onCompleted: selectAll()

                TableView.onCommit: {
                    display = text
                    // 'display = text' is short-hand for:
                    // let index = TableView.view.index(row, column)
                    // TableView.view.model.setData(index, "display", text)
                }
            }
        }
    }

Si el usuario pulsa Qt::Key_Enter o Qt::Key_Return mientras el delegado de edición está activo, TableView emitirá la señal TableView::commit al delegado de edición, de modo que este pueda volver a escribir los datos modificados en el modelo.

Nota: Para que una celda sea editable, el modelo debe sobrescribir QAbstractItemModel::flags() y devolver Qt::ItemIsEditable. Esta opción no está habilitada de forma predeterminada en QAbstractItemModel. La sobrescritura podría tener, por ejemplo, este aspecto:

Qt::ItemFlags QAbstractItemModelSubClass::flags(const QModelIndex &index) const override
{
    Q_UNUSED(index)
    return Qt::ItemIsSelectable | Qt::ItemIsEnabled | Qt::ItemIsEditable;
}

Si el ` TableView delegate ` tiene definida la propiedad ` required property bool editing `, se establecerá en ` true ` para el delegado que se esté editando. Consulte la documentación de ` editDelegate ` para ver un ejemplo de cómo utilizarlo.

Superposiciones y capas subyacentes

Todos los nuevos elementos que se instancian desde el delegado se vinculan al contentItem con el valor de z, 1. Puedes añadir tus propios elementos dentro de la Tableview, como elementos secundarios del Flickable. Al controlar su valor de z, puedes hacer que se sitúen por encima o por debajo de los elementos de la tabla.

A continuación se muestra un ejemplo que ilustra cómo añadir texto encima de la tabla, que se desplaza junto con ella al deslizar el dedo:

TableView {
    id: tableView

    topMargin: header.implicitHeight

    Text {
        id: header
        text: "A table header"
    }
}

Aquí tienes otro ejemplo que muestra cómo crear un elemento superpuesto que permanece encima de una celda concreta. Esto requiere un poco más de código, ya que la ubicación de una celda puede change si el usuario, por ejemplo, cambia el tamaño de una columna situada delante de ella.

Rectangle {
    id: overlay
    width: 20
    height: 20
    radius: 10
    color: "blue"

    z: 10
    parent: tableView.contentItem

    Connections {
        target: tableView
        function onLayoutChanged() {
            let item = tableView.itemAtCell(5, 5)
            let insideViewport = item !== null

            overlay.visible = insideViewport
            if (insideViewport) {
                overlay.x = item.x
                overlay.y = item.y
            }
        }
    }
}

También podrías vincular la superposición directamente a la celda en lugar de a la « contentItem ». Sin embargo, hacerlo así resultaría inestable, ya que la celda se descarga o se reutiliza cada vez que se desplaza fuera del área de visualización.

Selección de elementos

Puedes añadir soporte para la selección a TableView asignando un ` ItemSelectionModel ` a la propiedad ` selectionModel `. A continuación, utilizará este modelo para controlar qué elementos del delegado deben mostrarse como seleccionados y qué elemento debe mostrarse como actual. Puedes configurar ` selectionBehavior ` para controlar si se permite al usuario seleccionar celdas individuales, filas o columnas.

Para saber si un delegado está seleccionado o es el actual, declare las siguientes propiedades (a menos que el delegado sea un « TableViewDelegate », en cuyo caso las propiedades ya se han añadido):

delegate: Item {
    required property bool selected
    required property bool current
    // ...
}

Nota: las propiedades selected y current deben definirse como required. Esto indicará a TableView que debe encargarse de actualizar sus valores. De lo contrario, simplemente se ignorarán. Véase también Propiedades obligatorias.

El siguiente fragmento de código muestra cómo una aplicación puede representar el delegado de forma diferente en función de la propiedad ` selected `:

    TableView {
        id: tableView
        anchors.fill: parent
        clip: true

        model: TableModel {
            TableModelColumn { display: "name" }
            rows: [ { "name": "Harry" }, { "name": "Hedwig" } ]
        }

        selectionModel: ItemSelectionModel {}

        delegate: Rectangle {
            implicitWidth: 100
            implicitHeight: 30
            color: selected ? "blue" : "lightgray"

            required property bool selected

            Text { text: display }
        }
    }

Las propiedades « currentRow » y « currentColumn » también pueden resultar útiles si necesitas aplicar un comportamiento diferente a un delegado en función de si se encuentra en la misma fila o columna que el elemento actual.

Nota: Qt Quick Controls ofrece un control « SelectionRectangle » que se puede utilizar para permitir al usuario seleccionar celdas.

Nota: De forma predeterminada, una celda se convertirá en « current » y se eliminarán todas las selecciones cuando el usuario pulse sobre ella. Si no se desea este comportamiento predeterminado al pulsar (por ejemplo, si utilizas controladores de puntero personalizados dentro de tu delegado), puedes establecer « pointerNavigationEnabled » en « false ».

Navegación mediante teclado

Para que sea compatible con la navegación mediante teclado, debes asignar un ` ItemSelectionModel ` a la propiedad ` selectionModel `. TableView utilizará entonces este modelo para manipular el ` currentIndex` del modelo.

Es responsabilidad del delegado representarse a sí mismo como un « current ». Para ello, puede añadirle una propiedad « required property bool current » y hacer que su apariencia dependa de su estado. El valor de la propiedad « current » lo establece TableView. También puede desactivar por completo la navegación mediante el teclado (en caso de que desee implementar sus propios controladores de teclas) estableciendo « keyNavigationEnabled » en « false ».

Nota: Por defecto, la propiedad ` TableViewDelegate ` muestra las celdas actuales y seleccionadas, por lo que no es necesario añadir estas propiedades.

El siguiente ejemplo muestra cómo se puede utilizar la navegación por teclado junto con las propiedades « current » y « selected » en un delegado personalizado:

ApplicationWindow {
    width: 800
    height: 600
    visible: true
    ScrollView {
        anchors.fill: parent
        TableView {
            id: tableView
            clip: true
            interactive: true
            rowSpacing: 1
            columnSpacing: 1
            model: TableModel {
                TableModelColumn { display: "checked" }
                TableModelColumn { display: "amount" }
                TableModelColumn { display: "fruitType" }
                TableModelColumn { display: "fruitName" }
                TableModelColumn { display: "fruitPrice" }

                rows: [
                    {
                        checked: false,
                        amount: 1,
                        fruitType: "Apple",
                        fruitName: "Granny Smith",
                        fruitPrice: 1.50
                    },
                    {
                        checked: true,
                        amount: 4,
                        fruitType: "Orange",
                        fruitName: "Navel",
                        fruitPrice: 2.50
                    },
                    {
                        checked: false,
                        amount: 1,
                        fruitType: "Banana",
                        fruitName: "Cavendish",
                        fruitPrice: 3.50
                    }
                ]
            }
            selectionModel: ItemSelectionModel {}
            delegate: Rectangle {
                implicitWidth: 100
                implicitHeight: 50
                required property bool selected
                required property bool current
                border.width: current ? 2 : 0
                color: selected ? "lightblue" : palette.base
                Text{
                    text: model.display
                    padding: 12
                }
            }
        }
    }
    SelectionRectangle {
        target: tableView
    }
}

Copiar y pegar

La implementación de operaciones de copiar y pegar en un TableView suele incluir también el uso de un QUndoStack (o algún otro marco de trabajo de deshacer/rehacer). El QUndoStack se puede utilizar para almacenar las diferentes operaciones realizadas en el modelo, como añadir o eliminar filas, o pegar datos desde el portapapeles, con la posibilidad de deshacerlas más adelante. Sin embargo, debe diseñarse un « QUndoStack » complementario que describa las operaciones posibles y cómo deshacerlas, de acuerdo con las necesidades del modelo y de la aplicación. Por lo tanto, TableView no ofrece una API integrada para gestionar el copiar y pegar.

El siguiente fragmento de código puede servir de referencia para añadir compatibilidad con copiar y pegar a tu modelo y a TableView. Utiliza la API de datos MIME existente en QAbstractItemModel, junto con QClipboard. El fragmento funcionará tal cual, pero también puede ampliarse para utilizar un QUndoStack.

// Inside your C++ QAbstractTableModel subclass:

Q_INVOKABLE void copyToClipboard(const QModelIndexList &indexes) const
{
    QGuiApplication::clipboard()->setMimeData(mimeData(indexes));
}

Q_INVOKABLE bool pasteFromClipboard(const QModelIndex &targetIndex)
{
    const QMimeData *mimeData = QGuiApplication::clipboard()->mimeData();
    // Consider using a QUndoCommand for the following call. It should store
    // the (mime) data for the model items that are about to be overwritten, so
    // that a later call to undo can revert it.
    return dropMimeData(mimeData, Qt::CopyAction, -1, -1, targetIndex);
}

Las dos funciones se pueden utilizar, por ejemplo, desde QML de la siguiente manera:

TableView {
    id: tableView
    model: tableModel
    selectionModel: ItemSelectionModel {}

    Shortcut {
       sequence: StandardKey.Copy
       onActivated: {
           let indexes = tableView.selectionModel.selectedIndexes
           tableView.model.copyToClipboard(indexes)
       }
    }

    Shortcut {
       sequence: StandardKey.Paste
       onActivated: {
           let targetIndex = tableView.selectionModel.currentIndex
           tableView.model.pasteFromClipboard(targetIndex)
       }
    }
}

Véase también TableView::editDelegate, TableView::commit, editTriggers, edit(), closeEditor(), layoutChanged(), QAbstractItemModel::mimeData(), QAbstractItemModel::dropMimeData(), QUndoStack, QUndoCommand y QClipboard.

Documentación de propiedades

alternatingRows : bool

Esta propiedad controla si el color de fondo de las filas debe alternarse. El valor por defecto depende del estilo.

Nota: Esta propiedad es solo una sugerencia y, por lo tanto, es posible que los delegados personalizados no la respeten. Se recomienda que un delegado alterne entre palette.base y palette.alternateBase cuando esta sugerencia sea true, de modo que los colores se puedan establecer desde fuera del delegado. Por ejemplo:

background: Rectangle {
    color: control.row === control.tableView.currentRow
           ? control.palette.highlight
           : (control.tableView.alternatingRows && control.row % 2 !== 0
           ? control.palette.alternateBase
           : control.palette.base)
}

animate : bool [since 6.4]

Esta propiedad se puede configurar para controlar si TableView debe animar el contentItem (contentX y contentY). La utilizan positionViewAtCell() y al navegar por the current index con el teclado. El valor por defecto es true.

Si se establece en false, cualquier animación en curso se detendrá inmediatamente.

Nota: Esta propiedad es solo una sugerencia. TableView puede optar por colocar el elemento de contenido sin animación si, por ejemplo, la celda de destino no es loaded. Sin embargo, si se establece en false, las animaciones siempre estarán desactivadas.

Esta propiedad se introdujo en Qt 6.4.

Véase también positionViewAtCell().

bottomRow : int

Esta propiedad contiene la fila más inferior que está visible actualmente dentro de la vista.

Véase también leftColumn, rightColumn y topRow.

columnSpacing : real

Esta propiedad define el espaciado entre las columnas.

El valor por defecto es 0.

columnWidthProvider : var

Esta propiedad puede contener una función que devuelva el ancho de cada columna del modelo. Se invoca cada vez que TableView necesita conocer el ancho de una columna concreta. La función toma un argumento, column, cuya anchura necesita conocer TableView.

Desde Qt 5.13, si se desea ocultar una columna específica, se puede devolver un ancho de 0 para esa columna. Si se devuelve un número negativo o undefined, TableView calcula el ancho basándose en los elementos delegados.

Nota: Normalmente, se llamaráa `columnWidthProvider` dos veces cuando una columna esté a punto de cargarse (o al realizar el diseño). En primer lugar, para saber si la columna es visible y debe cargarse. Y, en segundo lugar, para determinar el ancho de la columna una vez que se hayan cargado todos los elementos. Si necesitas calcular el ancho de la columna en función del tamaño de los elementos delegados, debes esperar a la segunda llamada, cuando se hayan cargado todos los elementos. Puedes comprobarlo llamando a isColumnLoaded(column) y, simplemente, devolver -1 si aún no es el caso.

Véase también rowHeightProvider, isColumnLoaded() y Row heights and column widths.

columns : int [read-only]

Esta propiedad contiene el número de columnas de la tabla.

Nota: « columns » suele ser igual al número de columnas del modelo, pero puede diferir temporalmente hasta que se hayan procesado todos los cambios pendientes del modelo.

Si el modelo es una lista, las columnas serán 1.

Esta propiedad es de solo lectura.

contentHeight : real

Esta propiedad contiene la altura de la tabla necesaria para dar cabida al número de filas del modelo de datos. Por lo general, no coincide con la altura de la ventana de visualización ( height ) de la vista ( view), lo que significa que la altura de la tabla podría ser mayor o menor que la altura de la ventana de visualización. Dado que un « TableView » no siempre puede conocer la altura exacta de la tabla sin cargar todas las filas del modelo, la propiedad « contentHeight » suele ser una estimación basada en la tabla cargada inicialmente.

Si conoce cuál será la altura de la tabla, asigne un valor a contentHeight para evitar cálculos y actualizaciones innecesarios en TableView.

Véase también « contentWidth » y « rowHeightProvider ».

contentWidth : real

Esta propiedad contiene el ancho de la tabla necesario para dar cabida al número de columnas del modelo. Por lo general, no coincide con el valor de « width » de « view », lo que significa que el ancho de la tabla podría ser mayor o menor que el ancho de la ventana gráfica. Dado que un « TableView » no siempre puede conocer el ancho exacto de la tabla sin cargar todas las columnas del modelo, el « contentWidth » suele ser una estimación basada en la tabla cargada inicialmente.

Si conoce cuál será el ancho de la tabla, asigne un valor a contentWidth para evitar cálculos y actualizaciones innecesarios en TableView.

Véase también « contentHeight » y « columnWidthProvider ».

currentColumn : int [read-only]

Esta propiedad de solo lectura contiene la columna de la vista que alberga el elemento que se encuentra en current.. Si no hay ningún elemento seleccionado, será -1.

Nota: Para que TableView indique cuál es la columna actual, es necesario asignar un ItemSelectionModel a selectionModel.

Véase también currentRow, selectionModel y Selecting items.

currentRow : int [read-only]

Esta propiedad de solo lectura contiene la fila de la vista que contiene el elemento que es « current. ». Si no hay ningún elemento seleccionado, será « -1 ».

Nota: Para que TableView indique cuál es la fila actual, es necesario asignar un ItemSelectionModel a selectionModel.

Véase también currentColumn, selectionModel y Selecting items.

delegate : Component

El delegado proporciona una plantilla que define cada elemento de celda instanciado por la vista. Puede ser cualquier componente personalizado, pero se recomienda utilizar TableViewDelegate, ya que se adapta al estilo de la aplicación y ofrece funcionalidad lista para usar.

Para utilizar TableViewDelegate, basta con establecerlo como delegado:

delegate: TableViewDelegate { }

El índice del modelo se expone como una propiedad accesible de ` index `. Lo mismo se aplica a ` row ` y ` column`. Las propiedades del modelo también están disponibles en función del tipo de modelo de datos.

Un delegado debe especificar su tamaño utilizando implicitWidth y implicitHeight. La propiedad TableView distribuye los elementos basándose en esa información. Los ajustes explícitos de ancho o alto se ignoran y se sobrescriben.

Dentro del delegado, se pueden añadir opcionalmente una o más de las siguientes propiedades (a menos que el delegado sea un ` TableViewDelegate`, en cuyo caso las propiedades ya se han añadido). ` TableView ` modifica los valores de estas propiedades para informar al delegado del estado en el que se encuentra. El delegado puede utilizar esto para representarse de forma diferente en función de su propio estado.

  • Propiedad obligatoria `bool current` - ` true ` si el delegado es current.
  • propiedad obligatoria bool selected - true si el delegado está selected.
  • propiedad obligatoria bool editing: true si el delegado está siendo edited.
  • propiedad obligatoria bool containsDrag: indica true si actualmente se está arrastrando una columna o fila sobre este delegado. Esta propiedad solo es compatible con HorizontalHeaderView y VerticalHeaderView. (desde Qt 6.8)

El siguiente ejemplo muestra cómo utilizar estas propiedades en un delegado personalizado:

delegate: Rectangle {
    required property bool current
    required property bool selected
    border.width: current ? 1 : 0
    color: selected ? palette.highlight : palette.base
}

Nota: Los delegados se instancian según sea necesario y pueden destruirse en cualquier momento. Además, se reutilizan si la propiedad ` reuseItems ` está establecida en ` true`. Por lo tanto, se debe evitar almacenar información de estado en los delegados.

Véase también « Row heights and column widths» , « Reusing items », «Propiedades obligatorias», « TableViewDelegate » y «Personalización de TableViewDelegate».

delegateModelAccess : enumeration [since 6.10]

Esta propiedad determina cómo pueden acceder los delegados al modelo.

ConstanteDescripción
DelegateModel.ReadOnlyImpide que los delegados escriban en el modelo a través de las propiedades de contexto, el objeto ` model ` o las propiedades obligatorias.
DelegateModel.ReadWritePermite a los delegados escribir en el modelo a través de las propiedades de contexto, el objeto ` model ` o las propiedades obligatorias.
DelegateModel.Qt5ReadWritePermite a los delegados escribir en el modelo a través del objeto ` model ` y de las propiedades de contexto, pero no a través de las propiedades obligatorias.

El valor predeterminado es ` DelegateModel.Qt5ReadWrite`.

Esta propiedad se introdujo en Qt 6.10.

Véase también «Modelos y vistas» en Qt Quick, apartado «Modificación de los datos del modelo».

editTriggers : enumeration [default: TableView.DoubleTapped | TableView.EditKeyPressed., since 6.5]

Esta propiedad recoge las diferentes formas en que el usuario puede comenzar a editar una celda. Puede ser una combinación de los siguientes valores:

ConstanteDescripción
TableView.NoEditTriggers- El usuario no puede iniciar la edición de las celdas. Cuando se establece este valor, TableView no abrirá ni cerrará el delegado de edición en respuesta a ninguna interacción del usuario. Sin embargo, la aplicación puede llamar manualmente a edit() y closeEditor().
TableView.SingleTapped- El usuario puede editar una celda tocándola una vez.
TableView.DoubleTapped- El usuario puede editar una celda tocándola dos veces.
TableView.SelectedTapped- El usuario puede editar un « selected cell » tocándolo.
TableView.EditKeyPressed- El usuario puede editar el « current cell » pulsando una de las teclas de edición. Las teclas de edición las determina el sistema operativo, pero suelen ser « Qt::Key_Enter » y « Qt::Key_Return ».
TableView.AnyKeyPressed- El usuario puede editar el « current cell » pulsando cualquier tecla, excepto las teclas de navegación de la celda. La tecla pulsada también se envía al objeto de foco dentro del « edit delegate ».

Para que TableView.SelectedTapped, TableView.EditKeyPressed y TableView.AnyKeyPressed surtan efecto, TableView debe tener asignado un selection model, ya que dependen de que se haya establecido un current index. Para poder recibir cualquier evento de tecla, TableView también deberá tener QQuickItem::activeFocus.

Al editar una celda, el usuario puede pulsar Qt::Key_Tab o Qt::Key_Backtab para commit los datos y pasar a editar la siguiente celda. Este comportamiento se puede desactivar configurando QQuickItem::activeFocusOnTab en TableView como false.

Nota: Para que una celda sea editable, el delegate debe tener un edit delegate asociado, y el modelo debe devolver Qt::ItemIsEditable desde QAbstractItemModel::flags() (como se muestra a continuación). Si sigues sin poder editar una celda tras activar uno de los desencadenantes especificados, puedes, como ayuda, intentar llamar explícitamente a ` edit()` (por ejemplo, desde un botón o `TapHandler`). Al hacerlo, se mostrará un mensaje de advertencia explicando por qué no se puede editar la celda.

Qt::ItemFlags QAbstractItemModelSubClass::flags(const QModelIndex &index) const override
{
    Q_UNUSED(index)
    return Qt::ItemIsSelectable | Qt::ItemIsEnabled | Qt::ItemIsEditable;
}

Esta propiedad se introdujo en Qt 6.5.

Véase también TableView::editDelegate, TableView::commit y Editing cells.

keyNavigationEnabled : bool [since 6.4]

Esta propiedad se puede configurar para controlar si el usuario debe poder modificar the current index mediante el teclado. El valor por defecto es true.

Nota: Para que TableView admita la navegación mediante el teclado, es necesario asignar un ItemSelectionModel a selectionModel.

Esta propiedad se introdujo en Qt 6.4.

Véase también Keyboard navigation, selectionModel, selectionBehavior, pointerNavigationEnabled y interactive.

leftColumn : int

Esta propiedad contiene la columna situada más a la izquierda que está visible actualmente dentro de la vista.

Véase también rightColumn, topRow y bottomRow.

model : model

Esta propiedad contiene el modelo que proporciona los datos para la tabla.

El modelo proporciona el conjunto de datos que se utiliza para crear los elementos de la vista. Los modelos se pueden crear directamente en QML utilizando TableModel, ListModel, ObjectModel, o bien pueden ser proporcionados por una clase de modelo personalizada en C++. El modelo en C++ debe ser una subclase de QAbstractItemModel o una lista simple.

Véase también Modelos de datos.

pointerNavigationEnabled : bool [since 6.4]

Esta propiedad se puede configurar para controlar si el usuario puede cambiar the current index con el ratón o mediante la función táctil. El valor por defecto es true.

Esta propiedad se introdujo en Qt 6.4.

Véase también selectionModel, keyNavigationEnabled y interactive.

resizableColumns : bool [since 6.5]

Esta propiedad determina si el usuario puede cambiar el tamaño de las columnas arrastrando entre las celdas. El valor por defecto es « false ».

Esta propiedad se introdujo en Qt 6.5.

resizableRows : bool [since 6.5]

Esta propiedad indica si el usuario puede cambiar el tamaño de las filas arrastrando entre las celdas. El valor por defecto es « false ».

Esta propiedad se introdujo en Qt 6.5.

reuseItems : bool

Esta propiedad determina si los elementos instanciados a partir de delegate deben reutilizarse o no. Si se establece en false, se destruyen todos los elementos que se encuentren actualmente en el pool.

Véase también « Reusing items », « TableView::pooled » y « TableView::reused ».

rightColumn : int

Esta propiedad contiene la columna situada más a la derecha que está visible actualmente en la vista.

Véase también leftColumn, topRow y bottomRow.

rowHeightProvider : var

Esta propiedad puede contener una función que devuelva la altura de cada fila del modelo. Se invoca cada vez que TableView necesita conocer la altura de una fila concreta. La función toma un argumento, row, cuya altura necesita conocer TableView.

Desde Qt 5.13, si deseas ocultar una fila concreta, puedes devolver la altura de 0 para esa fila. Si devuelves un número negativo, TableView calcula la altura basándose en los elementos del delegado.

Nota: El ` rowHeightProvider` suele llamarse dos veces cuando una fila está a punto de cargarse (o al realizar el diseño). En primer lugar, para saber si la fila es visible y debe cargarse. Y, en segundo lugar, para determinar la altura de la fila una vez que se han cargado todos los elementos. Si necesitas calcular la altura de la fila en función del tamaño de los elementos delegados, debes esperar a la segunda llamada, cuando se hayan cargado todos los elementos. Puedes comprobarlo llamando a isRowLoaded(row) y, simplemente, devolver -1 si aún no es así.

Véase también columnWidthProvider, isRowLoaded() y Row heights and column widths.

rowSpacing : real

Esta propiedad define el espaciado entre las filas.

El valor por defecto es 0.

rows : int [read-only]

Esta propiedad contiene el número de filas de la tabla.

Nota: « rows » suele ser igual al número de filas del modelo, pero puede diferir temporalmente hasta que se hayan procesado todos los cambios pendientes del modelo.

Esta propiedad es de solo lectura.

selectionBehavior : enumeration [since 6.4]

Esta propiedad se aplica tanto si el usuario puede seleccionar celdas como si puede seleccionar filas o columnas.

ConstanteDescripción
TableView.SelectionDisabledEl usuario no puede realizar selecciones
TableView.SelectCells(Valor por defecto) El usuario puede seleccionar celdas individuales
TableView.SelectRowsEl usuario solo puede seleccionar filas
TableView.SelectColumnsEl usuario solo puede seleccionar columnas

Esta propiedad se introdujo en Qt 6.4.

Véase también Selecting items, selectionMode, selectionModel y keyNavigationEnabled.

selectionMode : enumeration [since 6.6]

Si « selectionBehavior » se establece en « TableView.SelectCells », esta propiedad determina si el usuario puede seleccionar una celda cada vez o varias celdas a la vez. Si « selectionBehavior » se establece en « TableView.SelectRows », esta propiedad determina si el usuario puede seleccionar una fila cada vez o varias filas a la vez. Si « selectionBehavior » se establece en « TableView.SelectColumns », esta propiedad determina si el usuario puede seleccionar una columna cada vez o varias columnas a la vez.

Están disponibles los siguientes modos:

ConstanteDescripción
TableView.SingleSelectionEl usuario puede seleccionar una sola celda, fila o columna.
TableView.ContiguousSelectionEl usuario puede seleccionar un único bloque contiguo de celdas. Una selección existente se puede ampliar o reducir manteniendo pulsada la tecla modificadora « Shift » mientras se selecciona.
TableView.ExtendedSelection(Valor por defecto) El usuario puede seleccionar varios bloques individuales de celdas. Se puede ampliar o reducir una selección existente manteniendo pulsada la tecla modificadora « Shift » mientras se realiza la selección. Se puede iniciar un nuevo bloque de selección sin borrar la selección actual manteniendo pulsada la tecla modificadora « Control » mientras se realiza la selección.

Esta propiedad se introdujo en Qt 6.6.

Véase también Selecting items, selectionBehavior, selectionModel y keyNavigationEnabled.

selectionModel : ItemSelectionModel [since 6.2]

Esta propiedad se puede configurar para controlar qué elementos del delegado deben mostrarse como seleccionados y qué elemento debe mostrarse como actual. Si el delegado tiene definido un ` required property bool selected `, ` TableView ` lo mantendrá sincronizado con el estado de selección del elemento correspondiente del modelo de selección. Si el delegado tiene definido un ` required property bool current `, ` TableView ` lo mantendrá sincronizado con `selectionModel.currentIndex`.

Esta propiedad se introdujo en Qt 6.2.

Véase también Selecting items, SelectionRectangle, keyNavigationEnabled y pointerNavigationEnabled.

syncDirection : Qt::Orientations

Si la propiedad « syncView » está establecida en « TableView », esta propiedad controla la sincronización de la(s) dirección(es) de deslizamiento para ambas tablas. El valor por defecto es « Qt.Horizontal | Qt.Vertical », lo que significa que, si deslizas cualquiera de las tablas en cualquier dirección, la otra tabla se deslizará la misma distancia en la misma dirección.

Esta propiedad y « syncView » pueden utilizarse para que dos «tableViews» se sincronicen entre sí de forma fluida al deslizarlas, independientemente de las diferencias en el sobreimpulso o subimpulso, la velocidad, la aceleración o desaceleración, la animación de rebote, etc.

Un caso de uso típico es hacer que varios encabezados se desplacen junto con la tabla.

Véase también syncView.

syncView : TableView

Si esta propiedad de un ` TableView ` se establece en otro ` TableView`, ambas tablas se sincronizarán en lo que respecta al desplazamiento rápido, los anchos de columna y las alturas de fila, así como al espaciado, de acuerdo con syncDirection.

Si syncDirection contiene Qt.Horizontal, los anchos de columna, el espaciado entre columnas y el desplazamiento horizontal de la tableView actual se sincronizarán con los de syncView.

Si syncDirection contiene Qt.Vertical, las alturas de las filas, el espaciado entre filas y el movimiento de deslizamiento vertical de la tableView actual se sincronizan con los de syncView.

Véase también « syncDirection ».

topRow : int

Esta propiedad contiene la fila más alta que está visible actualmente dentro de la vista.

Véase también leftColumn, rightColumn y bottomRow.

Documentación de la propiedad adjunta

TableView.editDelegate : Component [attached]

Esta propiedad adjunta contiene el delegado de edición. Se instancia al iniciar la edición y se vincula al delegado que edita. Admite las mismas propiedades obligatorias que ` TableView delegate`, incluidas ` index`, ` row ` y ` column`. Las propiedades del modelo, como ` display ` y ` edit`, también están disponibles (dependiendo de la ` role names ` expuesta por el modelo).

La edición comienza cuando se cumplen las condiciones especificadas en editTriggers y la celda actual es editable.

Nota: Para que una celda sea editable, el modelo debe sobrescribir QAbstractItemModel::flags(), y devolver Qt::ItemIsEditable.

También puedes abrir y cerrar el delegado de edición manualmente llamando a edit() y closeEditor(), respectivamente.

La edición finaliza cuando el usuario pulsa Qt::Key_Enter o Qt::Key_Return (y también Qt::Key_Tab o Qt::Key_Backtab, si TableView tiene QQuickItem::activeFocusOnTab establecido). En ese caso, se emitirá la señal « TableView::commit », de modo que el delegado de edición pueda responder escribiendo los datos modificados de nuevo en el modelo. Si la edición finaliza por otros motivos (por ejemplo, si el usuario pulsa « Qt::Key_Escape »), la señal no se emitirá. En cualquier caso, al final se emitirá « destruction()».

Mientras se muestra el delegado de edición, la celda subyacente seguirá siendo visible y, por lo tanto, se verá a través de él si el delegado de edición es translúcido o, de lo contrario, no cubre toda la celda. Si no se desea que esto ocurra, puedes hacer que el elemento raíz del delegado de edición sea opaco ( Rectangle) u ocultar algunos de los elementos dentro del TableView delegate.. Esto último se puede lograr definiendo una propiedad required property bool editing en su interior, que se vincule a la propiedad visible de algunos de los elementos hijos. El siguiente fragmento de código muestra cómo hacerlo en un delegado personalizado:

        delegate: Rectangle {
            implicitWidth: 100
            implicitHeight: 50

            required property bool editing

            Text {
                id: textField
                anchors.fill: parent
                anchors.margins: 5
                text: display
                visible: !editing
            }

            TableView.editDelegate: TextField {
                x: textField.x
                y: textField.y
                width: textField.width
                height: textField.height
                text: display
                TableView.onCommit: display = text
            }
        }

Cuando se instancia el delegado de edición, TableView llamará a QQuickItem::forceActiveFocus() en él. Si prefieres que el foco activo se establezca en un elemento secundario del delegado de edición, haz que el delegado de edición sea un FocusScope.

Por defecto, TableViewDelegate proporciona un delegado de edición, aunque también puedes establecer el tuyo propio:

delegate: TableViewDelegate {
    TableView.editDelegate: TextField {
        width: parent.width
        height: parent.height
        text: display
        TableView.onCommit: display = text
    }
}

Véase también editTriggers, TableView::commit, edit(), closeEditor(), Editing cells y TableViewDelegate.

TableView.view : TableView [attached]

Esta propiedad adjunta contiene la vista que gestiona la instancia del delegado. Se adjunta a cada instancia del delegado.

Documentación de Signal

[since 6.8] columnMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex)

Esta señal se emite cuando se desplaza una columna. El índice lógico de la columna se especifica mediante logicalIndex, el índice anterior mediante oldVisualIndex y la nueva posición del índice mediante newVisualIndex.

Nota: El controlador correspondiente es onColumnMoved.

Esta señal se introdujo en Qt 6.8.

[since 6.5] layoutChanged()

Esta señal se emite cada vez que la disposición de las filas y columnas de loaded pueda haber cambiado. Esto ocurrirá especialmente cuando se llame a forceLayout(), pero también, por ejemplo, al cambiar el tamaño de una fila o una columna, o cuando una fila o columna haya entrado o salido del área de visualización.

Esta señal se puede utilizar, por ejemplo, para actualizar la geometría de las superposiciones.

Nota: El controlador correspondiente es onLayoutChanged.

Esta señal se introdujo en Qt 6.5.

Véase también ` forceLayout()` y ` Overlays and underlays`.

[since 6.8] rowMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex)

Esta señal se emite cuando se desplaza una fila. El índice lógico de la fila se especifica mediante logicalIndex, el índice anterior mediante oldVisualIndex y la nueva posición del índice mediante newVisualIndex.

Nota: El controlador correspondiente es onRowMoved.

Esta señal se introdujo en Qt 6.8.

Documentación adjunta sobre la señal

[attached] commit()

Esta señal la emite el edit delegate

Esta señal adjunta se emite cuando el « edit delegate » está activo y el usuario pulsa « Qt::Key_Enter » o « Qt::Key_Return ». También se emitirá si « TableView » tiene activada la opción « QQuickItem::activeFocusOnTab » y el usuario pulsa « Qt::Key_Tab » o « Qt::Key_Backtab ».

Esta señal no se emitirá si la edición finaliza por motivos distintos a los mencionados. Esto incluye, por ejemplo, si el usuario pulsa Qt::Key_Escape, toca fuera del delegado, se elimina la fila o columna que se está editando, o si la aplicación llama a closeEditor().

Al recibir la señal, el delegado de edición debe volver a escribir en el modelo cualquier dato modificado.

Nota: Esta propiedad debe asociarse a ` edit delegate`, y no a ` delegate`.

Nota: El controlador correspondiente es ` onCommit`.

Véase también TableView::editDelegate, editTriggers y Editing cells.

[attached] pooled()

Esta señal se emite después de que se haya añadido un elemento al conjunto de reutilización. Puedes utilizarla para pausar los temporizadores o animaciones en curso dentro del elemento, o para liberar recursos que no se puedan reutilizar.

Esta señal se emite únicamente si la propiedad « reuseItems » tiene el valor « true ».

Nota: El controlador correspondiente es onPooled.

Véase también Reusing items, reuseItems y reused.

[attached] reused()

Esta señal se emite después de que se haya reutilizado un elemento. En ese momento, el elemento se ha extraído del grupo y se ha colocado dentro de la vista de contenido, y se han actualizado las propiedades del modelo, como el índice, la fila y la columna.

Las demás propiedades que no proporciona el modelo no cambian cuando se reutiliza un elemento. Se debe evitar almacenar cualquier estado dentro de un delegado, pero si se hace, hay que restablecer manualmente ese estado al recibir esta señal.

Esta señal se emite cuando el elemento se reutiliza, y no la primera vez que se crea.

Esta señal se emite únicamente si la propiedad ` reuseItems ` tiene el valor ` true`.

Nota: El controlador correspondiente es ` onReused`.

Véase también Reusing items, reuseItems y pooled.

Documentación del método

[since 6.4] point cellAtIndex(QModelIndex modelIndex)

Devuelve la celda de la vista que se corresponde con un modelIndex o del modelo. Función de conveniencia para realizar lo siguiente:

Qt.point(columnAtIndex(modelIndex), rowAtIndex(modelIndex))

Una celda es simplemente un « point » que combina la fila y la columna en un único tipo.

Nota: ese ` point.x ` se asignará a la columna, y ` point.y ` se asignará a la fila.

Este método se introdujo en Qt 6.4.

Point cellAtPosition(point position, bool includeSpacing)

Devuelve la celda situada en la posición indicada por ` position ` en la tabla. ` position ` debe ser una referencia relativa a ` contentItem`. Si ninguna celda de ` loaded ` se cruza con ` position`, el valor devuelto será ` point(-1, -1)`.

Si includeSpacing se establece en true, se considerará que el rectángulo delimitador de una celda incluye la mitad de los elementos adyacentes rowSpacing y columnSpacing a cada lado. El valor por defecto es false.

Nota: Un controlador de entrada (Input Handler) asociado a un control de entrada ( TableView ) se instala en el contentItem en lugar de en la vista. Por lo tanto, la posición indicada por el controlador puede utilizarse directamente en una llamada a esta función sin necesidad de ningún mapping.

Véase también columnSpacing y rowSpacing.

Point cellAtPosition(real x, real y, bool includeSpacing)

Para facilitar las llamadas, cellAtPosition(Qt.point(x, y), includeSpacing).

[since 6.8] void clearColumnReordering()

Restablece cualquier reordenación de columnas aplicada anteriormente.

Nota: Si se ha establecido un ` syncView `, una llamada a esta función se reenviará al elemento de vista correspondiente y restablecerá el orden de las columnas.

Este método se introdujo en Qt 6.8.

void clearColumnWidths()

Borra todos los anchos de columna establecidos con la función ` setColumnWidth()`.

Nota: Si se ha establecido un valor para « syncView », junto con « Qt.Horizontal » syncDirection, la vista de sincronización controlará los anchos de columna. Por lo tanto, en ese caso, cualquier llamada a esta función se reenviará a la vista de sincronización.

Véase también setColumnWidth(), clearRowHeights() y Row heights and column widths.

void clearRowHeights()

Borra todas las alturas de fila establecidas con la función ` setRowHeight()`.

Nota: Si se ha establecido un valor para « syncView », junto con un valor para « Qt.Vertical » syncDirection, la vista de sincronización controlará las alturas de las filas. Por lo tanto, en ese caso, cualquier llamada a esta función se reenviará a la vista de sincronización.

Véase también setRowHeight(), clearColumnWidths() y Row heights and column widths.

[since 6.8] void clearRowReordering()

Restablece cualquier reordenación de filas aplicada anteriormente.

Nota: Si se ha establecido un ` syncView `, una llamada a esta función se reenviará al elemento de vista correspondiente y restablecerá el orden de las filas.

Este método se introdujo en Qt 6.8.

[since 6.5] void closeEditor()

Si el usuario está editando una celda, al llamar a esta función se detendrá la edición y se eliminará la instancia del delegado de edición.

Este método se introdujo en Qt 6.5.

Véase también edit(), TableView::editDelegate y Editing cells.

[since 6.4] int columnAtIndex(QModelIndex modelIndex)

Devuelve la columna de la vista que se corresponde con « modelIndex » en el modelo.

Este método se introdujo en Qt 6.4.

Véase también ` rowAtIndex()` y ` index()`.

[since 6.2] real columnWidth(int column)

Devuelve la anchura de la columna « column » indicada. Si la columna no está cargada (y, por lo tanto, no es visible), el valor devuelto será « -1 ».

Este método se introdujo en Qt 6.2.

Véase también setColumnWidth(), columnWidthProvider, implicitColumnWidth(), isColumnLoaded() y Row heights and column widths.

[since 6.5] void edit(QModelIndex modelIndex)

Esta función inicia una sesión de edición para la celda que representa modelIndex. Si el usuario ya está editando otra celda, dicha sesión finaliza.

Normalmente, puedes especificar las diferentes formas de iniciar una sesión de edición utilizando editTriggers en su lugar. Si eso no es suficiente, puedes utilizar esta función. Para tener un control total sobre la edición de celdas y evitar que TableView interfiera, configura editTriggers en TableView.NoEditTriggers.

Nota: El valor de « current index » en « selection model » también cambiará a « modelIndex ».

Este método se introdujo en Qt 6.5.

Véase también closeEditor(), editTriggers, TableView::editDelegate y Editing cells.

real explicitColumnWidth(int column)

Devuelve el ancho de la columna « column » establecido con la función « setColumnWidth()». Este ancho puede diferir del ancho real de la columna si se está utilizando un « columnWidthProvider ». Para obtener el ancho real de una columna, utiliza la función « columnWidth()».

Un valor de retorno igual a 0 significa que se ha indicado que la columna se oculte. Un valor de retorno igual a -1 significa que no se ha establecido ningún ancho explícito para la columna.

Nota: Si se establece un valor de « syncView » junto con un « Qt.Horizontal » syncDirection, la vista de sincronización controlará los anchos de las columnas. Por lo tanto, en ese caso, cualquier llamada a esta función se reenviará a la vista de sincronización.

Véase también setColumnWidth(), columnWidth() y Row heights and column widths.

real explicitRowHeight(int row)

Devuelve la altura del « row » establecida con « setRowHeight()». Esta altura puede diferir de la altura real de la columna si se está utilizando un « rowHeightProvider ». Para obtener la altura real de una fila, utiliza « rowHeight()».

Un valor de retorno igual a 0 significa que se ha indicado que la fila se oculte. Un valor de retorno igual a -1 significa que no se ha establecido ninguna altura explícita para la fila.

Nota: Si se establece un valor de « syncView » junto con un « Qt.Vertical » syncDirection, la vista de sincronización controlará las alturas de las filas. Por lo tanto, en ese caso, cualquier llamada a esta función se reenviará a la vista de sincronización.

Véase también setRowHeight(), rowHeight() y Row heights and column widths.

void forceLayout()

Las respuestas a los cambios en el modelo se agrupan por lotes, de modo que solo se procesan una vez por fotograma. Esto significa que el TableView retrasa la visualización de cualquier cambio mientras se ejecuta un script. Lo mismo ocurre al modificar propiedades como rowSpacing o leftMargin.

Este método obliga a TableView a actualizar inmediatamente el diseño para que surtan efecto los cambios recientes.

Al llamar a esta función, se vuelven a evaluar el tamaño y la posición de cada fila y columna visible. Esto es necesario si las funciones asignadas a rowHeightProvider o columnWidthProvider devuelven valores diferentes a los que ya están asignados.

[since 6.2] real implicitColumnWidth(int column)

Devuelve el ancho implícito del objeto ` column` dado. Se trata del mayor valor de ` implicitWidth ` que se encuentre entre los elementos del delegado ` loaded ` actuales dentro de esa columna.

Si el column no está cargado (y, por lo tanto, no es visible), el valor devuelto es -1.

Este método se introdujo en Qt 6.2.

Véase también columnWidth(), isRowLoaded() y Row heights and column widths.

[since 6.2] real implicitRowHeight(int row)

Devuelve la altura implícita de la ` row` indicada. Se trata del mayor valor de ` implicitHeight ` que se encuentre entre los elementos del delegado ` loaded ` que se encuentran actualmente dentro de esa fila.

Si el row no está cargado (y, por lo tanto, no es visible), el valor devuelto es -1.

Este método se introdujo en Qt 6.2.

Véase también rowHeight(), isColumnLoaded() y Row heights and column widths.

[since 6.4.3] QModelIndex index(int row, int column)

Devuelve el objeto ` QModelIndex ` que se corresponde con ` row ` y ` column ` en la vista.

row Y « column » debe corresponder a la fila y la columna de la vista (fila y columna de la tabla), y no a una fila y una columna del modelo. Para un ` TableView` simple, esto equivale a llamar a ` model.index(row, column). `. Sin embargo, para una subclase de ` TableView`, como ` TreeView`, en la que el modelo de datos está envuelto dentro de un modelo proxy interno que aplana la estructura de árbol en una tabla, es necesario utilizar esta función para resolver el índice del modelo.

Este método se introdujo en Qt 6.4.3.

Véase también rowAtIndex() y columnAtIndex().

[since 6.2] bool isColumnLoaded(int column)

Devuelve un objeto ` true ` si se ha cargado el objeto ` column ` indicado.

Una columna se considera cargada cuando TableView ha cargado los elementos delegados necesarios para mostrar la columna dentro de la vista. Esto suele significar también que la columna es visible para el usuario, aunque no siempre es así.

Esta función se puede utilizar siempre que se necesite iterar sobre los elementos delegados de una columna, por ejemplo, desde un ` columnWidthProvider`, para asegurarse de que los elementos delegados están disponibles para la iteración.

Este método se introdujo en Qt 6.2.

[since 6.2] bool isRowLoaded(int row)

Devuelve ` true ` si el ` row ` indicado está cargado.

Una fila se considera cargada cuando TableView ha cargado los elementos delegados necesarios para mostrar la fila dentro de la vista. Esto suele significar también que la fila es visible para el usuario, aunque no siempre es así.

Esta función se puede utilizar siempre que sea necesario recorrer los elementos delegados de una fila, por ejemplo, desde un ` rowHeightProvider`, para asegurarse de que dichos elementos estén disponibles para su iteración.

Este método se introdujo en Qt 6.2.

Item itemAtCell(point cell)

Devuelve el elemento delegado en ` cell ` si está cargado; de lo contrario, ` null`.

Nota: normalmentesolo se cargan los elementos que están visibles en la vista. En cuanto una celda se desplaza fuera de la vista, el elemento que contiene se descargará o se colocará en el grupo de reciclaje. Por lo tanto, el valor devuelto nunca debe almacenarse.

[since 6.5] Item itemAtIndex(QModelIndex index)

Devuelve el elemento delegado instanciado para la celda que representa index. Si el elemento no es loaded, el valor será null.

Nota: normalmentesolo se cargan los elementos que están visibles en la vista. En cuanto una celda se desplaza fuera de la vista, el elemento que contiene se descargará o se colocará en el pool de reciclaje. Por lo tanto, el valor devuelto nunca debe almacenarse.

Nota: Si el ` model ` no es un ` QAbstractItemModel`, también puedes utilizar ` itemAtCell(Qt.point(columna, fila)`. Pero ten en cuenta que ` point.x ` se corresponde con las columnas y ` point.y ` con las filas.

Este método se introdujo en Qt 6.5.

[since 6.4] QModelIndex modelIndex(point cell)

Función práctica para realizar lo siguiente:

index(cell.y, cell.x)

Un « cell » es simplemente un « point » que combina la fila y la columna en un único tipo.

Nota: « point.x » se asignará a la columna, y « point.y » se asignará a la fila.

Este método se introdujo en Qt 6.4.

Véase también index().

[since 6.8] void moveColumn(int source, int destination)

Mueve una columna desde la posición « source » a la posición « destination ».

Nota: Si se ha establecido una posición de inicio ( syncView ), la vista de sincronización controlará la asignación del índice interno para la reordenación de columnas. Por lo tanto, en ese caso, la llamada a esta función se reenviará a la vista de sincronización.

Este método se introdujo en Qt 6.8.

[since 6.8] void moveRow(int source, int destination)

Mueve una fila desde la posición source a la posición destination.

Nota: Si se ha establecido un « syncView », la vista de sincronización controlará la asignación del índice interno para la reorganización de filas. Por lo tanto, en ese caso, la llamada a esta función se reenviará a la vista de sincronización.

Este método se introdujo en Qt 6.8.

void positionViewAtCell(point cell, PositionMode mode, point offset, rect subRect)

Posiciones contentX y contentY, de modo que cell se encuentre en la posición especificada por mode. mode puede ser una combinación mediante el operador «OR» de lo siguiente:

ConstanteDescripción
TableView.AlignLeftColoca la celda a la izquierda de la vista.
TableView.AlignHCenterColoca la celda en el centro horizontal de la vista.
TableView.AlignRightColoca la celda a la derecha de la vista.
TableView.AlignTopColoca la celda en la parte superior de la vista.
TableView.AlignVCenterColoca la celda en el centro vertical de la vista.
TableView.AlignBottomColoca la celda en la parte inferior de la vista.
TableView.AlignCenterEs lo mismo que (TableView.AlignHCenter | TableView.AlignVCenter)
TableView.VisibleSi alguna parte de la celda es visible, no realice ninguna acción. De lo contrario, mueva el elemento de contenido para que toda la celda quede visible.
TableView.ContainSi toda la celda está visible, no se realiza ninguna acción. De lo contrario, se desplaza el elemento de contenido para que toda la celda quede visible. Si la celda es más grande que la vista, se dará preferencia a la parte superior izquierda de la celda.

Si no se especifica ninguna alineación vertical, se ignorará el posicionamiento vertical. Lo mismo ocurre con la alineación horizontal.

Opcionalmente, puedes especificar ` offset ` para desplazar `contentX ` y `contentY` una cantidad adicional de píxeles más allá de la alineación de destino. Por ejemplo, si quieres colocar la vista de manera que la celda [10, 10] quede en la esquina superior izquierda con un margen de 5 píxeles, podrías hacer lo siguiente:

positionViewAtCell(Qt.point(10, 10), TableView.AlignLeft | TableView.AlignTop, Qt.point(-5, -5))

A partir de Qt 6.4, puedes especificar un « subRect » para posicionar en un rectángulo dentro de « cell », en lugar de en el rectángulo delimitador de toda la celda. Esto puede resultar útil si, por ejemplo, la celda es más grande que la vista y quieres asegurarte de que una parte específica de la misma quede visible. El « subRect » debe ser « valid » para que se tenga en cuenta.

Nota: Nose recomienda utilizar contentX o contentY para situar la vista en una celda concreta. Esto no es fiable, ya que eliminar elementos del principio de la tabla no provoca que se reubiquen todos los demás elementos. Además, TableView a veces puede situar filas y columnas en posiciones aproximadas para optimizar la velocidad. La única excepción es si la celda ya está visible en la vista, lo cual se puede comprobar de antemano llamando a ` itemAtCell()`.

Los métodos solo deben invocarse una vez que el componente haya finalizado. Para posicionar la vista al inicio, este método debe ser invocado por `Component.onCompleted`. Por ejemplo, para posicionar la vista al final:

Component.onCompleted: positionViewAtCell(Qt.point(columns - 1, rows - 1), TableView.AlignRight | TableView.AlignBottom)

Nota: El segundo argumento de esta función solía ser Qt.Alignment. Por motivos de compatibilidad con versiones anteriores, esa enumeración todavía se puede utilizar. El cambio para utilizar PositionMode se realizó en Qt 6.4.

Véase también animate.

void positionViewAtColumn(int column, PositionMode mode, real offset, rect subRect)

Posiciona contentX de tal forma que column se encuentre en la posición especificada por mode, offset y subRect.

Método de conveniencia para llamar a

positionViewAtCell(Qt.point(column, 0), mode & Qt.AlignHorizontal_Mask, offset, subRect)

[since 6.5] void positionViewAtIndex(QModelIndex index, PositionMode mode, point offset, rect subRect)

Coloca la vista de tal forma que index se encuentre en la posición especificada por mode, offset y subRect.

Método de conveniencia para llamar a

positionViewAtRow(rowAtIndex(index), mode & Qt.AlignVertical_Mask, offset.y, subRect)
positionViewAtColumn(columnAtIndex(index), mode & Qt.AlignVertical_Mask, offset.x, subRect)

Este método se introdujo en Qt 6.5.

void positionViewAtRow(int row, PositionMode mode, real offset, rect subRect)

Posiciona contentY de tal forma que row se encuentre en la posición especificada por mode, offset y subRect.

Método de conveniencia para llamar a

positionViewAtCell(Qt.point(0, row), mode & Qt.AlignVertical_Mask, offset, subRect)

[since 6.4] int rowAtIndex(QModelIndex modelIndex)

Devuelve la fila de la vista que se corresponde con « modelIndex » en el modelo.

Este método se introdujo en Qt 6.4.

Véase también ` columnAtIndex()` y ` index()`.

[since 6.2] real rowHeight(int row)

Devuelve la altura del ` row` indicado. Si la fila no está cargada (y, por lo tanto, no es visible), el valor devuelto será ` -1`.

Este método se introdujo en Qt 6.2.

Véase también setRowHeight(), rowHeightProvider, implicitRowHeight(), isRowLoaded() y Row heights and column widths.

void setColumnWidth(int column, real size)

Establece el ancho explícito de la columna « column » en « size ».

Si desea recuperar los valores establecidos con esta función, debe utilizar explicitColumnWidth(). columnWidth() devolverá el tamaño real de la columna, que puede ser diferente si se ha establecido un columnWidthProvider.

Cuando TableView necesita determinar el ancho de column, primero intentará llamar a columnWidthProvider. Solo si no se ha configurado ningún proveedor, se utilizarán por defecto los anchos establecidos con esta función. No obstante, puedes llamar a ` explicitColumnWidth()` desde el propio proveedor y, si es necesario, ajustar los valores para que, por ejemplo, se mantengan siempre dentro de un intervalo determinado. El siguiente fragmento de código muestra un ejemplo de cómo hacerlo:

columnWidthProvider: function(column) {
    let w = explicitColumnWidth(column)
    if (w >= 0)
        return Math.max(100, w);
    return implicitColumnWidth(column)
}

Si size es igual a 0, la columna quedará oculta. Si size es igual a -1, la columna se restablecerá para que utilice implicitColumnWidth(). Se permite especificar tamaños de columna para columnas que superen el tamaño del modelo.

Nota: Los tamaños que se establezcan no se borrarán si se cambia el valor de « model ». Para borrar los tamaños, es necesario llamar explícitamente a « clearColumnWidths()».

Nota: Si se establece un ` syncView `, junto con un ` Qt.Horizontal ` syncDirection, la vista de sincronización controlará los anchos de columna. Por lo tanto, en ese caso, cualquier llamada a esta función se reenviará a la vista de sincronización.

Nota: En modelos con muchas columnas, utilizar setColumnWidth() para establecer los anchos de todas las columnas al inicio puede no ser la mejor opción. Esto consumirá tiempo de inicio y memoria (para almacenar todos los anchos). Un enfoque más escalable consiste en utilizar una ` columnWidthProvider ` en su lugar, o basarse en el ancho implícito del delegado. Una ` columnWidthProvider ` solo se llamará cuando sea necesario y no se verá afectada por el tamaño del modelo.

Véase también columnWidth(), explicitColumnWidth(), setRowHeight(), clearColumnWidths() y Row heights and column widths.

void setRowHeight(int row, real size)

Establece la altura explícita de la fila « row » en « size ».

Si deseas recuperar los valores que has establecido con esta función, debes utilizar explicitRowHeight(). rowHeight() devolverá la altura real de la fila, que puede ser diferente si se ha establecido un rowHeightProvider.

Cuando TableView necesite calcular la altura de row, intentará primero llamar a rowHeightProvider. Solo si no se ha establecido ningún proveedor, se utilizarán por defecto las alturas establecidas con esta función. No obstante, puedes llamar a ` explicitRowHeight()` desde el propio proveedor y, si es necesario, ajustar los valores para que, por ejemplo, se mantengan siempre dentro de un intervalo determinado. El siguiente fragmento de código muestra un ejemplo de cómo hacerlo:

rowHeightProvider: function(row) {
    let h = explicitRowHeight(row)
    if (h >= 0)
        return Math.max(100, h);
    return implicitRowHeight(row)
}

Si size es igual a 0, la fila quedará oculta. Si size es igual a -1, la fila se restablecerá para que utilice implicitRowHeight(). Se permite especificar tamaños de fila para aquellas filas que se encuentren fuera del tamaño del modelo.

Nota: Los tamaños que se establezcan no se borrarán si se cambia el valor de « model ». Para borrar los tamaños, es necesario llamar explícitamente a « clearRowHeights()».

Nota: Si se establece un ` syncView `, junto con un ` Qt.Vertical ` syncDirection, la vista de sincronización controlará las alturas de las filas. Por lo tanto, en ese caso, cualquier llamada a esta función se reenviará a la vista de sincronización.

Nota: En modelos con muchas filas, utilizar setRowHeight() para establecer las alturas de todas las filas al inicio puede no ser la mejor opción. Esto consumirá tiempo de inicio y memoria (para almacenar todas las alturas). Un enfoque más escalable consiste en utilizar en su lugar un ` rowHeightProvider ` o basarse en la altura implícita del delegado. Un ` rowHeightProvider ` solo se llamará cuando sea necesario y no se verá afectado por el tamaño del modelo.

Véase también « rowHeight()», « explicitRowHeight()», « setColumnWidth()» y « Row heights and column widths ».

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