Класс QSqlTableModel

Класс QSqlTableModel предоставляет изменяемую модель данных для единственной таблицы базы данных. Подробнее...

• Список всех членов, включая унаследованные
• Устаревшие члены

Открытые типы

Открытые функции

Переопределённые открытые функции

• 17 открытых функций унаследовано от QSqlQueryModel
• 4 открытых функции унаследовано от QAbstractTableModel
• 40 открытых функций унаследовано от QAbstractItemModel
• 31 открытых функций унаследовано от QObject

Открытые слоты

• 2 открытых слота унаследовано от QAbstractItemModel
• 1 открытый слот унаследовано от QObject

Сигналы

• 18 сигналов унаследовано от QAbstractItemModel
• 2 сигнала унаследовано от QObject

Статические открытые члены

• 9 статических открытых членов унаследовано от QObject

Защищённые функции

Реализованные защищённые функции

• 3 защищённых функции унаследованы от QSqlQueryModel
• 19 защищённых функций унаследованы от QAbstractItemModel
• 9 защищённых функций унаследованы от QObject

Дополнительные унаследованные члены

• 1 свойство унаследовано от QObject
• 1 защищённый слот унаследован от QAbstractItemModel

Подробное описание

Класс QSqlTableModel предоставляет редактируемую модель данных для одной таблицы базы данных.

QSqlTableModel — это высокоуровневый интерфейс для чтения и записи записей из одной таблицы базы данных. Он построен на базе QSqlQuery и может использоваться для предоставления данных для таких классов отображения, как QTableView. Например:

    QSqlTableModel *model = new QSqlTableModel(parentObject, database);
    model->setTable("employee");
    model->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); // don't show the ID
    view->show();

Мы задаём имя SQL-таблицы и стратегию редактирования, а затем настраиваем метки, отображаемые в заголовке представления. Стратегия редактирования определяет, когда изменения, внесённые пользователем в представлении, фактически применяются к базе данных. Возможные значения — OnFieldChange, OnRowChange и OnManualSubmit.

QSqlTableModel также может использоваться для доступа к базе данных программно, без привязки к представлению:

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

Приведённый выше фрагмент кода извлекает поле salary из записи 4 в наборе результатов запроса SELECT * from employee.

Можно задавать фильтры с помощью setFilter() или изменять порядок сортировки с помощью setSort(). В конце необходимо вызвать select() для заполнения модели данными.

Пример tablemodel демонстрирует, как использовать QSqlTableModel в качестве источника данных для QTableView.

QSqlTableModel не предоставляет прямой поддержки внешних ключей. Используйте QSqlRelationalTableModel и QSqlRelationalDelegate, если вам нужно разрешать внешние ключи.

См. также QSqlRelationalTableModel, QSqlQuery, Программирование моделей/представлений, Пример табличной модели и Пример кэшированной таблицы.

Документация по типам членов

перечисление QSqlTableModel::EditStrategy

Это перечисление типов описывает стратегию, которую следует выбрать при редактировании значений в базе данных.

Примечание: для предотвращения вставки в базу данных строк, инициализированных частично, OnFieldChange будет вести себя как OnRowChange для новых вставленных строк.

См. также setEditStrategy().

Документация по функциям-членам

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

Создаёт пустой QSqlTableModel и устанавливает родителя в parent и соединение с базой данных в db. Если db недействительно, будет использоваться по умолчанию.

Стратегия редактирования по умолчанию — OnRowChange.

[virtual] QSqlTableModel::~QSqlTableModel()

Уничтожает объект и освобождает все выделенные ресурсы.

[signal] void QSqlTableModel::beforeDelete(int row)

Этот сигнал излучается deleteRowFromTable() перед удалением строки row из текущей активной таблицы базы данных.

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

Этот сигнал излучается insertRowIntoTable() перед вставкой новой строки в текущую активную таблицу базы данных. Значения, которые должны быть вставлены, хранятся в record и могут быть изменены перед вставкой.

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

Этот сигнал излучается updateRowInTable() перед обновлением строки row в текущей активной таблице базы данных значениями из record.

Обратите внимание, что будут обновлены только значения, помеченные как сгенерированные. Флаг сгенерированного значения можно установить с помощью QSqlRecord::setGenerated() и проверить с помощью QSqlRecord::isGenerated().

См. также QSqlRecord::isGenerated().

[override virtual] void QSqlTableModel::clear()

Переопределено из QSqlQueryModel::clear().

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

Переопределено из QSqlQueryModel::data().

См. также setData().

QSqlDatabase QSqlTableModel::database() const

Возвращает соединение с базой данных модели.

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

Удаляет заданную строку row из текущей активной таблицы базы данных.

Это метод низкого уровня, который работает непосредственно с базой данных и не должен вызываться напрямую. Используйте removeRow() или removeRows() для удаления значений. Модель сама решит, когда изменить базу данных в зависимости от своей стратегии редактирования.

Возвращает true если строка была удалена; в противном случае возвращает false.

См. также removeRow() и removeRows().

QSqlTableModel::EditStrategy QSqlTableModel::editStrategy() const

Возвращает текущую стратегию редактирования.

См. также setEditStrategy().

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

Возвращает индекс поля fieldName или -1, если соответствующего поля в модели нет.

QString QSqlTableModel::filter() const

Возвращает текущий заданный фильтр.

См. также setFilter() и select().

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

Переопределено из QAbstractTableModel::flags().

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

Переопределено из QSqlQueryModel::headerData().

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

Переопределено из QSqlQueryModel::indexInQuery().

Возвращает индекс значения в наборе результатов базы данных для заданного элемента item в модели.

Значение возврата идентично item, если не было вставлено, удалено или перемещено строк или столбцов.

Возвращает недействительный индекс модели, если item находится за пределами границ или если item не указывает на значение в наборе результатов.

См. также QSqlQueryModel::indexInQuery().

bool QSqlTableModel::insertRecord(int row, const QSqlRecord &record)

Вставляет record в позицию row. Если row отрицательно, запись будет добавлена в конец. Вызывает insertRows() и setRecord() внутри.

Возвращает true если запись была успешно вставлена, в противном случае false.

Изменения отправляются немедленно для OnFieldChange и OnRowChange. Ошибка не оставит новую строку в модели.

См. также insertRows(), removeRows() и setRecord().

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

Вставляет значения values в текущую активную таблицу базы данных.

Это метод низкого уровня, который работает непосредственно с базой данных и не должен вызываться напрямую. Используйте insertRow() и setData() для вставки значений. Модель решит, когда изменить базу данных, в зависимости от своей стратегии редактирования.

Возвращает true если значения были успешно вставлены, в противном случае false. Информацию об ошибке можно получить с помощью lastError().

См. также lastError(), insertRow() и insertRows().

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

Переопределено из QAbstractItemModel::insertRows().

Вставляет count пустых строк в позицию row. Обратите внимание, что parent должна быть недействительной, так как эта модель не поддерживает отношения «родитель-потомок».

Для стратегий редактирования OnFieldChange и OnRowChange может быть вставлена только одна строка за раз, и модель не должна содержать другие кэшированные изменения.

Сигнал primeInsert() будет испускаться для каждой новой строки. Подключитесь к нему, если хотите инициализировать новую строку значениями по умолчанию.

Не отправляет строки, независимо от стратегии редактирования.

Возвращает false если параметры находятся за пределами границ или строка не может быть вставлена; в противном случае возвращает true.

См. также primeInsert() и insertRecord().

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

Возвращает true если значение по индексу index повреждено, в противном случае false. Изменённые значения — это значения, которые были изменены в модели, но ещё не записаны в базу данных.

Если index недействителен или указывает на несуществующую строку, возвращается false.

bool QSqlTableModel::isDirty() const

Это перегруженный метод.

Возвращает true если модель содержит изменённые значения, которые не были сохранены в базе данных, в противном случае false.

Этот метод был добавлен в Qt 5.0.

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

Возвращает SQL ORDER BY-оператор, основанный на текущем порядке сортировки.

См. также setSort() и selectStatement().

QSqlIndex QSqlTableModel::primaryKey() const

Возвращает первичный ключ для текущей таблицы или пустой QSqlIndex, если таблица не задана или не имеет первичного ключа.

См. также setTable(), setPrimaryKey() и QSqlDatabase::primaryIndex().

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

Возвращает запись, содержащую поля, представленные в первичном ключе, со значениями в позиции row. Если первичный ключ не определён, возвращаемая запись будет содержать все поля.

Этот метод был добавлен в Qt 5.1.

См. также primaryKey().

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

Этот сигнал испускается методом insertRows(), когда выполняется вставка в заданную строку row текущей активной таблицы базы данных. Параметр record может быть изменён (так как это ссылка), например, для заполнения некоторых полей значениями по умолчанию и установки сгенерированных флагов полей. Не пытайтесь изменять запись другими способами, такими как setData() или setRecord(), при обработке этого сигнала.

QSqlRecord QSqlTableModel::record() const

Это перегруженный метод.

Возвращает пустую запись, содержащую только имена полей. Этот метод может использоваться для получения имён полей записи.

См. также setRecord() и QSqlRecord::isEmpty().

QSqlRecord QSqlTableModel::record(int row) const

Возвращает запись в позиции row в модели.

Если row является индексом корректной строки, запись будет заполнена значениями из этой строки.

Если модель не инициализирована, возвращается пустая запись.

Этот метод был добавлен в Qt 5.0.

См. также QSqlRecord::isEmpty().

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

Переопределено из QSqlQueryModel::removeColumns().

Удаляет count столбцов из модели parent, начиная с индекса column.

Возвращает true, если столбцы были успешно удалены; в противном случае возвращает false.

См. также removeRows().

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

Переопределено из QAbstractItemModel::removeRows().

Удаляет count строк, начиная с row. Поскольку эта модель не поддерживает иерархические структуры, parent должна быть недействительным индексом модели.

Когда стратегия редактирования — OnManualSubmit, удаление строк из базы данных откладывается до вызова submitAll().

Для OnFieldChange и OnRowChange может быть удалена только одна строка за раз и только если у другой строки нет кэшированного изменения. Удаления отправляются в базу данных немедленно. Модель сохраняет пустую строку для удалённой строки до её обновления методом select().

После неудаленного удаления операция не отменяется в модели. Приложение может повторить или отменить операцию.

Вставленные, но ещё не успешно отправленные строки в диапазоне для удаления немедленно удаляются из модели.

Перед удалением строки из базы данных испускается сигнал beforeDelete().

Если row < 0 или row + count > rowCount(), никаких действий не выполняется, и возвращается false. Возвращает true если все строки были удалены; в противном случае возвращает false. Подробная информация об ошибке базы данных может быть получена с помощью lastError().

См. также removeColumns() и insertRows().

[override virtual slot] void QSqlTableModel::revert()

Переопределено из QAbstractItemModel::revert().

Этот переопределенный слот вызывается делегатами элементов, когда пользователь отменил редактирование текущей строки.

Отменяет изменения, если стратегия модели установлена на OnRowChange или OnFieldChange. Ничего не делает для стратегии OnManualSubmit.

Используйте revertAll(), чтобы отменить все ожидающие изменения для стратегии OnManualSubmit, или revertRow(), чтобы отменить изменения определённой строки.

См. также submit(), submitAll(), revertRow() и revertAll().

[slot] void QSqlTableModel::revertAll()

Отменяет все ожидающие изменения.

См. также revert(), revertRow() и submitAll().

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

Отменяет все изменения для указанной строки row.

См. также revert(), revertAll(), submit() и submitAll().

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

Переопределено из QSqlQueryModel::rowCount().

[virtual slot] bool QSqlTableModel::select()

Заполняет модель данными из таблицы, которая была установлена через setTable(), используя указанный фильтр и сортировку, и возвращает true при успехе; в противном случае возвращает false.

Примечание: Вызов select() отменит все несохранённые изменения и удалит любые добавленные столбцы.

См. также setTable(), setFilter() и selectStatement().

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

Обновляет строку row в модели значениями из строки таблицы базы данных, соответствующей значениям первичного ключа. Без первичного ключа все значения столбцов должны совпадать. Если соответствующая строка не найдена, модель отобразит пустую строку.

Возвращает true при успехе; в противном случае возвращает false.

Эта функция была добавлена в Qt 5.0.

См. также select().

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

Возвращает SQL SELECT-запрос, используемый внутри для заполнения модели. Запрос включает фильтр и ORDER BY-оператор.

См. также filter() и orderByClause().

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

Переопределено из QAbstractItemModel::setData().

Устанавливает данные для элемента index для роли role на value.

Для стратегии редактирования OnFieldChange индекс может получить изменение только если ни один другой индекс не имеет сохранённого изменения. Изменения отправляются немедленно. Однако строки, которые ещё не были вставлены в базу данных, могут быть изменены свободно и не отправляются автоматически. Отправленные изменения не отменяются при ошибке.

Для OnRowChange индекс может получить изменение только если ни одна другая строка не имеет сохранённого изменения. Изменения не отправляются автоматически.

Возвращает true если value равно текущему значению. Однако значение не будет отправлено в базу данных.

Возвращает true если значение может быть установлено или false при ошибке, например, если index выходит за пределы.

Возвращает false если роль не Qt::EditRole. Чтобы установить данные для ролей, отличных от EditRole, используйте пользовательский прокси-модель или подкласс QSqlTableModel.

См. также editStrategy(), data(), submit(), submitAll() и revertRow().

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

Устанавливает стратегию редактирования значений в базе данных на strategy.

Это приведет к отмене любых ожидающих изменений.

См. также editStrategy() и revertAll().

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

Устанавливает текущий фильтр на filter.

Фильтр — это SQL WHERE-оператор без ключевого слова WHERE (например, name='Josephine')).

Если модель уже заполнена данными из базы данных, модель повторно выбирает её с новым фильтром. В противном случае фильтр будет применён при следующем вызове select().

См. также filter(), select(), selectStatement() и orderByClause().

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

Защищённый метод, позволяющий подклассам установить первичный ключ на key.

Обычно первичный индекс устанавливается автоматически при вызове setTable().

См. также primaryKey() и QSqlDatabase::primaryIndex().

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

Эта функция просто вызывает QSqlQueryModel::setQuery(query). Обычно её не следует вызывать для QSqlTableModel. Вместо этого используйте setTable(), setSort(), setFilter() и т.д. для настройки запроса.

См. также selectStatement().

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

Применяет values к строке row в модели. Источник и целевые поля сопоставляются по имени поля, а не по позиции в записи.

Обратите внимание, что сгенерированные флаги в values сохраняются для определения, используются ли соответствующие поля при отправке изменений в базу данных. По умолчанию он установлен на true для всех полей в QSqlRecord. Вы должны установить флаг на false с помощью setGenerated(false) для любого значения в values, чтобы сохранить изменения обратно в базу данных.

Для стратегий редактирования OnFieldChange и OnRowChange строка может получить изменение только если ни одна другая строка не имеет сохранённого изменения. Изменения отправляются немедленно. Отправленные изменения не отменяются при ошибке.

Возвращает true если все значения могут быть установлены; в противном случае возвращает false.

См. также record() и editStrategy().

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

Устанавливает порядок сортировки для column на order. Это не влияет на текущие данные. Чтобы обновить данные с новым порядком сортировки, вызовите select().

См. также sort(), select() и orderByClause().

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

Устанавливает таблицу базы данных, с которой работает модель, на tableName. Не выбирает данные из таблицы, а извлекает её информацию о полях.

Чтобы заполнить модель данными таблицы, вызовите select().

Информация об ошибке может быть получена с помощью lastError().

См. также select(), setFilter() и lastError().

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

Переопределено из QAbstractItemModel::sort().

Сортирует данные по столбцу с порядком сортировки order. Это сразу же выберет данные, используйте setSort(), чтобы установить порядок сортировки без заполнения модели данными.

См. также setSort(), select() и orderByClause().

[override virtual slot] bool QSqlTableModel::submit()

Переопределено из QAbstractItemModel::submit().

Этот переопределенный слот вызывается делегатами элементов, когда пользователь закончил редактирование текущей строки.

Отправляет текущую редактируемую строку, если стратегия модели установлена в OnRowChange или OnFieldChange. Ничего не делает для стратегии OnManualSubmit.

Используйте submitAll(), чтобы отправить все ожидающие изменения для стратегии OnManualSubmit.

Возвращает true при успехе; в противном случае возвращает false. Используйте lastError(), чтобы получить подробную информацию об ошибке.

Не перестраивает модель автоматически. Отправленные строки обновляются из базы данных при успехе.

См. также revert(), revertRow(), submitAll(), revertAll() и lastError().

[slot] bool QSqlTableModel::submitAll()

Отправляет все ожидающие изменения и возвращает true при успехе. Возвращает false при ошибке, подробную информацию об ошибке можно получить с помощью lastError().

В режиме OnManualSubmit, при успехе модель будет перезаполнена. Любые представления, отображающие её, потеряют свой выбор.

Примечание: В режиме OnManualSubmit уже отправленные изменения не будут удалены из кэша, если submitAll() завершится ошибкой. Это позволяет отменять транзакции и повторно отправлять их без потери данных.

См. также revertAll() и lastError().

QString QSqlTableModel::tableName() const

Возвращает имя текущей выбранной таблицы.

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

Обновляет заданную строку в текущей активной таблице базы данных заданными значениями. Возвращает true при успехе; в противном случае возвращает false.

Это метод низкого уровня, который работает непосредственно с базой данных и не должен вызываться напрямую. Используйте setData(), чтобы обновить значения. Модель решит, когда изменять базу данных в зависимости от своей стратегии редактирования.

Обратите внимание, что обновляются только значения, для которых установлен флаг generated. Флаг generated можно установить с помощью QSqlRecord::setGenerated() и проверить с помощью QSqlRecord::isGenerated().

См. также QSqlRecord::isGenerated() и setData().