Back to Qt.io
Contact Us Blog Download Qt
本页内容

QSqlRelationalTableModel Class

QSqlRelationalTableModel 类为单个数据库表提供了一个可编辑的数据模型，并支持外键。更多内容...

头文件： #include <QSqlRelationalTableModel>
CMake： find_package(Qt6 REQUIRED COMPONENTS Sql)
target_link_libraries(mytarget PRIVATE Qt6::Sql)
qmake： QT += sql
继承自： QSqlTableModel

公共类型

enum JoinMode { InnerJoin, LeftJoin }

公共函数

QSqlRelationalTableModel(QObject *parent = nullptr, const QSqlDatabase &db = QSqlDatabase())
virtual ~QSqlRelationalTableModel()
QSqlRelation relation(int column) const
virtual QSqlTableModel *relationModel(int column) const
void setJoinMode(QSqlRelationalTableModel::JoinMode joinMode)
virtual void setRelation(int column, const QSqlRelation &relation)

重新实现的公共函数

virtual void clear() override
virtual QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override
virtual bool removeColumns(int column, int count, const QModelIndex &parent = QModelIndex()) override
virtual bool select() override
virtual bool setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole) override
virtual void setTable(const QString &table) override

公共插槽

virtual void revertRow(int row) override

重新实现的受保护函数

virtual bool insertRowIntoTable(const QSqlRecord &values) override
virtual QString orderByClause() const override
virtual QString selectStatement() const override
virtual bool updateRowInTable(int row, const QSqlRecord &values) override

详细说明

QSqlRelationalTableModel 的行为与QSqlTableModel 类似，但允许将列设置为指向其他数据库表的外键。

显示城市和国家作为数值外键值的表格显示已转换为文本字符串的城市和国家/地区的表格

左侧的屏幕截图展示了一个位于QTableView 中的普通QSqlTableModel 。外键（city 和country ）并未解析为人类可读的值。右侧的屏幕截图展示了一个QSqlRelationalTableModel，其中外键已被解析为人类可读的文本字符串。

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

    model->setTable("employee");

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

通过调用setRelation()函数，可以在两个表之间建立关系。第一个调用指定表employee 的第2列是一个外键，与表city 的字段id 建立映射关系，并且视图应向用户展示city 的name 字段。第二个调用对第3列执行类似操作。

如果您使用的是可读写的 QSqlRelationalTableModel，那么您可能希望在视图上使用QSqlRelationalDelegate 。与默认委托不同，QSqlRelationalDelegate 会为作为其他表外键的字段提供下拉列表框。要使用该类，只需在视图上调用QAbstractItemView::setItemDelegate() 并传入QSqlRelationalDelegate 的实例即可：

    std::unique_ptr<QTableView> view{new QTableView};
    view->setModel(model);
    view->setItemDelegate(new QSqlRelationalDelegate(view.get()));

relationaltablemodel示例演示了如何将 QSqlRelationalTableModel 与QSqlRelationalDelegate 结合使用，为表提供外键支持。

用户可以编辑关系表中的外键

注意事项：

  • 表必须已声明主键。
  • 该表的主键不得包含指向另一张表的关联。
  • 如果关系表中包含引用了被引用表中不存在的行的键，则包含这些无效键的行将不会通过模型暴露出来。用户或数据库负责维护参照完整性。
  • 如果某个关系的显示列名同时被用作关系表中的列名，或者被用作多个关系的显示列名，则该列名将被别名化。 别名由关系表的表名、显示列名和一个唯一 ID 通过下划线连接而成（例如 tablename_columnname_id）。QSqlRecord::fieldName() 将返回该别名列名。 当检测到重复时，所有重复的显示列名都会被别名化，但主表中的列名不会被别名化。别名化不会影响 `QSqlRelation`，因此 `QSqlRelation::displayColumn()` 将返回原始的显示列名。
  • 引用表名会被别名化。别名由“relTblAl”和关系列索引通过下划线连接而成（例如 relTblAl_2）。 该别名可用于过滤表（例如，setFilter("relTblAl_2='Oslo' OR relTblAl_3='USA'")）。
  • 使用setData() 时，角色应始终为Qt::EditRole ；使用data() 时，角色应始终为Qt::DisplayRole 。

另请参阅 QSqlRelation 、QSqlRelationalDelegate 以及关系表模型示例。

成员类型文档

enum QSqlRelationalTableModel::JoinMode

常数值描述
QSqlRelationalTableModel::InnerJoin0- 内连接模式，当两张表中均至少存在一个匹配项时，返回相关行。
QSqlRelationalTableModel::LeftJoin1- 左连接模式，返回左表（table_name1）中的所有行，即使右表（table_name2）中没有匹配项。

另请参阅 QSqlRelationalTableModel::setJoinMode()。

成员函数文档

[explicit] QSqlRelationalTableModel::QSqlRelationalTableModel(QObject *parent = nullptr, const QSqlDatabase &db = QSqlDatabase())

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

[virtual noexcept] QSqlRelationalTableModel::~QSqlRelationalTableModel()

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

[override virtual] void QSqlRelationalTableModel::clear()

重写了：QSqlTableModel::clear()。

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

重写了：QSqlTableModel::data(const QModelIndex &index, int role) const。

另请参阅 setData()。

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

重写了：QSqlTableModel::insertRowIntoTable(const QSqlRecord &values)。

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

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

QSqlRelation QSqlRelationalTableModel::relation(int column) const

返回列column 的关联，如果未设置关联，则返回无效关联。

另请参阅 setRelation() 和QSqlRelation::isValid()。

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

返回一个QSqlTableModel 对象，用于访问column 作为外键的表；如果给定的column 不存在关联，则返回nullptr 。

返回的对象由 `QSqlRelationalTableModel` 拥有。

另请参阅 setRelation() 和relation()。

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

重写了：QSqlTableModel::removeColumns （int column, int count, const QModelIndex &parent）。

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

重新实现了：QSqlTableModel::revertRow(int row)。

[override virtual] bool QSqlRelationalTableModel::select()

重写了：QSqlTableModel::select()。

[override virtual protected] QString QSqlRelationalTableModel::selectStatement() const

重新实现了：QSqlTableModel::selectStatement() const。

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

重写了：QSqlTableModel::setData(const QModelIndex &index, const QVariant &value, int role)。

将指定index 对应的项中role 的数据设置为给定的value 。根据编辑策略的不同，该值可能会立即应用到数据库中，也可能被缓存到模型中。

若能成功设置值，则返回true ；若发生错误（例如index 超出范围），则返回false。

对于关系型列，value 必须是索引，而非显示值。如果指定了索引，该索引必须在所引用的表中存在，否则该函数将返回false 。如果传递的是 QVariant() 而不是索引，则索引将被清空。

另请参阅 editStrategy()、data()、submit() 和revertRow()。

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

设置 SQLjoinMode 以显示或隐藏外键为 NULL 的行。在InnerJoin 模式（默认）下，这些行将不会显示：若要显示它们，请使用LeftJoin 模式。

另请参阅 QSqlRelationalTableModel::JoinMode 。

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

假设指定的column 是一个由relation 指定的外键索引。

示例：

    model->setTable("employee");

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

setRelation() 调用指定表employee 中的第 2 列是一个外键，该外键与表city 的字段id 建立映射关系，并且视图应向用户展示city 的name 字段。

注意：表的主键不得包含与其他表的关联。

另请参阅 relation()。

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

重写了：QSqlTableModel::setTable(const QString &tableName)。

[override virtual protected] bool QSqlRelationalTableModel::updateRowInTable(int row, const QSqlRecord &values)

重写了：QSqlTableModel::updateRowInTable(int row, const QSqlRecord &values)。

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