Тип QML TableView

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

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

Свойства

• bottomRow : int
• columnSpacing : real
• columnWidthProvider : var
• columns : int
• contentHeight : real
• contentWidth : real
• delegate : Component
• leftColumn : int
• model : модель
• reuseItems : bool
• rightColumn : int
• rowHeightProvider : var
• rowSpacing : real
• rows : int
• selectionModel : ItemSelectionModel
• syncDirection : Qt::Orientations
• syncView : TableView
• topRow : int

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

• view : TableView

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

• pooled()
• reused()

Методы

• Точка cellAtPos(real x, real y, bool includeSpacing)
• Точка cellAtPos(point position, bool includeSpacing)
• real columnWidth(int column)
• forceLayout()
• real implicitColumnWidth(int column)
• real implicitRowHeight(int row)
• bool isColumnLoaded(int column)
• bool isRowLoaded(int row)
• Элемент itemAtCell(int column, int row)
• Элемент itemAtCell(point cell)
• positionViewAtCell(int column, int row, Qt.Alignment alignment, point offset)
• positionViewAtCell(point cell, Qt.Alignment alignment, point offset)
• positionViewAtColumn(int column, Qt.Alignment alignment, real offset)
• positionViewAtRow(int row, Qt.Alignment alignment, real offset)
• real rowHeight(int row)

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

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

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

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

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

Модели C++

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

#include <qqml.h>
#include <QAbstractTableModel>

class TableModel : public QAbstractTableModel
{
    Q_OBJECT
    QML_ELEMENT
    QML_ADDED_IN_MINOR_VERSION(1)

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"} };
    }
};

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

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

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

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

Если вы измените значения, возвращаемые 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"
    }
}

Выбор элементов

Вы можете добавить поддержку выбора в TableView, назначив ItemSelectionModel свойству selectionModel. Затем он будет использовать эту модель для управления отображением выбранных элементов делегата. Для отображения выбранного элемента делегата, он должен содержать следующее свойство:

required property bool selected

Следующий фрагмент показывает, как приложение может отображать делегат по-разному в зависимости от свойства selected.

    TableView {
        id: tableView
        anchors.fill: parent
        clip: true

        model: TableModel {
            TableModelColumn { display: "name" }
            rows: [ { "name": "Harry" }, { "name": "Hedwig" } ]
        }

        selectionModel: ItemSelectionModel {
            model: tableView.model
        }

        delegate: Rectangle {
            implicitWidth: 100
            implicitHeight: 30
            color: selected ? "blue" : "lightgray"

            required property bool selected

            Text { text: display }
        }
    }

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

bottomRow : int

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

См. также leftColumn, rightColumn и topRow.

columnSpacing : real

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

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

columnWidthProvider : var

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

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

См. также rowHeightProvider, isColumnLoaded() и Высоты строк и ширины столбцов.

[только для чтения] columns : int

Это свойство содержит количество столбцов в таблице.

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

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

leftColumn : int

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

См. также rightColumn, topRow и bottomRow.

model : model

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

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

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

reuseItems : bool

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

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

rightColumn : int

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

См. также leftColumn, topRow и bottomRow.

rowHeightProvider : var

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

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

См. также rowHeightProvider, isRowLoaded() и Высоты строк и ширины столбцов.

rowSpacing : real

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

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

[только чтение] rows : int

Это свойство содержит количество строк в таблице.

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

[с 6.2] selectionModel : ItemSelectionModel

Это свойство можно установить для управления тем, какие элементы делегата должны отображаться как выбранные. Если у делегата определен required property bool selected , TableView будет поддерживать его синхронизацию с состоянием выбора соответствующего элемента модели в модели выбора.

Это свойство было добавлено в Qt 6.2.

См. также Выбор элементов и SelectionRectangle.

syncDirection : Qt::Orientations

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

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

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

См. также syncView.

syncView : TableView

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

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

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

См. также syncDirection.

topRow : int

Это свойство содержит самую верхнюю строку, которая в данный момент видна внутри представления.

См. также leftColumn, rightColumn и bottomRow.

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

TableView.view : TableView

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

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

pooled()

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

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

Примечание: Соответствующий обработчик равен onPooled.

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

reused()

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

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

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

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

Примечание: Соответствующий обработчик равен onReused.

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

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

Point cellAtPos(real x, real y, bool includeSpacing)

Удобный способ вызова cellAtPos(Qt.point(x, y), includeSpacing).

Point cellAtPos(point position, bool includeSpacing)

Возвращает ячейку в заданной position в представлении. Если ни одна ячейка не пересекается с position, возвращаемое значение будет point(-1, -1).

Если includeSpacing установлено в true, область ячейки будет считаться включающей половину смежных rowSpacing и columnSpacing с каждой стороны. Значение по умолчанию false.

См. также columnSpacing и rowSpacing.

[since 6.2] real columnWidth(int column)

Возвращает ширину данного column. Если столбец не загружен (и, следовательно, не виден), возвращаемое значение будет -1.

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

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

forceLayout()

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

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

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

[since 6.2] real implicitColumnWidth(int column)

Возвращает неявную ширину данного column. Если столбец не загружен (и, следовательно, не виден), возвращаемое значение будет -1.

Неявная ширина столбца — это наибольшая неявная ширина, найденная среди текущих загруженных элементов делегата внутри этого столбца. Ширины, возвращаемые columnWidthProvider, не будут учтены.

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

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

[since 6.2] real implicitRowHeight(int row)

Возвращает неявную высоту данной row. Если строка не загружена (и, следовательно, не видна), возвращаемое значение будет -1.

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

Этот метод был представлен в Qt 6.2.

См. также rowHeightProvider, rowHeight(), isRowLoaded() и Высоты строк и ширины столбцов.

[since 6.2] bool isColumnLoaded(int column)

Возвращает true, если заданный столбец column загружен.

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

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

Этот метод был представлен в Qt 6.2.

[since 6.2] bool isRowLoaded(int row)

Возвращает true, если заданная строка row загружена.

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

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

Этот метод был представлен в Qt 6.2.

Item itemAtCell(int column, int row)

Удобный способ вызова itemAtCell(Qt.point(column, row)).

Item itemAtCell(point cell)

Возвращает элемент делегата в ячейке cell, если он загружен, в противном случае null.

positionViewAtCell(int column, int row, Qt.Alignment alignment, point offset)

Удобный способ вызова

positionViewAtCell(Qt.point(column, row), alignment, offset)

positionViewAtCell(point cell, Qt.Alignment alignment, point offset)

Размещает contentX и contentY таким образом, что cell находится в позиции, указанной alignment. alignment может быть логическим ИЛИ следующих значений:

Если вертикальное выравнивание не указано, вертикальное позиционирование будет проигнорировано. То же самое относится к горизонтальному выравниванию.

Вы можете дополнительно указать offset, чтобы сместить contentX и contentY на дополнительное количество пикселей за целевым выравниванием. Например, если вы хотите позиционировать представление так, чтобы ячейка [10, 10] оказалась в левом верхнем углу с отступом 5 пикселей, вы можете сделать следующее:

positionViewAtCell(Qt.point(10, 10), Qt.AlignLeft | Qt.AlignTop, Qt.point(-5, -5))

Методы следует вызывать только после завершения компонента. Чтобы позиционировать представление при запуске, этот метод должен вызываться методом Component.onCompleted. Например, для позиционирования представления в конце:

Component.onCompleted: positionViewAtCell(Qt.point(columns - 1, rows - 1), Qt.AlignRight | Qt.AlignBottom)

positionViewAtColumn(int column, Qt.Alignment alignment, real offset)

Удобный метод для вызова

positionViewAtCell(Qt.point(column, 0),alignment& Qt.AlignHorizontal_Mask, Qt.point(offset, 0))

positionViewAtRow(int row, Qt.Alignment alignment, real offset)

Удобный метод для вызова

positionViewAtCell(Qt.point(0,row),alignment& Qt.AlignVertical_Mask, Qt.point(0,offset))

[since 6.2] real rowHeight(int row)

Возвращает высоту заданной строки row. Если строка не загружена (и, следовательно, не видна), возвращаемое значение будет -1.

Этот метод был представлен в Qt 6.2.

См. также rowHeightProvider, implicitRowHeight(), isRowLoaded() и Высоты строк и ширины столбцов.