TableView QML Type

提供一种以表格形式展示项目的视图，用于显示模型中的数据。更多...

• 所有成员的列表，包括继承的成员
• 已弃用的成员

属性

• alternatingRows : bool
• animate : bool (since 6.4)
• bottomRow : int
• columnSpacing : real
• columnWidthProvider : var
• columns : int
• contentHeight : real
• contentWidth : real
• currentColumn : int
• currentRow : int
• delegate : Component
• delegateModelAccess : enumeration (since 6.10)
• editTriggers : enumeration (since 6.5)
• keyNavigationEnabled : bool (since 6.4)
• leftColumn : int
• model : model
• pointerNavigationEnabled : bool (since 6.4)
• resizableColumns : bool (since 6.5)
• resizableRows : bool (since 6.5)
• reuseItems : bool
• rightColumn : int
• rowHeightProvider : var
• rowSpacing : real
• rows : int
• selectionBehavior : enumeration (since 6.4)
• selectionMode : enumeration (since 6.6)
• selectionModel : ItemSelectionModel (since 6.2)
• syncDirection : Qt::Orientations
• syncView : TableView
• topRow : int

关联属性

• editDelegate : Component
• view : TableView

信号

• columnMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex) (since 6.8)
• layoutChanged() (since 6.5)
• rowMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex) (since 6.8)

附加信号

• commit()
• pooled()
• reused()

方法

• point cellAtIndex(QModelIndex modelIndex) (since 6.4)
• Point cellAtPosition(point position, bool includeSpacing)
• Point cellAtPosition(real x, real y, bool includeSpacing)
• void clearColumnReordering() (since 6.8)
• void clearColumnWidths()
• void clearRowHeights()
• void clearRowReordering() (since 6.8)
• void closeEditor() (since 6.5)
• int columnAtIndex(QModelIndex modelIndex) (since 6.4)
• real columnWidth(int column) (since 6.2)
• void edit(QModelIndex modelIndex) (since 6.5)
• real explicitColumnWidth(int column)
• real explicitRowHeight(int row)
• void forceLayout()
• real implicitColumnWidth(int column) (since 6.2)
• real implicitRowHeight(int row) (since 6.2)
• QModelIndex index(int row, int column) (since 6.4.3)
• bool isColumnLoaded(int column) (since 6.2)
• bool isRowLoaded(int row) (since 6.2)
• Item itemAtCell(point cell)
• Item itemAtIndex(QModelIndex index) (since 6.5)
• QModelIndex modelIndex(point cell) (since 6.4)
• void moveColumn(int source, int destination) (since 6.8)
• void moveRow(int source, int destination) (since 6.8)
• void positionViewAtCell(point cell, PositionMode mode, point offset, rect subRect)
• void positionViewAtColumn(int column, PositionMode mode, real offset, rect subRect)
• void positionViewAtIndex(QModelIndex index, PositionMode mode, point offset, rect subRect) (since 6.5)
• void positionViewAtRow(int row, PositionMode mode, real offset, rect subRect)
• int rowAtIndex(QModelIndex modelIndex) (since 6.4)
• real rowHeight(int row) (since 6.2)
• void setColumnWidth(int column, real size)
• void setRowHeight(int row, real size)

详细说明

TableView 包含一个定义要显示数据的 `model `，以及一个定义数据显示方式的 `delegate `。

TableView 继承自Flickable 。这意味着，虽然模型可以包含任意数量的行和列，但通常只有表格的一部分会在视口内显示。 一旦您进行滑动操作，新的行和列就会进入视口，而旧的行和列则会退出并从视口中移除。移出的行和列会被重复利用，用于构建进入视口的行和列。因此，TableView 能够支持任意大小的模型，且不会影响性能。

TableView 显示来自基于内置 QML 类型（如ListModel 和XmlListModel ）创建的模型数据，这些类型在 TableView 中仅填充第一列。要创建多列模型，请使用TableModel 或继承自QAbstractItemModel 的 C++ 模型。

TableView 默认不包含标题行。您可以使用Qt Quick Controls 中的HorizontalHeaderView 和VerticalHeaderView 来添加标题行。

用法示例

C++ 模型

以下示例演示了如何使用 C++ 创建包含多列的模型：

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

class TableModel : public QAbstractTableModel
{
    Q_OBJECT
    QML_ELEMENT

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

随后，TableViewDelegate 会自动使用该模型来设置/获取数据。TableViewDelegate 使用Qt::DisplayRole 显示文本，并使用Qt::EditRole 编辑模型中的数据。

以下代码片段演示了如何在自定义委托中从 QML 使用该模型：

import QtQuick
import TableModel

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

    model: TableModel {}

    delegate: Rectangle {
        implicitWidth: 100
        implicitHeight: 50
        Text {
            text: display
        }
    }
}

QML 模型

对于原型设计和显示非常简单的数据（例如来自 Web API 的数据），可以使用TableModel ：

import QtQuick
import Qt.labs.qmlmodels

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

由于TableViewDelegate 使用Qt::EditRole 来设置数据，因此当委托为TableViewDelegate 时，必须在TableModelColumn 中指定编辑角色：

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

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

项的复用

TableView 默认会回收委托项，而不是在通过轻扫将新行和新列推入视图时，每次都从delegate 实例化。这种方法能显著提升性能，具体效果取决于委托的复杂程度。

当项目被滑出视图时，它会被移至重用池——这是一个用于存储未使用项目的内部缓存。此时，会发出TableView::pooled 信号以通知该项目。同样地，当项目从重用池中被重新加载时，会发出TableView::reused 信号。

当项被重用时，源自模型的任何项属性都会被更新。这包括index 、row 和column ，同时也包括任何模型角色。

如果某个项包含定时器或动画，请考虑在收到TableView::pooled 信号时将其暂停。这样可以避免为不可见的项消耗CPU资源。同样，如果某个项包含无法复用的资源，也可以将其释放。

如果您不想重用项，或者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 来确定其宽度。如果该函数已设置，则仅由它决定列的宽度；否则，它会检查是否已通过setColumnWidth()显式设置了宽度。若未设置，则将使用implicitColumnWidth()。 列的隐式宽度等于该列中当前已加载的委托项中找到的最大implicit width 值。尝试直接在委托上设置显式width 将无效，该设置会被忽略并被覆盖。相同的逻辑也适用于行高。

一个与默认逻辑等效的columnWidthProvider 实现如下：

columnWidthProvider: function(column) {
    let w = explicitColumnWidth(column)
    if (w >= 0)
        return w;
    return implicitColumnWidth(column)
}

一旦列宽确定，同一列中的所有其他项目都会调整为该宽度，包括后续被滑入视图中的任何项目。

如果您更改了rowHeightProvider 或columnWidthProvider 为视口内的行和列返回的值，则必须调用forceLayout 。这会通知TableView需要再次调用提供程序函数来重新计算并更新布局。

自 Qt 5.13 起，若要隐藏特定列，可从该列的columnWidthProvider 方法中返回0 。同样地，若要隐藏某行，可从rowHeightProvider 方法中返回 0。若返回负数或undefined ，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();
        }
    }
}

编辑单元格

您可以通过提供编辑委托（edit delegate）来允许用户编辑表格单元格。编辑委托将根据编辑触发条件（editTriggers ）进行实例化，默认情况下，当用户双击单元格或按下如Qt::Key_Enter 或Qt::Key_Return 等按钮时，该条件即被触发。编辑委托通过TableView::editDelegate 进行设置，这是一个您需要在delegate 上设置的附加属性。以下代码片段演示了具体操作方法：

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

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

        selectionModel: ItemSelectionModel {}

        delegate: Rectangle {
            implicitWidth: 100
            implicitHeight: 50

            Text {
                anchors.centerIn: parent
                text: display
            }

            TableView.editDelegate: TextField {
                anchors.fill: parent
                text: display
                horizontalAlignment: TextInput.AlignHCenter
                verticalAlignment: TextInput.AlignVCenter
                Component.onCompleted: selectAll()

                TableView.onCommit: {
                    display = text
                    // 'display = text' is short-hand for:
                    // let index = TableView.view.index(row, column)
                    // TableView.view.model.setData(index, "display", text)
                }
            }
        }
    }

如果在编辑委托处于活动状态时，用户点击了Qt::Key_Enter 或Qt::Key_Return ，TableView 会向编辑委托发出TableView::commit 信号，以便其将更改后的数据写回模型。

Qt::ItemFlags QAbstractItemModelSubClass::flags(const QModelIndex &index) const override
{
    Q_UNUSED(index)
    return Qt::ItemIsSelectable | Qt::ItemIsEnabled | Qt::ItemIsEditable;
}

如果TableView delegate 定义了required property bool editing 属性，则该属性将针对正在编辑的委托被设置为true 。有关如何使用该属性的示例，请参阅editDelegate 的文档。

覆盖层和底层

所有从委托实例化的新项都会作为contentItem 的子项，其z 值为1 。您可以在 Tableview 中添加自定义项，作为 Flickable 的子项。通过控制这些项的z 值，您可以使其位于表格项之上或之下。

以下示例演示了如何在表格上方添加文本，该文本会在您滑动时随表格一同移动：

TableView {
    id: tableView

    topMargin: header.implicitHeight

    Text {
        id: header
        text: "A table header"
    }
}

以下是另一个示例，演示如何创建一个始终位于特定单元格上方的叠加项。这需要稍多一些代码，因为如果用户（例如）调整其前方列的宽度，该单元格的位置可能会发生change 。

Rectangle {
    id: overlay
    width: 20
    height: 20
    radius: 10
    color: "blue"

    z: 10
    parent: tableView.contentItem

    Connections {
        target: tableView
        function onLayoutChanged() {
            let item = tableView.itemAtCell(5, 5)
            let insideViewport = item !== null

            overlay.visible = insideViewport
            if (insideViewport) {
                overlay.x = item.x
                overlay.y = item.y
            }
        }
    }
}

你也可以将覆盖项直接作为该单元格的子项，而不是作为contentItem 的子项。但这样做会比较脆弱，因为每当单元格被滑出视口时，它都会被卸载或被重复利用。

选择项目

您可以通过将ItemSelectionModel 赋值给selectionModel 属性，为TableView添加选中支持。随后，它将使用该模型来控制哪些委托项应显示为选中状态，以及哪个项应显示为当前项。您可以设置selectionBehavior 来控制是否允许用户选中单个单元格、行或列。

要判断一个委托是否已被选中或当前处于活动状态，请声明以下属性（除非该委托是TableViewDelegate ，在这种情况下，这些属性已自动添加）：

delegate: Item {
    required property bool selected
    required property bool current
    // ...
}

以下代码片段展示了应用程序如何根据selected 属性以不同方式呈现委托：

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

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

        selectionModel: ItemSelectionModel {}

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

            required property bool selected

            Text { text: display }
        }
    }

如果需要根据委托是否与当前项目位于同一行或同一列来以不同方式呈现该委托，则currentRow 和currentColumn 属性也会很有用。

键盘导航

为了支持键盘导航，您需要将ItemSelectionModel 赋值给selectionModel 属性。TableView随后将使用该模型来操作模型的currentIndex 。

作为current ，其渲染工作由委托负责。您可以通过为其添加required property bool current 属性来实现，并让外观随其状态变化而变化。current 属性的值由TableView设置。您还可以通过将keyNavigationEnabled 设置为false 来完全禁用键盘导航（例如，当您希望实现自定义键盘处理程序时）。

以下示例演示了如何在自定义委托中结合使用键盘导航以及current 和selected 属性：

ApplicationWindow {
    width: 800
    height: 600
    visible: true
    ScrollView {
        anchors.fill: parent
        TableView {
            id: tableView
            clip: true
            interactive: true
            rowSpacing: 1
            columnSpacing: 1
            model: TableModel {
                TableModelColumn { display: "checked" }
                TableModelColumn { display: "amount" }
                TableModelColumn { display: "fruitType" }
                TableModelColumn { display: "fruitName" }
                TableModelColumn { display: "fruitPrice" }

                rows: [
                    {
                        checked: false,
                        amount: 1,
                        fruitType: "Apple",
                        fruitName: "Granny Smith",
                        fruitPrice: 1.50
                    },
                    {
                        checked: true,
                        amount: 4,
                        fruitType: "Orange",
                        fruitName: "Navel",
                        fruitPrice: 2.50
                    },
                    {
                        checked: false,
                        amount: 1,
                        fruitType: "Banana",
                        fruitName: "Cavendish",
                        fruitPrice: 3.50
                    }
                ]
            }
            selectionModel: ItemSelectionModel {}
            delegate: Rectangle {
                implicitWidth: 100
                implicitHeight: 50
                required property bool selected
                required property bool current
                border.width: current ? 2 : 0
                color: selected ? "lightblue" : palette.base
                Text{
                    text: model.display
                    padding: 12
                }
            }
        }
    }
    SelectionRectangle {
        target: tableView
    }
}

复制和粘贴

为 TableView 实现复制和粘贴操作通常还包括使用QUndoStack （或其他撤销/重做框架）。QUndoStack 可用于存储对模型执行的各种操作（如添加或删除行，或从剪贴板粘贴数据），以便日后撤销这些操作。 不过，描述可能操作及其撤销方式的配套QUndoStack ，应根据模型和应用程序的需求进行设计。因此，TableView并未提供用于处理复制和粘贴的内置API。

以下代码片段可作为参考，用于向您的模型和 TableView 添加复制和粘贴支持。它使用了QAbstractItemModel 中现有的 MIME 数据 API，并结合了QClipboard 。该代码片段按原样即可运行，但也可以扩展为使用QUndoStack 。

// Inside your C++ QAbstractTableModel subclass:

Q_INVOKABLE void copyToClipboard(const QModelIndexList &indexes) const
{
    QGuiApplication::clipboard()->setMimeData(mimeData(indexes));
}

Q_INVOKABLE bool pasteFromClipboard(const QModelIndex &targetIndex)
{
    const QMimeData *mimeData = QGuiApplication::clipboard()->mimeData();
    // Consider using a QUndoCommand for the following call. It should store
    // the (mime) data for the model items that are about to be overwritten, so
    // that a later call to undo can revert it.
    return dropMimeData(mimeData, Qt::CopyAction, -1, -1, targetIndex);
}

例如，可以在 QML 中像这样使用这两个函数：

TableView {
    id: tableView
    model: tableModel
    selectionModel: ItemSelectionModel {}

    Shortcut {
       sequence: StandardKey.Copy
       onActivated: {
           let indexes = tableView.selectionModel.selectedIndexes
           tableView.model.copyToClipboard(indexes)
       }
    }

    Shortcut {
       sequence: StandardKey.Paste
       onActivated: {
           let targetIndex = tableView.selectionModel.currentIndex
           tableView.model.pasteFromClipboard(targetIndex)
       }
    }
}

另请参阅 TableView::editDelegate 、TableView::commit 、editTriggers 、edit()、closeEditor()、layoutChanged()、QAbstractItemModel::mimeData()、QAbstractItemModel::dropMimeData()、QUndoStack 、QUndoCommand 以及QClipboard 。

属性文档

alternatingRows : bool

此属性控制行背景色是否应交替显示。默认值取决于样式。

background: Rectangle {
    color: control.row === control.tableView.currentRow
           ? control.palette.highlight
           : (control.tableView.alternatingRows && control.row % 2 !== 0
           ? control.palette.alternateBase
           : control.palette.base)
}

animate : bool [since 6.4]

该属性可用于控制TableView 是否应为contentItem （contentX 和contentY ）添加动画效果。该属性由positionViewAtCell()方法使用，并在使用键盘导航the current index 时生效。默认值为true 。

若设置为false ，任何正在进行的动画将立即停止。

该属性在 Qt 6.4 中引入。

另请参阅 positionViewAtCell()。

bottomRow : int

该属性保存当前在视图中可见的最底层行。

另请参阅 leftColumn 、rightColumn 以及topRow 。

columnSpacing : real

该属性用于控制列之间的间距。

默认值为0 。

columnWidthProvider : var

该属性可存储一个函数，该函数用于返回模型中每列的列宽。每当TableView 需要获取特定列的宽度时，该函数就会被调用。该函数接受一个参数column ，即TableView 需要获取其宽度的列。

自 Qt 5.13 起，若要隐藏特定列，可为该列返回 `0 ` 宽度。若返回负数或 `undefined`，`TableView ` 将根据委托项计算宽度。

另请参阅 rowHeightProvider 、isColumnLoaded() 以及Row heights and column widths 。

columns : int [read-only]

该属性存储表中的列数。

如果模型是一个列表，则列数为1 。

此属性为只读。

contentHeight : real

该属性存储了容纳数据模型中行数所需的表格高度。这通常与view 的height 属性不同，这意味着表格的高度可能大于或小于视口高度。 由于TableView 在未加载模型中的所有行之前无法始终确切知道表格的高度，因此contentHeight 通常是基于初始加载的表格得出的估计值。

如果您知道表格的具体高度，请为 `contentHeight` 赋值，以避免对 `TableView` 进行不必要的计算和更新。

另请参阅 contentWidth 和rowHeightProvider 。

contentWidth : real

该属性存储了容纳模型中列数所需的表格宽度。这通常与view 的width 不同，这意味着表格的宽度可能大于或小于视口宽度。 由于TableView 在未加载模型中所有列的情况下，无法始终确切知道表格的宽度，因此contentWidth 通常是基于初始加载的表格所作的估计值。

如果您知道表格的具体宽度，请为contentWidth 赋值，以避免对TableView 进行不必要的计算和更新。

另请参阅 contentHeight 和columnWidthProvider 。

currentColumn : int [read-only]

此只读属性保存视图中包含当前项的列，即current. 。如果当前没有选定项，则该属性值为-1 。

另请参阅 currentRow 、selectionModel 和Selecting items 。

currentRow : int [read-only]

此只读属性保存视图中包含当前项（current. ）的那一行。如果没有当前项，则该属性值为-1 。

另请参阅 currentColumn 、selectionModel 和Selecting items 。

delegate : Component

该委托提供了一个模板，用于定义由视图实例化的每个单元格项。它可以是任何自定义组件，但建议使用TableViewDelegate ，因为它会根据应用程序的样式进行样式设置，并提供开箱即用的功能。

要使用TableViewDelegate ，只需将其设置为委托即可：

delegate: TableViewDelegate { }

模型索引作为可访问的index 属性对外暴露。row 和column 也是如此。根据数据模型的类型，模型的其他属性也可用。

委托应使用 `implicitWidth ` 和 `implicitHeight` 指定其尺寸。`TableView ` 将根据这些信息布局项目。显式的宽度或高度设置将被忽略并被覆盖。

在委托内部，您可以选择性地添加以下一个或多个属性（除非该委托是TableViewDelegate ，在这种情况下这些属性已自动添加）。TableView 会修改这些属性的值，以告知委托其当前所处的状态。委托可利用此信息根据自身状态以不同的方式进行渲染。

• 必填属性 bool current - 若委托为true ，则该属性current.
• 必填属性 bool selected -true （当委托处于选中状态时）selected.
• 必填属性 bool editing -true 表示委托当前正在edited.
• 必填属性 bool containsDrag -true 表示当前是否有列或行正在被拖动经过此委托。该属性仅支持HorizontalHeaderView 和VerticalHeaderView 。（自 Qt 6.8 起）

以下示例演示了如何在自定义委托中使用这些属性：

delegate: Rectangle {
    required property bool current
    required property bool selected
    border.width: current ? 1 : 0
    color: selected ? palette.highlight : palette.base
}

另请参阅 Row heights and column widths 、Reusing items 、必填属性、TableViewDelegate 以及自定义 TableViewDelegate。

delegateModelAccess : enumeration [since 6.10]

此属性决定了委托如何访问模型。

默认值为 `DelegateModel.Qt5ReadWrite`。

该属性在 Qt 6.10 中引入。

另请参阅 《Qt Quick 中的模型和视图》#更改模型数据。

editTriggers : enumeration [default: TableView.DoubleTapped | TableView.EditKeyPressed., since 6.5]

该属性存储了用户开始编辑单元格的各种方式。它可以是以下值的组合：

为了使TableView.SelectedTapped 、TableView.EditKeyPressed 和TableView.AnyKeyPressed 生效，TableView 必须已分配selection model ，因为它们依赖于current index 的设置。为了能够接收任何键事件，TableView 还必须设置QQuickItem::activeFocus 。

编辑单元格时，用户可以按Qt::Key_Tab 或Qt::Key_Backtab 来commit 数据，并将编辑操作移至下一个单元格。通过将TableView 上的QQuickItem::activeFocusOnTab 设置为false ，可以禁用此行为。

Qt::ItemFlags QAbstractItemModelSubClass::flags(const QModelIndex &index) const override
{
    Q_UNUSED(index)
    return Qt::ItemIsSelectable | Qt::ItemIsEnabled | Qt::ItemIsEditable;
}

该属性在 Qt 6.5 中引入。

另请参阅 TableView::editDelegate 、TableView::commit 以及Editing cells 。

keyNavigationEnabled : bool [since 6.4]

此属性可用于控制用户是否可以通过键盘更改the current index 。默认值为true 。

该属性在 Qt 6.4 中引入。

另请参阅 Keyboard navigation 、selectionModel 、selectionBehavior 、pointerNavigationEnabled 以及interactive 。

leftColumn : int

该属性保存当前在视图中可见的最左侧列。

另请参阅 rightColumn 、topRow 以及bottomRow 。

model : model

该属性保存了为表格提供数据的模型。

该模型提供了一组数据，用于创建视图中的项目。模型可以直接在 QML 中使用 `TableModel`、`ListModel`、`ObjectModel` 创建，也可以由自定义的 C++ 模型类提供。C++ 模型必须是 `QAbstractItemModel ` 的子类，或者是一个简单的列表。

另请参阅 “数据模型”。

pointerNavigationEnabled : bool [since 6.4]

可以设置此属性来控制用户是否可以通过鼠标或触摸操作来更改the current index 。默认值为true 。

该属性于 Qt 6.4 版本中引入。

另请参阅 selectionModel 、keyNavigationEnabled 以及interactive 。

resizableColumns : bool [since 6.5]

该属性用于控制用户是否可以通过在单元格之间拖动来调整列宽。默认值为false 。

该属性在 Qt 6.5 中引入。

resizableRows : bool [since 6.5]

该属性用于控制用户是否可以通过在单元格之间拖动来调整行的高。默认值为false 。

该属性在 Qt 6.5 中引入。

reuseItems : bool

该属性控制是否应重复使用从delegate 实例化的项目。如果设置为false ，则会销毁当前池中的所有项目。

另请参阅 Reusing items 、TableView::pooled 以及TableView::reused 。

rightColumn : int

该属性表示当前在视图中可见的最右侧列。

另请参阅 leftColumn 、topRow 以及bottomRow 。

rowHeightProvider : var

该属性可存储一个函数，该函数用于返回模型中每行的高度。每当TableView 需要获取特定行的高度时，就会调用该函数。该函数接受一个参数row ，即TableView 需要获取其高度的行。

自 Qt 5.13 起，若要隐藏特定行，可为该行返回0 的高度。若返回负数，TableView 将根据委托项计算该行的高度。

另请参阅 columnWidthProvider 、isRowLoaded() 和Row heights and column widths 。

rowSpacing : real

该属性用于控制行与行之间的间距。

默认值为0 。

rows : int [read-only]

该属性存储表中的行数。

该属性为只读。

selectionBehavior : enumeration [since 6.4]

无论用户能否选择单元格、行或列，此属性均成立。

该属性自 Qt 6.4 起引入。

另请参阅 Selecting items 、selectionMode 、selectionModel 以及keyNavigationEnabled 。

selectionMode : enumeration [since 6.6]

如果将selectionBehavior 设置为TableView.SelectCells ，则该属性决定用户每次是只能选择一个单元格，还是可以选择多个单元格。如果将selectionBehavior 设置为TableView.SelectRows ，则该属性决定用户每次是只能选择一行，还是可以选择多行。如果将selectionBehavior 设置为TableView.SelectColumns ，则该属性决定用户每次是只能选择一列，还是可以选择多列。

可用的模式如下：

该属性在 Qt 6.6 中引入。

另请参阅 Selecting items 、selectionBehavior 、selectionModel 以及keyNavigationEnabled 。

selectionModel : ItemSelectionModel [since 6.2]

可以设置此属性来控制哪些委托项应显示为已选中，以及哪个项应显示为当前项。如果委托定义了required property bool selected ，则TableView 会将其与选择模型中相应模型项的选择状态保持同步。如果委托定义了required property bool current ，则TableView 会将其与selectionModel.currentIndex保持同步。

该属性自 Qt 6.2 起引入。

另请参阅 Selecting items 、SelectionRectangle 、keyNavigationEnabled 以及pointerNavigationEnabled 。

syncDirection : Qt::Orientations

如果在TableView 上设置了syncView ，则该属性将控制两个表格的滑动方向同步。默认值为Qt.Horizontal | Qt.Vertical ，这意味着无论您朝哪个方向滑动任一表格，另一个表格都会以相同幅度朝同一方向滑动。

通过此属性与“syncView ”的配合使用，可使两个 TableView 在滑动时实现平滑同步，无论它们在超调/欠调、速度、加减速或回弹动画等方面存在何种差异。

一个典型的用例是让多个标题栏随表格一起滑动。

另请参阅 syncView 。

syncView : TableView

如果将TableView 的此属性设置为另一个TableView ，则两个表格将根据syncDirection 的规定，在滑动、列宽/行高以及间距方面保持同步。

如果 `syncDirection ` 包含 `Qt.Horizontal`，则当前 `tableView` 的列宽、列间距以及水平滑动行为将与 `syncView` 保持同步。

如果 `syncDirection ` 包含 `Qt.Vertical`，则当前 `tableView` 的行高、行间距和垂直滑动行为将与 `syncView` 保持同步。

另请参阅 syncDirection 。

topRow : int

该属性存储当前在视图中可见的最顶层行。

另请参阅 leftColumn 、rightColumn 以及bottomRow 。

附加属性文档

TableView.editDelegate : Component [attached]

此附加属性保存了编辑委托。它在编辑开始时被实例化，并作为子对象附加到其所编辑的委托上。它支持与TableView delegate 相同的必填属性，包括index 、row 和column 。模型的属性（如display 和edit ）也可用（具体取决于模型公开的role names ）。

当满足editTriggers 指定的条件且当前单元格可编辑时，编辑操作即开始。

您还可以通过分别调用edit() 和closeEditor() 来手动打开和关闭编辑委托。

当用户按下Qt::Key_Enter 或Qt::Key_Return 时（如果TableView 的QQuickItem::activeFocusOnTab 被设置为true，则还包括Qt::Key_Tab 或Qt::Key_Backtab ），编辑即告结束。 在这种情况下，将发出TableView::commit 信号，以便编辑委托能够响应并将其修改后的数据写回模型。如果因其他原因结束编辑（例如用户按下了Qt::Key_Escape ），则不会发出该信号。无论如何，最终都会发出destruction()信号。

在编辑委托显示期间，其下方的单元格仍然可见；因此，如果编辑委托是半透明的，或者未能完全覆盖整个单元格，则底下的单元格会透出来。 如果不想出现这种情况，你可以让编辑委托的根项成为一个实心Rectangle ，或者隐藏TableView delegate. 内部的部分项。后者可以通过在其中定义一个属性required property bool editing 来实现，并将该属性绑定到某些子项的visible 属性上。以下代码片段展示了如何在自定义委托中实现这一点：

        delegate: Rectangle {
            implicitWidth: 100
            implicitHeight: 50

            required property bool editing

            Text {
                id: textField
                anchors.fill: parent
                anchors.margins: 5
                text: display
                visible: !editing
            }

            TableView.editDelegate: TextField {
                x: textField.x
                y: textField.y
                width: textField.width
                height: textField.height
                text: display
                TableView.onCommit: display = text
            }
        }

当编辑委托被实例化时，TableView 会调用其上的QQuickItem::forceActiveFocus()方法。若希望将活动焦点设置在编辑委托的某个子项上，请将编辑委托设为FocusScope 。

默认情况下，TableViewDelegate 会提供一个编辑委托，你也可以设置自己的编辑委托：

delegate: TableViewDelegate {
    TableView.editDelegate: TextField {
        width: parent.width
        height: parent.height
        text: display
        TableView.onCommit: display = text
    }
}

另请参阅 editTriggers 、TableView::commit 、edit()、closeEditor()、Editing cells 以及TableViewDelegate 。

TableView.view : TableView [attached]

此附加属性保存了管理委托实例的视图。它附加在每个委托实例上。

Signal 文档

[since 6.8] columnMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex)

当列被移动时，会触发此信号。列的逻辑索引由logicalIndex 指定，旧索引由oldVisualIndex 指定，新索引位置由newVisualIndex 指定。

该信号于 Qt 6.8 中引入。

[since 6.5] layoutChanged()

每当loaded 行和列的布局可能发生变化时，都会触发此信号。这在调用forceLayout()时尤其常见，但在调整行或列的大小，或者行或列进入或离开视口时也会发生。

该信号可用于更新覆盖层的几何形状等操作。

该信号在 Qt 6.5 中引入。

另请参阅 forceLayout() 和Overlays and underlays 。

[since 6.8] rowMoved(int logicalIndex, int oldVisualIndex, int newVisualIndex)

当行被移动时，会触发此信号。行的逻辑索引由logicalIndex 指定，旧索引由oldVisualIndex 指定，新索引位置由newVisualIndex 指定。

该信号在 Qt 6.8 中引入。

附带的信号文档

[attached] commit()

该信号由edit delegate

当edit delegate 处于活动状态时，若用户按下Qt::Key_Enter 或Qt::Key_Return ，该附加信号将被触发。此外，若TableView 的QQuickItem::activeFocusOnTab 属性已设置，且用户按下Qt::Key_Tab 或Qt::Key_Backtab ，该信号也会被触发。

如果编辑因上述原因以外的其他原因结束，则不会发出此信号。这包括：例如用户按下Qt::Key_Escape 、在委托体外部点击、正在编辑的行或列被删除，或者应用程序调用了closeEditor()。

收到该信号后，编辑委托应将任何修改后的数据写回模型。

另请参阅 TableView::editDelegate 、editTriggers 和Editing cells 。

[attached] pooled()

当某个项目被添加到重用池后，会触发此信号。您可以利用它来暂停该项目内部正在运行的计时器或动画，或者释放无法重用的资源。

仅当reuseItems 属性值为true 时，才会发出此信号。

另请参阅 Reusing items 、reuseItems 和reused 。

[attached] reused()

该信号在项目被重用后触发。此时，该项目已被从资源池中取出并放置到内容视图中，且索引、行和列等模型属性已更新。

当项目被重用时，模型未提供的其他属性不会发生变化。您应避免在委托中存储任何状态，但如果确实存储了，请在接收到此信号时手动重置该状态。

该信号在项目被复用时发出，而非项目首次创建时。

只有当 `reuseItems ` 属性为 `true` 时，才会发出此信号。

另请参阅 Reusing items 、reuseItems 和pooled 。

方法文档

[since 6.4] point cellAtIndex(QModelIndex modelIndex)

返回视图中与模型中modelIndex 对应的单元格。这是执行以下操作的便捷函数：

Qt.point(columnAtIndex(modelIndex), rowAtIndex(modelIndex))

单元格本质上就是将行和列合并为单一类型的 `point `。

该方法在 Qt 6.4 中引入。

Point cellAtPosition(point position, bool includeSpacing)

返回表格中位于给定position 处的单元格。position 应相对于contentItem 。如果没有loaded 处的单元格与position 相交，则返回值为point(-1, -1) 。

如果将includeSpacing 设置为true ，则会认为单元格的边界框包含两侧各一半的相邻rowSpacing 和columnSpacing 。默认值为false 。

另请参阅 columnSpacing 和rowSpacing 。

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

方便拨打cellAtPosition(Qt.point(x, y), includeSpacing) 。

[since 6.8] void clearColumnReordering()

重置之前应用的任何列重新排序。

此方法于 Qt 6.8 中引入。

void clearColumnWidths()

清除所有通过 `setColumnWidth()` 设置的列宽。

另请参阅 setColumnWidth()、clearRowHeights() 和Row heights and column widths 。

void clearRowHeights()

清除所有通过 `setRowHeight()` 设置的行高。

另请参阅 setRowHeight()、clearColumnWidths() 和Row heights and column widths 。

[since 6.8] void clearRowReordering()

重置之前应用过的任何行重新排序。

此方法在 Qt 6.8 中引入。

[since 6.5] void closeEditor()

如果用户正在编辑某个单元格，调用此函数将停止编辑操作，并销毁编辑委托实例。

该方法在 Qt 6.5 中引入。

另请参阅 edit(),TableView::editDelegate 以及Editing cells 。

[since 6.4] int columnAtIndex(QModelIndex modelIndex)

返回视图中与模型中modelIndex 相对应的列。

该方法于 Qt 6.4 中引入。

另请参阅 rowAtIndex() 和index()。

[since 6.2] real columnWidth(int column)

返回给定column 的宽度。如果该列未加载（因此不可见），则返回值为-1 。

该方法自 Qt 6.2 起引入。

另请参阅 setColumnWidth()、columnWidthProvider 、implicitColumnWidth()、isColumnLoaded() 以及Row heights and column widths 。

[since 6.5] void edit(QModelIndex modelIndex)

该函数为代表modelIndex 的单元格启动一个编辑会话。如果用户正在编辑另一个单元格，则该会话将结束。

通常，您可以通过使用editTriggers 来指定不同的编辑会话启动方式。如果这还不够，您可以使用此函数。若要完全控制单元格编辑并防止TableView 进行干预，请将editTriggers 设置为TableView.NoEditTriggers 。

此方法在 Qt 6.5 中引入。

另请参阅 closeEditor()、editTriggers 、TableView::editDelegate 以及Editing cells 。

real explicitColumnWidth(int column)

返回通过 `setColumnWidth()` 设置的 `column ` 的宽度。如果使用了 `columnWidthProvider `，则该宽度可能与列的实际宽度不同。要获取列的实际宽度，请使用 `columnWidth()`。

若返回值为0 ，则表示该列已被设置为隐藏。若返回值为-1 ，则表示该列未被显式设置宽度。

另请参阅 setColumnWidth()、columnWidth() 和Row heights and column widths 。

real explicitRowHeight(int row)

返回通过 `setRowHeight()` 设置的 `row ` 的高度。如果正在使用 `rowHeightProvider `，则该高度可能与列的实际高度不同。要获取行的高，请使用 `rowHeight()`。

返回值等于0 表示该行已被设置为隐藏。返回值等于-1 表示该行未被显式设置高度。

另请参阅 setRowHeight()、rowHeight() 和Row heights and column widths 。

void forceLayout()

对模型变化的响应会被批处理，因此每帧仅处理一次。这意味着在脚本运行期间，TableView 会延迟显示任何变化。当修改属性（例如rowSpacing 或leftMargin ）时，情况也是如此。

此方法会强制TableView 立即更新布局，从而使最近的更改立即生效。

调用此函数将重新计算每行每列的可见大小和位置。如果分配给rowHeightProvider 或columnWidthProvider 的函数返回的值与已分配的值不同，则需要执行此操作。

[since 6.2] real implicitColumnWidth(int column)

返回给定column 的隐式宽度。这是该列中当前loaded 委托项中找到的最大implicitWidth 。

如果column 未加载（因此不可见），则返回值为-1 。

该方法在 Qt 6.2 中引入。

另请参阅 columnWidth()、isRowLoaded() 以及Row heights and column widths 。

[since 6.2] real implicitRowHeight(int row)

返回给定row 的隐式高度。该高度即该行内当前loaded 委托项中找到的最大implicitHeight 值。

如果该row 未加载（因此不可见），则返回值为-1 。

该方法在 Qt 6.2 中引入。

另请参见 rowHeight()、isColumnLoaded() 和Row heights and column widths 。

[since 6.4.3] QModelIndex index(int row, int column)

返回QModelIndex ，该对象在视图中分别映射到row 和column 。

row 其中column 应为视图中的行和列（即表格的行和列），而非模型中的行和列。 对于普通的TableView ，这相当于调用model.index(row, column). 。但对于TableView 的子类（如TreeView ），其数据模型被封装在内部代理模型中，该代理模型将树结构扁平化为表格，此时需要使用此函数来解析模型索引。

该方法在 Qt 6.4.3 中引入。

另请参阅 rowAtIndex() 和columnAtIndex()。

[since 6.2] bool isColumnLoaded(int column)

如果给定的column 已加载，则返回true 。

当TableView 已加载在视图中显示该列所需的委托项时，该列即被视为已加载。这通常也意味着该列对用户可见，但并非总是如此。

当您需要遍历某列的委托项（例如来自 `columnWidthProvider`）时，可以使用此函数，以确保这些委托项可供遍历。

该方法在 Qt 6.2 中引入。

[since 6.2] bool isRowLoaded(int row)

如果给定的row 已加载，则返回true 。

当 `TableView ` 已加载在视图中显示该行所需的委托项时，即视为该行已加载。这通常也意味着该行对用户可见，但并非总是如此。

当您需要遍历某一行（例如来自 `rowHeightProvider`）的委托项时，可以使用此函数，以确保这些委托项可供遍历。

该方法于 Qt 6.2 中引入。

Item itemAtCell(point cell)

如果已加载，则返回位于cell 处的委托项；否则返回null 。

[since 6.5] Item itemAtIndex(QModelIndex index)

返回代表index 的单元格的已实例化委托项。如果该项不是loaded ，则返回值为null 。

该方法在 Qt 6.5 中引入。

[since 6.4] QModelIndex modelIndex(point cell)

用于执行以下操作的便捷函数：

index(cell.y, cell.x)

cell 实际上就是一种将行和列合并为单一类型的point 。

该方法在 Qt 6.4 中引入。

另请参阅 index()。

[since 6.8] void moveColumn(int source, int destination)

将一列从source 移动到destination 位置。

此方法于 Qt 6.8 中引入。

[since 6.8] void moveRow(int source, int destination)

将一行从source 移动到destination 位置。

此方法于 Qt 6.8 中引入。

void positionViewAtCell(point cell, PositionMode mode, point offset, rect subRect)

将contentX 和contentY 定位，使得cell 位于由mode 指定的位置。mode 可以是以下选项的“或”运算组合：

如果未指定垂直对齐方式，则将忽略垂直定位。水平对齐也是如此。

可选地，您可以指定 `offset `，将`contentX`和`contentY`向目标对齐位置之外额外移动指定像素数。例如，若要将视图定位为使单元格 [10, 10] 位于左上角并留有 5 像素边距，可这样做：

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

从 Qt 6.4 开始，您可以指定 `subRect `，将视图定位在 `cell` 内的矩形上，而非整个单元格的边界矩形上。当单元格大于视图，且您希望确保其特定部分可见时，此功能非常有用。此时，subRect 必须设置为 `valid ` 才会被考虑。

方法应在组件（Component）完成加载后才调用。若要在启动时定位视图，应由 Component.onCompleted 调用此方法。例如，若要将视图定位在末尾：

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

另请参阅 animate 。

void positionViewAtColumn(int column, PositionMode mode, real offset, rect subRect)

将contentX 定位，使得column 位于由mode 、offset 和subRect 指定的位置。

调用该方法的便捷方式

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

[since 6.5] void positionViewAtIndex(QModelIndex index, PositionMode mode, point offset, rect subRect)

将视图定位，使index 位于由mode 、offset 和subRect 指定的位置。

调用该方法的便捷方式

positionViewAtRow(rowAtIndex(index), mode & Qt.AlignVertical_Mask, offset.y, subRect)
positionViewAtColumn(columnAtIndex(index), mode & Qt.AlignVertical_Mask, offset.x, subRect)

该方法于 Qt 6.5 中引入。

void positionViewAtRow(int row, PositionMode mode, real offset, rect subRect)

将contentY 定位，使得row 位于由mode 、offset 和subRect 指定的位置。

调用该函数的便捷方法

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

[since 6.4] int rowAtIndex(QModelIndex modelIndex)

返回视图中与模型中modelIndex 对应的行。

该方法在 Qt 6.4 中引入。

另请参阅 columnAtIndex() 和index()。

[since 6.2] real rowHeight(int row)

返回给定row 的高度。如果该行尚未加载（因此不可见），则返回值为-1 。

该方法自 Qt 6.2 起引入。

另请参阅 setRowHeight()、rowHeightProvider 、implicitRowHeight()、isRowLoaded() 以及Row heights and column widths 。

void setColumnWidth(int column, real size)

将第column 列的显式列宽设置为size 。

若要读取通过此函数设置的值，应使用explicitColumnWidth()。columnWidth() 将返回该列的实际宽度，若已设置columnWidthProvider ，则实际宽度可能与此不同。

当TableView 需要确定column 的宽度时，它会首先尝试调用columnWidthProvider 。只有在未设置提供程序的情况下，才会默认使用通过此函数设置的宽度。 不过，您可以在提供程序内部调用explicitColumnWidth()，并在必要时调整数值，例如确保其始终处于某个特定区间内。以下代码片段展示了如何实现这一点：

columnWidthProvider: function(column) {
    let w = explicitColumnWidth(column)
    if (w >= 0)
        return Math.max(100, w);
    return implicitColumnWidth(column)
}

如果 `size ` 等于 `0`，则该列将被隐藏。如果 `size ` 等于 `-1`，则该列将重置为使用 `implicitColumnWidth()`。您可以为超出模型尺寸范围的列指定列宽。

另请参阅 columnWidth()、explicitColumnWidth()、setRowHeight()、clearColumnWidths() 以及Row heights and column widths 。

void setRowHeight(int row, real size)

将行row 的显式行高设置为size 。

若要读取通过此函数设置的值，应使用explicitRowHeight()。rowHeight() 将返回该行的实际高度，若已设置rowHeightProvider ，则该值可能有所不同。

当TableView 需要确定row 的高度时，它会首先尝试调用rowHeightProvider 。只有在未设置提供程序的情况下，该函数设置的高度值才会被默认采用。 不过，您可以在提供程序内部调用explicitRowHeight()，并在必要时调整数值，例如确保其始终处于某个特定区间内。以下代码片段展示了具体实现方法：

rowHeightProvider: function(row) {
    let h = explicitRowHeight(row)
    if (h >= 0)
        return Math.max(100, h);
    return implicitRowHeight(row)
}

如果 `size ` 等于 `0`，则该行将被隐藏。如果 `size ` 等于 `-1`，则该行将重置为使用 `implicitRowHeight()`。您可以为超出模型尺寸范围的行指定行尺寸。

另请参阅 rowHeight()、explicitRowHeight()、setColumnWidth() 以及Row heights and column widths 。