HorizontalHeaderView QML Type
提供一个水平标题视图，用于配合TableView 使用。更多内容...
| Import Statement: | import QtQuick.Controls |
| Inherits: |
属性
- model : QVariant
- movableColumns : bool
(since 6.8) - syncView : TableView
- textRole : string
详细说明
HorizontalHeaderView 提供了一个具有样式化的表格标题。它既可以作为独立视图使用，也可以作为TableView 的标题。
您可以通过将TableView 赋值给HorizontalHeaderView的syncView 属性，为TableView 添加表头。这样，在滑动操作时，表头和表格将保持同步。
header data 默认情况下，HorizontalHeaderView 会显示来自sync view's 的model 数据。如果您不想使用该模型中的标题数据，或者未使用syncView ，可以将模型显式赋值给model 属性。
注意：为了 显示QAbstractItemModel 的标题数据，HorizontalHeaderView会在 内部将该模型的标题数据封装在一个独立的代理模型中。该代理模型与application model 不共享任何模型项。这意味着，如果您调用诸如index()之类的函数，所返回的模型索引将属于代理模型，而非应用程序模型。
默认情况下，textRole 设置为"display" ，这意味着将使用模型中Qt::DisplayRole 的数据。您可以将其设置为其他角色名称，以便显示相应数据。
应用程序负责将标题放置在场景中的正确位置。您可以向单个TableView 添加任意数量的标题，例如，如果您希望在表格的四边都放置标题，这将非常有用。
以下代码片段演示了如何向表格视图添加水平和垂直标题视图：
import QtQuick
import QtQuick.Controls
import Qt.labs.qmlmodels
ApplicationWindow {
visible: true
width: 640
height: 480
title: qsTr("HeaderView")
Rectangle {
anchors.fill: parent
// The background color will show through the cell
// spacing, and therefore become the grid line color.
color: Application.styleHints.appearance === Qt.Light ? palette.mid : palette.midlight
HorizontalHeaderView {
id: horizontalHeader
anchors.left: tableView.left
anchors.top: parent.top
syncView: tableView
clip: true
}
VerticalHeaderView {
id: verticalHeader
anchors.top: tableView.top
anchors.left: parent.left
syncView: tableView
clip: true
}
TableView {
id: tableView
anchors.left: verticalHeader.right
anchors.top: horizontalHeader.bottom
anchors.right: parent.right
anchors.bottom: parent.bottom
clip: true
columnSpacing: 1
rowSpacing: 1
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: 20
color: palette.base
Label {
text: display
}
}
}
}
}默认情况下，HorizontalHeaderView 的 `resizableColumns ` 属性将设置为 `true `。
另请参阅 VerticalHeaderView 。
属性文档
model : QVariant
该属性保存为水平标题视图提供数据的模型。
默认情况下，水平标题视图会显示来自sync view's 的header data （model ）。如果您不想使用该模型中的标题数据，或者未使用syncView ，则可以显式地将模型赋值给此属性。如果model 是一个QAbstractTableModel ，则将使用其header data ；否则，如果它是QAbstractItemModel ，则将使用data 。
除了QAbstractItemModels 之外，您还可以将其他类型的模型赋值给此属性，例如 JavaScript 数组。
另请参阅 TableView 、model 以及QAbstractTableModel 。
movableColumns : bool [since 6.8]
此属性允许用户在视图中移动列。默认值为false 。
注意：如果 设置了此属性，HorizontalHeaderView 将允许用户将列拖放至所需位置。当启用“syncView ”时，任何更改都会应用到相应的视图项上。
该属性于 Qt 6.8 版本中引入。
syncView : TableView
该属性存储用于同步的TableView 对象。
一旦此属性绑定到另一个TableView ，标题栏和表格将在列宽、列间距以及水平滑动方面保持同步。
如果未显式设置model ，则标题将使用 syncView 的模型来标注列。
textRole : string
该属性用于存储在每个标题单元格中显示文本时所使用的模型角色。
当模型具有多个角色时，可设置 textRole 来确定应显示哪个角色。
在呈现模型中的数据时，委托（delegate）有责任遵循已分配的“文本角色”（textRole ）。虽然HorizontalHeaderViewDelegate 和VerticalHeaderViewDelegate 会自动处理这一点，但自定义委托必须显式实现此行为。
如果模型是QAbstractItemModel ，则默认值为“display”；否则为空。
如果模型的roleNames() 方法未提供 textRole 中指定的角色，则会发出警告。可通过设置 textRole 来抑制该警告。
另请参阅 ` QAbstractItemModel::roleNames()`。
© 2026 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.
