Qt SQL-2

9、QSqlQuery类

QSqslQuery类提供了执行和操作SQL语句的方法。

头：#include <QSqlQuery>

qmake：QT += sql

公有类型

enum BatchExecutionMode {ValuesAsRows, ValuesAsColumns}

详细描述

QSqlQuery类提供了执行和操作SQL语句的方法。

QSqlQuery封装了包含创建，导航和从QSL查询获取数据的功能，在QSqlDatabase上执行它们。它可用于执行DML(数据库操作语言)语句，诸如SELECT, INSERT, UPDATE和DELETE，以及DDL(数据库定义语句)语言，诸如CREATE TABLE。它也可以用于执行非标准SQL的数据库专用命令(例如，对于PostgreSQL SET DATASYLTE=ISO)。

成功执行的SQL语句设置这条查询的状态为生效，使得isActive()返回true。否则，查询的状态设为无效。在任一种情况下，当执行一条新的SQL语句时，查询被置于一个无效记录。在值可以被获取钱，一个有效查询必需被导航到一个有效记录(因而isValid()返回true)。

对于某些数据库，当你调用commit()或rollback()时，一个作为SELECT语句存在的有效查询将出错。详见isActive()。用以下函数执行记录导航：

next() previous() first() last() seek()

这些函数允许程序员在这个查询返回的记录上向前，向后或任意移动。如果你只需要向前移动结果(例如，通过使用next())，你可以使用setForwardOnly()，这将显著地节约内存开销量，并且提升某些数据库性能。一旦一个有有效查询定位在了一个有效记录，可以通过value()获取数据。所有数据使用QVariants从SQL支持传输。

例如：

...   
if (!db.open()){
    qDebug() << "Failed to connect to database";
    qDebug() << db.lastError().text();
    return -1;
}
else{
    qDebug() << "database opened:";
    qDebug() << "Connect to database:" << db.connectionName();
    qDebug() << "Tables:" << db.tables();

    QSqlQuery query("SELECT username from users;");
    query.exec();

    while (query.next()){
    QString name = query.value(0).toString();
    qDebug() << "name:" << name;
    }
}
...

执行结果：

Connect to database: "qt_sql_default_connection"
Tables: ("books", "orders", "users")
name: "administrator"
name: "user2"
name: "user3"
name: "user4"

要访问query返回地数据，使用value(int)。通过传递语句中字段的位置访问由SELECT返回地数据中的字段，从0开始。这使得不建议使用SELECT *查询，因为字段返回的顺是不确定的。

为了效率，没有通过名称访问字段的函数(除非你使用了带有名称的预备语句)。要转换一个字段为索引，使用record().indexOf()。例如：

QSqlQuery query;
if(query.exec("SELECT * FROM  users;")){
    int fieldNo = query.record().indexOf("username");
    qDebug() << "fieldNo:" << fieldNo;

    while (query.next()){
        QString name = query.value(fieldNo).toString();
        qDebug() << "name:" << name;
    }
}

执行结果：

fieldNo: 1
name: "administrator"
name: "user2"
name: "user3"
name: "user4"

QSqlQuery支持预备查询执行和绑定参数值到占位符。某写数据库不支持这些特性，因而对于那些，Qt模拟所需的功能。例如，例如，对于Oralce和ODBC驱动有合适的预备查询支持，使用它，但对于没有这种支持的数据库，Qt它自己实现这个特性，例如，通过在执行查询时，用实际值替代占位符。使用numRowsAffected()查找多少行受到了非SELECT查询的影响，而size()查找多少行由一个SELECT获取。

Oracle数据库通过使用一个冒号名称语法识别占位符。ODBC只是使用？字符。Qt支持两种语法，带有你不能在相同查询中混合它们的限制。

你可以使用boundValues()在单个变量(一个map)中获取所有字段的值。

绑定值的方法

以下，我们使用四种不同方法展现了相同的示例，以及一个绑定值到一个存储过程的示例。

1）使用命名的占位符的命名绑定

2）使用命名的占位符的位置绑定

QSqlQuery query;

query.prepare("INSERT INTO users (username, password, email) VALUES(:name, :pass, :email);");
query.bindValue(":name", "xixi");
query.bindValue(":pass", "yyy");
query.bindValue(":email", "[email protected]");
query.exec();

3）使用位置占位符绑定值(版本1)

QSqlQuery query;
  
query.prepare("INSERT INTO users (username, password, email) VALUES(:name, :pass, :email);");
query.bindValue(0, "haha");
query.bindValue(1, "xxx");
query.bindValue(2, "[email protected]");
query.exec();

4）使用位置占位符绑定值(版本2)

QSqlQuery query;

query.prepare("INSERT INTO users (username, password, email) VALUES(?, ?, ?);");
query.addBindValue( "lala");
query.addBindValue( "lll");
query.addBindValue( "[email protected]");
query.exec();

5）绑定值到一个存储过程

此代码调用一个名为AsciiToInt()的存储过程，通过字符在参数中传递它一个字符，并且在out参数中获取它的结果。

QSqlQuery query;
query.prepare("CALL AsciiToInt(?,?)");
query.bindValue(0, "A");
query.bindValue(1, , 0, QSql::Out);
query.exec();

int i = query.boundValue(1).toInt();

注意：未绑定的参数将保持它们的值。

不完全支持使用返回语句返回值或返回多个结果集的存储过程。

警告：在创建一个QSqlQuery前，你必需装载SQL驱动并且打开连接。在查询存在时，连接必须保存打开，否则，QSqlQuery的行为是未定义的。

成员类型文档

enum QSqlQuery::BatchExecutionMode

|----------------------------|---|-------------------------------------|
| 常数 | 值 | 描述 |
| QSqlQuery::ValuesAsRows | 0 | 更新多行。当在QVariantList中的每项为一个值，用于更新下一行 |
| QSqlQuery::ValuesAsColumns | 1 | 更新单行。当在QVariantList中的每项为一个数组类型的单个值 |

成员函数文档

QSqlQuery::QSqlQuery(QSqlQuery *result)

构建一个QSqlQuery对象，它使用QSqlResult结果与数据库通信。

QSqlQuery::QSqlQuery(QString &query = QString(), QSqlDatabase db = QSqlDatabase())

使用SQL query和数据库db构造一个QSqlQuery对象。如果没有指定db，或者无效，使用程序的默认数据库。 如果query不是一个空串，将执行它。

QSqlQuery::QSqlQuery(QSqlDatabase db)

使用数据库db构造一个QSqlQuery对象。如果db无效，使用程序的默认数据库对象。

QSqlQuery::QSqlQuery(QSqlQuery &other)

构造other的一个副本。

~QSqlQuery::QSqlQuery()

销毁对象并且释放所有分配的资源。

void QSqlQuery::addBindValue(const QVariant &val, QSql::ParamType paramType = QSql::In)

当使用位置值绑定时，添加值val到这个值列表。addBindValue()调用顺序决定了在预备查询中一个值绑定到哪个占位符。如果paramType是QSql::Out或QSql::InOut，在exec()执行后，将用来自数据库的数据重写占位符。

要绑定一个NULL值，使用一个null QVaiant，例如，你绑定一个字符串，使用QVariant(QVariant::String)。

int QSqlQuery::at() const

返回查询的当前内部位置。第一个记录是在位置0.如果位置无效，这个函数返回QSql::BeforeFirstRow或QSql::AfterLastRow，这些是特别的负值。

void QSqlQuery::bindValue(const QString &placeholder, const QVariant &val, QSql::ParmType paramType = QSql::In)

在预备语句中，设置占位符placeholder被绑定到值val。注意：占位符标记(例如，:)，在指定占位符名称时必须被包括。如果paramType是QSql::Out或QSql::InOut，在exec()调用后，占位符将被来自数据库的数据重写。在这种情况下，预分配足够空间存储结果。

要绑定一个NULL值，使用null QVariant，例如，如果你绑定一个字符串时，使用QVariant(QVarint::String)。

void QSqlQuery::bindValue(int pos, const QVariant *val, QSql::ParamType paramType = QSql::In)

在预备语句中，按位置pos设置要被绑定到值val的 占位符。字段编号从0开始。如果paramType是QSql::Out或QSql::InOut，在exec()调用后，占位符将被来自数据库的数据重写。

QVariant QSqlQuery::boundValue(const QString &placeholder) const

返回对应这个占位符的值。

QVariant QSqlQuery::boundValue(int pos) const

返回位置pos处的占位符的值。

QMap<QString, QVariant> QSqlQuery::boundValues() const

返回一个绑定值的map。

用命名绑定时，用以下方法检查绑定值：

query.prepare("INSERT INTO users (username, password, email) VALUES(:name, :pass, :email);");
query.bindValue(":name", "xixi");
query.bindValue(":pass", "yyy");
query.bindValue(":email", "[email protected]");

qDebug() << "QSqlQuery::boundValues():";
QMapIterator<QString, QVariant> i(query.boundValues());

while (i.hasNext()){
    i.next();
    qDebug() << i.key().toUtf8().data() << ":" << i.value().toString().toUtf8().data();
}
qDebug() << "-------------------------";

执行结果：

QSqlQuery::boundValues():
:email : [email protected]
:name : xixi
:pass : yyy
-------------------------

用位置绑定时，代码变成：

query.prepare("INSERT INTO users (username, password, email) VALUES(:name, :pass, :email);");
query.bindValue(0, "haha");
query.bindValue(1, "xxx");
query.bindValue(2, "[email protected]");

qDebug() << "QSqlQuery::boundValues():";
QList<QVariant> list = query.boundValues().values();
for (int i = 0; i < list.size(); i++){
    qDebug() << i << ":" << list.at(i).toString().toUtf8().data();
}
qDebug() << "-------------------------";

执行结果：

QSqlQuery::boundValues():
:email : [email protected]
:name : xixi
:pass : yyy
-------------------------

void QSqlQuery::clear()

清理由这个查询保存的结果集并且释放所有资源。设置query的窗体为失效。你应该几乎不需要调用这个函数。

const QSqlDriver * QSqlQuery::driver() const

返回与这个查询相关联的数据库驱动。

bool QSqlQuery::exec(const QString &query)

在查询中执行这条SQL。如果查询成功，返回true并且设置查询状态为有效；否则false。查询字串必须使用适合于被查询SQL数据库的语法(例如，标准SQL)。在执行查询后，查询被定位到了一个无效记录上并且在数据值可以被获取前，必须被导航到一个有效记录(例如next())。

注意：在调用exec()时，这个查询的上次错误被重置。

对于SQLite，查询串一次可以仅包含一条语句。如果制定了多条语句，这个函数返回false。

query.exec("SELECT id, username, password, email FROM users");
while (query.next()){
    qDebug() << query.value(0).toString() << ":" << query.value(1).toString()  << ":" << query.value(2).toString() << ":" << query.value(3).toString();
}

执行结果：

"1" : "administrator" : "password123" : "[email protected]"
"2" : "user2" : "password456" : "[email protected]"
"3" : "haha" : "xxx" : "[email protected]"
"4" : "xixi" : "yyy" : "[email protected]"
"5" : "kiki" : "kkk" : "[email protected]"
"6" : "lala" : "lll" : "[email protected]"

bool QSqlQuery::exec()

执行一条先前预备的SQL查询。如果查询执行成功，返回true，否则返回false。

注意：在调用exec()时，这条查询的上次错误被重置。

bool QSqlQuery::execBatch(BatchExecutionMode mode = ValuesAsRows)

在一个处处理中，执行一条先前预备的SQL查询。所哟绑定的参数必须是变量的列表。如果数据库不支持批执行，驱动将使用常规的exec()调用模拟它。

如果查询执行成功，返回true，否则false。

示例：

query.prepare("INSERT INTO users VALUES (?, ?, ?);");
QVariantList names;
names << "aa" << "bb" << "cc" << QVariant(QVariant::String);

QVariantList passwds;
passwds << "xxaa" << "xxbb" << "xxcc" << QVariant(QVariant::String);

QVariantList emails;
emails << "[email protected]" << "[email protected]" << "[email protected]" << QVariant(QVariant::String);

query.addBindValue(names);
query.addBindValue(passwds);
query.addBindValue(emails);

if (!query.execBatch()){
    qDebug() << query.lastError();
}
else{
    qDebug() << "QSqlQuery::execBatch() successfully!" ;
}

在MySQL上执行：

QSqlQuery::execBatch()
QSqlError("1136", "QMYSQL: Unable to execute query", "Column count doesn't match value count at row 1")

要绑定NULL值，一个相关类型的null QVariant被添加到了绑定的QVariantList，例如，如果你使用字符串，应该使用QVariant(QVariant::String)。

注意：每个绑定的QVariantList必须包含相同变量数目。

注意：在列表中的QVariants类型不能更改。例如，你不能在一个QVariantList中混合整数和字符串变量。

模式参数表明如何解析绑定的QVariantList。如果模式是ValuesAsRows，在QVRariantList中的每个变量将被解析成以新行的一个值。ValuesAsColumns是用于Oracle驱动的特殊情况。在这种模式，在QVariantList中每项将被解析成用于存储过程中一个IN或OUT值的数组值。注意：这仅在IN或OUT是一个表类型，它由一个基本类型的一列组成，才有效，例如：

TYPE myType IS TABLE OF VARCHAR(64) INDEX BY BINARY_INTEGER

QString QSqlQuery::executeQuery() const

返回上次被执行执行的查询。在大多数情况，这个函数返回字符串同lastQuery()。如果在DBMS上执行的带有占位符的预备查询不支持它，这个查询的预备被模拟。在原来查询中的占位符被它们绑定的值替换，形成一条新查询。这个函数返回修改的查询。它对调试目的最有用。

void QSqlQuery::finish()

指示数据库驱动在重新执行查询前，不再从这条查询获取更多数据。通常不需要调用这个函数，但如果你打算之后再使用这条查询，为了释放诸如锁或游标的资源，这会有帮助。

设置查询失效。绑定值保持它们的值。

bool QSqlQuery::first()

如果可用，获取结果中第一个记录，并且定位这个查询到获取的记录。注意：再调用这个函数前，结果必须处于有效状态并且isSelect()必须返回true，否则，它将什么也不做并且返回false。如果程成功返回true。如果失败，此查询位置被设置成一个无效位置并且返回false。

bool QSqlQuery::isActive() const

如果查询是有效的，返回true。一个有效QSqlQuery是一个已经被成功地执行了exec()但还未结束的查询。当你用完了一个有效查询，你可以通过调用finish()或clear()， 或者你可以删除这个QSqlQuery实例，使得这条查询失效。

注意：尤其注意是SELECT语句的有效查询。对于某些支持事务的数据库，一个SELECT语句的有效查询会使得commit或rollback()失败，因而再提交或回滚前，你应该是哦那个以上列出的方式之一使得你的有效SELECT语句失效。

bool QSqlQuery::isForwardOnly() const

如果你只能向前滚动一个结果集，返回true，否则返回false。

bool QSqlQuery::isNull(int field) const

如果查询不是有效的，查询不能被定位到一个有效记录，美誉哦哦这样的字段或者字段是空，返回true；否则false。注意：对于某些驱动，直到进行获取数据的尝试后，isNull()才返回准确的信息。

bool QSqlQuery::isNull(const QString &name) const

这是一个重载函数。如果没有名为这个名称的字段，返回true。否则对相应字段索引返回isNull(int index)

bool QSqlQuery::isSelect() const

如果当前查询是一个SELECT语句，返回true。否则返回false。

bool QSqlQuery::isValid() const

如果查询当前定位到了一个有效记录，返回true，否则返回false。

bool QSqlQuery::last()

如果可用返回结果中的最后 一个记录，并且定位查询到获取的记录上。注意：再调用这个函数前，结果必须是有效状态并且isSelect()必须返回真，否则返回false。如果成功返回true。如果不成功，查询位置被设置到一个无效位置并且返回false。

QSqlError QSqlQuery::lastError() const

返回这条查询发生的上次错误(如果有)，反错误信息。

QVariant QSqlQuery::lastInserted() const

如果数据库支持，返回最近被插入的对象ID。如果查询未插入任何值或者数据库不回报这个id，将返回一个无效QVariant。如果插入影响多行，行为是未定义的。

对于MySQL数据库，将返回行的自增字段。

注意：对于再PSQL中运行的函数，表table必须包含OIDs，可能默认未创建它。检查default_with_oids配置变量来确认。

bool QSqlQuery::lastQuery() const

返回正在被使用的当前查询的文本，如果没有当前查询文本，一个空串。

bool QSqlQuery::next()

如果可用，获取结果中下一个记录，并且定位查询到获取的记录。注意：在调用这个函数前，结果必须处于有效状态并且isSelect()必须返回true，否则它什么也不做，并且返回false。

使用以下规则：

• 如果结果当前被定位在在第一个记录前，例如，就在查询被执行后，进行获取第一个记录的尝试。
• 如果结果当前被定位在了最后一个记录之后，没有变化并且返回false。
• 如果记录被定位在了中间的某处，进行获取下一个记录的尝试。

如果记录不能被获取，结果被定位到了最后一个记录之后并且返回false。如果记录被成功获取，返回true。

bool QSqlQuery::nextResult()

如果下条可用，抛弃当前结果集并且导航到下条记录。

某些数据库能够返回存储过程或SQL批处理(一个包含多个语句的查询字符串)的多个结果集。如果在执行一个查询后，多个结果集可用，这个函数可以用于导航到下个结果集。

如果一个新的结果集可用，这个函数将返回true。查询将被重新定位到这个新结果集的一个无效记录上并且在数据可以被获取前，必须被导航到一个有效的记录上。如果一个新结果集不可用，这个函数返回false，并且这个查询被设为无效。在任何情况下，老的结果集将被丢弃。

当其中一个语句是非选择语句时，受影响行数可获取而不是结果集。

注意：某些数据库，如Microsoft SQL server，在使用多个结果集时，需要一个非滚动游标。某些数据库可以一次执行所有语句，而另一些要延迟执行，直到结果集实际被访问，某些数据库对哪些语句被允许在SQL批处理中被使用有限制。

int QSqlQuery::numRowsAffected() const

返回受到结果的SQL语句影响的行数，或者不能确定它，返回-1。注意对于SELECT语句，值是未定义的，使用size()替代。如果查询是无效的，返回-1。

QSql::NumericPrecisionPolicy QSqlQuery::numericalPrecisionPolicy() const

返回当前的精度策略。

bool QSqlQuery::prepare(const QString &query)

预备用于执行的SQL查询语句。如果查询预备成功返回true，否则返回false。查询可以包含用于绑定值的占位符。支持Oracle风格的冒号-名称(例如：:surname)和ODBC风格占位符(?)；但在相同查询中不能混用它们。

移植性注意：某些数据库选择推迟预备一个查询，直到它被首次执行。在这种情况下，预备一个语法错误的查询成功，但每次连续的exec()将出错。

对于SQLite，查询字符串可以一次只包含一条语句。如果指定多个语句，此函数返回false。

示例：

QSqlQuery query;
query.prepare("INSERT INTO users (username, password, email) VALUES(:name, :pass, :email);");
query.bindValue(":name", "xixi");
query.bindValue(":pass", "yyy");
query.bindValue(":email", "[email protected]");
query.exec();

bool QSqlQuery::previous()

如果可用，获取结果中前一条记录，并且定位这条查询到获取的记录。注意：在调用这个函数前，结果必须处于有效状态，并且isSelect()必须返回true，否则它将什么都不做并返回false。

使用以下规则：

• 如果结果当前被定位在第一条记录前，没有变化并且返回false。
• 如果结果定位在最后一条记录之后，尝试获取末尾的记录。
• 如果记录在中间的某个位置，尝试获取前一个记录。

如果记录不能被获取，结果被定位在第一个记录前并且返回false。如果记录被成功的获取，返回true。

QSqlQuery QSqlQuery::record() const

为当前查询返回一个包含了字段信息的QSqlRecord。如果查询指向一有效行(isValid()返回true)，用这行的值填充记录。当没有有效查询(isActive返回false)时，返回一个空记录。

要冲一个查询获取值，由于其基于索引查找更快，应该使用value()。

在以下示例中，执行一个SELECT * FROM查询。由于列的顺序未被定义，QSqlRecord::indexOf()用于获取列的索引。

query.exec("SELECT * FROM users");
qDebug() << "Successfully executed: " << query.executedQuery();
qDebug() << "lastQuery() executed: " << query.lastQuery();

QSqlRecord rec = query.record();
int nameCol = rec.indexOf("username");
qDebug() << "Number of columns:"  << rec.count();
qDebug() << "Name column index: " << nameCol;
while (query.next()){
    qDebug() << query.value(nameCol).toString();
}

const QSqlResult *QSqlQuery::result() const

返回与此查询相关联的结果。

bool QSqlQuery::seek(int index, bool relative = false)

如果可用，获取位置index处的记录，并且定位此查询到获取的记录。第一天记录位于位置0。注意：在调用此函数前，查询必须处于有效状态并且isSelect必须返回true。

如果relative是false(默认)，使用以下规则：

• 如果index为负数，结果被定位到第一条记录前，并且返回false。
• 否则，尝试移动记录到位置index。如果位于位置index的记录不能被获取，结果被定位到最后一条记录之后，并且返回false。如果记录被成功的获取，返回true。

如果relative是true，使用以下规则：

1）如果结果当前被定位在了第一个记录之前：

• index是负数或0，没有变化，并且返回false。
• index是正数，尝试定位结果到绝对位置index-1，按照以上使用非相对搜索的相同规则。

2）如果结果当前是定位在最后一个规则之后，并且：

• index是正或者0，没有变化，并且返回false。
• index是负数，尝试定位结果在相对于最后一个记录的index+1，按照以下规则。

3）如果记录当前定位在中间的某处，并且相对偏移index移动记录小于0了，结果被定位在了第一个记录前，并且返回false。

4）此外，尝试前移当前记录到index个记录的记录(或者如果index是负数，当前记录之后index个记录)。如果在偏移index的记录不能被获取，结果被定位在了最后一个记录之后(如果index>=0),（或者如果index是负数，在第一个记录之前），并且返回false。如果记录被成功地获取了，返回true。

void QSqlQuery::ssetForwardOnly(bool forward)

设置仅向前模式为向前。如果forwad是true，对于导航这些结果，仅允许next()和seek()。

(取决于驱动)仅向前模式会更加内存有效，由于不需要缓存结果。它也将在某些数据库上提高性能。要使得这个成立，在查询被预备或执行前，你必须调用setForwardOnly()。注意，进行查询地构造器和数据库可能执行了这个查询。

仅向前模式默认关闭。

注意：在查询执行后调用setForwardOnly将最好导致无法预计地结果，最坏导致崩溃。

void QSqlQuery::setNumericalPrecsionPolicy(QSql::NumericalPrecisionPolicy precisionPolicy)

指示数据库驱动返回由precisionPolicy指定精度地数值。

例如 Oracle驱动可以以字符串获取数值以防止精度损失。如果高精度无所谓，使用这个方法通过忽略字符串转换增加执行速度。

注意：不支持用低精度获取数值地驱动将忽略这个精度策略。你可以使用QSqlDriver::hasFeature()查找驱动是否支持这个特性。

注意：设置精度策略不影响当前生效地查询。为了激活这个策略，调用exec(QString)或prepare()。

int QSqlQuery::Size() const

返回结果的大小(返回的行数)，或者如果大小不能被确定或者数据数据库不支持报告查询大小的信息，返回-1。注意对于非-SELECT语句，(isSelect()返回false)，size()将返回-1。如果查询不是有效的(isActive返回false)，返回-1。

要确定受到非SELECT语句影响的行数，使用useRowsAffected()。

QVariant QSqlQuery::value(int index) const

返回当前记录中字段index的值。使用SELECT语句的文本，从左到右编号这些字段，例如：

SELECT forename, surname FROM people;

字段0是forename, 字段1是surname。使用SELECT *不推荐，因为在查询中的字段顺序是未定义的。

如果字段index不存在，如果查询是无效的，或者查询被定位在了一个无效记录上，返回一个无效的QVariant。

QVariant QSqlQuery::value(const QString &name) const

这是一个重载函数。

返回当前记录中名为name的字段的值。如果字段名不存在，返回一个无效值。这个重载效率低于value()。

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

把other值赋给了这个对象。

10、QSqlRecord类

QSqlRecord类封装了一个数据库记录。

头：#include <QSqlRecord>

qmake：QT += sql

由QSqlIndex继承。

详细信息

QSqlRecord类封装了一个数据库记录。

QSqlReocrd类封装一个数据库记录的功能和特性(通常在数据库内的表或视图中的行或者)。QSqlRecord支持添加和删除字段以及设置和获取字段值。

可以用setValue()通过名称或位置设置记录字段的值；如果你想要设置一个字段未null, 使用setNull()。要通过名称查找一个字段的位置，使用indexOf()，以及要查找字段名称在特定位置，使用fieldName()。使用field()获取指定字段的OSqlField对象。使用contains()查看一个记录是否包含特定的字段名称。

当对数据库执行查询时，仅那些对于isGenerated()为true的字段才被包含在了产生的SQL中。

用append()或insert()添加，一个记录有的字段，用replace()替代，用remove()移除。所有字段可以用clear()删除。字段数目由count()获取，使用clearValues()清除所有它们的值。

成员函数文档

QSqlRecord::QSqlRecord()

构造一个空记录。

QSqlRecord::QSqlRecord(const QSsqlRecord &other)

构造other的一个副本。

QSqlRecord::~QSqlRecord()

销毁这个对象并且释放所有资源。

void QSqlRecord::append(const QSqlField &field)

添加字段field的一个副本到这个记录末尾。

void QSqlRecord::clear()

删除所有这个记录的字段。

void QSqlRecord::clearValues()

清除这个字段中所有字段的值并且设置每个字段为null。

bool QSqlRecord::contains(const QString &name) const

如果在这个记录中有一个名为name的记录，返回true；否则返回false。

int QSqlRecord::count() const

返回这个记录中字段数目。

QSqlField QSqlReocrd::field(int index) const

返回位置index处的字段。如果index超出范围，函数返回一个默认的构造值。

QSqlField QSqlRecord::field(const QString &name) const

这是重载函数。返回名为name的字段。

QString QSqlRecord::fieldName(int index) const

返回指定位置的字段的名称。如果这个字段不存在，返回一个空串。

int QSqlRecord::indexOf(const QString &name)

返回记录中名为name的字段的位置，否则，如果找不到它，返回-1。字段名不区分大小写。如果匹配了多个字段，返回第一个字段。

void QSqlRecord::insert(int pos, const QSqlField &field)

在记录中位置pos插入字段field。

bool QSqlRecord::isEmpty() const

如果在记录中没有字段，返回true，否则返回false。

bool  QSqlRecord::isGenerated(const QString &name) const

如果记录有一个名为name的字段并且这个字段要被生成(默认)，返回true，否则返回false。

bool  QSqlRecord::isGenerated(int index) const

这是重载函数。如果记录在位置index有一个字段并且这个字段是要被生成的(默认)，返回true。否则，返回false。

bool QSqlRecord::isNull(const QString &name) const

如果名为name的字段是null，或者美欧名为name的字段，返回true；否则返回false。

bool QSqlRecord::isNull(int index) const

这是重载函数。如果字段index是null，或者在位置index没有字段，返回true；否则，返回false。

QSqlRecord QSqlRecord::keyValues(const QSqlRecord &keyFields) const

返回一个包含用keyFields表示的字段的记录，被设置成了由字段名匹配的值。

void QSqlRecord::remove(int pos)

删除位置pos处的字段。如果pos超过范围，什么也不发生。

void QSqlRecord::replace(int pos, const QSqlField &field)

用指定字段替代位置pos处的字段。如果pos超出范围，什么也不发生。

void QSqlRecord::setGenerated(const QString &name, bool generated)

为名为name要产生的字段设置产生标记。如果字段不存在，什么都不发生。包含在SQL中仅设置generated为true的字段才由如QSqlQueryModel产生。

void QSqlRecord::setGenerated(const QString &name, bool generated)

为名为name要产生的字段设置产生标记。如果字段不存在，什么也不发生。包含在SQL中generated仅设置成true的字段才由QSqlQueryModel产生。

void QSqlRecord::setGenerated(int index, bool generated)

这是一个过载函数。为索引为index要产生的字段设置generated标记。

void QSqlRecord::setNull(int index)

设置字段索引的值为null。如果字段不存在，什么也不发生。

void QSqlRecord::setNull(const QString &name)

这是重载函数。设置名为name的字段的值为null。如果这个字段不存在，什么也不发生。

void QSqlRecord::setValue(int index, const QVariant &val)

设置位置index处的字段的值为val。如果这个字段不存在，什么也不发生。

void QSqlRecord::setValue(const QString &name , const QVariant &val)

这是重载函数。设置名为name的字段的值为val。如果这个字段不存在，什么也不发生

QVariant QSqlRecord::value(int index) const

返回记录中位置index处的字段的值。如果index无效，返回一个无效的QVariant。

QVariant QSqlRecord::value(const QString &name)

重载函数。返回记录中名为name的字段的值。如果字段不存在，返回一个无效变量。

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

如果这个对象不同于other，返回true，否则返回false。

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

设置这个记录等于other。

QSqlRecord是隐式共享的。这表示你可以在恒定事件中复制一个记录。

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

如果这个对象同于other，返回true，否则返回false。

11、QSqlResult类

QSqlResult类提供一个用于访问来自特定数据库的抽象接口。

头：#include <QSqlResult>

qmake：QT += sql

受保护类型

enum BindingSyntax{PositionBinding, NamedBinding}

详细描述

QSqlResult类提供一个用于访问来自特定数据库的抽象接口。

通常，你是应用QSqlQuery替代QSqlResult，由于QSqlQuery为QSqlResult的特定数据库实现提供了一个通用的包装器。

如果你时下你你自己的SQL驱动(通过子类化QSqlDriver)，你将需要提供你自己的实现了你所需的纯虚函数和其它虚函数的QSqlResult子类。

成员类型文档

enum QSqlResult::BindingSyntax

这个枚举类型为预备查询中指定占位符指定不同的语法。

|-------------------------------|---|-----------------------------|
| 常数 | 值 | 描述 |
| QSqlResult::PositionalBinding | 0 | 使用ODBC风格位置参数，用?作为占位符 |
| QSqlResult::NamedBinding | 1 | 使用Oracle风格语法，命名的占位符(例如：:id) |

[protected] QSqlResult::QSqlResult(const QSqlDriver *db)

使用驱动db创建一个QSqlResult。对象被初始化为一个无效的状态。

[protected] QSqlResult::QSqlResult()

销毁这个对象并且释放所有资源。

[protected] QSqlResult::addBindValue(const QVariant &val, QSql::ParamType paramType)

绑定参数类型paramType的值val到当前记录的下个可用位置(行)。

[protected] int QSqlResult::at() const

返回这个结果的当前(基于0)行的位置。可能返回特殊值QSql::BeforeFirstRow或QSql::AfterLastRow。

[virtual protected] void QSqlResult::bindValue(int index, const QVariant &val, QSql::ParamType paramType)

绑定参数类型paramType的值val为当前记录中位置index(行)。

[virtual protected] void QSqlResult::bindValue(const QString &placeholder, const QVariant &val, QSql::ParamType paramType)

这是重载函数。绑定参数类型paramType的值val到当前记录中占位符名称name(行)。

注意：绑定一个未定义的占位符，将导致未定义的结果。

[protected] QSql::ParamType QSqlResult::bindValueType(int index) const

返回被绑定在位置index处的值的参数类型。

[protected] QSql::ParamType QSqlResult::bindValueType(const QString &placeholder) const

这是一个重载函数。

返回对应绑定了指定占位符名称的值的参数类型。

[protected] BindingSyntax QSqlResult::bindingSyntax() const

返回预备查询使用的绑定参数。

[protected] QVariant QSqlResult::boundValue(int index) const

返回在当前记录中绑定在位置index的值。

[protected] QVariant QSqlResult::boundValue(const QString &placerholder)

这是过载函数。

返回当前记录中由指定占位符名称绑定的值。

[protected] QString QSqlResult::boundValueCount() const

返回结果中绑定值的数目。

[protected] QString QSqlResult::boundValueName(int index) const

返回当前记录中位置index的绑定值的名称。

[protected] QVector<QVariant> &QSqlResult::boundValues() const

返回对应当前记录的结果的绑定值的向量(QVector)。

[protected] void QSqlResult::clear()

清除整个结构集并且释放所有关联的资源。

[pure virtual protected] QVariant QSqlResult::data(int index)

以QVariant返回当前行中对应字段index的数据。仅在这个结果处于有效状态并且被定位在一个有效记录并且index非负时，才调用这个函数。派生类必须重新实现这个函数并且返回字段index的值，如果不能确定它，QVariant()。

[protected] const QSqlDriver * QSqlResult::driver() const

返回于这个结果相关联的驱动。这是被传递给构造函数的对象。

[virtual protected] bool QSqlResult::exec()

执行查询，如果成功，返回true，否则返回false。

[protected] QString QSqlResult::executedQuery() const

返回被实际执行的查询。这可能不同于被传递的查询，例如，如果和预备查询一起使用绑定值，而下层数据库不支持预备查询。

[pure virtual protected] bool QSqlResult::fetch(int index)

定位结果到一个任意(基于0)的行索引。

仅在结果处于有效状态时才调用这个函数。派生类必须重新实现这个函数，并且定位结果到这个行索引，并且用合适的值调用setAt()。返回true表示成功，或false表示失败。

[pure virtual protected] bool QSqlResult::fetchFirst()

定位结果到结果中的第一个记录(行0)。派生类必须重新实现这个函数，并且定位结果到第一个记录，并且用合适的值调用setAt()。返回true表示成功，或false表示 失败。

[pure virtual protected] bool QSqlResult::fetchLast()

定位姐到记录中最右一个记录。

仅在结果处于有效状态时才调用这个函数。派生类必须重新实现这个函数，并且定位结果到最后一个记录，并且用合适的值调用setAt()。返回true表明成功，或false表示失败。

[virtual protected] bool QSqlResult::fetchNext()

在结果中定位结果到下一个可用的记录(行)。

仅在结果处于有效状态时才调用这个函数。默认实现用下一个索引调用fetch()。派生类可以重新实现这个函数，并且用某种其它方式定位结果到下一个记录，并且用合适的值调用setAt()。返回true表明成功，或false表示失败。

[virtual protected] bool QSqlResult::fetchPrevious()

在结果中定位记录到前一个记录(行)。

仅在结果处于有效状态时才调用这个函数。默认实现用前一个索引调用fetch()。派生类可以重新实现这个函数，并且用某种方式定位结果到下个记录，并且用合适值调用setAt()。返回true表明成功，或false表示失败。

[virtual] QVariant QSqlResult::handle() const

返回这个结果集的底层数据库句柄，被包在了一个QVariant，如果没有句柄，一个无效QVariant。

警告：使用这个尤其小心，并在仅在你知道你正在做什么。

警告：如果结果被修改(例如，你清除了它)，这里返回的句柄会成为失效指针。

警告：如果记录还未被执行，这个句柄会是NULL。

这里返回的句柄是依赖数据库的，在访问它前，你应该查询这个变量的类型名称。

[protected] bool QSqlResult::hasOutValues() const

查询的绑定值中最少一个是QSql::Out或者QSql::InOut，返回true，否则返回false。

[protected] bool QSqlResult::isActive() const

如果这个结果有要被获取的记录，返回true，否则返回false。

[protected] bool QSqlResult::isForwardOnly() const

如果你只能向前浏览结果集，返回true，否则返回false。

[pure virtual protected] bool QSqlResult::isNull(int index)

如果位于当前行中位置index的字段是null，返回true，否则返回false。

[protected] bool QSqlResult::isSelect() const

如果当前结果集来自一条SELECT语句，返回true，否则返回false。

[protected] bool QSqlResult::isValid() const

如果结果被定位在了一个有效记录上(既是，结果不是被定位在第一个前或者最后一个之后)；否则返回false。

[protected] QSqlError QSqlResult::lastError() const

返回与这个结果关联的上个错误。'

[virtual protected] QVariant QSqlResult::lastInsertId() const 

如果数据库支持，返回最近插入的对象ID。如果查询未插入任何值或者数据库不支持回报id，将返回一个无效QVariant。如果多行受到插入影响，行为是未定义的。

注意：对于Oracle数据库，将返回行的ROWID，而对于MySQL数据库，将返回自增字段。

[protected] QString QSqlResult::lastQuery() const

返回当前的SQL查询文本，或者没有，一个空串。

[pure virtual protected] int QSqlResult::numRowsAffected()

返回受到上次执行的查询影响的行数，或者如果查询是一条SELECT语句或者不能确定，返回-1。

[virtual protected] bool QSqlResult::prepare(const QString &query)

为执行预备指定的查询；查询将正常地使用占位符，使得它可以被重复地执行。如果查询成功预备，返回true，否则返回false。

[virtual protected] QSqlRecord QSqlResult::record() const

如果查询是有效地，返回当前地记录，否则返回一个空地QSqlRecord。

默认实现总是返回一个空的QSqlRecord。

[pure virtual protected] bool QSqlResult::reset(const QString &query)

为后续数据获取，设置结果使用SQL语句。

派生类必须重新实现这个函数并且对数据库使用这个查询。在结果被设置成失效状态后才调用这个函数，并且定位在了新结果的第一条记录前。如果查询成功并且准备要被使用，派生类应该返回true，否则返回false。

[protected] void QSqlResult::resetBindCount()

返回绑定参数的数目。

[virtual protected] bool QSqlResult::savePrepare(const QString &query)

预备指定的查询，在可能时，使用下层数据库功能。如果查询预备成功，返回true，否则返回false。

注意：此方法应该被成为"safePrepared()"

[virtual protected] void QSqlResult::setActive(bool use)

为派生类提供此函数设置内部有效状态为active。

[virtual protected] void QSqlResult::setAt(int index) 

为派生类提供这个函数设置内部行位置为index。

[virtual protected] void QSqlResult::setForwardOnly(bool forward) 

设置仅向前模式为forward。如果forward为true，仅允许fetchNext()来浏览结果。仅向前模式需要少得多的内存，由于结果不需要缓存。默认，此特性被禁用。

设置仅向前为false，是对数据库引擎的建议，数据库引擎最终决定一个结果集是仅向前或者可滚动。isForwardOnly()将总是返回结果集的正确状态。

注意：在查询执行后，调用setForwardOnly将导致无法预计的结果，并且最坏情况是崩溃。

[virtual protected] void QSqlResult::setLastError(const QString &error)

为派生类提供这个函数设置上次错误为error

[virtual protected] void QSqlResult::setQuery(const QString &query)

为结果设置当前查询为query。你必须调用reset()对数据库执行这个query。

[virtual protected] void QSqlResult::setSelect(bool select)

为派生类提供这个函数表示当前语句是否是一条SQL SELECT语句。如果语句是SELECT语句，select参数应该是true，否则它应该是false。

[pure virtual protected] int QSqlResult::size()

返回SELECT结果的大小，或者如果不能确定或者如果查询不是SELECT语句，返回-1。

12、QSqlQueryModel类

QSqlQueryModel类为SQL结果集提供了一个只读数据模型。

头：#include <QSqlQueryModel>

qmake：QT += sql

继承：QAbstrctTableModel

由QSqlTableModel继承。

详细描述

QSqlQueryModel类为SQL结果集提供了一个只读数据模型。

QSqlQueryModel是一个高级接口，用于执行SQL语句和翻译结果集。它在下层QSqlQuery上被构建，并且而可以用于提供数据给诸如QTableView的视图类。例如：

db = QSqlDatabase::addDatabase("QMYSQL");
db.setHostName("192.168.50.245");
db.setPort(3306);
db.setDatabaseName("mytestDB");
db.setUserName("test");
db.setPassword("@TESTtest");

if (db.open()){
    this->model = new QSqlQueryModel();
    this->model->setQuery("SELECT id , username , password , email FROM users;");
    this->model->setHeaderData(0, Qt::Horizontal, QVariant("ID"));
    this->model->setHeaderData(1, Qt::Horizontal, QVariant("Name"));
    this->model->setHeaderData(2, Qt::Horizontal, QVariant("Password"));
    this->model->setHeaderData(3, Qt::Horizontal, QVariant("Email"));

    ui->tableView->setModel(model);
}

运行结果：

我们设置模型的查询，接着我们设置视图头中显示的标签。

QSqlQueryModel也可以用于编程地访问数据库，而不需要绑定它到视图：

QSqlTableModel model;
model.setTable("users");
model.select();

int id = model.record(1).value("Id").toInt();

以上代码段从查询SELECT * FROM users结果集中记录1提取"Id"字段。假设Id是是第2列，我们可以按以下重写最后一行：

id = model.data(model.index(1,0)).toInt();
qDebug() << "ID:" << id;

模型默认只读。要使得它读写，你必须子类化它并且重新实现setData()和flags()。零一个选项是使用QSqlTableModel，它提供了基于单个数据库表地读写模型。

querymodel示例展示了如何使用QSqlQueryModel显示指定查询结果。它也展示了如何子类化QSqlQueryModel在向用户展示它前自定义这些数据，以及如何根据QSqlQueryModel创建一个读写模型。

如果数据库未在查询中返回所选行地数目，这个型号将递增地获取行。更多信息见fetchMore()。

成员函数文档

QSqlQueryModel::QSqlQueryModel(QObject *parent = Q_NULLPTR)

用指定父对象创建一个空的QSqlQueryModel。

[virtual] QSqlQueryModel::~QSqlQueryModel()

销毁这个对象并且释放所有分配的资源。

[virtual] bool QSqlQueryModel::canFetchMore(const QModelIndex &parent = QModelIndex()) const

重新实现QAbstractItemModel::canFetchMore()。

如果从数据库读取更多行是可能的，返回true。这仅影响不回报查询大小的数据库(见：QSqlDriver::hasFeature())。

parent应该总是一个无效的QModelIndex。

[virtual] void QSqlQueryModel::clear()

清理模型并且释放所获取的资源。

[virtual] QVariant QSqlQueryModel::data(const QModelIndex &item, int role = Qt::DisplayRow) const

重新实现QAbstractItemModel::clear()

返回对应指定item和role的值。

[virtual] void QSqlQueryModel::fetchMore(const QModelIndex &parent = QModelIndex())

重新实现来自QAbstractItemModel::fetchMore()。

从数据库获取更多行。这只影响不支持回报查询大小的数据库。(见QSqlDriver::hasFeature)。

要强制获取整个结果集，你可以使用以下：

while (myModel->canFetchMore())
    myModel->fetchMore();

parent应该总是一个无效的QModelIndex。

[virtual] QVariant QSqlQueryModel::headerData(int section, Qt::Qrientation orientation, int role = Qt::DisplayRole)

重新实现QAbstractItemModel::headerData()。

用指定方向返回这个header的section中指定role的头数据。

[virtual protected] QModelIndex QSqlQueryModel::indexInQuery(const QModelIndex &item) const 

为模型中指定item返回数据库结果集中值的索引。

如果没有插入，移除或移动列，返回值与item相同。

如果item越界或者item没有指向结果集中的值，返回一个无效模型索引。

[virtual] bool QSqlQueryModel::insertColumns(int column, int count, const QModelIndex &parent = QModelIndex())

重新实现QAbstractItemModel::insertColumns()。

在位置column向模型插入count列。父对象必须总是一个无效QModelIndex，由于这个模型不支持父-子关系。

如果column是在范围内，返回true，否则返回false。

默认，插入的列必须空。要用数据填充它们，重新实现data()并且单独处理任何插入的列。

QVariant MyModel::data(const QModelIndex &item, int role) const
{
    if (item.column() == m_specialColumnNo){
        // 单独处理列
    }
    return QSqlQueryModel::data(item, role);
}

QSqlError QSqlQueryModel::lastError() const

返回在数据库上上次发生的错误。

QSqlQuery QSqlQueryModel::query() const

返回与这个模型相关联的QSqlQuery()。

[virtual protected] void QSqlQueryModel::queryChange()

这是在查询变化时被调用的虚函数。默认实现什么也不做。

query()返回新查询。

QSqlRecord QSqlQueryModel::record(int row) const

返回包含当前查询的字段的信息的记录。如果row时一个有效索引，将用来自那行的值填充这个记录。

如果这个模型没有被初始化，将返回一个空记录。

QSqlRecord QSqlQueryModel::record() const

这是重载函数。

返回包含当前查询的字段的信息的一个空记录。

如果这个模型没有被初始化，将返回一个空记录。

[virtual] bool QSqlQueryModel::removeColumns(int column, int count, const QModelIndex &parent = QModelIndex())

重新实现QAbstractModel::removeColumns()。

从模型中删除从位置column开始的count列。父参数必须总是一个无效的QModelIndex，由于此模型不支持父-子关系。

删除列有效地隐藏了它们。它不影响下层地QSqlQuery。

如果列被删除了，返回true，否则返回false。

[virtual] int QSqlQueryModel::rowCount(const QModelIndex &parent = QModelIndex()) const

重新实现QAbstractItemModel::rowCount()。

如果数据库支持返回一个查询的大小(见QSqlDriver::hasFeature)，返回当前查询的行数。否则，返回当前缓存在客户端上的行数。

parent应该总是一个无效的QModelIndex。

[virtual] bool QSqlQueryModel::setHeaderData(int section, Qt::Orientation orientation, const QVariant &value, int role = Qt::EditRole)

重新实现了QAbstractItemModel::setHeaderData()。

用指定的role设置水平头的标题为value。如果这个模型用于在视图中显示数据，这是有用的。

如果orientation是Qt::Horizontal并且section指向一个有效段，返回true，否则返回false。

注意：不能调用这个函数修改数据库中的值，因俄日这个模型是只读的。

[protected] void QSqlQueryModel::setLastError(const QsqlError &error)

受保护函数，它允许派生类设置在数据库上发生的上次错误为error。

void QSqlQueryModel::setQuery(const QSqlQuery &query)

重置模型并且设置数据提供者为指定的查询。注意，查询必须有效并且必须不是isForwardOnly()。

如果由一个设置这个查询的错误，lastError()可以用于获取详细的信息。

注意：调用setQuery()将删除所有插入的列。

void QSqlQueryModel::setQuery(const QSqlQuery &query， const QSqlDatabase &db = QSqlDatabase())

这是重载函数。

为指定的数据库连接db执行查询query。如果没有指定数据库(或者无效数据库)，使用默认连接。

如果由设置这个查询的错误，lastError()用于获取详细信息。

示例：

QSqlQueryModel model;
model.setQuery("SELECT * FROM MyTable");
if (model.lastError().isValid())
    qDebug() << model.lastError();

13、QSqlRelationalDelegate类

QSqlRelationalDelegate类提供了一个委托，它用来显示和编辑来自QSqlRelationalModel的数据。

头：#inlcude <QSqlRelationalDelegate>

qmake：QT += sql

继承：QItemDelegate

详细描述

QSqlRelationalDelegate类提供了一个委托，它用来显示和编辑来自QSqlRelationalModel的数据。

不同于默认的委托，QSqlRelationalDelegate为作为到其它表的外键的字段提供了一个组合框。要使用这个类，只要在视图上用一个QSqlRelationalDelegate的示例调用QAbstractItemView::setItemDelegate()。

QTableView *view = new QTableView;
view->setModel(model);
view->setItemDelegate(new QSqlRelationalDelegate(view));

成员函数

QSqlRelationalDelegate::QSqlRelationalDelegate(QObject * parent = nullptr)

用指定的父对象构造一个QSqlReationalDelegate对象。

QSqlRelationalDelegate::~QSqlRelationalDelegate()

销毁这个个QSqlReationalDelegate对象并且释放所有资源。

[override virtual]QSqlRelationalDelegate::createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const

重新实现了QAbstractItemDeletegate::createEditor()。

[override virtual]QSqlRelationalDelegate::setDataModel(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const

重新实现了QAbstractItemDeletegate::setModelData()。

14、QSqlRelation 类

QSqlRelation类存储有关一个SQL外键的信息。

头：#include<QSqlRelation>

qmake：QT += sql

详细描述

QSqlRelation类存储有关一个SQL外键的信息。

QSqlRelation时QSqlRelationalTableModel的帮助类。详见QSqlRelationalTableModel::setRelation()和QSqlRelationalTableModel::relation()。

成员函数文档

QSqlRelation::QSqlRelation()

构建一个无效的QSqlRelation对象。

对于这样一个对象，tableName()， indexColumn和displayColumn()函数返回一个空字符串。

QSqlRelation::QSqlRelation(const QString &tableName, const QString &indexColumn, const QString &displayColumn)

构造一个QSqlRelation对象，此处tableName是外键指向的一个SQL表名，indexColumn是这个外键，而displayColumn是应该显示给使用者的字段。

QString QSqlRelation::displayColumn() const

从要展现给使用者的表tableName()返回列，而不是外键。

QString QSqlRelation::indexColumn() const

从一个外键指向的表tableName()返回索引列。

bool QSqlRelation::isValid() const

如果这个QSqlRelation对象哟i小，返回真，否则返回false。

void QSqlRelation::swap(QSqlRelation &other)

QString QSqlRelation::tableName() const

返回一个外键指向的表的名称。

15、QSqlRelationalTableModel类

QSqlRelationalTableModel类提供了一个带有外键支持的对单个数据库表的可编辑数据支持。

头：#include <QSqlRelationTableModel>

qmake：QT += sql

继承：QSqlTableModel

公有类型

enum JoinMode {InnerJoin, LeftJoin}

详细描述

QSqlRelationalTableModel类提供了一个带有外键支持的对单个数据库表的可编辑数据支持。

QSqlRelationalTableModel作用类似QSqlTableModel，但允许用其它数据库表当成外键设置列。

在QTableView中，左边截图展示了一个文本QSqlTableModel。外键(city和country)未被解析成人可读的值。右侧截图展示了一个QSqlRelationTableModel，外键解析成了人可读的字符串。

以下代码片段展示了如何设置QSqlRelationTableModel：

model->setTable("emplyee");

model->setRelation(2, QSqlRelation("city", "id", "name"));
model->setRelation(3, QSqlRelation("country", "id", "name"));

setRelation()函数调用在两个表之间建立一个关系。第一个调用指定表employee中第2列是一个外键映射成表city的字段id，并且此视图应该显示city的name字段给使用者。第二个调用对第3列做相同的事情。

如果你使用一个读写QSqlRelationalTableModel，你可能想要对这个视图使用QSqlRelationDelegate。不同于默认的委托，QSqlRelationDelegate为字段提供了一个复选框，它们是对其它表的外键。要使用这个类，只要用QSqlRelationDelegate的实例对视图调用QAbstractItemView::setItemDelegate()。

QTableView *view = new QTableView;
view->setModel(model);
view->setItemDelegate(new QSqlRelationalDelegate(view));

relationaltablemodel示例说明了如何使用QSqlRelationTable和QSqlRelationDelegate一起提供了对表的外键支持。

注意：

• 表必须有一个声明的主键。
• 表的主键不能包含对另一个表的关系。
• 如果一个关系表包含健指向被引用表中不存在的列，这些包含无效健的行不能通过这个模型被展示。使用者负责保持参考完整性。
• 如果一个关系的显示列名也用作关系表中一个列名，或者如果它在多个关系中用作显示列名，它将被用别名。别名是关系的表名，显示列名和一个唯一id由下划线组合（例如：tablename_columnname_id）。QSqlRecord::fieldName()将返回这个被用别名的列名。当发现重复时，所有出现的重复显示列名被命名别名，但对主表中的列名不进行命别名。别名不影响QSqlRelation，因此QSqlRelation::display()将返回原来的显示列名。
• 参考表名被命别名。别名是"relTblAl"并且关系的列索引由下划线组合(例如：relTblAl_2)。别名可以用于过滤表(例如：setFiltter("relTblAl_2='Oslo' 或relTblAl_3='USA'" ) )。
• 当使用setData()，角色应该总是Qt::EditRole，并且使用data()时，角色应该总是Qt::DisplayRole。

成员类型文档

|-------------------------------------|---|---------------------------|
| 常数 | 值 | 描述 |
| QSqlRelationalTableModel::InnerJoin | 0 | 内连接模式，当在两个表中有至少一个匹配时，返回行。 |
| QSqlRelationalTableModel::LeftJoin | 1 | 左连接，返回左表的左右行，即使在右表中没有匹配 |

成员函数文档

QSqlRelationalTableModel::QSqlRelationalTableModel(QObject *parent = Q_NULLPTR, QSqlDatabase db = QSqlDatabase())

创建一个空QSqlRelationalTableModel并且设置父对象为parent，数据库连接为db。如果db非空，将使用默认数据库连接。

[virtual] QSqlRelationalTableModel::~QSqlRelationalTableModel()

销毁这个对象并且释放所有分配的资源。

[virtual] void QSqlRelationalTableModel::clear()

重新实现了QSqlQueryModel::clear()

[virtual] QVariant QSqlRelationalTableModel::data(const QModelIndex &index, int role = Qt::DisplayRole) const

重新实现了QAbstractItemModel::data()

[virtual protected] bool QSqlRelationalTableModel::insertRowInfoTable(const QSqlRecord &values)

重新实现了QSqlTableModel::insertRowIntoTable。

[virtual protected] QString QSqlRelationalTableModel::orderByClause() const

重新实现了QSqlTableModel::orderByClause()。

QSqlRelation ​QSqlRelationalTableModel::relation(int column) const

返回对应列column的关系，如果没有设置关系，一个无效关系。

[virtual] QSqlTableModel * QSqlRelationTableModel::relationModel(int column) const

返回访问其列是一个外键的表的QSqlTableModel对象，或者如果对于指定列没有关系，返回0。

返回的对象是由QSqlRelationalTableModel所有。

[virtual] bool QSqlRelationalTableModel::removeColumns(int column, int count, const QModelIndex &parent = QModelIndex())

重新实现了QAbstractItemModel::removeColumns()。

[virtual slot] void QSqlRelationalTableModel::revertRow(int row) 

重新实现了QSqlTabelModel::revertRow(int row)

[virtual] bool QSqlRelationalTabelModel::select()  

重新实现了QSqlTableModel::select()。

[virtual protected] QString QSqlRelationalTabelModel::selectStatement() const  

重新实现QSqlTableModel::selectStatement()。

[virtual] bool QSqlRelationalTableModel::setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole)

重新实现了QAbstractItemModel::setData()。

设置指定索引的项中的role设置数据为指定值。取决于编辑策略，这个值可能立即应用于数据库，或者它可能被缓存于这个模型。

如果值可以被设置，返回true，出错返回。(例如，如果索引越界)

对于关系的列，值必须是索引，不是显示的值。索引必须也存在于存在于参考的表中，否则函数返回false。

void QSqlRelationalTableModel::setJoinMode(QSqlRelationalTableModel::JoinMode joinMode)

设置SQL joinMode来显示或隐藏带NULL外键的行。在InnerJoin模式(默认)，这些行将不被显示：如果你想要显示它们，使用LeftJoin模式。

[virtual] void QSqlRelationalTableModel::setRelation(int column, const QSqlRelation &relation)

让指定的列成为relation指定的外键索引。

示例：

model->setTable("employee");
model->setRelation(2, QSqlRelation("city", "id", "name"));

setRelation()调用指定了表employee中第2列是一个外键，用表city中id字段映射，并且视图应该显示city的name字段给使用者。

注意：表的主键不能包含对另一个表的关系。

[virtual] void QSqlRelationalTableModel::setTable(const QString &table)

重新实现了QSqlTableModel::setTable()。

[virtual proected] bool QSqlRelationalTableModel::updateRowInTable(int row, const QSqlRecord &value)

重新实现了QSqlTableModel::updateRowInTable()。

16、QSqlTableModel类

QSqlTableModel类为单个数据库表提供了一个可编辑的数据模型。

头：#include <QSqlTableModel>

qmake：QT += sql

继承：QSqlQueryModel

由QSqlRelationTableModel继承。

详细描述

QSqlTableModel类为单个数据库表提供了一个可编辑的数据模型。

QSqlTableModel是一个用于从单个表读取和编写数据库记录的高级接口。它建立在底层QSqlQuery上，并且可以用于提供诸如QTableView的视图。例如：

QSqlTableModel * model = new QSqlTableModel(parentObject , database);
model->setTable("employee");
moedl->setEditStrategy(QSqlTableModel::OnManualSubmit);
model->select();
model->setHeaderData(0, Qt::Horizontal, tr("Name"));
model->setHeaderData(1, Qt::Horizontal, tr("Salary"));

QTableView *view = new QTableView;
view->setModel(model);
view->hideColumn(0);
view->show();

我们设置了SQL表的名称和编辑策略，接着我们设置视图头中显示的标签。编辑策略确定由在视图中的使用者实际应用于数据库时进行更改。可能的值是OnFieldChange, OnRowChange和OnManualSubmit。

QSqlTableModel可以用于编程方式访问数据库，不需要绑定它到视图：

QSqlTableModel model;
model.setTable("employee");
model.select();
int salary = model.record(4).value("salary").toInt();

以上代码片段在查询SELECT * FROM employee的记录4中提取了salary字段。

使用setFilter()设置过滤器，或者使用setSort排列顺序是可能的。最后，你必须调用select()用数据填充这个模型。

tablemodel示例展示了如何使用QSqlTableModel作为QTable的数据源。

QSqlTableModel不直接支持外键。如果你想要解析外键，使用QSqlRelationalTableModel和QSqlRelationalDelegate。

成员类型文档

枚举类型描述了当编辑数据库中值时，使用哪个策略。

|-------------------------------|---|-----------------------------------------|
| 常数 | 值 | 描述 |
| QSqlTableModel::OnFieldChange | 0 | 对模型的所有更改被立即用于数据库 |
| QSqlTableModel::OnRowChange | 1 | 当使用者选择一个不同行时，将使用对一行的更改 |
| QSqlTableModel::OnManulSubmit | 2 | 在调用submitAll()或revertAll()前，所有更改被缓存在模型中 |

注意：为了防止向数据库插入仅部分初始化的行，对于新插入的行，OnFieldChange将行为类似OnRowChange

成员函数文档

QSqlTableModel::QSqlTableModel(QObject * parent = Q_NULLPTR, QSqlDatabase db = QSqlDatabase())

创建一个空的QSqlTableModel并且设置其父对象为parent，和数据库连接为db。如果db无效，默认数据库连接将被使用。

默认编辑策略是OnRowChange。

[virtual] QSqlTableMdoel::~QSqlTableModel()

销毁这个对象并且释放所有资源。

[signal] void QSqlTableMdoel::beforeInsert(QSqlRecord &record)

在一新行被插入到当前有效数据库表前，由insertRowIntoTable()发出这个信号。将要被插入的值被存储在记录中，并且在将插入它们前，可以被修改。

[signal] void QSqlTableMdoel::beforeUpdate(QSqlRecord &record)

在用来自record的值更新当前有效数据库表中行前，由updateRowInTable()发出这个信号。

[virtual] void QSqlTableMdoel::clear()

重新实现QSqlQueryModel::clear()

[virtual] QVariant QSqlTableMdoel::data(const QModelIndex &index, int role = Qt::DisplayRole) const

重新实现QAbstractItemModel::data()。

[virtual] QVariant QSqlTableModel::database() const

返回模型的数据库连接。

[virtual protected] bool QSqlTableModel::deleteRowFromTable(int row) const

从当前有效数据库表删除指定行。

这是一个底层方法，对数据库直接操作，并且不应该被直接调用。使用removeRow()或removes()删除值。这个模型将决定在修改数据库时的编辑策略。

如果这行被删除，返回true，否则返回false。

EditStrategy QSqlTableModel::editStrategy() const

返回当前编辑的策略。

int QSqlTableModel::fieldIndex(const QString &fieldName) const

返回字段名filedName的索引，或者如果在模型中没有相应字段-1。

QString QSqlTableModel::filter() const

返回当前设置的过滤器。

[virtual] Qt::ItemFlags QSqlTableModel::flags(const QModelIndex &index) const

重新实现QAbstractItemModel::flags()。

[virtual] QVariant QSqlTableModel::headerData(int section, Qt::Orientation, int role = Qt::DisplayRole)

重新实现QAbstractItemModel::headerData()。

[virtual protected] QModelIndex::indexInQuery(const QModelIndex &item)

重新实现QSqlQueryModel::indexInQuery()。

为模型中指定项返回数据库结果集中这个值的索引。

如果没有列或行被插入，删除或移动，返回值于item相同。

如果item越界，或者如果item不指向结果集中一个值，返回一个无效的模型索引。

[virtual protected] bool QSqlTableMdodel::insertRecord(int row, const QSqlRecord &record)

在位置row插入这个record。如果row是负数，记录将被追加到末尾。内部调用insertRows()和setRecord()。

如果记录可以被插入，返回true，否则返回false。

对于OnFieldchange和OnRowChange，立即提交更改。出错不在模型中留下一个新记录。

[virtual protected] bool QSqlTableModel::insertRowIntoTable(const QSqlRecord &values)

插入值values到当前有效的数据库表。

这是一个底层方法，它直接操作数据库，并且不应该被直接调用。使用insertRow()和setData()插入值。模型将取决于它的编辑策略，决定何时修改数据库。

如果值不应该被插入，返回true，否则false。用lastError()获取错误信息。

[virtual] bool QSqlTableModel::insertRows(int row, int count, QModelIndex &parent = QModelIndex())

重新实现了QAbstractItemModel::insertRows()。

在位置row插入count个空行。注意：parent必须无效，由于这个模型不支持父子关系。

对于编辑策略OnFieldChange和OnRowChange，一次仅能插入一行，并且模型不能包含其它缓存的变化。

将为每一新行发出primeInsert()信号。如果你想要用默认值初始化这一新行，连接它。

不管编辑策略，不要提交行。

如果参数越界或者行不能被插入，返回false，否则返回true。

bool QSqlTableModel::isDirty(const QModelIndex &index) const

如果索引index处的值是脏的，返回true。脏值是在模型中被修改但还未写入到数据库的值。

如果index无效或者指向一个不存在的行，返回false。

bool QSqlTableModel::isDirty() const

这是重载函数。如果模型包含被修改但还未写入数据库的值，返回true，否则返回false。

[virtual protected] QString QSqlTableModel::orderByClause() const

返回根据当前设定的排序的一个SQL ORDER BY条件。

QSqlIndex QSqlTableModel::primaryKey() const

返回当前表的主键，或者如果表未设置或者没有主键，一个空的QSqlIndex。

[protected] QSqlRecord QSqlTableModel::primaryValues(int row) const

返回一个记录，其包含主键在row行设为values的字段。如果主键没有定义，返回的记录将包含所有字段。

[signal] void QSqlTableModel::primeInsert(int row, QSqlRecord &record)

当在当前有效数据库表的指定行启动插入时，由insertRow()发出这个信号。这个记录参数可以被写入，例如用默认值填充某些字段并且设置字段的产生标记。当处理这个信号时，不要尝试通过诸如setData()或setRecord()编辑这个记录。

QSqlRecord QSqlTableModel::record() const

这是一个重载函数。

它返回一个仅有字段名称的空记录。这个函数可以用于获取一个记录的字段名。

QSqlRecord QSqlTableModel::record(int row) const

返回模型中row行的记录。

如果row是有效行，将用来自那行的值填充记录。

如果模型未初始化，将返回一个空的记录。

[virtual] bool QSqlTableModel::removeColumns(int column, int count, const QModelIndex &parent = QModelIndex())

重新实现QAbstractItemModel::removeColumns()

从parent模型从index列移除count列。

如果列被成功移除，返回真，否则返回false。

[virtual] bool QSqlTableModel::removeRows(int row, int count, const QModelIndex &parent = QModelIndex())

重新实现QAbstractItemModel::removeRows()。

删除从row开始的count行。由于这个模型不支持层级结构，parent必须是一个无效的模型索引。

当编辑策略是OnManualSubmit，从数据库删除行推迟到在调用submitAll()时。

对于OnField和OnRowChange时，一次仅删除一行并且只在没有其它行有一个缓存的更改时。删除立即被提交给了数据库。在用select()刷新前，模型未成功删除行保留一个空白行。

在删除失败后，操作在模型中不能被恢复。程序可以重新提交或者恢复。

在从数据库删除一行前，发出beforeDelete()信号。

如果row<0或者row+count > rowCount()，不采取操作并且返回false。如果所有行被删除，返回true，否则返回false。用lastError()获取详细的数据库错误信息。

[virtual slot ] void QSqlTableModel::revert() 

重新实现了QAbstractItemModel::revert()

当用户取消编辑当前行时，这个重新实现的槽被item委托调用。

如果模型的编辑策略设为OnRowChange或OnFieldChange，恢复更改。对于OnManualSubmit策略时，什么也不做。

使用revertAll()对于OnManualSubmit策略恢复所有要发生的变化或者revertRow()恢复一特定的行。

[slot] void QSqlTableModel::revertAll()

恢复所有要发生的变化。

[virtual] void QSqlTableModel::revertRow(int row)

恢复指定行的所有更改。

[virtual] int QSqlTableModel::rowCount(const QModelIndex &parent = QModelIndex()) const

重新实现QAbstractItemModel::rowCount()

[virtual slot] bool QSqlTableModel::select()

用通过来自用setTable设置的表的数据填充模型，使用指定过滤器和排序条件，如果成功返回true，否则返回false。

注意：调用select()将恢复任何未提交的改变并且删除任何插入的行。

[virtual slot] bool QSqlTableModel::selectRow(int row)

用来自匹配主键值的数据库表行的值刷新模型中的行。没有主键，所有列值必须匹配。如果没有找到匹配的行，模型将展示一空行。

如果成功，返回true，否则返回false。

[virtual protected] QString QSqlTableMdodal::selectStatement() const

返回内部使用来填充这个模型的SQL SELECT语句。语句包括过滤器和ORDER BY条件。

[virtual] bool QSqlTableModel::setData(const QModelIndex &index, const QVariant &value, int role::Qt::EditRole)

重新实现QAbstractItemModel::setData()。

为角色role设置项index的数据为value。

对于编辑策略OnFieldChange，仅在没有其它索引有缓存的变化时，一个索引才接收一个修改。修改立即被提交。但，还未插入到数据库中的行可以被随意更改并且不被立即提交。提交的变化遇到出错时不被恢复。

对于OnRowChange，只在没有其它行有缓存的变化时，一个索引才接收一个修改。不自动提交更改。

如果value等于当前值，返回true，但，值将不被提交给数据库。

如果值能被设置，返回true，出错，返回false，例如，如果index越界。

[virtual] void QSqlTableModel::setEditStrategy(EditStrategy strategy)

设置用于编辑数据库中值的策略为strategy。

者将恢复任何要进行的更改。

[virtual] void QSqlTableModel::setFilter(const QString &filter)

设置当前的过滤器为filter。

过滤器时一个没有关键字WHERE的SQL WHERE条件(例如：name='Josephine')。

如果模型已经用来自数据库的数据填充了，模型用新的过滤器重新select。否则，将在下次调用select()时使用这个过滤器。

[protected] void QSqlTableModel::setPrimaryKey(const QSqlIndex &key)

保护方法，它允许子类设置主键为key。

通常，在你调用setTable()时，主键自动被设置。

[protected] void QSqlTableModel::setQuery(const QSqlQuery &query)

这个函数指示调用QSqlQueryModel::setQuery(query)。你应该对QSqlTableModel不调用它。而是，使用setTable(), setSort()，setFilter()等来设置查询。

bool QSqlTableModel::setRecord(int row, const QSqlRecord &values)

对这个模型中的row使用values。通过字段名称，不是通过记录中位置，映射源和目标字段。

注意：在values中生成的标记被保留，并且在向数据库提交更改时，确定是否使用对应字段。调用者应该记住为数据库提供值的字段设置生成标记为FALSE，诸如自动增长的ID。

对于编辑策略OnFieldChange和OnRowChange，只在没有其它行有一个缓存的更改时，一行才接收一个更改。更改被立即提交。出错时，提交的更改不被恢复。

如果所有值可以被设置，返回true，否则返回false。

[virtual] void QSqlTableModel::setSort(int column, Qt::SortOrder order)

设置column的排序为order。这不影响当前数据，使用新排序调用select()刷新数据。

[virtual] void QSqlTableModel::setTable(const QString &tableName)

设置这个模型要操作的数据表为tableName。不从表选取数据，但是获取它的字段信息。

要用表的数据填充这个模型，调用select()。

用lastError()获取错误信息。

[virtual] void QSqlTableModel::sort(int column, Qt::SortOrder order)

重新实现QAbstractItemModel::sort()。

通过对column排序order排序数据。这将立即选择数据，使用setSort设置一个排序，而不用数据填充模型。

[virtual slot] bool QSqlTableModel::submit() 

重新实现了QAbstractItemModel::submit()。

这个重新实现的槽，由项代理在用户停止编辑当前行时被调用。

如果模型的策略设为OnRowChange或者OnFieldChange，提交当前编辑的行。对于OnManualSubmit策略，什么也不做。

使用submitAll()为OnManualSubmit策略提交所有要发生的更改。

成功返回true，或者返回false。使用lastError()查询详细的错误信息。

不要自动重新填充模型。提交的行在成功时被冲数据库刷新。

[slot] bool QSqlTableModel::submitAll()

提交所有要发生的更改，并且成功时返回true。出错时返回false，用lastError()获取详细的错误信息。

在OnManualSubmit中，成功时，模型将被重新填充，任何显示它的视图将丢失它们的选择。

注意：在OnManualSubmit模式中，当submitAll()失败时，不能从缓存清除已经提交的更改。这允许在不丢失数据下事务被回滚和被重新提交。

QString QSqlTableModel::tableName() const

返回当前选择的表的名称。

[virtual protected] bool QSqlTableModel::updateRowInTable(int row, const QSqlRecord &value)

用指定的values更新当前有效数据库中指定行。如果成功，返回true，否则返回false。

这是一个底层方法，它直接操作数据库，并且不应该被直接调用。使用setData()更新值。当要修改数据库时，这个模型更加它的编辑策略，决定。

注意：仅更新具有生成标记设置的值。用QSqlRecord::setGenerated设置生成标记，并且用QSqlRecord::isGenerated()测试生成标记。