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

QSqlField Class

La classe QSqlField permet de manipuler les champs des tables et des vues d'une base de données SQL. En savoir plus...

En-tête : #include <QSqlField>
CMake : find_package(Qt6 REQUIRED COMPONENTS Sql)
target_link_libraries(mytarget PRIVATE Qt6::Sql)
qmake : QT += sql

Types publics

enum RequiredStatus { Required, Optional, Unknown }

Propriétés

Fonctions publiques

(since 6.0) QSqlField(const QString &fieldName = QString(), QMetaType type = QMetaType(), const QString &table = QString())
QSqlField(const QSqlField &other)
QSqlField(QSqlField &&other)
~QSqlField()
void clear()
QVariant defaultValue() const
bool isAutoValue() const
bool isGenerated() const
bool isNull() const
bool isReadOnly() const
bool isValid() const
int length() const
QMetaType metaType() const
QString name() const
int precision() const
QSqlField::RequiredStatus requiredStatus() const
void setAutoValue(bool autoVal)
void setDefaultValue(const QVariant &value)
void setGenerated(bool gen)
void setLength(int fieldLength)
void setMetaType(QMetaType type)
void setName(const QString &name)
void setPrecision(int precision)
void setReadOnly(bool readOnly)
void setRequired(bool required)
void setRequiredStatus(QSqlField::RequiredStatus required)
void setTableName(const QString &tableName)
void setValue(const QVariant &value)
(since 6.6) void swap(QSqlField &other)
QString tableName() const
QVariant value() const
bool operator!=(const QSqlField &other) const
QSqlField &operator=(const QSqlField &other)
bool operator==(const QSqlField &other) const

Description détaillée

QSqlField représente les caractéristiques d'une colonne d'une table ou d'une vue de base de données, telles que le type de données et le nom de la colonne. Un champ contient également la valeur de la colonne de la base de données, qui peut être consultée ou modifiée.

Les valeurs des données de champ sont stockées sous forme de QVariants. L'utilisation d'un type incompatible n'est pas autorisée. Par exemple :

    QSqlField field("age", QMetaType::fromType<int>());
    field.setValue(QPixmap());  // WRONG

Cependant, le champ tentera, dans la mesure du possible, de convertir certains types de données vers le type de données du champ :

    QSqlField field("age", QMetaType::fromType<int>());
    field.setValue(QString("123"));  // casts QString to int

Les objets QSqlField sont rarement créés explicitement dans le code de l'application. On y accède généralement de manière indirecte via des objets ` QSqlRecord` qui contiennent déjà une liste de champs. Par exemple :

    QSqlQuery query;
    ...
    QSqlRecord record = query.record();
    QSqlField field = record.field("country");

Un objet QSqlField peut fournir certaines métadonnées sur le champ, par exemple : son name(), son variant metaType(), son length(), son precision(), son defaultValue(), son typeID(), ainsi que ses requiredStatus(), isGenerated() et isReadOnly(). Il est possible de vérifier les données du champ à l'aide de la fonction « isNull » () et d'en récupérer la valeur à l'aide de la fonction « value » (). Lors de la modification, les données peuvent être définies à l'aide de la fonction « setValue » () ou mises à NULL à l'aide de la fonction « clear » ().

Voir également QSqlRecord.

Documentation sur les types de membres

enum QSqlField::RequiredStatus

Indique si le champ est obligatoire ou facultatif.

ConstanteValeurDescription
QSqlField::Required1Le champ doit être renseigné lors de l'insertion d'enregistrements.
QSqlField::Optional0Il n'est pas nécessaire de renseigner ce champ lors de l'insertion d'enregistrements.
QSqlField::Unknown-1Le pilote de base de données n'a pas pu déterminer si le champ est obligatoire ou facultatif.

Voir aussi requiredStatus.

Documentation sur les propriétés

[since 6.8] autoValue : bool

Si la valeur est générée automatiquement par la base de données, par exemple les valeurs de clé primaire à incrémentation automatique, cette valeur est « true ».

Remarque : lors de l'écriture d'un nouvel enregistrement dans la base de données, le champ « autoValue » ne contiendra la nouvelle valeur générée par la base de données qu'une fois l'enregistrement validé. Lors de l’utilisation du pilote ODBC, en raison des limitations de l’API ODBC, le champ « isAutoValue() » n’est renseigné que dans un objet « QSqlField » résultant d’un « QSqlRecord » obtenu par l’exécution d’une requête « SELECT ». Il est « false » pour un « QSqlField » résultant d’un « QSqlRecord » renvoyé par « QSqlDatabase::record() » ou « QSqlDatabase::primaryIndex() ».

Cette énumération a été introduite dans Qt 6.8.

Fonctions d'accès :

bool isAutoValue() const
void setAutoValue(bool autoVal)

[since 6.8] defaultValue : QVariant

Cette propriété contient la valeur par défaut de ce champ. Seuls certains pilotes de base de données prennent en charge cette propriété. Il s'agit actuellement de SQLite, PostgreSQL, Oracle et MySQL/MariaDB.

Cette énumération a été introduite dans Qt 6.8.

Fonctions d'accès :

QVariant defaultValue() const
void setDefaultValue(const QVariant &value)

[since 6.8] generated : bool

Cette propriété contient l'état généré. Si la valeur de « generated » est « false », aucune instruction SQL ne sera générée pour ce champ ; dans le cas contraire, les classes Qt telles que « QSqlQueryModel » et « QSqlTableModel » généreront du code SQL pour ce champ.

Cette énumération a été introduite dans Qt 6.8.

Fonctions d'accès :

bool isGenerated() const
void setGenerated(bool gen)

[since 6.8] length : int

Cette propriété contient la longueur du champ.

Si la valeur est négative, cela signifie que l'information n'est pas disponible dans la base de données. Pour les chaînes de caractères, il s'agit du nombre maximal de caractères que la chaîne peut contenir ; la signification varie selon les autres types.

Cette énumération a été introduite dans Qt 6.8.

Fonctions d'accès :

int length() const
void setLength(int fieldLength)

[since 6.8] metaType : QMetaType

Cette propriété contient le type du champ tel qu'il est stocké dans la base de données. Notez que la valeur réelle peut être d'un type différent. Les valeurs numériques trop grandes pour être stockées dans un « long int » ou un « double » sont généralement stockées sous forme de chaînes de caractères afin d'éviter toute perte de précision.

Cette énumération a été introduite dans Qt 6.8.

Fonctions d'accès :

QMetaType metaType() const
void setMetaType(QMetaType type)

Voir également QSqlDatabase::numericalPrecisionPolicy.

name : QString

Cette propriété contient le nom du champ. Il peut s'agir du nom de la colonne ou d'un alias défini par l'utilisateur.

Fonctions d'accès :

QString name() const
void setName(const QString &name)

[since 6.8] precision : int

Cette propriété indique la précision du champ ; elle n'a de sens que pour les types numériques.

Si la valeur renvoyée est négative, cela signifie que l'information n'est pas disponible dans la base de données.

Cette énumération a été introduite dans Qt 6.8.

Fonctions d'accès :

int precision() const
void setPrecision(int precision)

[since 6.8] readOnly : bool

Lorsque cette propriété est définie sur « true », l'QSqlField ne peut pas être modifiée. La valeur d'un champ en lecture seule ne peut pas être définie à l'aide de setValue() et ne peut pas être remise à NULL à l'aide de clear().

Cette énumération a été introduite dans Qt 6.8.

Fonctions d’accès :

bool isReadOnly() const
void setReadOnly(bool readOnly)

[since 6.8] requiredStatus : RequiredStatus

Cette propriété contient l'RequiredStatus du champ. Une INSERT échouera si un champ obligatoire ne comporte pas de valeur.

Cette énumération a été introduite dans Qt 6.8.

Fonctions d'accès :

QSqlField::RequiredStatus requiredStatus() const
void setRequiredStatus(QSqlField::RequiredStatus required)

Voir aussi RequiredStatus.

[since 6.8] tableName : QString

Cette propriété contient le nom de table (tableName) du champ.

Remarque : lors de l'utilisation du pilote QPSQL, en raison de limitations de la bibliothèque libpq, le champ « tableName() » n'est pas renseigné dans l'QSqlField ion résultant d'une QSqlRecord obtenue par la fonction QSqlQuery::record() d'une requête unidirectionnelle.

Cette énumération a été introduite dans Qt 6.8.

Fonctions d'accès :

QString tableName() const
void setTableName(const QString &tableName)

[since 6.8] value : QVariant

Cette propriété contient l’ value sous la forme d’un QVariant

L'affectation d'une valeur de type « value » à une variable de type « QSqlField » en lecture seule n'a aucun effet. Si le type de données de « value » diffère du type de données actuel du champ, le système tente de le convertir au type approprié. Cela permet de conserver le type de données du champ en cas d'affectation, par exemple lors de la conversion d'un « QString » en un type de données «integer».

Pour définir la valeur sur NULL, utilisez la fonction ` clear()`.

Cette énumération a été introduite dans Qt 6.8.

Fonctions d'accès :

QVariant value() const
void setValue(const QVariant &value)

Documentation des fonctions membres

[explicit, since 6.0] QSqlField::QSqlField(const QString &fieldName = QString(), QMetaType type = QMetaType(), const QString &table = QString())

Crée un champ vide nommé « fieldName » de type « type » dans « table ».

Il s'agit d'une fonction surchargée.

Cette fonction a été introduite dans Qt 6.0.

QSqlField::QSqlField(const QSqlField &other)

Crée une copie de other.

[noexcept default] QSqlField::QSqlField(QSqlField &&other)

Crée par « move » une instance de ` QSqlField`.

[noexcept] QSqlField::~QSqlField()

Détruit l'objet et libère toutes les ressources allouées.

void QSqlField::clear()

Efface la valeur du champ et la remplace par NULL. Si le champ est en lecture seule, aucune action n'est effectuée.

QVariant QSqlField::defaultValue() const

Définit la valeur de `defaultValue`.

Remarque : fonctiongetter pour la propriété defaultValue.

Voir aussi setDefaultValue().

bool QSqlField::isAutoValue() const

Renvoie la valeur de autoValue.

Remarque : fonction de lecture (getter ) pour la propriété autoValue.

bool QSqlField::isGenerated() const

Renvoie la valeur de generated.

Remarque : fonctionde lecture pour la propriété generated.

bool QSqlField::isNull() const

Renvoie « true » si la valeur du champ est NULL ; sinon, renvoie « false ».

Voir aussi value.

bool QSqlField::isReadOnly() const

Renvoie la valeur de readOnly.

Remarque : fonctionde lecture pour la propriété readOnly.

bool QSqlField::isValid() const

Renvoie « true » si le type de variante du champ est valide ; sinon, renvoie « false ».

int QSqlField::length() const

Renvoie la valeur de la propriété « length ».

Remarque : fonctiongetter pour la propriété « length ».

Voir aussi setLength().

QMetaType QSqlField::metaType() const

Renvoie la valeur de metaType.

Remarque : fonctiongetter pour la propriété metaType.

Voir aussi setMetaType().

QString QSqlField::name() const

Renvoie la valeur de « name ».

Remarque : fonctiongetter pour la propriété « name ».

Voir aussi setName().

int QSqlField::precision() const

Renvoie la valeur de precision.

Remarque : fonctiongetter pour la propriété « precision ».

Voir aussi setPrecision().

QSqlField::RequiredStatus QSqlField::requiredStatus() const

Renvoie la valeur de requiredStatus.

Remarque : fonctiongetter pour la propriété requiredStatus.

Voir aussi setRequiredStatus().

void QSqlField::setAutoValue(bool autoVal)

Définit la propriété « autoValue » sur « autoVal ».

Remarque : fonctionde définition de la propriété autoValue.

Voir également isAutoValue().

void QSqlField::setDefaultValue(const QVariant &value)

Définit la propriété « defaultValue » sur « value ».

Remarque : fonctionde définition de la propriété defaultValue.

Voir également defaultValue().

void QSqlField::setGenerated(bool gen)

Définit la propriété generated sur gen.

Remarque : fonctionde définition de la propriété generated.

Voir également isGenerated().

void QSqlField::setLength(int fieldLength)

Définit la propriété ` length ` sur ` fieldLength`.

Remarque : fonctionde définition pour la propriété length.

Voir aussi length().

void QSqlField::setMetaType(QMetaType type)

Définit la propriété « metaType » sur « type ».

Remarque : fonctionde définition pour la propriété metaType.

Voir également metaType().

void QSqlField::setName(const QString &name)

Définit la propriété « name » sur « name ».

Remarque : fonctionde définition de la propriété name.

Voir également name().

void QSqlField::setPrecision(int precision)

Définit la propriété « precision » sur « precision ».

Remarque : fonctionde définition de la propriété precision.

Voir également precision().

void QSqlField::setReadOnly(bool readOnly)

Définit la propriété « readOnly » sur « readOnly ».

Remarque : fonctionde définition de la propriété readOnly.

Voir également isReadOnly().

void QSqlField::setRequired(bool required)

Définit l'état requis de ce champ sur « Required » si « required » est vrai ; sinon, il le définit sur « Optional ».

Voir également requiredStatus.

void QSqlField::setRequiredStatus(QSqlField::RequiredStatus required)

Définit la propriété « requiredStatus » sur « required ».

Remarque : fonctionde définition de la propriété requiredStatus.

Voir aussi requiredStatus().

void QSqlField::setTableName(const QString &tableName)

Définit la propriété « tableName » sur « tableName ».

Remarque : fonctionde définition de la propriété tableName.

Voir également tableName().

void QSqlField::setValue(const QVariant &value)

Définit la propriété « value » sur « value ».

Remarque : fonctionde définition de la propriété value.

Voir également value().

[noexcept, since 6.6] void QSqlField::swap(QSqlField &other)

Permute ce champ avec other. Cette opération est très rapide et ne rencontre jamais d'échec.

Cette fonction a été introduite dans Qt 6.6.

QString QSqlField::tableName() const

Renvoie le nom de la table (tableName).

Remarque : fonctiongetter pour la propriété tableName.

Voir aussi : setTableName().

QVariant QSqlField::value() const

Renvoie la valeur de « value ».

Remarque : fonctiongetter pour la propriété « value ».

Voir aussi setValue().

bool QSqlField::operator!=(const QSqlField &other) const

Renvoie « true » si le champ n'est pas égal à « other » ; sinon, renvoie « false ».

QSqlField &QSqlField::operator=(const QSqlField &other)

Définit la valeur du champ sur « other ».

bool QSqlField::operator==(const QSqlField &other) const

Renvoie « true » si le champ est égal à « other » ; sinon, renvoie « false ».

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