Тип 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 <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"
    }
}

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

columnSpacing : real

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

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

columnWidthProvider : var

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

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

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

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

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

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

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

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

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

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.

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

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

reused()

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

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

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

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

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

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

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

forceLayout()

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

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

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