Тип QML TableView

Обеспечивает представление таблицы элементов, предоставляемых моделью. Подробнее...

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

Свойства

• columnSpacing : real
• columnWidthProvider : var
• columns : int
• contentHeight : real
• contentWidth : real
• delegate : Component
• model : model
• reuseItems : bool
• rowHeightProvider : var
• rowSpacing : real
• rows : int

Присоединенные свойства

• view : TableView

Присоединенные сигналы

• pooled()
• reused()

Методы

• forceLayout()

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

У TableView есть model, определяющий отображаемые данные, и delegate, определяющий, как данные должны отображаться.

TableView наследует Flickable. Это означает, что, хотя модель может содержать любое количество строк и столбцов, обычно внутри области просмотра видна только часть таблицы. Как только вы пролистываете, новые строки и столбцы появляются в области просмотра, а старые исчезают и удаляются из области просмотра. Строки и столбцы, которые перемещаются, повторно используются для построения строк и столбцов, которые входят в область просмотра. Таким образом, TableView поддерживает модели любого размера без ущерба для производительности.

TableView отображает данные из моделей, созданных из встроенных типов QML, таких как ListModel и XmlListModel, которые заполняют только первый столбец в TableView. Чтобы создать модели с несколькими столбцами, создайте модель на C++, которая наследует QAbstractItemModel, и предоставьте её QML.

Пример использования

Следующий пример демонстрирует, как создать модель на C++ с несколькими столбцами:

#include <QGuiApplication>
#include <QQmlApplicationEngine>
#include <QAbstractTableModel>

class TableModel : public QAbstractTableModel
{
    Q_OBJECT

public:

    int rowCount(const QModelIndex & = QModelIndex()) const override
    {
        return 200;
    }

    int columnCount(const QModelIndex & = QModelIndex()) const override
    {
        return 200;
    }

    QVariant data(const QModelIndex &index, int role) const override
    {
        switch (role) {
            case Qt::DisplayRole:
                return QString("%1, %2").arg(index.column()).arg(index.row());
            default:
                break;
        }

        return QVariant();
    }

    QHash<int, QByteArray> roleNames() const override
    {
        return { {Qt::DisplayRole, "display"} };
    }
};

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    qmlRegisterType<TableModel>("TableModel", 0, 1, "TableModel");

    QQmlApplicationEngine engine;
    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));

    return app.exec();
}

#include "main.moc"

А затем, как использовать её в QML:

import QtQuick 2.12
import TableModel 0.1

TableView {
    anchors.fill: parent
    columnSpacing: 1
    rowSpacing: 1
    clip: true

    model: TableModel {}

    delegate: Rectangle {
        implicitWidth: 100
        implicitHeight: 50
        Text {
            text: display
        }
    }
}

Повторное использование элементов

TableView по умолчанию повторно использует элементы делегата вместо создания нового экземпляра из delegate каждый раз, когда в область просмотра входят новые строки и столбцы. Это может значительно повысить производительность в зависимости от сложности делегата.

Когда элемент выезжает из области просмотра, он перемещается в пул повторного использования, который представляет собой внутренний кэш неиспользуемых элементов. В этом случае испускается сигнал TableView::pooled, чтобы сообщить элементу об этом. Аналогично, когда элемент возвращается из пула, испускается сигнал TableView::reused.

Любые свойства элементов, которые поступают из модели, обновляются при повторном использовании элемента. Это включает index, row, и column, а также любые роли модели.

Примечание: Избегайте хранения состояния внутри делегата. Если вы это делаете, сбросьте его вручную при получении сигнала TableView::reused.

Если у элемента есть таймеры или анимации, рассмотрите возможность приостановки их при получении сигнала TableView::pooled. Таким образом, вы избежите использования ресурсов ЦП для элементов, которые не отображаются. Аналогично, если у элемента есть ресурсы, которые нельзя повторно использовать, их можно освободить.

Если вы не хотите повторно использовать элементы или если delegate не поддерживает это, вы можете установить свойство reuseItems в false.

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

Следующий пример демонстрирует делегат, который анимирует вращающийся прямоугольник. При помещении в пул анимация временно приостанавливается:

Component {
    id: tableViewDelegate
    Rectangle {
        implicitWidth: 100
        implicitHeight: 50

        TableView.onPooled: rotationAnimation.pause()
        TableView.onReused: rotationAnimation.resume()

        Rectangle {
            id: rect
            anchors.centerIn: parent
            width: 40
            height: 5
            color: "green"

            RotationAnimation {
                id: rotationAnimation
                target: rect
                duration: (Math.random() * 2000) + 200
                from: 0
                to: 359
                running: true
                loops: Animation.Infinite
            }
        }
    }
}

Размеры строк и столбцов

Когда новый столбец входит в область просмотра, TableView определит его ширину, вызвав функцию columnWidthProvider. TableView сам по себе никогда не хранит высоту строки или ширину столбца, поскольку он разработан для поддержки больших моделей, содержащих любое количество строк и столбцов. Вместо этого он будет запрашивать приложение всякий раз, когда ему нужно знать эти значения.

TableView использует наибольшее implicitWidth среди элементов в качестве ширины столбца, если свойство columnWidthProvider не задано явно. После определения ширины столбца все остальные элементы в том же столбце масштабируются до этой ширины, даже если впоследствии в область просмотра входят новые элементы с большей implicitWidth. Задание явной width для элемента игнорируется и переписывается.

Примечание: Вычисленная ширина столбца отбрасывается при выезде столбца за пределы области просмотра и пересчитывается, если столбец снова появляется в области просмотра. Вычисление всегда основано на элементах, которые видны, когда столбец входит в область просмотра. Это означает, что результат может отличаться каждый раз в зависимости от того, в какой строке находится столбец при входе. Поэтому у всех элементов в столбце должны быть одинаковые implicitWidth, или же необходимо явно задать columnWidthProvider. Та же логика применяется к вычислению высоты строки.

Если вы измените значения, которые возвращает rowHeightProvider или columnWidthProvider для строк и столбцов внутри области просмотра, необходимо вызвать forceLayout. Это информирует TableView о необходимости повторного использования функций поставщика для перерасчёта и обновления макета.

С Qt 5.13, если вы хотите скрыть конкретный столбец, вы можете вернуть 0 из columnWidthProvider для этого столбца. Аналогично, вы можете вернуть 0 из rowHeightProvider, чтобы скрыть строку. Если вы вернёте отрицательное число, TableView вернётся к вычислению размера на основе элементов делегата.

Примечание: Размер строки или столбца должен быть целым числом для избежания подпиксельного выравнивания элементов.

Следующий пример показывает, как задать простую columnWidthProvider вместе с таймером, который изменяет возвращаемые значения функции. Когда массив изменяется, вызывается forceLayout для применения изменений:

TableView {
    id: tableView

    property var columnWidths: [100, 50, 80, 150]
    columnWidthProvider: function (column) { return columnWidths[column] }

    Timer {
        running: true
        interval: 2000
        onTriggered: {
            tableView.columnWidths[2] = 150
            tableView.forceLayout();
        }
    }
}

Наложения и подложки

TableView наследует Flickable. И когда новые элементы создаются из делегата, они будут родителями для contentItem со значением z равным 1. Вы можете добавить свои собственные элементы внутри TableView, как дочерние элементы Flickable. Управляя их значением z, вы можете расположить их поверх или под элементами таблицы.

Вот пример, демонстрирующий, как добавить текст поверх таблицы, который перемещается вместе с таблицей при пролистывании:

TableView {
    id: tableView

    topMargin: header.implicitHeight

    Text {
        id: header
        text: "A table header"
    }
}

Документация по свойствам

columnSpacing : real

Это свойство содержит отступ между столбцами.

Значение по умолчанию - 0.

columnWidthProvider : var

Это свойство может содержать функцию, возвращающую ширину столбца для каждого столбца в модели. При назначении она вызывается всякий раз, когда TableView нуждается в ширине определенного столбца. Функция принимает один аргумент, column, для которого TableView нуждается в ширине.

С Qt 5.13, если вы хотите скрыть конкретный столбец, вы можете вернуть 0 ширину для этого столбца. Если вы вернете отрицательное число, TableView вернётся к вычислению ширины на основе элементов делегата.

См. также rowHeightProvider и Размеры строк и столбцов.

columns : int

Это свойство содержит количество столбцов в таблице. Оно равно количеству столбцов в модели. Если модель представляет собой список, столбцов будет 1.

Это свойство является только для чтения.

contentHeight : real

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

Если вы заранее знаете высоту таблицы, явно задайте значение contentHeight, чтобы избежать ненужных вычислений и обновлений TableView.

См. также contentWidth.

contentWidth : real

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

Если вы заранее знаете ширину таблицы, явно задайте значение contentWidth, чтобы избежать ненужных вычислений и обновлений TableView.

См. также contentHeight.

delegate : Component

Делегат предоставляет шаблон, определяющий каждый элемент ячейки, создаваемый представлением. Индекс модели представлен как доступное index свойство. То же самое относится к row и column. Свойства модели также доступны в зависимости от типа модели данных.

Делегат должен указывать свой размер, используя implicitWidth и implicitHeight. TableView выстраивает элементы на основе этой информации. Явные значения ширины или высоты игнорируются и перезаписываются.

Примечание: Делегаты создаются по мере необходимости и могут быть уничтожены в любое время. Они также повторно используются, если свойство reuseItems установлено в true. Поэтому следует избегать хранения информации о состоянии в делегатах.

См. также Высоты строк и ширины столбцов и Повторное использование элементов.

model : model

Это свойство содержит модель, предоставляющую данные для таблицы.

Модель предоставляет набор данных, используемых для создания элементов в представлении. Модели могут быть созданы непосредственно в QML с помощью ListModel, XmlListModel или ObjectModel, или предоставлены пользовательским классом модели C++. Если это модель C++, она должна быть подклассом QAbstractItemModel или простым списком.

См. также Модели данных.

reuseItems : bool

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

См. также Повторное использование элементов, TableView::pooled и TableView::reused.

rowHeightProvider : var

Это свойство может содержать функцию, возвращающую высоту строки для каждой строки в модели. При назначении она будет вызываться всякий раз, когда TableView нуждается в высоте конкретной строки. Функция принимает один аргумент, row, для которой TableView нуждается в высоте.

Начиная с Qt 5.13, если вы хотите скрыть конкретную строку, вы можете вернуть 0 высоту для этой строки. Если вы возвращаете отрицательное число, TableView вернётся к расчёту высоты на основе элементов делегата.

См. также columnWidthProvider и Высоты строк и ширины столбцов.

rowSpacing : real

Это свойство хранит отступ между строками.

Значение по умолчанию равно 0.

rows : int

Это свойство хранит количество строк в таблице. Это равно количеству строк в модели.

Это свойство является только для чтения.

Документация по свойству "Прикреплённое свойство"

TableView.view : TableView

Это прикреплённое свойство хранит представление, которое управляет экземпляром делегата. Оно прикрепляется к каждому экземпляру делегата.

Документация по прикреплённому сигналу

pooled()

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

Этот сигнал подаётся только если свойство reuseItems равно true.

См. также Повторное использование элементов, reuseItems и reused.

reused()

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

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

Этот сигнал подаётся при повторном использовании элемента, а не при первом его создании.

Этот сигнал подаётся только если свойство reuseItems равно true.

См. также Повторное использование элементов, reuseItems и pooled.

Документация по методу

forceLayout()

Обработка изменений в модели осуществляется группами, так что они обрабатываются только один раз за кадр. Это означает, что TableView откладывает отображение любых изменений, пока выполняется сценарий. То же самое верно при изменении таких свойств, как rowSpacing или leftMargin.

Этот метод заставляет TableView немедленно обновить макет, чтобы любые недавние изменения вступили в силу.

Вызов этой функции переоценивает размер и положение каждой видимой строки и столбца. Это необходимо, если функции, назначенные rowHeightProvider или columnWidthProvider, возвращают значения, отличные от уже назначенных.