Back to Qt.io
Contact Us Blog Download Qt
En esta página

TableModel QML Type

Encapsula un modelo de tabla simple. Más...

Import Statement: import Qt.labs.qmlmodels

Propiedades

Métodos

  • void appendRow(var row)
  • void clear()
  • variant data(QModelIndex index, string role)
  • var getRow(int rowIndex)
  • QModelIndex index(int row, int column)
  • void insertRow(int rowIndex, var row)
  • void moveRow(int fromRowIndex, int toRowIndex, int rows)
  • void removeRow(int rowIndex, int rows)
  • bool setData(QModelIndex index, variant value, string role)
  • void setRow(int rowIndex, var row)

Descripción detallada

El tipo TableModel almacena objetos JavaScript/JSON como datos para un modelo de tabla que se puede utilizar con TableView. Está pensado para soportar modelos muy sencillos sin necesidad de crear una subclase personalizada QAbstractTableModel en C++.

import QtQuick
import QtQuick.Window
import Qt.labs.qmlmodels

Window {
    width: 400
    height: 400
    visible: true

    TableView {
        anchors.fill: parent
        columnSpacing: 1
        rowSpacing: 1
        boundsBehavior: Flickable.StopAtBounds

        model: TableModel {
            TableModelColumn { display: "checked" }
            TableModelColumn { display: "amount" }
            TableModelColumn { display: "fruitType" }
            TableModelColumn { display: "fruitName" }
            TableModelColumn { display: "fruitPrice" }

            // Each row is one type of fruit that can be ordered
            rows: [
                {
                    // Each property is one cell/column.
                    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
                }
            ]
        }
        delegate:  TextInput {
            text: model.display
            padding: 12
            selectByMouse: true

            onAccepted: model.display = text

            Rectangle {
                anchors.fill: parent
                color: "#efefef"
                z: -1
            }
        }
    }
}

Los datos iniciales de la fila del modelo se establecen con la propiedad rows o llamando a appendRow(). Cada columna del modelo se especifica declarando una instancia de TableModelColumn, donde el orden de cada instancia determina su índice de columna. Una vez emitida la señal Component::completed() del modelo, se habrán establecido las columnas y los roles, que quedarán fijados para toda la vida del modelo.

Para acceder a una fila concreta, se puede utilizar la función getRow(). También es posible acceder directamente a los datos JavaScript del modelo a través de la propiedad rows, pero no es posible modificar los datos del modelo de esta forma.

Para añadir nuevas filas, utilice appendRow() y insertRow(). Para modificar filas existentes, utilice setRow(), moveRow(), removeRow() y clear().

También es posible modificar los datos del modelo a través del delegado, como se muestra en el ejemplo anterior:

        delegate:  TextInput {
            text: model.display
            padding: 12
            selectByMouse: true

            onAccepted: model.display = text

            Rectangle {
                anchors.fill: parent
                color: "#efefef"
                z: -1
            }
        }

Si el tipo de los datos en la función modificada no coincide con el tipo de los datos que se establecen, se convertirán automáticamente a través de QVariant.

Estructuras de datos de fila compatibles

TableModel está diseñado para trabajar con datos JavaScript/JSON, donde cada fila es una lista de simples pares clave-valor:

{
    // Each property is one cell/column.
    checked: false,
    amount: 1,
    fruitType: "Apple",
    fruitName: "Granny Smith",
    fruitPrice: 1.50
},
// ...

Como la manipulación del modelo en Qt se realiza mediante índices de fila y columna, y como las claves de los objetos no están ordenadas, cada columna debe especificarse mediante TableModelColumn. Esto permite mapear los roles incorporados de Qt a cualquier propiedad de cada objeto fila.

Se admiten estructuras de filas complejas, pero con funcionalidad limitada. Como TableModel no tiene forma de saber cómo está estructurada cada fila, no puede manipularla. Como consecuencia de ello, la copia de los datos del modelo que TableModel ha almacenado en rows no se mantiene sincronizada con los datos de origen que se establecieron en QML. Por estas razones, la manipulación de los datos no está soportada.

Por ejemplo, supongamos que desea utilizar una fuente de datos en la que cada fila es una matriz y cada celda es un objeto. Para utilizar esta fuente de datos con TableModel, defina un getter:

TableModel {
    TableModelColumn {
        display: function(modelIndex) { return rows[modelIndex.row][0].checked }
    }
    // ...

    rows: [
        [
            { checked: false, checkable: true },
            { amount: 1 },
            { fruitType: "Apple" },
            { fruitName: "Granny Smith" },
            { fruitPrice: 1.50 }
        ]
        // ...
    ]
}

La fila anterior es un ejemplo de fila compleja.

Nota: Las funciones de manipulación de filas como appendRow(), removeRow(), etc. no son compatibles cuando se utilizan filas complejas.

Uso de DelegateChooser con TableModel

Para la mayoría de los casos de uso del mundo real, se recomienda utilizar DelegateChooser como delegado de un TableView que utilice TableModel. Esto permite utilizar funciones específicas en los delegados correspondientes. Por ejemplo, el fragmento anterior puede reescribirse para utilizar DelegateChooser de la siguiente manera:

import QtQuick
import QtQuick.Controls
import Qt.labs.qmlmodels

ApplicationWindow {
    width: 400
    height: 400
    visible: true

    TableView {
        anchors.fill: parent
        columnSpacing: 1
        rowSpacing: 1
        boundsBehavior: Flickable.StopAtBounds

        model: TableModel {
            TableModelColumn { display: "checked" }
            TableModelColumn { display: "amount" }
            TableModelColumn { display: "fruitType" }
            TableModelColumn { display: "fruitName" }
            TableModelColumn { display: "fruitPrice" }

            // Each row is one type of fruit that can be ordered
            rows: [
                {
                    // Each property is one cell/column.
                    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
                }
            ]
        }
        delegate: DelegateChooser {
            DelegateChoice {
                column: 0
                delegate: CheckBox {
                    checked: model.display
                    onToggled: model.display = checked
                }
            }
            DelegateChoice {
                column: 1
                delegate: SpinBox {
                    value: model.display
                    onValueModified: model.display = value
                }
            }
            DelegateChoice {
                delegate: TextField {
                    text: model.display
                    selectByMouse: true
                    implicitWidth: 140
                    onAccepted: model.display = text
                }
            }
        }
    }
}

Los delegados más específicos se declaran primero: las columnas en el índice 0 y 1 tienen tipos de datos bool y integer, por lo que utilizan un CheckBox y SpinBox, respectivamente. Las columnas restantes pueden utilizar simplemente un TextField, por lo que ese delegado se declara en último lugar como alternativa.

Uso de TableModel con fuentes JSON externas

Si la estructura de los datos de un objeto JSON coincide con la estructura definida por el TableModel, puede asignarse directamente al modelo utilizando la propiedad rows. Todas las filas de los datos deben ajustarse a las columnas definidas por el modelo.

Por ejemplo, si el modelo se define como:

            model: TableModel {
                TableModelColumn { display: "driverId" }
                TableModelColumn { display: "code" }
                TableModelColumn { display: "url" }
                TableModelColumn { display: "givenName" }
                TableModelColumn { display: "familyName" }
                TableModelColumn { display: "dateOfBirth" }
                TableModelColumn { display: "nationality" }
            }

La fuente tiene los datos requeridos pero no necesariamente en la estructura requerida, puede descargarlos y parsearlos en un formulario que se ajuste a la estructura que define el modelo y asignar el resultado directamente.

    function requestJson() {
        let doc = new XMLHttpRequest()
        doc.onreadystatechange = function() {
            if (doc.readyState === XMLHttpRequest.DONE) {
                var root = JSON.parse(doc.responseText)
                var race = root.MRData.RaceTable.Races[0]
                var raceResults = race.Results
                var drivers = []
                for (let i = 0; i < raceResults.length; ++i) {
                    drivers.push(raceResults[i].Driver)
                }
                tableView.model.rows = drivers
                print(JSON.stringify(drivers))
            }
        }

        doc.open("GET", "https://api.jolpi.ca/ergast/f1/2005/1/results.json")
        doc.send()
    }

y el resultado se puede asignar directamente

    Component.onCompleted: requestJson()

También puede proporcionar el objeto JSON importando un archivo JavaScript como módulo. Consulte la documentación de TreeModel para ver un ejemplo de cómo hacerlo.

Atención: Asegúrese de que los datos JSON provienen de una fuente de confianza. Dado que el modelo rellena dinámicamente sus filas basándose en la entrada, un JSON malformado o que no sea de confianza puede provocar un comportamiento inesperado o problemas de rendimiento.

Véase también TableModelColumn, TableView, y QAbstractTableModel.

Documentación de propiedades

columnCount : int [read-only]

Esta propiedad de sólo lectura contiene el número de columnas del modelo.

El número de columnas es fijo durante toda la vida del modelo después de que se establezca la propiedad rows o se llame a appendRow() por primera vez.

rowCount : int [read-only]

Esta propiedad de sólo lectura contiene el número de filas del modelo.

Este valor cambia cada vez que se añaden o eliminan filas del modelo.

rows : var

Esta propiedad contiene los datos del modelo en forma de matriz de filas:

            rows: [
                {
                    // Each property is one cell/column.
                    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
                }
            ]

Véase también getRow(), setRow(), moveRow(), appendRow(), insertRow(), clear(), rowCount, y columnCount.

Documentación del método

void appendRow(var row)

Añade una nueva fila al final del modelo, con los valores (celdas) en row.

model.appendRow({
    checkable: true,
    amount: 1,
    fruitType: "Pear",
    fruitName: "Williams",
    fruitPrice: 1.50,
})

Véase también insertRow(), setRow() y removeRow().

void clear()

Elimina todas las filas del modelo.

Véase también removeRow().

variant data(QModelIndex index, string role)

Devuelve los datos de la celda de la tabla en el index dado perteneciente al role dado.

Véase también index() y setData().

var getRow(int rowIndex)

Devuelve la fila en rowIndex en el modelo.

Tenga en cuenta que esto equivale a acceder a la fila directamente a través de la propiedad rows:

Component.onCompleted: {
    // These two lines are equivalent.
    console.log(model.getRow(0).display);
    console.log(model.rows[0].fruitName);
}

Nota: el objeto devuelto no puede utilizarse para modificar el contenido del modelo; utilice en su lugar setRow().

Véase también setRow(), appendRow(), insertRow(), removeRow() y moveRow().

QModelIndex index(int row, int column)

Devuelve un objeto QModelIndex que hace referencia a las celdas row y column, que pueden pasarse a la función data() para obtener los datos de esa celda, o a setData() para editar el contenido de esa celda.

import QtQml 2.14
import Qt.labs.qmlmodels 1.0

TableModel {
    id: model

    TableModelColumn { display: "fruitType" }
    TableModelColumn { display: "fruitPrice" }

    rows: [
        { fruitType: "Apple", fruitPrice: 1.50 },
        { fruitType: "Orange", fruitPrice: 2.50 }
    ]

    Component.onCompleted: {
        for (var r = 0; r < model.rowCount; ++r) {
            console.log("An " + model.data(model.index(r, 0)).display +
                        " costs " + model.data(model.index(r, 1)).display.toFixed(2))
        }
    }
}

Ver también QModelIndex y Clases relacionadas en QML y data().

void insertRow(int rowIndex, var row)

Añade una nueva fila al modelo en la posición rowIndex, con los valores (celdas) en row.

model.insertRow(2, {
    checkable: true, checked: false,
    amount: 1,
    fruitType: "Pear",
    fruitName: "Williams",
    fruitPrice: 1.50,
})

rowIndex debe apuntar a un elemento existente en la tabla, o a uno pasado el final de la tabla (equivalente a appendRow()).

Véase también appendRow(), setRow(), removeRow() y rowCount.

void moveRow(int fromRowIndex, int toRowIndex, int rows)

Mueve rows del índice en fromRowIndex al índice en toRowIndex.

Los rangos desde y hasta deben existir; por ejemplo, para mover los 3 primeros elementos al final de la lista:

model.moveRow(0, model.rowCount - 3, 3)

Véase también appendRow(), insertRow(), removeRow() y rowCount.

void removeRow(int rowIndex, int rows = 1)

Elimina un número de rows en rowIndex del modelo.

Véase también clear() y rowCount.

bool setData(QModelIndex index, variant value, string role)

Inserta o actualiza el campo de datos nombrado por role en la celda de la tabla en el index dado con value. Devuelve true si tiene éxito, false si no.

Véase también data() y index().

void setRow(int rowIndex, var row)

Cambia la fila en rowIndex en el modelo con row.

Todas las columnas/celdas deben estar presentes en row, y en el orden correcto.

model.setRow(0, {
    checkable: true,
    amount: 1,
    fruitType: "Pear",
    fruitName: "Williams",
    fruitPrice: 1.50,
})

Si rowIndex es igual a rowCount(), se añade una nueva fila al modelo. En caso contrario, rowIndex debe apuntar a una fila existente en el modelo.

Véase también appendRow(), insertRow() y rowCount.

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