Тип 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 есть модель, определяющая данные для отображения, и делегат, определяющий, как следует отображать данные.

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 по умолчанию повторно использует элементы делегата вместо создания новых элементов из делегата всякий раз, когда новые строки и столбцы попадают в область просмотра. Это может значительно улучшить производительность, в зависимости от сложности делегата.

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

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

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

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

Если вы не хотите повторно использовать элементы или если делегат не поддерживает это, вы можете установить свойство 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, что ему нужно снова использовать функции поставщика для перерасчёта и обновления макета.

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

В следующем примере показано, как задать простую 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 требует ширину.

Примечание: Ширина столбца всегда должна быть больше 0.

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

columns : int

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

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

contentHeight : real

Это свойство содержит высоту view, которая также является высотой таблицы (включая отступы). Поскольку 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

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

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

rowHeightProvider : var

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

Примечание: Высота строки всегда должна быть больше 0.

См. также 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, возвращают значения, отличные от уже назначенных.