Back to Qt.io
Contact Us Blog Download Qt
Sur cette page

TableModel QML Type

Encapsule un modèle de table simple. En savoir plus…

Import Statement: import Qt.labs.qmlmodels

Propriétés

Méthodes

  • 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)

Description détaillée

Le type TableModel stocke des objets JavaScript/JSON en tant que données pour un modèle de tableau pouvant être utilisé avec TableView. Il est destiné à prendre en charge des modèles très simples sans nécessiter la création d'une sous-classe personnalisée de 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
            }
        }
    }
}

Les données de la ligne initiale du modèle sont définies soit via la propriété ` rows `, soit en appelant la fonction ` appendRow()`. Chaque colonne du modèle est spécifiée en déclarant une instance de ` TableModelColumn `, l'ordre de ces instances déterminant l'index de chaque colonne. Une fois que le signal ` Component::completed()` du modèle a été émis, les colonnes et leurs rôles sont établis et restent fixes pendant toute la durée de vie du modèle.

Pour accéder à une ligne spécifique, on peut utiliser la fonction getRow(). Il est également possible d’accéder directement aux données JavaScript du modèle via la propriété rows, mais il n’est pas possible de modifier les données du modèle de cette manière.

Pour ajouter de nouvelles lignes, utilisez appendRow() et insertRow(). Pour modifier des lignes existantes, utilisez setRow(), moveRow(), removeRow() et clear().

Il est également possible de modifier les données du modèle via le délégué, comme le montre l’exemple ci-dessus :

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

            onAccepted: model.display = text

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

Si le type des données au niveau du rôle modifié ne correspond pas au type des données définies, celles-ci seront automatiquement converties via QVariant.

Structures de données de ligne prises en charge

TableModel est conçu pour fonctionner avec des données JavaScript/JSON, où chaque ligne est une liste de paires clé-valeur simples :

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

Comme la manipulation des modèles dans Qt s'effectue via des indices de ligne et de colonne, et que les clés des objets ne sont pas ordonnées, chaque colonne doit être spécifiée via ` TableModelColumn`. Cela permet de mapper les rôles intégrés de Qt à n'importe quelle propriété de chaque objet de ligne.

Les structures de lignes complexes sont prises en charge, mais avec des fonctionnalités limitées. Comme TableModel n'a aucun moyen de savoir comment chaque ligne est structurée, il ne peut pas la manipuler. En conséquence, la copie des données du modèle que TableModel a stockée dans ` rows ` n’est pas synchronisée avec les données sources définies dans QML. Pour ces raisons, la manipulation des données n’est pas prise en charge.

Par exemple, supposons que vous souhaitiez utiliser une source de données où chaque ligne est un tableau et chaque cellule un objet. Pour utiliser cette source de données avec TableModel, définissez un accesseur :

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 ligne ci-dessus est un exemple de ligne complexe.

Remarque : les fonctions de manipulationde lignes telles que ` appendRow()`, ` removeRow()`, etc. ne sont pas prises en charge lors de l’utilisation de lignes complexes.

Utilisation de DelegateChooser avec TableModel

Dans la plupart des cas d’utilisation concrets, il est recommandé d’utiliser DelegateChooser comme délégué d’un TableView qui utilise TableModel. Cela vous permet d’utiliser des rôles spécifiques dans les délégués concernés. Par exemple, l’extrait de code ci-dessus peut être réécrit pour utiliser DelegateChooser comme suit :

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
                }
            }
        }
    }
}

Les délégués les plus spécifiques sont déclarés en premier : les colonnes aux indices 0 et 1 ont respectivement les types de données bool et integer; elles utilisent donc respectivement CheckBox et SpinBox. Les colonnes restantes peuvent simplement utiliser TextField; ce délégué est donc déclaré en dernier, en tant que solution de secours.

Utilisation de TableModel avec des sources JSON externes

Si la structure des données d’un objet JSON correspond à celle définie par le TableModel, cet objet peut être directement affecté au modèle à l’aide de la propriété `rows`. Toutes les lignes des données doivent respecter les colonnes définies par le modèle.

Par exemple, si le modèle est défini comme suit :

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

Si la source contient les données requises mais pas nécessairement dans la structure requise, vous pouvez les télécharger et les analyser pour les mettre au format conforme à la structure définie par le modèle, puis affecter directement le résultat.

    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()
    }

et le résultat peut être attribué directement

    Component.onCompleted: requestJson()

Vous pouvez également fournir l’objet JSON en important un fichier JavaScript en tant que module. Consultez la documentation relative à TreeModel pour découvrir un exemple illustrant cette procédure.

Avertissement : assurez-vous que les données JSON proviennent d’une source fiable. Étant donné que le modèle remplit dynamiquement ses lignes en fonction des données d’entrée, un JSON mal formé ou non fiable peut entraîner un comportement inattendu ou des problèmes de performances.

Voir également TableModelColumn, TableView et QAbstractTableModel.

Documentation sur les propriétés

columnCount : int [read-only]

Cette propriété en lecture seule contient le nombre de colonnes du modèle.

Le nombre de colonnes est fixe pendant toute la durée de vie du modèle après la définition de la propriété ` rows ` ou le premier appel de la méthode ` appendRow()`.

rowCount : int [read-only]

Cette propriété en lecture seule contient le nombre de lignes du modèle.

Cette valeur change chaque fois que des lignes sont ajoutées ou supprimées du modèle.

rows : var

Cette propriété contient les données du modèle sous la forme d'un tableau de lignes :

            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
                }
            ]

Voir également getRow(), setRow(), moveRow(), appendRow(), insertRow(), clear(), rowCount et columnCount.

Documentation des méthodes

void appendRow(var row)

Ajoute une nouvelle ligne à la fin du modèle, avec les valeurs (cellules) contenues dans row.

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

Voir également insertRow(), setRow() et removeRow().

void clear()

Supprime toutes les lignes du modèle.

Voir également removeRow().

variant data(QModelIndex index, string role)

Renvoie les données de la cellule du tableau située à l'index indiquée et appartenant à l'role spécifiée.

Voir également index() et setData().

var getRow(int rowIndex)

Renvoie la ligne située à l'adresse rowIndex dans le modèle.

Notez que cela revient à accéder directement à la ligne via la propriété ` rows ` :

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

Remarque : l'objet renvoyé ne peut pas être utilisé pour modifier le contenu du modèle ; utilisez plutôt setRow().

Voir également setRow(), appendRow(), insertRow(), removeRow() et moveRow().

QModelIndex index(int row, int column)

Renvoie un objet ` QModelIndex ` faisant référence aux éléments ` row ` et ` column` indiqués, qui peut être transmis à la fonction ` data()` pour récupérer les données de cette cellule, ou à la fonction ` setData()` pour modifier le contenu de cette cellule.

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))
        }
    }
}

Voir également QModelIndex et les classes associées dans QML, ainsi que les fonctions data().

void insertRow(int rowIndex, var row)

Ajoute une nouvelle ligne au modèle à la position rowIndex, avec les valeurs (cellules) contenues dans row.

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

L'rowIndex doit pointer vers un élément existant dans le tableau, ou vers un élément situé au-delà de la fin du tableau (ce qui équivaut à appendRow()).

Voir également appendRow(), setRow(), removeRow() et rowCount.

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

Déplace l'rows de l'index situé à l'adresse fromRowIndex vers l'index situé à l'adresse toRowIndex.

Les plages « from » et « to » doivent exister ; par exemple, pour déplacer les 3 premiers éléments à la fin de la liste :

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

Voir également appendRow(), insertRow(), removeRow() et rowCount.

void removeRow(int rowIndex, int rows = 1)

Supprime du modèle un certain nombre d'rows s disponibles à l'adresse rowIndex.

Voir également clear() et rowCount.

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

Insère ou met à jour le champ de données nommé par role dans la cellule de la table située à l'adresse index avec la valeur value. Renvoie « true » en cas de succès, « false » dans le cas contraire.

Voir également data() et index().

void setRow(int rowIndex, var row)

Remplace la ligne de l'adresse rowIndex dans le modèle par celle de l'adresse row.

Toutes les colonnes/cellules doivent être présentes dans row, et dans le bon ordre.

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

Si ` rowIndex ` est égal à ` rowCount()`, une nouvelle ligne est ajoutée au modèle. Sinon, ` rowIndex ` doit pointer vers une ligne existante du modèle.

Voir également appendRow(), insertRow() et 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.