Тип QML TableView

Предоставляет вид таблицы для отображения данных из модели. Подробнее...

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

Свойства

• columnSpacing : real
• columnWidthProvider : var
• columns : int
• contentHeight : real
• contentWidth : real
• delegate : Component
• model : model
• reuseItems : bool
• rowHeightProvider : var
• rowSpacing : real
• rows : int
• syncDirection : Qt::Orientations
• syncView : TableView

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

• view : TableView

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

• pooled()
• reused()

Методы

• forceLayout()

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

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

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

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

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

Модели C++

Следующий пример демонстрирует создание модели из 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
        }
    }
}

Модели QML

Для прототипирования и отображения очень простых данных (например, из веб-API) можно использовать TableModel:

import QtQuick 2.14
import Qt.labs.qmlmodels 1.0

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

    model: TableModel {
        TableModelColumn { display: "name" }
        TableModelColumn { display: "color" }

        rows: [
            {
                "name": "cat",
                "color": "black"
            },
            {
                "name": "dog",
                "color": "brown"
            },
            {
                "name": "bird",
                "color": "white"
            }
        ]
    }

    delegate: Rectangle {
        implicitWidth: 100
        implicitHeight: 50
        border.width: 1

        Text {
            text: display
            anchors.centerIn: parent
        }
    }
}

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

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();
        }
    }
}

Перекрытия и подложки

Все новые элементы, созданные из делегата, добавляются в качестве дочерних элементов к 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

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

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

См. также contentWidth и rowHeightProvider.

contentWidth : real

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

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

См. также contentHeight и columnWidthProvider.

delegate : Component

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

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

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

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

model : model

Это свойство хранит модель, которая предоставляет данные для таблицы.

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

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

reuseItems : bool

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

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

rowHeightProvider : var

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

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

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

rowSpacing : real

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

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

[read-only] rows : int

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

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

syncDirection : Qt::Orientations

Если syncView задано для TableView, это свойство управляет синхронизацией направления прокрутки для обеих таблиц. Значение по умолчанию Qt.Horizontal | Qt.Vertical, что означает, что если вы прокручиваете одну таблицу в любом направлении, другая таблица прокручивается на такое же количество в том же направлении.

Это свойство и syncView могут использоваться для плавной синхронизации прокрутки двух таблиц независимо от перескоков/недоскоков, скорости, ускорения/замедления или анимации отскока и т.д.

Типичный пример использования — синхронизация нескольких заголовков с таблицей.

См. также syncView и headerView.

syncView : TableView

Если это свойство TableView установлено на другой TableView, обе таблицы будут синхронизированы по прокрутке, ширине столбцов/высоте строк и интервалам в соответствии с syncDirection.

Если syncDirection содержит Qt.Horizontal, текущие ширины столбцов, интервалы между столбцами и горизонтальное движение прокрутки текущего tableView синхронизируются с syncView.

Если syncDirection содержит Qt.Vertical, текущие высоты строк, интервалы между строками и вертикальное движение прокрутки текущего tableView синхронизируются с syncView.

См. также syncDirection.

Документация по свойствам, прикрепленным к объекту

TableView.view : TableView

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

Документация по сигналам, прикрепленным к объекту

pooled()

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

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

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

reused()

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

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

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

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

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

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

forceLayout()

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

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

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