Тип QML TableView

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

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

Свойства

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

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

• view : TableView

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

• pooled()
• reused()

Методы

• Точка cellAtPos(real x, real y, bool includeSpacing)
• Точка cellAtPos(point position, bool includeSpacing)
• forceLayout()
• Элемент 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)

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

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

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

Начиная с 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"
    }
}

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

bottomRow : int

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

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

columnSpacing : real

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

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

columnWidthProvider : var

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

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

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

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

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

Примечание: columns обычно равно количеству столбцов в модели, но может временно отличаться до обработки всех ожидающих изменений модели.

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

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

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

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 рассчитывает высоту на основе элементов делегата.

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

rowSpacing : real

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

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

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

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

Примечание: rows обычно равно количеству строк в модели, но может временно отличаться до обработки всех ожидающих изменений модели.

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

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.

forceLayout()

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

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

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

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))

Примечание: Не рекомендуется использовать contentX или contentY для позиционирования представления в конкретной ячейке. Это ненадежно, так как удаление элементов с начала таблицы не вызывает перепозиционирования всех остальных элементов. TableView также иногда может помещать строки и столбцы в приблизительные позиции для оптимизации скорости. Единственным исключением является случай, когда ячейка уже видна в представлении, что можно проверить предварительно, вызвав itemAtCell().

Методы должны вызываться только после завершения компонента. Чтобы позиционировать представление при запуске, этот метод следует вызывать в 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))