Back to Qt.io
Contact Us Blog Download Qt

TableView QML Type

提供项目表视图以显示模型中的数据。更多

Import Statement: import QtQuick
Inherits:

Flickable

Inherited By:

TreeView

属性

附属物业

信号

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

附加信号

方法

详细说明

TableView 的model 定义了要显示的数据，delegate 定义了数据的显示方式。

TableView 继承于Flickable 。这意味着虽然模型可以有任意数量的行和列，但在视口中通常只能看到表格的一部分。只要您轻弹一下，新的行和列就会进入视口，而旧的行和列则会退出并从视口移除。移出的行和列将重新用于构建移入视口的行和列。因此，TableView 支持任何大小的模型，而不会影响性能。

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

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

注意： TableView 将只load 填满视图所需的委托项。虽然 TableView 有时会出于优化原因预先加载项目，但并不保证视图之外的项目也会被加载。因此，宽度或高度为零的 TableView 可能根本不会加载任何委托项。

使用示例

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::reused 信号时手动重置。

如果项目有计时器或动画，请考虑在接收到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)
}

一旦解决了列宽问题，同一列中的所有其他项目（包括稍后弹入视图的任何项目）都将调整为该宽度。

注意： 当整列从视图中弹出时，已解决的列宽度会被丢弃，如果再弹回视图，则会重新计算。这意味着，如果宽度取决于implicitColumnWidth() ，那么每次的计算结果都可能不同，这取决于列进入时所处的行数（因为implicitColumnWidth() 只考虑当前loaded 的委托项）。为避免这种情况，应使用columnWidthProvider ，或确保同一列中的所有委托项都有相同的implicitWidth 。

如果更改rowHeightProvider 或columnWidthProvider 返回的视口中行和列的值，则必须调用forceLayout 。这将通知 TableView，它需要再次使用提供者函数来重新计算和更新布局。

自 Qt 5.13 起，如果要隐藏特定列，可以从columnWidthProvider 中为该列返回0 。同样，您也可以从rowHeightProvider 返回 0 来隐藏一行。如果返回负数，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();
        }
    }
}

编辑单元格

通过提供编辑委托，用户可以编辑表格单元格。编辑委托将根据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 信号，以便将更改的数据写回模型。

注意： 为了使单元格可编辑，模型需要覆盖QAbstractItemModel::flags() 并返回Qt::ItemIsEditable 。QAbstractItemModel 默认不启用该标志。例如，覆盖可以如下所示：

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 文档。

覆盖层和底层

所有从委托实例化的新项目都会以z 值（1 ）作为contentItem 的父级。您可以在 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 。但这样做会很脆弱，因为只要将单元格弹出视口，它就会被卸载或重新使用。

选择项目

您可以为selectionModel 属性指定一个ItemSelectionModel ，从而为 TableView 添加选择支持。然后，它将使用此模型来控制哪些委托项应显示为选中，哪些项目应显示为当前。您可以设置selectionBehavior 来控制是否允许用户选择单个单元格、行或列。

要了解委托项是否处于选中或当前状态，请声明以下属性（除非委托项是TableViewDelegate ，在这种情况下，已添加了这些属性）：

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

注意： selected 和current 属性必须定义为required 。这将告知 TableView 应负责更新它们的值。否则，它们将被忽略。另请参阅必填属性。

以下代码段展示了应用程序如何根据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 属性也很有用。

注意 Qt Quick Controls提供了一个SelectionRectangle ，可用于让用户选择单元格。

注： 默认情况下，当用户点击一个单元格时，该单元格将变为current ，并且任何选择都将被移除。如果不希望出现这种默认的点击行为（例如，如果在委托中使用了自定义指针处理程序），可以将pointerNavigationEnabled 设置为false 。

键盘导航

为了支持键盘导航，您需要为selectionModel 属性分配一个ItemSelectionModel 。然后，TableView 将使用该模型来操作模型的currentIndex 。

将自己呈现为current 是委托的责任。为此，您可以为其添加一个属性required property bool current ，并让外观取决于其状态。current 属性的值由 TableView 设置。您还可以通过将keyNavigationEnabled 设置为false 来完全禁用键盘导航（以防您要实现自己的按键处理程序）。

注： 默认情况下，TableViewDelegate 会显示当前单元格和选定单元格，因此无需添加这些属性。

下面的示例演示了如何在自定义委托中将键盘导航与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

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

注意： 该属性只是一个提示，因此自定义委托可能不会遵守。建议委托在此提示为true 时交替使用palette.base 和palette.alternateBase ，以便可以从委托外部设置颜色。例如

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 ，任何正在进行的动画都将立即停止。

注意： 此属性只是一个提示。例如，如果目标单元格不是loaded ，TableView 可能会选择不使用动画来定位内容项。但是，如果设置为false ，动画将始终关闭。

此属性在 Qt 6.4 中引入。

另请参阅 positionViewAtCell()。


bottomRow : int

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

另请参阅 leftColumn,rightColumn, 和topRow 。


columnSpacing : real

该属性表示列之间的间距。

默认值为0 。


columnWidthProvider : var

该属性可以包含一个函数，用于返回模型中每一列的列宽。当TableView 需要知道特定列的宽度时，就会调用该函数。该函数需要一个参数column ，TableView 需要知道该参数的宽度。

自 Qt 5.13 起，如果要隐藏特定列，可以返回0 该列的宽度。如果返回负数，TableView 将根据委托项计算宽度。

注意： 在即将加载一列时（或进行布局时），columnWidthProvider 通常会被调用两次。首先，了解列是否可见，是否应加载。其次，在加载所有项目后确定列宽。如果需要根据委托项的大小计算列宽，则需要等待第二次调用，即所有项目都已加载完毕。您可以通过调用isColumnLoaded(column) 来检查这一点，如果还没有，则直接返回-1。

另请参阅 rowHeightProvider,isColumnLoaded() 和Row heights and column widths 。


columns : int [read-only]

该属性表示表格中的列数。

注意： columns 通常等于模型中的列数，但在处理完所有待处理的模型更改之前，可能会暂时不同。

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

此属性为只读。


contentHeight : real

该属性包含容纳数据模型中行数所需的表格高度。这通常与height 的view 不同，这意味着表格的高度可能大于或小于视口高度。由于TableView 在不加载模型中所有行的情况下不可能总是知道表的确切高度，因此contentHeight 通常是根据最初加载的表估算出来的。

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

另请参阅 contentWidth 和rowHeightProvider 。


contentWidth : real

该属性包含容纳模型中列数所需的表格宽度。这通常与width 的view 不一致，这意味着表格的宽度可能大于或小于视口宽度。由于TableView 在不加载模型中所有列的情况下不可能总是知道表格的确切宽度，因此contentWidth 通常是基于最初加载的表格的估计值。

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

另请参阅 contentHeight 和columnWidthProvider 。


currentColumn : int [read-only]

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

注意： 为了让TableView 报告当前列是什么，需要为selectionModel 指定一个ItemSelectionModel 。

另请参阅 currentRow,selectionModel, 和Selecting items 。


currentRow : int [read-only]

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

注意： 为了让TableView 报告当前行，需要为selectionModel 指定一个ItemSelectionModel 。

另请参阅 currentColumn 、selectionModel 和Selecting items 。


delegate : Component

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

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

delegate: TableViewDelegate { }

模型索引作为可访问的index 属性公开。这同样适用于row 和column 。根据数据模型的类型，模型的属性也是可用的。

委托应使用implicitWidth 和implicitHeight 指定其大小。TableView 会根据这些信息布局项目。明确的宽度或高度设置会被忽略和覆盖。

在委托中，您可以选择添加以下一个或多个属性（除非委托是TableViewDelegate ，在这种情况下，属性已被添加）。TableView 会修改这些属性的值，以告知委托所处的状态。委托可以使用这些属性，根据自身状态以不同方式呈现。

  • 必填属性 bool current -true ，如果代表处于以下状态current.
  • required 属性 bool selected -true 如果代表处于selected.
  • required 属性 bool editing -true （如果委托正在编辑）。edited.
  • 必填属性 bool containsDrag -true 当前是否有列或行正在此委托上拖动。此属性仅支持HorizontalHeaderView 和VerticalHeaderView.（自 Qt XML 6.8 起）

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

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

注意： 委托按需实例化，可随时销毁。如果reuseItems 属性设置为true ，它们也会被重复使用。因此，应避免在委托中存储状态信息。

另请参阅 Row heights and column widths,Reusing items,Required Properties,TableViewDelegate, 以及Customizing TableViewDelegate。


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

该属性包含用户开始编辑单元格的不同方式。它可以是以下值的组合：

常量说明
TableView.NoEditTriggers- 则用户无法触发单元格编辑。设置该值后，TableView 将不会打开或关闭编辑委托作为对任何用户交互的响应。但应用程序可以手动调用edit() 和closeEditor() 。
TableView.SingleTapped- 用户可以通过单击单元格来编辑单元格。
TableView.DoubleTapped- 用户可以通过双击编辑单元格。
TableView.SelectedTapped- 用户可以通过点击selected cell 来编辑单元格。
TableView.EditKeyPressed- 用户可以按编辑键编辑current cell 。编辑键由操作系统决定，但通常是Qt::Key_Enter 和Qt::Key_Return 。
TableView.AnyKeyPressed- 用户可以通过按单元格导航键以外的任意键来编辑current cell 。按下的键也会发送到edit delegate 中的焦点对象。

要使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 来禁用此行为。

注意： 为了使单元格可以编辑，delegate 需要附加edit delegate ，并且模型需要从QAbstractItemModel::flags() 返回Qt::ItemIsEditable （下面有示例）。如果在激活指定的触发器后仍无法编辑单元格，可以尝试明确调用edit() 作为帮助（例如从按钮/TapHandler ）。这样做会打印出一个警告，解释无法编辑单元格的原因。

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 。

注意： 为了让TableView 支持键盘导航，需要为selectionModel 指定一个ItemSelectionModel 。

该属性在 Qt 6.4 中引入。

另请参阅 Keyboard navigation,selectionModel,selectionBehavior,pointerNavigationEnabled 和interactive 。


leftColumn : int

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

另请参阅 rightColumn,topRow, 和bottomRow 。


model : model

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

模型提供用于创建视图中项的数据集。模型可以使用TableModel,ListModel,ObjectModel 直接在 QML 中创建，也可以由自定义的 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 将根据委托项计算高度。

注意： 当一行即将加载（或进行布局）时，rowHeightProvider 通常会被调用两次。首先，要知道该行是否可见并应加载。其次，在加载所有项目后确定行的高度。如果需要根据委托项的大小计算行的高度，则需要等待第二次调用，即所有项目都已加载完毕。您可以通过调用isRowLoaded(row) 来检查这一点，如果尚未加载，则直接返回-1。

另请参见 rowHeightProvider、isRowLoaded() 和Row heights and column widths 。


rowSpacing : real

该属性用于保存行间距。

默认值为0 。


rows : int [read-only]

该属性表示表格中的行数。

注意： rows 通常等于模型中的行数，但在处理完所有待处理的模型更改之前可能暂时不同。

此属性为只读。


selectionBehavior : enumeration [since 6.4]

此属性表示用户是否可以选择单元格、行或列。

常数说明
TableView.SelectionDisabled用户不能执行选择
TableView.SelectCells(默认值） 用户可以选择单个单元格
TableView.SelectRows用户只能选择行
TableView.SelectColumns用户只能选择列

此属性在 Qt 6.4 中引入。

另请参阅 Selecting items,selectionMode,selectionModel, 和keyNavigationEnabled 。


selectionMode : enumeration [since 6.6]

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

可使用以下模式：

常量说明
TableView.SingleSelection用户可以选择单个单元格、行或列。
TableView.ContiguousSelection用户可以选择单个连续的单元格块。在选择时按住Shift 修改器，可将现有选区变大或变小。
TableView.ExtendedSelection(默认值）用户可以选择多个单独的单元格块。在选择时按住Shift 修饰符，可将现有选区变大或变小。通过在选择时按住Control 修改器，可以在不清除当前选择的情况下启动一个新的选择块。

此属性在 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

如果syncView 被设置在TableView 上，该属性将控制两个表的滑动方向同步。默认值为Qt.Horizontal | Qt.Vertical ，这意味着如果向任一方向轻弹其中一个表，另一个表也会向同一方向轻弹相同的幅度。

利用该属性和syncView ，可以使两个表格视图在弹动时顺利实现同步，而无需考虑不同的过冲/反冲、速度、加速/减速或回弹动画等因素。

一个典型的用例是让多个标题与表格一起闪烁。

另请参阅 syncView 。


syncView : TableView

如果将TableView 的此属性设置为另一个TableView ，则两个表格将根据syncDirection 同步闪动、列宽/行高和间距。

如果syncDirection 包含Qt.Horizontal ，则当前 tableView 的列宽、列间距和水平翻页移动将与 syncView 的同步。

如果syncDirection 包含Qt.Vertical ，则当前表格视图的行高、行间距和垂直滑动移动与 syncView 的同步。

另请参阅 syncDirection 。


topRow : int

该属性保存当前视图中可见的最顶端行。

另请参阅 leftColumn,rightColumn, 和bottomRow 。


附加属性文档

TableView.editDelegate : Component

此附加属性用于保存编辑委托。它在编辑开始时实例化，并作为编辑委托的父对象。它支持与TableView delegate 相同的必需属性，包括index,row 和column 。模型的属性，如display 和edit ，也是可用的（取决于模型暴露的role names ）。

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

注意： 为了使单元格可编辑，模型需要覆盖QAbstractItemModel::flags() 并返回Qt::ItemIsEditable 。

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

当用户按下Qt::Key_Enter 或Qt::Key_Return 时，编辑结束（如果TableView 已设置QQuickItem::activeFocusOnTab ，则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

此附加属性包含管理委托实例的视图。它会附加到每个委托实例。


信号文档

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

列移动时发出该信号。列的逻辑索引由logicalIndex 指定，旧索引由oldVisualIndex 指定，新索引位置由newVisualIndex 指定。

注： 相应的处理程序是onColumnMoved 。

此信号在 Qt 6.8 中引入。


[since 6.5] layoutChanged()

当loaded 行和列的布局可能发生变化时，就会发出该信号。尤其是在调用forceLayout() 时，以及在调整行或列的大小、行或列进入或离开视口等情况下。

例如，该信号可用于更新覆盖层的几何图形。

注： 相应的处理程序是onLayoutChanged 。

此信号在 Qt 6.5 中引入。

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


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

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

注： 相应的处理程序是onRowMoved 。

该信号在 Qt 6.8 中引入。


附加信号文档

commit()

此信号由edit delegate

当edit delegate 处于活动状态，且用户按下Qt::Key_Enter 或Qt::Key_Return 时，会发出该附加信号。如果TableView 已设置QQuickItem::activeFocusOnTab ，且用户按下Qt::Key_Tab 或Qt::Key_Backtab ，也会发出该信号。

如果由于上述原因以外的原因导致编辑结束，则不会发出该信号。这包括用户按下Qt::Key_Escape 、在委托之外点击、正在编辑的行或列被删除或应用程序调用closeEditor() 等情况。

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

注意： 此属性应附加到edit delegate ，而不是delegate 。

注意： 相应的处理程序是onCommit 。

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


pooled()

该信号在项目被添加到重用池后发出。您可以用它来暂停项目中正在进行的计时器或动画，或释放无法重复使用的资源。

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

注： 相应的处理程序是onPooled 。

另请参阅 Reusing items,reuseItems, 和reused 。


reused()

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

项目被重复使用时，模型不提供的其他属性不会改变。应避免在委托中存储任何状态，如果要存储，请在收到此信号时手动重置该状态。

该信号在项目被重复使用时发出，而不是在首次创建项目时发出。

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

注： 相应的处理程序是onReused 。

另请参阅 Reusing items,reuseItems, 和pooled 。


方法文档

[since 6.4] point cellAtIndex(QModelIndex modelIndex)

返回视图中与modelIndex 对应的单元格。这是一个方便的函数：

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

单元格是一个简单的point ，它将行和列合并为一个类型。

注意： point.x 将映射到列，而point.y 将映射到行。

此方法在 Qt 6.4 中引入。


Point cellAtPosition(point position, bool includeSpacing)

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

如果includeSpacing 设置为true ，则单元格的边框将被视为包括相邻rowSpacing 和columnSpacing 每边的一半。默认值为false 。

注： 附加到TableView 的输入处理程序会安装到contentItem 而不是视图上。因此，处理程序报告的位置可以直接用于对该函数的调用，而无需任何mapping 。

另请参阅 columnSpacing 和rowSpacing 。


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

方便调用cellAtPosition(Qt.point(x, y), includeSpacing) 。


[since 6.8] clearColumnReordering()

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

注： 如果设置了syncView ，对该函数的调用将被转发到相应的视图项，并重置列排序。

此方法在 Qt 6.8 中引入。


clearColumnWidths()

清除所有使用setColumnWidth() 设置的列宽。

注： 如果syncView 与Qt.Horizontal syncDirection 一起设置，同步视图将控制列宽。因此，在这种情况下，对该函数的任何调用都将转发给同步视图。

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


clearRowHeights()

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

注意： 如果设置了syncView 和Qt.Vertical syncDirection ，同步视图将控制行高。因此，在这种情况下，对该函数的任何调用都将转发给同步视图。

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


[since 6.8] clearRowReordering()

重置之前应用的行重排。

注： 如果设置了syncView ，对该函数的调用将被转发到相应的视图项，并重置行排序。

此方法在 Qt 6.8 中引入。


[since 6.5] 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] edit(QModelIndex modelIndex)

此函数启动表示modelIndex 的单元格的编辑会话。如果用户已经在编辑另一个单元格，则会话结束。

通常，您可以使用editTriggers 来指定启动编辑会话的不同方式。如果还不够，可以使用本功能。要完全控制单元格编辑并防止TableView 干扰，可将editTriggers 设置为TableView.NoEditTriggers 。

注意： selection model 中的current index 也将更改为modelIndex 。

此方法在 Qt 6.5 中引入。

另请参阅 closeEditor(),editTriggers,TableView::editDelegate, 和Editing cells 。


qreal explicitColumnWidth(int column)

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

返回值等于0 表示该列已被告知隐藏。返回值等于-1 意味着没有为列设置明确的宽度。

注意： 如果设置了syncView 和Qt.Horizontal syncDirection ，同步视图将控制列宽。因此，在这种情况下，对该函数的任何调用都将转发给同步视图。

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


qreal explicitRowHeight(int row)

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

返回值等于0 意味着该行已被告知隐藏。返回值等于-1 意味着没有为该行设置明确的高度。

注意： 如果设置了syncView 和Qt.Vertical syncDirection ，同步视图将控制行的高度。因此，在这种情况下，对该函数的任何调用都将转发给同步视图。

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


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)

返回视图中映射到row 和column 的QModelIndex 。

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 。

注意： 通常只加载视图中可见的项目。一旦单元格从视图中弹出，其中的项目将被卸载或放入回收池。因此，不应存储返回值。

注： 如果model 不是QAbstractItemModel ，也可以使用itemAtCell(Qt.point(column, row))。但要注意，point.x 映射列，而point.y 映射行。

此方法在 Qt 6.5 中引入。


[since 6.4] QModelIndex modelIndex(point cell)

的方便函数：

index(cell.y, cell.x)

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

注意： point.x 将映射到列，而point.y 将映射到行。

此方法在 Qt 6.4 中引入。

另请参阅 index()。


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

将列从source 移动到destination 位置。

注意： 如果设置了syncView ，同步视图将控制内部索引映射以进行列重排。因此，在这种情况下，对该函数的调用将转发给同步视图。

此方法在 Qt 6.8 中引入。


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

将一条记录从source 移动到destination 位置。

注意： 如果设置了syncView ，同步视图将控制内部索引映射以进行行重排。因此，在这种情况下，对该函数的调用将转发给同步视图。

此方法在 Qt 6.8 中引入。


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

contentX 和contentY 的位置，使cell 位于mode 指定的位置。mode 可以是以下内容的任意组合：

常量说明
TableView.AlignLeft将单元格定位在视图左侧。
TableView.AlignHCenter将单元格定位在视图的水平中心。
TableView.AlignRight将单元格定位在视图的右侧。
TableView.AlignTop将单元格置于视图顶部。
TableView.AlignVCenter将单元格置于视图的垂直中心。
TableView.AlignBottom将单元格置于视图的底部。
TableView.AlignCenter与 (TableView.AlignHCenter |TableView.AlignVCenter) 相同。
TableView.Visible如果单元格的任何部分可见，则不做任何操作。否则移动内容项，使整个单元格可见。
TableView.Contain如果整个单元格可见，则不执行任何操作。否则移动内容项，使整个单元格可见。如果单元格比视图大，则优先选择单元格的左上角部分。

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

您可以选择指定offset ，将contentX和contentY移动到目标对齐方式之外的额外像素数。例如，如果你想定位视图，使单元格 [10, 10] 以 5px 的边距位于左上角，你就可以这样做：

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

从 Qt 6.4 开始，您可以指定subRect 定位在cell 内部的矩形上，而不是整个单元格的边界矩形上。如果单元格比视图大，而您又想确保单元格的特定部分可见，这将非常有用。subRect 需要考虑到valid 。

注意： 不建议使用contentX或contentY将视图定位到特定单元格。这样做并不可靠，因为从表格起始位置移除项目并不会导致所有其他项目重新定位。TableView 有时也会将行和列放置在近似位置，以优化速度。唯一的例外是如果单元格在视图中已经可见，这可以通过调用itemAtCell() 进行预先检查。

方法只能在组件完成后调用。要在启动时定位视图，应通过 Component.onCompleted 调用该方法。例如，在结束时定位视图：

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

注： 该函数的第二个参数曾是 Qt.Alignment。为了向后兼容，仍可使用该枚举。改用 PositionMode 是在 Qt 6.4 中完成的。

另请参见 animate 。


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

定位 {Flickable::}{contentX}，使column 位于mode,offset 和subRect 指定的位置。

调用

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

[since 6.5] 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 中引入。


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

定位 {Flickable::}{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 。


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() 。您可以为超出模型大小的列指定列大小。

注意： 如果更改model ，您设置的尺寸不会被清除。要清除尺寸，需要明确调用clearColumnWidths() 。

注意： 如果设置了syncView 和Qt.Horizontal syncDirection ，同步视图将控制列宽。因此，在这种情况下，对该函数的任何调用都将转发给同步视图。

注意： 对于有很多列的模型，使用 setColumnWidth() 在启动时设置所有列的宽度可能不是最佳选择。这会消耗启动时间和内存（用于存储所有宽度）。更具扩展性的方法是使用columnWidthProvider ，或依赖委托的隐式宽度。columnWidthProvider 只会在需要时被调用，不会受模型大小的影响。

另请参阅 columnWidth(),explicitColumnWidth(),setRowHeight(),clearColumnWidths() 和Row heights and column widths 。


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()。您可以为超出模型大小的行指定行大小。

注意： 如果更改model ，您设置的大小将不会被清除。要清除大小，需要明确调用clearRowHeights() 。

注意： 如果设置了syncView 和Qt.Vertical syncDirection ，同步视图将控制行高。因此，在这种情况下，对该函数的任何调用都将转发给同步视图。

注意： 对于有大量行的模型，在启动时使用 setRowHeight() 设置所有行的高度可能不是最佳选择。这会消耗启动时间和内存（用于存储所有高度）。更具扩展性的方法是使用rowHeightProvider ，或依赖委托的隐式高度。rowHeightProvider 只会在需要时被调用，不会受到模型大小的影响。

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


© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.