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

Если вы не хотите повторно использовать элементы или если 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"
    }
}

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

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