class QHeaderView#

QHeaderView类提供用于项目视图的标题行或列。 更多…

Inheritance diagram of PySide6.QtWidgets.QHeaderView

概要#

属性#

方法#

虚拟方法#

槽#

信号#

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们欢迎对片段翻译的贡献。如果您发现翻译有误，也可以通过在https:/bugreports.qt.io/projects/PYSIDE创建票据的方式告诉我们。

详细描述#

QHeaderView用于显示在QTableView和QTreeView类等物品视图中使用的标题。它取代了之前用于相同目的的Qt3的QHeader类，但使用Qt的模型/视图架构以符合物品视图类的一致性。

QHeaderView类是模型/视图类之一，并是Qt的模型/视图框架的一部分。

标题通过使用QAbstractItemModel::headerData()函数从模型中获取每个部分的显式数据。您可以使用QAbstractItemModel::setHeaderData()设置数据。

每个标题都有一个orientation()和一个由count()函数给出的部分数量。部分指的是标题的一部分 - 无论是行还是列，具体取决于方向。

可以使用moveSection()和resizeSection()移动和调整部分的大小；它们还可以通过hideSection()和showSection()隐藏和显示。

每个标题部分通过section()指定的部分ID进行描述，可以在标题中的特定位置visualIndex()找到。部分可以设置排序指示器，使用setSortIndicator()；这表示关联项视图中的项目是否按部分给定的顺序排序。

对于水平标题，部分在模型中相当于列；对于垂直标题，部分在模型中相当于行。

移动标题部分#

标题可以放置固定，或通过setSectionsMovable()使其可移动。可以使用setSectionsClickable()使其可点击，并根据setSectionResizeMode()设置相应的调整大小行为。

注意

双击标题以调整部分大小仅适用于可见行。

如果用户移动部分，标题会发出sectionMoved()，如果用户调整部分大小，则会发出sectionResized()，以及鼠标点击响应的sectionClicked()和sectionHandleDoubleClicked()。标题还会发出sectionCountChanged()。

您可以使用logicalIndex()和logicalIndexAt()函数，或使用索引位置，通过visualIndex()和visualIndexAt()函数来标识部分。如果移动部分，则视觉索引会改变，但逻辑索引不会改变。

外观#

QTableWidget和QTableView会创建默认的表头。如果您想让表头可见，可以使用setVisible()方法。

并非所有ItemDataRoles（项数据角色）都会对QHeaderView产生效果。如果您需要绘制其他角色，可以继承QHeaderView并重写paintEvent()方法。QHeaderView尊重以下数据角色，除非它们与样式冲突（这可能发生在遵循桌面主题的样式的情况下）：

TextAlignmentRole（文本对齐角色）、DisplayRole（显示角色）、FontRole（字体角色）、DecorationRole（装饰角色）、ForegroundRole（前景角色）和BackgroundRole（背景角色）。

注意

每个表头都自己渲染每个段的数据，并不依赖于代理。因此，调用表头的setItemDelegate()方法不会有任何效果。

另请参阅

模型/视图编程 QListView QTableView QTreeView

class ResizeMode#

调整大小模式指定表头部分的 beha

常数

描述

QHeaderView.Interactive

用户可以调整部分大小。部分大小也可以使用resizeSection()方法程序化进行调整。部分大小默认为defaultSectionSize。（另请参阅cascadingSectionResizes。）

QHeaderView.Fixed

用户不能调整部分大小。部分大小只能使用resizeSection()方法程序化进行调整。部分大小默认为defaultSectionSize。

QHeaderView.Stretch

QHeaderView将自动调整大小以填充可用空间。大小不能由用户或通过程序更改。

QHeaderView.ResizeToContents

QHeaderView 将自动将节大小调整到基于整列或整行的内容的最优大小。大小不能由用户或程序更改。（此功能在 4.2 版本中引入。）

以下值为已废弃

常数

描述

QHeaderView.Custom

请使用固定值。

另请参阅

setSectionResizeMode() stretchLastSection minimumSectionSize

注意

当使用 from __feature__ import true_property 时可以直接使用属性，否则通过访问函数。

属性 cascadingSectionResizesᅟ: 布尔值#

此属性表示一旦用户调整大小的当前节达到其最小大小，互动调整大小的操作是否将级联到后续节。

此属性仅影响那些将 Interactive 作为其调整大小模式的节。

默认值为 false。

另请参阅

setSectionResizeMode()

访问函数
属性 defaultAlignmentᅟ: Qt.AlignmentFlag 组合#

此属性表示每个标题节的文字的默认对齐方式。

访问函数
属性 defaultSectionSizeᅟ: 整数#

此属性表示调整大小前的标题节默认大小。

此属性仅影响那些将 Interactive 或 Fixed 作为其调整大小模式的节。

默认情况下，此属性的值依赖于样式。因此，当样式更改时，此属性会从它更新。调用 setDefaultSectionSize() 停止更新，调用 resetDefaultSectionSize() 将恢复默认行为。

访问函数
属性firstSectionMovable: bool#

此属性表示第一列是否可以被用户移动。

此属性控制是否允许用户移动第一列。在一个 QTreeView 中，第一列包含树的层次结构，因此默认不可移动，即使调用 setSectionsMovable (true) 或许会变。

可以通过调用此方法重新使其可移动，例如在没有任何树结构的平面列表中。在这种情况下，建议同时调用 setRootIsDecorated (false)。

treeView->setRootIsDecorated(false);
treeView->header()->setFirstSectionMovable(true);

除非同时调用 setSectionsMovable (true)，否则将其设置为true将没有任何效果。

另请参阅

setSectionsMovable()

访问函数
属性highlightSections: bool#

此属性表示是否突出显示包含选中项的节。

默认情况下，此属性为 false。

访问函数
属性maximumSectionSize: int#

此属性表示标题节的最大大小。

最大节大小是允许的最大节大小。此属性的默认值为1048575，也是节的最大可能大小。将最大值设置为-1会将值重置为最大节大小。

除了拉伸外，此属性受到所有 resize modes 的尊重。

访问函数
属性minimumSectionSize: int#

此属性表示头部节的最小大小。

最小节大小是允许的最小节大小。如果将最小节大小设置为-1，则 QHeaderView 将使用 font metrics 的大小。

该属性受所有 resize modes 的尊重。

访问函数
属性showSortIndicator: bool#

该属性表示是否显示排序指示器。

默认情况下，此属性为 false。

另请参阅

setSectionsClickable()

访问函数
属性sortIndicatorClearable: bool#

该属性表示是否可以通过多次点击一个部分来清除排序指示器。

该属性控制用户是否可以通过多次点击某个部分来移除该部分的排序指示器。通常情况下，点击某个部分只会改变该部分的排序顺序。通过将此属性设置为 true，会在交替升序和降序后清除排序指示器；这通常会恢复模型的原始排序。

将此属性设置为 true 无效，除非 sectionsClickable 也设置为 true（某些视图的默认值，例如 QTableView 或在设置视图可排序时自动设置，例如通过调用 setSortingEnabled )。

访问函数
属性stretchLastSection: bool#

该属性表示头部最后一个可见部分是否占据所有可用空间。

默认值为 false。

注意

QTreeView 提供的水平表头使用此属性设置为 true，确保视图不会浪费分配给其标题的空间。如果此值设置为 true，则此属性将覆盖头部最后一个部分的调整为大小的模式。

另请参阅

setSectionResizeMode()

访问函数
__init__(orientation[, parent=None])#
参数:

使用给定的 orientation 和 parent 创建一个新的泛型标题。

cascadingSectionResizes()#
返回类型：

bool

另请参阅

setCascadingSectionResizes()

属性 cascadingSectionResizes 的 getter。

count()#
返回类型：

int

返回标题中的节区数量。

defaultAlignment()#
返回类型：

组合 AlignmentFlag

另请参阅

setDefaultAlignment()

属性 defaultAlignment 的 getter。

defaultSectionSize()#
返回类型：

int

另请参阅

setDefaultSectionSize()

属性 defaultSectionSize 的 getter。

geometriesChanged()#

当标题的几何形状发生变化时，会发出此信号。

headerDataChanged(orientation, logicalFirst, logicalLast)#
参数:

  • orientation – Orientation

  • logicalFirst – int

  • logicalLast – int

更新给定 orientation 的标题节区，从 logicalFirst 到 logicalLast（包含）的更改。

hiddenSectionCount()#
返回类型：

int

返回标题中被隐藏的节区数量。

hideSection(logicalIndex)#
参数:

logicalIndex – int

隐藏由 logicalIndex 指定的节区。

highlightSections()#
返回类型：

bool

另请参阅

setHighlightSections()

属性 highlightSections 的获取器。

initStyleOption(option)#
参数:

option – QStyleOptionHeader

使用此 QHeaderView 的值初始化 option。此方法对于需要 QStyleOptionHeader 但不想自行填写全部信息的子类非常有用。

initStyleOptionForIndex(option, logicalIndex)#
参数:

从指定的 logicalIndex 初始化样式 option。此函数在调用 initStyleOption 之后，由 paintSection 的默认实现调用。

initialize()#
initializeSections()#
initializeSections(start, end)
参数:

  • start – int

  • end – int

isFirstSectionMovable()#
返回类型：

bool

属性 firstSectionMovable 的获取器。

isSectionHidden(logicalIndex)#
参数:

logicalIndex – int

返回类型：

bool

如果由 logicalIndex 指定的部分被显式地从用户界面中隐藏，则返回 true；否则返回 false。

isSortIndicatorClearable()#
返回类型：

bool

属性 sortIndicatorClearable 的获取器。

isSortIndicatorShown()#
返回类型：

bool

属性 showSortIndicator 的获取器。

length()#
返回类型：

int

返回头部的方向长度。

另请参阅

sizeHint() setSectionResizeMode() offset()

logicalIndex(visualIndex)#
参数:

visualIndex – int

返回类型：

int

返回给定 visualIndex 位置的节区的逻辑索引，如果有错误（如 visualIndex < 0 或 visualIndex >= count()），则返回 -1。

请注意，visualIndex不受隐藏节区的影响。

logicalIndexAt(x, y)#
参数:

  • x – int

  • y – int

返回类型：

int

返回给定坐标的节区的逻辑索引。如果表头是水平的，则使用 x，否则使用 y 来查找逻辑索引。

logicalIndexAt(pos)#
参数:

pos – QPoint

返回类型：

int

返回给定 pos 位置节区的逻辑索引。如果表头是水平的，则使用 x 坐标，否则使用 y 坐标来查找逻辑索引。

另请参阅

sectionPosition()

logicalIndexAt(position)
参数:

position – int

返回类型：

int

返回覆盖给定 position 的节区。

maximumSectionSize()#
返回类型：

int

另请参阅

setMaximumSectionSize()

属性 maximumSectionSize 的获取器。

minimumSectionSize()#
返回类型：

int

另请参阅

setMinimumSectionSize()

属性 minimumSectionSize 的获取器。

moveSection(from, to)#
参数:

  • from – int

  • to – int

将视索引为 from 的节移动到占用视索引 to。

另请参阅

sectionsMoved()

offset()#
返回类型：

int

返回标题的偏移量：这是标题最左侧（或对于垂直标题是最顶部）的可见像素。

另请参阅

setOffset()

orientation()#
返回类型：

方向

返回标题的方向。

另请参阅

方向

paintSection(painter, rect, logicalIndex)#
参数:

使用给定的 painter 和 rect 绘制由给定 logicalIndex 指定的节。

通常不需要调用此函数。

resetDefaultSectionSize()#

重置属性 defaultSectionSize 的功能。

resizeContentsPrecision()#
返回类型：

int

返回 QHeaderView 在 ResizeToContents 时计算的精度。

resizeSection(logicalIndex, size)#
参数:

  • logicalIndex – int

  • size – int

将指定由 logicalIndex 的部分调整到 size 的大小，单位为像素。尺寸参数必须是大于或等于零的值。不过，建议不要使用大小为零，在这种情况下应使用 hideSection 来隐藏部分。

resizeSections()#

根据部分的大小提示调整部分的大小。通常情况下，无需调用此函数。

resizeSections(mode)
参数:

mode – ResizeMode

根据给定的 mode 调整部分的大小，忽略当前的调整大小模式。

另请参阅

sectionResized()

restoreState(state)#
参数:

state – QByteArray

返回类型：

bool

恢复此表头的状态。如果成功恢复状态，则此函数返回 true，否则返回 false。

另请参阅

saveState()

saveState()#
返回类型：

QByteArray

保存此表头视图的当前状态。

要恢复已保存的状态，请将返回值传递给 restoreState()。

另请参阅

restoreState()

sectionClicked(logicalIndex)#
参数:

logicalIndex – int

当点击部分时发出此信号。部分的逻辑索引由 logicalIndex 指定。

请注意，还会发出 sectionPressed 信号。

sectionCountChanged(oldCount, newCount)#
参数:

  • oldCount – int

  • newCount – int

该信号在分区数量发生变化时发出，即添加或删除分区时。原始数量由 oldCount 指定，新数量由 newCount 指定。

sectionDoubleClicked(logicalIndex)#
参数:

logicalIndex – int

当双击分区时发出此信号。分区的逻辑索引由 logicalIndex 指定。

另请参阅

setSectionsClickable()

sectionEntered(logicalIndex)#
参数:

logicalIndex – int

当鼠标指针移动到分区上并按下左键时，发出此信号。分区的逻辑索引由 logicalIndex 指定。

sectionHandleDoubleClicked(logicalIndex)#
参数:

logicalIndex – int

当双击分区时发出此信号。分区的逻辑索引由 logicalIndex 指定。

另请参阅

setSectionsClickable()

sectionMoved(logicalIndex, oldVisualIndex, newVisualIndex)#
参数:

  • logicalIndex – int

  • oldVisualIndex – int

  • newVisualIndex – int

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

另请参阅

moveSection()

sectionPosition(logicalIndex)#
参数:

logicalIndex – int

返回类型：

int

返回给定 logicalIndex 的分区位置，如果分区隐藏，则返回 -1。位置是从第一个可见项的左上角到具有 logicalIndex 的项左上角的像素数。对于水平表头，测量沿 x 轴进行；对于垂直表头，测量沿 y 轴进行。

sectionPressed(logicalIndex)#
参数:

logicalIndex – int

当按下分区时发出此信号。分区的逻辑索引由 logicalIndex 指定。

另请参阅

setSectionsClickable()

sectionResizeMode(logicalIndex)#
参数:

logicalIndex – int

返回类型：

段调整模式

返回指定 logicalIndex 的段所应用的调整模式。

另请参阅

setSectionResizeMode()

sectionResized(logicalIndex, oldSize, newSize)#
参数:

  • logicalIndex – int

  • oldSize – int

  • newSize – int

当调整段大小时发送此信号。通过 logicalIndex 指定段的逻辑编号，通过 oldSize 指定旧大小，通过 newSize 指定新大小。

另请参阅

resizeSection()

sectionSize(logicalIndex)#
参数:

logicalIndex – int

返回类型：

int

返回给定 logicalIndex 的宽度（或垂直表头的高度）。

sectionSizeFromContents(logicalIndex)#
参数:

logicalIndex – int

返回类型：

QSize

返回指定 logicalIndex 的段的 内容大小。

另请参阅

defaultSectionSize()

sectionSizeHint(logicalIndex)#
参数:

logicalIndex – int

返回类型：

int

返回指定 logicalIndex 的段的一个合适的大小提示。

Qt::SizeHintRole

sectionViewportPosition(logicalIndex)#
参数:

logicalIndex – int

返回类型：

int

返回给定 logicalIndex 的段的视口位置。

如果该段已隐藏，则返回值未定义。

sectionsAboutToBeRemoved(parent, logicalFirst, logicalLast)#
参数:

  • parent – QModelIndex

  • logicalFirst – int

  • logicalLast – int

此插槽在从 parent 移除栏时被调用。 logicalFirst 和 logicalLast 标示了栏被移除的位置。

如果只移除一个栏，则 logicalFirst 和 logicalLast 将相同。

sectionsClickable()#
返回类型：

bool

如果标题可点击，则返回 true；否则返回 false。可点击的标题可以配置为允许用户更改与标题相关的视图数据表示。

另请参阅

setSectionsClickable()

sectionsHidden()#
返回类型：

bool

如果标题中的栏已被隐藏，则返回 true；否则返回 false；

另请参阅

setSectionHidden()

sectionsInserted(parent, logicalFirst, logicalLast)#
参数:

  • parent – QModelIndex

  • logicalFirst – int

  • logicalLast – int

此插槽在向 parent 插入栏时被调用。 logicalFirst 和 logicalLast 索引表示新栏被插入的位置。

如果只插入一个栏，则 logicalFirst 和 logicalLast 将相同。

sectionsMovable()#
返回类型：

bool

如果用户可以移动标题，则返回 true；否则返回 false。

默认情况下，在 QTreeView 中栏可以移动（除了第一个），而在 QTableView 中则不可移动。

另请参阅

setSectionsMovable()

sectionsMoved()#
返回类型：

bool

如果标题中的栏已被移动，则返回 true；否则返回 false；

另请参阅

moveSection()

setCascadingSectionResizes(enable)#
参数:

enable — bool类型

另请参阅

cascadingSectionResizes()

设置属性 cascadingSectionResizes 的值。

setDefaultAlignment(alignment)#
参数:

alignment — 将AlignmentFlag组合

另请参阅

defaultAlignment()

设置属性 defaultAlignment 的值。

setDefaultSectionSize(size)#
参数:

size – int

另请参阅

defaultSectionSize()

设置属性 defaultSectionSize 的值。

setFirstSectionMovable(movable)#
参数:

movable — bool类型

另请参阅

isFirstSectionMovable()

设置属性 firstSectionMovable 的值。

setHighlightSections(highlight)#
参数:

highlight — bool类型

另请参阅

highlightSections()

设置属性 highlightSections 的值。

setMaximumSectionSize(size)#
参数:

size – int

另请参阅

maximumSectionSize()

设置属性 maximumSectionSize 的值。

setMinimumSectionSize(size)#
参数:

size – int

另请参阅

minimumSectionSize()

设置属性 minimumSectionSize 的值。

setOffset(offset)#
参数:

offset — int类型

设置标题的偏移量为offset。

另请参阅

offset() length()

setOffsetToLastSection()#

设置偏移量，以使最后一个部分可见。

setOffsetToSectionPosition(visualIndex)#
参数:

visualIndex – int

将偏移量设置为在给定的 visualSectionNumber 的部分开始位置。在隐藏部分不被考虑的情况下，这不一定与 visualIndex() 相同。

setResizeContentsPrecision(precision)#
参数:

precision – int

设置当使用 QHeaderView 的 ResizeToContents 时，应该有多精确地计算大小。
低值将提供不太精确但快速的自动调整大小，而高值将提供更精确的调整大小，但可能会较慢。

数字 precision 指定了在计算首选大小时应该考虑的分区数量。

默认值是 1000，这意味着在自动调整大小时，垂直列将查看最多 1000 行进行计算。

特殊值 0 表示将只查看可见区域。特殊值 -1 将表示查看所有元素。

此值用于 sizeHintForColumn() 、sizeHintForRow() 和 sizeHintForColumn() 。重新实现这些函数可以使此功能不起作用。

另请参阅

resizeContentsPrecision() setSectionResizeMode() resizeSections() sizeHintForColumn() sizeHintForRow() sizeHintForColumn()

setSectionHidden(logicalIndex, hide)#
参数:

  • logicalIndex – int

  • hide – bool

如果 hide 为 true，则隐藏通过 logicalIndex 指定的部分；否则显示该部分。

setSectionResizeMode(mode)#
参数:

mode – ResizeMode

设置限制，以描述如何调整表头的大小。

setSectionResizeMode(logicalIndex, mode)
参数:

设置通过 logicalIndex 指定的头部部分的缩放模式。

注意

如果将 stretchLastSection 属性设置为 true，此设置将被忽略。这是由 QTreeView 提供的水平标题的默认值。

另请参阅

setStretchLastSection() resizeContentsPrecision()

setSectionsClickable(clickable)#
参数:

clickable – bool类型

如果clickable值为true，则标题栏将对单次点击做出响应。

setSectionsMovable(movable)#
参数:

movable — bool类型

如果movable值为true，则用户可移动标题栏部分；否则，标题栏部分固定在原位。

在使用QTreeView时，默认情况下第一列不可移动（因为它包含树结构）。您可以使用setFirstSectionMovable（true）将其设置为可移动。

setSortIndicator(logicalIndex, order)#
参数:

根据order指定的方向，为指定逻辑索引（logicalIndex）的标题栏设置排序指示器，并从显示排序指示器的其他任何标题栏中移除。

logicalIndex可能为-1，此时不显示排序指示器，并且模型将返回其自然、未排序的顺序。请注意，并非所有模型都支持此功能，并且在此情况下可能会崩溃。

setSortIndicatorClearable(clearable)#
参数:

clearable – bool类型

另请参阅

isSortIndicatorClearable()

属性 sortIndicatorClearableᅟ 的设置器。

setSortIndicatorShown(show)#
参数:

show – bool

另请参阅

isSortIndicatorShown()

属性 showSortIndicatorᅟ 的设置器。

setStretchLastSection(stretch)#
参数:

stretch – bool

另请参阅

stretchLastSection()

属性 stretchLastSectionᅟ 的设置器。

showSection(logicalIndex)#
参数:

logicalIndex – int

显示由 logicalIndex 指定的部分。

sortIndicatorChanged(logicalIndex, order)#
参数:

当包含排序指示器或指定的顺序改变的部分时，发出此信号。部分的逻辑索引由 logicalIndex 指定，排序顺序由 order 指定。

另请参阅

setSortIndicator()

sortIndicatorClearableChanged(clearable)#
参数:

clearable – bool类型

属性 sortIndicatorClearableᅟ 的通知信号。

sortIndicatorOrder()#
返回类型：

SortOrder

返回排序指示器的顺序。如果没有部分有排序指示器，此函数的返回值是未定义的。

sortIndicatorSection()#
返回类型：

int

返回带有排序指示符的章节的逻辑索引。默认为第0章节。

stretchLastSection()#
返回类型：

bool

另请参阅

setStretchLastSection()

属性 stretchLastSection 的获取器。

stretchSectionCount()#
返回类型：

int

返回设置为拉伸模式的章节数。在视图中，这可以用来判断当视图的几何形状改变时，headerview是否需要调整章节大小。

另请参阅

stretchLastSection

swapSections(first, second)#
参数:

  • first – int

  • second – int

交换视觉索引为 first 的章节和视觉索引为 second 的章节。

另请参阅

moveSection()

updateSection(logicalIndex)#
参数:

logicalIndex – int

visualIndex(logicalIndex)#
参数:

logicalIndex – int

返回类型：

int

返回给定 logicalIndex 指定的章节的视觉索引位置，否则返回 -1。

隐藏的章节仍然有有效的视觉索引。

另请参阅

logicalIndex()

visualIndexAt(position)#
参数:

position – int

返回类型：

int

返回覆盖视口中给定 position 的章节的视觉索引。

另请参阅

logicalIndexAt()