PySide6.QtGui.QStandardItem

class QStandardItem

QStandardItem 类提供了一个用于 QStandardItemModel 类的项目。更多…

概要

方法

虚拟方法

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

项目通常包含文本、图标或复选框。

每个项目都可以有自己的背景画刷，这是通过setBackground()函数设置的。当前的背景画刷可以通过background()找到。每个项目的文本标签可以用自己的字体和画刷渲染。这些是通过setFont()和setForeground()函数指定的，并通过font()和foreground()读取。

默认情况下，项目是启用的、可编辑的、可选择的、可勾选的，并且可以作为拖放操作的源和目标。每个项目的标志可以通过调用setFlags()来更改。可勾选的项目可以使用setCheckState()函数进行勾选和取消勾选。相应的checkState()函数指示项目当前是否被勾选。

您可以通过调用setData()来存储特定于应用程序的数据。

每个项目可以有一个二维的子项目表。这使得构建项目的层次结构成为可能。典型的层次结构是树，在这种情况下，子表是一个单列的表（一个列表）。

子表的维度可以通过setRowCount()和setColumnCount()来设置。可以使用setChild()将项目定位在子表中。使用child()获取指向子项目的指针。还可以使用insertRow()和insertColumn()插入新的行和列，或者使用appendRow()和appendColumn()追加新的行和列。当使用追加和插入函数时，子表的维度会根据需要自动增长。

可以使用removeRow()或takeRow()移除现有的子行；相应地，可以使用removeColumn()或takeColumn()移除列。

可以通过调用 sortChildren() 来对项目的子项进行排序。

子类化

当子类化QStandardItem以提供自定义项时，可以为它们定义新类型，以便将它们与基类区分开来。应重新实现type()函数以返回等于或大于UserType的新类型值。

如果你想对数据查询进行自定义处理和/或控制项目数据的表示方式，请重新实现 data() 和 setData()。

如果你希望 QStandardItemModel 能够按需创建自定义项类的实例，请重新实现 clone()（参见 setItemPrototype() ）。

如果你想控制项目在序列化形式中的表示方式，请重新实现 read() 和 write()。

如果你想控制项目比较的语义，请重新实现operator。operator在使用sortChildren()或sort()对项目进行排序时决定排序顺序。

另请参阅

QStandardItemModel 项目 视图 便捷 类模型/视图 编程

class ItemType

此枚举描述了用于描述标准项目的类型。

常量

描述

QStandardItem.Type

标准项目的默认类型。

QStandardItem.UserType

自定义类型的最小值。低于UserType的值由Qt保留。

你可以在QStandardItem子类中定义新的用户类型，以确保自定义项得到特殊处理；例如，在排序项时。

另请参阅

type()

__init__()

构建一个项目。

__init__(other)
Parameters:

其他 – QStandardItem

构造一个other的副本。请注意，model()不会被复制。

这个函数在重新实现clone()时非常有用。

__init__(text)
Parameters:

文本 – str

使用给定的text构造一个项目。

__init__(icon, text)
Parameters:

  • 图标 – QIcon

  • 文本 – str

使用给定的icon和text构造一个项目。

__init__(rows[, columns=1])
Parameters:

  • rows – int

  • columns – 整数

构建一个包含rows行和columns列子项目的项目。

accessibleDescription()
Return type:

字符串

返回项目的可访问描述。

可访问的描述由辅助技术使用（即对于无法使用传统交互方式的用户）。

accessibleText()
Return type:

字符串

返回项目的可访问文本。

可访问文本由辅助技术使用（即对于无法使用传统交互方式的用户）。

appendColumn(items)
Parameters:

items – QStandardItem 的列表

追加一个包含items的列。如果需要，行数将增加到items的大小。

另请参阅

insertColumn()

appendRow(item)
Parameters:

项目 – QStandardItem

这是一个重载函数。

追加一行包含 item。

在构建只有一个列的列表或树时，此函数提供了一种方便的方式来追加单个新项。

appendRow(items)
Parameters:

items – QStandardItem 的列表

追加一行包含items。如有必要，列数将增加到items的大小。

另请参阅

insertRow()

appendRows(items)
Parameters:

items – QStandardItem 的列表

追加包含items的行。列数不会改变。

另请参阅

insertRow()

background()
Return type:

QBrush

返回用于渲染项目背景的画笔。

checkState()
Return type:

CheckState

返回项目的选中状态。

child(row[, column=0])
Parameters:

  • row – int

  • column – 整数

Return type:

QStandardItem

返回在(row, column)位置的子项，如果已设置；否则返回None。

clearData()

移除之前设置的所有角色的所有数据。

另请参阅

data() setData()

clone()
Return type:

QStandardItem

返回此项目的副本。项目的子项不会被复制。

当子类化 QStandardItem 时，你可以重新实现这个函数，以向 QStandardItemModel 提供一个工厂，它可以在需要时使用该工厂创建新项目。

另请参阅

setItemPrototype() operator=()

column()
Return type:

整数

返回项目在其父级的子表中的列位置，如果项目没有父级，则返回-1。

另请参阅

row() parent()

columnCount()
Return type:

整数

返回该项具有的子项列数。

data([role=Qt.UserRole + 1])
Parameters:

角色 – int

Return type:

对象

返回给定role的项目数据，如果没有该角色的数据，则返回无效的QVariant。

如果你重新实现这个函数，你的重新实现应该为你未处理的角色调用基础实现，否则获取标志，例如通过调用flags()、isCheckable()、isEditable()等，将无法工作。

注意

默认实现将Qt::EditRole和Qt::DisplayRole视为引用相同的数据。

另请参阅

setData()

emitDataChanged()

导致与此项关联的模型为此项发出dataChanged()信号。

通常只有在您子类化了QStandardItem并重新实现了data()和/或setData()时，才需要调用此函数。

另请参阅

setData()

flags()
Return type:

ItemFlag的组合

返回项目的项目标志。

项目标志决定了用户如何与项目进行交互。

默认情况下，项目是启用的、可编辑的、可选择的、可检查的，并且可以用作拖放操作的源和放置目标。

另请参阅

setFlags()

font()
Return type:

QFont

返回用于渲染项目文本的字体。

另请参阅

setFont()

foreground()
Return type:

QBrush

返回用于渲染项目前景（例如文本）的画笔。

hasChildren()
Return type:

布尔

如果此项目有任何子项，则返回true；否则返回false。

icon()
Return type:

QIcon

返回项目的图标。

另请参阅

setIcon() iconSize

index()
Return type:

QModelIndex

返回与此项关联的QModelIndex。

当您需要在基于QModelIndex的API（例如QAbstractItemView）中调用项目功能时，您可以调用此函数以获取与模型中项目位置对应的索引。

如果项目未与模型关联，则返回无效的QModelIndex。

另请参阅

model() itemFromIndex()

insertColumn(column, items)
Parameters:

  • column – 整数

  • items – QStandardItem 的列表

在column列插入包含items的列。如有必要，行数将增加到items的大小。

insertColumns(column, count)
Parameters:

  • column – 整数

  • count – int

在列 column 处插入 count 列子项。

insertRow(row, item)
Parameters:

这是一个重载函数。

在 row 处插入一行，包含 item。

在构建只有一个列的列表或树时，此函数提供了一种方便的方式来插入单个新项。

insertRow(row, items)
Parameters:

  • row – int

  • items – QStandardItem 的列表

在row处插入一行，包含items。如有必要，列数将增加到items的大小。

insertRows(row, items)
Parameters:

  • row – int

  • items – QStandardItem 的列表

在row处插入items。列数不会改变。

insertRows(row, count)
Parameters:

  • row – int

  • count – int

在行 row 处插入 count 行的子项。

isAutoTristate()
Return type:

布尔

返回该项目是否为三态并由QTreeWidget控制。

默认值为 false。

isCheckable()
Return type:

布尔

返回项目是否可由用户勾选。

默认值为 false。

isDragEnabled()
Return type:

布尔

返回项目是否启用了拖动功能。启用了拖动功能的项目可以被用户拖动。

默认值为true。

请注意，必须在视图中启用项目拖动才能使拖动工作；请参阅 QAbstractItemView::dragEnabled。

isDropEnabled()
Return type:

布尔

返回项目是否启用了拖放功能。当项目启用了拖放功能时，它可以作为拖放目标使用。

默认值为true。

isEditable()
Return type:

布尔

返回项目是否可以被用户编辑。

当项目可编辑（并且启用）时，用户可以通过调用视图的编辑触发器之一来编辑项目；请参阅 QAbstractItemView::editTriggers。

默认值为true。

另请参阅

setEditable() flags()

isEnabled()
Return type:

布尔

返回项目是否启用。

当项目启用时，用户可以与之交互。交互的可能类型由其他项目标志指定，例如 isEditable() 和 isSelectable() 。

默认值为true。

另请参阅

setEnabled() flags()

isSelectable()
Return type:

布尔

返回项目是否可由用户选择。

默认值为true。

另请参阅

setSelectable() flags()

isUserTristate()
Return type:

布尔

返回项目是否为三态；也就是说，如果它是可检查的，具有三种独立的状态，并且用户可以循环遍历所有三种状态。

默认值为 false。

model()
Return type:

QStandardItemModel

返回此项目所属的QStandardItemModel。

如果该项目不属于模型的另一个项目的子项，此函数返回 None。

另请参阅

index()

multiData(roleDataSpan)
Parameters:

roleDataSpan – QModelRoleDataSpan

用此项目的数据填充roleDataSpan span。

默认实现只是为span中的每个角色调用data()。

另请参阅

data()

__lt__(other)
Parameters:

其他 – QStandardItem

Return type:

布尔

如果此项小于 other，则返回 true；否则返回 false。

默认实现使用项目的排序角色数据（参见sortRole）来执行比较，如果项目属于模型；否则，使用项目的Qt::DisplayRole（text()）数据来执行比较。

sortChildren() 和 sort() 在排序项目时使用此函数。如果您想要自定义排序，可以子类化 QStandardItem 并重新实现此函数。

parent()
Return type:

QStandardItem

返回项目的父项目，如果项目没有父项目，则返回None。

注意

对于顶级项目，parent() 返回 None。要获取顶级项目的父级，请使用 invisibleRootItem() 代替。

另请参阅

child() invisibleRootItem()

read(in)
Parameters:

in – QDataStream

从流 in 中读取项目。只读取项目的数据和标志，不读取子项目。

另请参阅

write()

removeColumn(column)
Parameters:

列 – int

移除给定的column。列中的项目将被删除。

removeColumns(column, count)
Parameters:

  • column – 整数

  • count – int

移除位于列 column 的 count 列。这些列中的项目将被删除。

removeRow(row)
Parameters:

行 – 整数

移除给定的row。该行中的项目将被删除。

removeRows(row, count)
Parameters:

  • row – int

  • count – int

移除第 row 行的 count 行。这些行中的项目将被删除。

row()
Return type:

整数

返回项目在其父级的子表中的行位置，如果项目没有父级，则返回-1。

另请参阅

column() parent()

rowCount()
Return type:

整数

返回项目具有的子项目行数。

setAccessibleDescription(accessibleDescription)
Parameters:

accessibleDescription – str

将项目的可访问描述设置为由accessibleDescription指定的字符串。

可访问的描述由辅助技术使用（即对于无法使用传统交互方式的用户）。

setAccessibleText(accessibleText)
Parameters:

accessibleText – str

将项目的可访问文本设置为由accessibleText指定的字符串。

可访问文本由辅助技术使用（即对于无法使用传统交互方式的用户）。

setAutoTristate(tristate)
Parameters:

tristate – 布尔值

确定项目是三态的，并且如果tristate为true，则由QTreeWidget控制。这使得QTreeWidget中父项的状态能够自动管理（如果所有子项都被选中，则选中；如果所有子项都未选中，则未选中；或者如果只有部分子项被选中，则部分选中）。

setBackground(brush)
Parameters:

画笔 – QBrush

将项目的背景画笔设置为指定的 brush。

setCheckState(checkState)
Parameters:

checkState – CheckState

将项目的检查状态设置为 state。

setCheckable(checkable)
Parameters:

checkable – 布尔值

设置项目是否可由用户勾选。如果checkable为true，用户可以选择勾选该项目；否则，用户不能勾选该项目。

项目委托将呈现一个可勾选的项目，项目文本旁边有一个复选框。

setChild(row, item)
Parameters:

这是一个重载函数。

将row处的子项设置为item。

setChild(row, column, item)
Parameters:

将子项设置在(row, column)位置为item。此项目（父项目）将拥有item的所有权。如果需要，行数和列数将增加以适应项目。

注意

将 None 作为 item 传递会移除该项。

另请参阅

child()

setColumnCount(columns)
Parameters:

columns – int

设置子项列数为columns。如果此值小于columnCount()，则不需要的列中的数据将被丢弃。

setData(value[, role=Qt.UserRole + 1])
Parameters:

  • value – 对象

  • role – int

将项目的role数据设置为指定的value。

如果你子类化 QStandardItem 并重新实现此函数，你的重新实现应该：

  • 如果你没有调用setData()的基本实现，请调用emitDataChanged()。这将确保使用模型的视图能够收到更改的通知

  • 对于你不处理的角色，调用基础实现，否则设置标志，例如通过调用setFlags()、setCheckable()、setEditable()等，将无法工作。

注意

默认实现将Qt::EditRole和Qt::DisplayRole视为引用相同的数据。

另请参阅

data() setFlags()

setDragEnabled(dragEnabled)
Parameters:

dragEnabled – 布尔值

设置项目是否启用拖动。如果dragEnabled为true，用户可以拖动项目；否则，用户无法拖动项目。

请注意，您还需要确保在视图中启用了项目拖动功能；请参阅 QAbstractItemView::dragEnabled。

setDropEnabled(dropEnabled)
Parameters:

dropEnabled – 布尔值

设置项目是否启用拖放功能。如果dropEnabled为true，则该项目可以用作拖放目标；否则，不能。

请注意，您还需要确保视图中启用了拖放功能；参见 QWidget::acceptDrops()；并且模型支持所需的拖放操作；参见 QAbstractItemModel::supportedDropActions()。

setEditable(editable)
Parameters:

editable – 布尔值

设置项目是否可编辑。如果editable为true，用户可以编辑该项目；否则，用户无法编辑该项目。

用户如何编辑视图中的项目由视图的编辑触发器决定；请参阅 QAbstractItemView::editTriggers。

另请参阅

isEditable() setFlags()

setEnabled(enabled)
Parameters:

enabled – 布尔值

设置项目是否启用。如果enabled为true，则项目启用，意味着用户可以与该项目进行交互；如果enabled为false，则用户无法与该项目进行交互。

此标志优先于其他项目标志；例如，如果项目未启用，即使设置了Qt::ItemIsSelectable标志，用户也无法选择它。

另请参阅

isEnabled() setFlags()

setFlags(flags)
Parameters:

flags – ItemFlag 的组合

将项目的标志设置为flags。

项目标志决定了用户如何与项目进行交互。这通常用于禁用项目。

另请参阅

flags() setData()

setFont(font)
Parameters:

字体 – QFont

将用于显示项目文本的字体设置为给定的font。

setForeground(brush)
Parameters:

画笔 – QBrush

设置用于显示项目前景（例如文本）的画笔为给定的 brush。

setIcon(icon)
Parameters:

图标 – QIcon

将项目的图标设置为指定的icon。

另请参阅

icon()

setRowCount(rows)
Parameters:

行数 – int

设置子项行的数量为rows。如果这个值小于rowCount()，则不需要的行中的数据将被丢弃。

setSelectable(selectable)
Parameters:

selectable – 布尔值

设置项目是否可选。如果selectable为true，用户可以选择该项目；否则，用户无法选择该项目。

您可以通过操作它们的视图属性来控制选择行为和模式；请参阅 QAbstractItemView::selectionMode 和 QAbstractItemView::selectionBehavior。

另请参阅

isSelectable() setFlags()

setSizeHint(sizeHint)
Parameters:

sizeHint – QSize

设置项目的大小提示为size。如果没有设置大小提示，项目委托将根据项目数据计算大小提示。

另请参阅

sizeHint()

setStatusTip(statusTip)
Parameters:

statusTip – str

将项目的状态提示设置为由statusTip指定的字符串。

setText(text)
Parameters:

文本 – str

将项目的文本设置为指定的text。

setTextAlignment(textAlignment)
Parameters:

textAlignment – AlignmentFlag 的组合

将项目的文本对齐方式设置为指定的alignment。

另请参阅

textAlignment()

setToolTip(toolTip)
Parameters:

toolTip – str

将项目的工具提示设置为由toolTip指定的字符串。

setUserTristate(tristate)
Parameters:

tristate – 布尔值

设置项目是否为三态并由用户控制。如果tristate为真，用户可以循环切换三个独立的状态；否则，项目可检查且有两种状态。（请注意，这也要求项目是可检查的；参见isCheckable()。）

setWhatsThis(whatsThis)
Parameters:

whatsThis – str

将项目的“这是什么？”帮助设置为由whatsThis指定的字符串。

sizeHint()
Return type:

QSize

返回为项目设置的大小提示，如果未设置大小提示，则返回无效的QSize。

如果没有设置大小提示，项目委托将根据项目数据计算大小提示。

另请参阅

setSizeHint()

sortChildren(column[, order=Qt.AscendingOrder])
Parameters:

使用给定的order，按给定column中的值对项目的子项进行排序。

注意

这个函数是递归的，因此它会排序项目的子项、孙项等。

另请参阅

operator

statusTip()
Return type:

字符串

返回项目的状态提示。

takeChild(row[, column=0])
Parameters:

  • row – int

  • column – 整数

Return type:

QStandardItem

移除位于(row, column)的子项而不删除它，并返回指向该项目的指针。如果在给定位置没有子项，则此函数返回None。

请注意，此函数与takeRow()和takeColumn()不同，不会影响子表的维度。

takeColumn(column)
Parameters:

列 – int

Return type:

QStandardItem的列表

移除column而不删除列项，并返回指向移除项的指针列表。对于列中未设置的项，列表中的相应指针将为None。

takeRow(row)
Parameters:

行 – 整数

Return type:

QStandardItem的列表

移除row而不删除行项目，并返回指向被移除项目的指针列表。对于行中未设置的项目，列表中的相应指针将为None。

text()
Return type:

字符串

返回项目的文本。这是在视图中呈现给用户的文本。

另请参阅

setText()

textAlignment()
Return type:

AlignmentFlag 的组合

返回项目文本的文本对齐方式。

另请参阅

setTextAlignment()

toolTip()
Return type:

字符串

返回项目的工具提示。

type()
Return type:

整数

返回此项目的类型。该类型用于区分自定义项目和基类。当子类化 QStandardItem 时，您应该重新实现此函数并返回一个大于或等于 UserType 的新值。

另请参阅

类型

whatsThis()
Return type:

字符串

返回项目的“这是什么？”帮助。

write(out)
Parameters:

输出 – QDataStream

将项目写入流 out。只写入项目的数据和标志，不包括子项目。

另请参阅

read()