class QComboBox#

控件QComboBox结合了按钮和下拉列表功能。更多...

Inheritance diagram of PySide6.QtWidgets.QComboBox

继承： QFontComboBox

概要#

属性#

方法#

虚拟方法#

槽函数#

信号#

注意#

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

详细描述#

collapsed_combobox1

折叠的QCombobox

expanded_combobox2

展开的QCombobox

显示功能#

QComboBox是以紧凑方式向用户展示选项列表的一种方式。

组合框是一个选择小部件，显示当前项，并在点击时弹出一个可选择的项列表。如果insertItem()和setItemText()函数适当重载，组合框可以包含图片以及字符串。

编辑功能#

组合框可能是可编辑的，允许用户修改列表中的每个项目。对于可编辑的组合框，提供clearEditText()函数，用于清除显示的字符串，但不更改组合框的内容。

当用户在一个可编辑的组合框中输入新的字符串时，该控件可能会插入或者不插入这个字符串，并且可以在多个位置插入。默认策略是 InsertAtBottom，但您可以使用 setInsertPolicy() 来更改这个策略。

您可以使用 QValidator 来约束可编辑组合框的输入；请参阅 setValidator()。默认情况下，接受任何输入。

可以使用插入函数（如 insertItem() 和 insertItems()）来填充组合框。可以使用 setItemText() 来更改项目。可以使用 removeItem() 来移除一个项目，并使用 clear() 来移除所有项目。当前项的文本由 currentText() 返回，编号项的文本通过 text() 返回。使用 setCurrentIndex() 可以设置当前项。组合框中项目的数量由 count() 返回；可以设置最大项目数量为 setMaxCount()。您可以通过 setEditable() 允许编辑。对于可编辑组合框，您可以使用 setCompleter() 来设置自动完成，并使用 setDuplicatesEnabled() 来设置用户是否可以添加重复的条目。

信号#

当组合框的当前项发生变化时，会发出三个信号：currentIndexChanged()，currentTextChanged()，和 activated() 。无论变化是由编程实现还是用户交互引起的，currentIndexChanged() 和 currentTextChanged() 总是会发出，而 activated() 仅当变化由用户交互引起时发出。当用户在组合框的下拉列表中选择或高亮显示项时，会发出 highlighted() 信号。所有三个信号都存在两种版本，一种带有 QString 参数，另一种带有 int 参数。如果用户选择或高亮显示位图，只有 int 信号会发出。当可编辑组合框的文本改变时，会发出 editTextChanged() 信号。

模型/视图框架#

QComboBox 使用 模型/视图框架 来显示其弹出列表并存储其项。默认情况下，QStandardItemModel 存储项，一个 QListView 子类用于显示弹出列表。您可以直接访问模型和视图（使用 model() 和 view() ），但 QComboBox 还提供了设置和获取项数据的功能，例如 setItemData() 和 itemText() 。您还可以设置新的模型和视图（使用 setModel() 和 setView() ）。组合框标签中的文本和图标使用具有 Qt::DisplayRole 和 Qt::DecorationRole 的模型中的数据。

注意#

您不能更改SelectionMode，例如，不能通过使用setSelectionMode() 来改变视图的view()。

另请参阅

QLineEdit QSpinBox QRadioButton QButtonGroup

class InsertPolicy#

枚举用于指定当用户输入一个新字符串时，QComboBox应执行的操作。

常量

描述

QComboBox.NoInsert

该字符串不会被插入到组合框中。

QComboBox.InsertAtTop

该字符串将被插入到组合框的第一个项目。

QComboBox.InsertAtCurrent

当前项目将被字符串所替换。

QComboBox.InsertAtBottom

字符串将被插入到组合框的最后一个项目之后。

QComboBox.InsertAfterCurrent

字符串将被插入到组合框的当前项目之后。

QComboBox.InsertBeforeCurrent

字符串将被插入到组合框的当前项目之前。

QComboBox.InsertAlphabetically

字符串将以字母顺序插入到组合框中。
class SizeAdjustPolicy#

枚举指定当添加或更改内容时，QComboBox的大小提示应如何调整。

常量

描述

QComboBox.AdjustToContents

组合框将始终调整到内容。

QComboBox.AdjustToContentsOnFirstShow

组合框将第一次显示时调整到其内容。

QComboBox.AdjustToMinimumContentsLengthWithIcon

组合框将调整到minimumContentsLength 加上图标的空间。出于性能考虑，在大型模型上使用此策略。

注意#

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

property countʹ: int#

此属性包含组合框中的项目数量。

默认情况下，对于空组合框，此属性值默认为0。

访问函数
属性 currentData: object#

该属性持有当前项的数据。

默认情况下，对于一个空的下拉框或未设置当前项的下拉框，该属性包含一个无效的QVariant。

访问函数
属性 currentIndex: int#

该属性持有组合框中当前项的索引。

当插入或删除项时，当前索引可能会改变。

默认情况下，对于一个空的下拉框或未设置当前项的下拉框，该属性值为-1。

访问函数
属性 currentText: str#

该属性持有当前文本。

如果组合框是可编辑的，则当前文本是行编辑器显示的值。否则，它是当前项的值，或者如果组合框为空或未设置当前项，则为空字符串。

如果组合框是可编辑的，则setCurrentText()方法将简单调用setEditText。否则，如果列表中有匹配的文本，则currentIndex被设置为相应的索引。

另请参阅

editable setEditText

访问函数
属性 duplicatesEnabled: bool#

该属性表明用户是否可以将重复项输入到组合框中。

请注意，始终可以通过程序在组合框中插入重复项。

默认情况下，该属性为false（不允许重复）。

访问函数
属性 editable: bool#

该属性表明组合框是否可以由用户编辑。

默认情况下，该属性为false。编辑的效果取决于插入策略。

注意#

当禁用 editable 状态时，验证器和补全器将被移除。

另请参阅

插入策略

访问函数
属性 frame honored:布尔值#

此属性保存组合框是否以框架形式绘制自身。

如果启用（默认值），组合框将在框架内部绘制自身，否则组合框将不带任何框架绘制自身。

访问函数
属性 iconSize honored:QSize#

此属性保存组合框中显示的图标的大小。

除非显式设置，否则返回当前样式的默认值。此大小是图标可以具有的最大尺寸；较小尺寸的图标不会被放大。

访问函数
属性 insertPolicy honored:QComboBox.InsertPolicy#

此属性保存用于确定用户插入项应在组合框中显示位置的策略。

默认值是 InsertAtBottom ，表示新项目将出现在项目列表的底部。

另请参阅

插入策略

访问函数
属性 maxCount honored:整数#

此属性保存组合框允许的最大项目数。

注意#

如果您将最大数量设置为小于组合框中当前项目的数量，则将截断额外的项目。如果已在组合框上设置了外部模型，这也适用。

默认情况下，此属性值来源于可用的最高有符号整数（通常是 2147483647）。

访问函数
属性 maxVisibleItems honored:整数#

此属性保存组合框在屏幕上允许的最大允许大小，以项计数。

默认情况下，此属性值为 10。

注意#

对于在 SH_ComboBox_Popup 返回 true 的样式中（如 Mac 样式或 Gtk+ 样式）的非可编辑组合框，忽略此属性。

访问函数
属性 minimumContentsLength honored:整数#

此属性保存应适合组合框中的最小字符数。

默认值为0。

如果将此属性设置为正值，则minimumSizeHint()和sizeHint()会将其考虑在内。

另请参阅

尺寸调整策略

访问函数
属性modelColumn: int#

此属性表示模型中可见的列。

如果在进行组合框数据填充之前设置，弹出视图将不受影响，并显示第一列（使用此属性的默认值）。

默认情况下，此属性值为0。

注意#

在可编辑的组合框中，可见列也将成为completion column。

访问函数
属性placeholderText: str#

此属性用于设置在没有设置有效索引时显示的占位文本。

当设置无效索引时，会显示placeholderText。文本在下拉列表中不可用。当在添加条目之前调用此函数时将显示占位文本，否则如果您想显示占位文本，请通过程序调用setCurrentIndex (-1)。要将占位文本重置为空，设置一个空的占位文本。

当QComboBox可编辑时，请使用setPlaceholderText()代替。

访问函数
属性sizeAdjustPolicy: QComboBox.SizeAdjustPolicy#

此属性表示描述组合框大小如何随内容变化而变化的策略。

默认值是AdjustToContentsOnFirstShow。

另请参阅

SizeAdjustPolicy

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

parent – QWidget

使用给定的parent构建组合框，使用默认模型QStandardItemModel。

activated(index)#
参数

index – int

当用户在组合框中选择一个项目时，会发送此信号。传入项目的 index。注意，即使选择没有变化，此信号也会发送。如果您需要知道选择实际何时变化，请使用信号 currentIndexChanged() 或 currentTextChanged()。

addItem(text[, userData=None])#
参数

  • text – str

  • userData – object

使用给定的 text 将项目添加到组合框中，并包含指定的 userData（存储在 Qt::UserRole 中）。该项目将被追加到现有项目列表中。

addItem(icon, text[, userData=None])
参数

  • icon – QIcon

  • text – str

  • userData – object

使用给定的 icon 和 text 将项目添加到组合框中，并包含指定的 userData（存储在 Qt::UserRole 中）。该项目将被追加到现有项目列表中。

addItems(texts)#
参数

texts – 字符串列表

将给定 texts 中的每个字符串添加到组合框中。每个项目将依次追加到现有项目列表中。

clear()#

清除组合框，移除所有项目。

注意：如果您已在外部模型上设置了组合框，则在调用此函数时，此模型也将被清除。

clearEditText()#

清除用于组合框编辑的行编辑内容。

completer()#
返回类型：:

QCompleter

返回用于自动完成组合框文本输入的补全器。

另请参阅

setCompleter() editable

count()#
返回类型：:

int

属性 countᅟ 的获取器。

currentData([role=Qt.UserRole])#
参数

role – int

返回类型：:

对象

currentIndex()#
返回类型：:

int

另请参阅

setCurrentIndex()

属性 currentIndexᅟ 的获取器。

currentIndexChanged(index)#
参数

index – int

当组合框中的 currentIndex 改变时（无论通过用户交互还是程序性操作），都会发出此信号。传递了项的 index，如果组合框变空或 currentIndex 被重置，则传递 -1。

currentIndexᅟ 属性的通知信号。

currentText()#
返回类型：:

str

另请参阅

setCurrentText()

属性 currentTextᅟ 的获取器。

currentTextChanged(arg__1)#
参数

arg__1 – str

每当 currentText 发生变化时，都会发出此信号。新值作为 text 传递。

注意#

如果 currentText 仍然相同，即使 currentIndex 发生了变化，则不会发出。

currentTextᅟ 属性的通知信号。

duplicatesEnabled()#
返回类型：:

bool

另请参阅

setDuplicatesEnabled()

属性 duplicatesEnabledᅟ 的获取器。

editTextChanged(arg__1)#
参数

arg__1 – str

当组合框的行编辑部件中的文本发生变化时，会发出此信号。新的文本由 text 指定。

findData(data[, role=Qt.UserRole[, flags=static_cast<Qt.MatchFlags>(Qt.MatchExactly|Qt.MatchCaseSensitive)]])#
参数

  • data – 对象

  • role – int

  • flags – MatchFlag 的组合

返回类型：:

int

返回包含给定 data 和给定 role 的项目的索引；否则返回 -1。

flags 指定如何搜索组合框中的项。

findText(text[, flags=static_cast<Qt.MatchFlags>(Qt.MatchExactly|Qt.MatchCaseSensitive)])#
参数
返回类型：:

int

返回包含给定 text 的项的索引；否则返回 -1。

flags 指定如何搜索组合框中的项。

hasFrame()#
返回类型：:

bool

属性 frame 的获取器。

hidePopup()#

当组合框中的物品列表当前可见时，隐藏该列表并重置内部状态，这样如果自定义弹出窗口在重新实现的 showPopup() 内显示，那么还需要重新实现 hidePopup() 函数来隐藏您的自定义弹出窗口，并在您的自定义弹出窗口小部件被隐藏时调用基类的实现来重置内部状态。

另请参阅

showPopup()

highlighted(index)#
参数

index – int

当用户通过鼠标或键盘渲染焦点到组合框弹出列表中的项时，会发出此信号。项的 index 被传递。

iconSize()#
返回类型：:

QSize

另请参阅

setIconSize()

属性 iconSize 的获取器。

initStyleOption(option)#
参数

option – QStyleOptionComboBox

使用此 QComboBox 的值初始化 option 。该方法对于子类非常有用，当它们需要一个 QStyleOptionComboBox 但不想自己填写所有信息时。

另请参阅

initFrom()

inputMethodQuery(query, argument)#
参数
返回类型：:

对象

insertItem(index, icon, text[, userData=None])#
参数

  • index – int

  • icon – QIcon

  • text – str

  • userData – object

将 icon、text 和 userData（存储在 Qt::UserRole 中）插入到给定 index 的 Combobox 中。

如果索引等于或高于项目总数，则新项目将追加到现有项目的列表中。如果索引为零或负值，则新项目将插入到现有项目的列表前面。

另请参阅

insertItems()

insertItem(index, text[, userData=None])
参数

  • index – int

  • text – str

  • userData – object

将 text 和 userData（存储在 Qt::UserRole 中）插入到给定 index 的 Combobox 中。

如果索引等于或高于项目总数，则新项目将追加到现有项目的列表中。如果索引为零或负值，则新项目将插入到现有项目的列表前面。

另请参阅

insertItems()

insertItems(index, texts)#
参数

  • index – int

  • texts – 字符串列表

从 list 中插入字符串到 Combobox 中，作为单独的项目，从指定的 index 开始。

如果索引等于或高于项目总数，则新项目将被追加到现有项目的列表中。如果索引为零或负值，则新项目将被插入到现有项目的列表前面。

另请参阅

insertItem()

insertPolicy()#
返回类型：:

插入策略

另请参阅

setInsertPolicy()

属性 insertPolicy 的获取器。

insertSeparator(index)#
参数

index – int

在给定位置 index 的 combobox 中插入分隔符项。

如果索引等于或高于项目总数，则新项目将追加到现有项目的列表中。如果索引为零或负值，则新项目将插入到现有项目的列表前面。

另请参阅

insertItem()

isEditable()#
返回类型：:

bool

属性 editableᅟ 的获取器。

itemData(index[, role=Qt.UserRole])#
参数

  • index – int

  • role – int

返回类型：:

对象

返回 combobox 中指定 index 在给定 role 的数据，如果没有此角色的数据，则返回无效的 QVariant。

另请参阅

setItemData()

itemDelegate()#
返回类型：:

QAbstractItemDelegate

返回弹出的列表视图使用的项目委托。

另请参阅

setItemDelegate()

itemIcon(index)#
参数

index – int

返回类型：:

QIcon

返回 combobox 中指定 index 的图标。

另请参阅

setItemIcon()

itemText(index)#
参数

index – int

返回类型：:

str

返回 combobox 中指定 index 的文本。

另请参阅

setItemText()

lineEdit()#
返回类型：:

QLineEdit

返回用于编辑 combobox 项的行编辑器，如果没有行编辑器则返回 None。

只有可编辑的 combobox 才有行编辑器。

另请参阅

setLineEdit()

maxCount()#
返回类型：:

int

另请参阅

setMaxCount()

属性 maxCountᅟ 的获取器。

maxVisibleItems()#
返回类型：:

int

另请参阅

setMaxVisibleItems()

属性 maxVisibleItemsᅟ 的获取器。

minimumContentsLength()#
返回类型：:

int

另请参阅

setMinimumContentsLength()

属性 minimumContentsLengthᅟ 的获取器。

model()#
返回类型：:

QAbstractItemModel

返回 combobox 使用的模型。

另请参阅

setModel()

modelColumn()#
返回类型：:

int

另请参阅

setModelColumn()

属性 modelColumnᅟ 的获取器。

placeholderText()#
返回类型：:

str

另请参阅

setPlaceholderText()

属性 placeholderText 的获取器。

removeItem(index)#
参数

index – int

从组合框中移除指定 index 的项。如果移除的索引是当前的索引，则会更新当前索引。

如果 index 超出范围，此函数不会执行任何操作。

rootModelIndex()#
返回类型：:

QModelIndex

返回组合框中项的根模型项索引。

另请参阅

setRootModelIndex()

setCompleter(c)#
参数

c – QCompleter

设置要使用的 completer 替代当前的自完成器。如果 completer 是 None，则禁用自动完成。

默认情况下，对于可编辑的组合框，将自动创建一个执行不区分大小写的逐行完成的 QCompleter。

注意#

当 editable 属性变为 false 或当行编辑被调用某个函数（如 setLineEdit()）所替代时，将移除自完成器。

另请参阅

completer()

setCurrentIndex(index)#
参数

index – int

另请参阅

currentIndex()

属性 currentIndex 的设置器。

setCurrentText(text)#
参数

text – str

另请参阅

currentText()

属性 currentText 的设置器。

setDuplicatesEnabled(enable)#
参数

enable – bool

另请参阅

duplicatesEnabled()

属性 duplicatesEnabledµ 的设置器。

setEditText(text)#
参数

text – str

设置组合框的文本编辑器中的 text。

setEditable(editable)#
参数

editable – bool

另请参阅

isEditable()

属性 editableµ 的设置器。

setFrame(arg__1)#
参数

arg__1 – bool

另请参阅

hasFrame()

属性 frameµ 的设置器。

setIconSize(size)#
参数

size – QSize

另请参阅

iconSize()

属性 iconSizeµ 的设置器。

setInsertPolicy(policy)#
参数

policy – InsertPolicy

另请参阅

insertPolicy()

属性 insertPolicyµ 的设置器。

setItemData(index, value[, role=Qt.UserRole])#
参数

  • index – int

  • value – object

  • role – int

将组合框中指定 index 位置的项的 role 数据设置为指定的 value。

另请参阅

itemData()

setItemDelegate(delegate)#
参数

delegate – QAbstractItemDelegate

设置弹出列表视图的项 delegate。组合框将接管委托的所有权。

现有代理对象将被移除，但不会删除。 QComboBox 不负责 delegate 的所有权。

警告

请勿在组合框、小部件映射器或视图中共享相同的代理对象实例。这样做可能会导致编辑行为不正确或不可预测，因为连接到特定代理的每个视图都可能接收到 closeEditor() 信号，并尝试访问、修改或关闭已关闭的编辑器。

另请参阅

itemDelegate()

setItemIcon(index, icon)#
参数

  • index – int

  • icon – QIcon

为组合框中给定 index 的项设置图标。

另请参阅

itemIcon()

setItemText(index, text)#
参数

  • index – int

  • text – str

为组合框中给定 index 的项设置文本。

另请参阅

itemText()

setLineEdit(edit)#
参数

edit – QLineEdit

将行 edit 设置为替代当前行编辑小部件。

组合框负责行编辑的所有权。

注意#

由于组合框的行编辑拥有 QCompleter ，任何之前的 setCompleter() 调用将不再有任何效果。

另请参阅

lineEdit()

setMaxCount(max)#
参数

max – int

另请参阅

maxCount()

maxCount 属性的设置器。

setMaxVisibleItems(maxItems)#
参数

maxItems – int

另请参阅

maxVisibleItems()

maxVisibleItems 属性的设置器。

setMinimumContentsLength(characters)#
参数

characters – int

另请参阅

minimumContentsLength()

minimumContentsLength 属性的设置器。

setModel(model)#
参数

model – QAbstractItemModel

设置模型为 model。 model 不能为 None。如果您想清除模型的内容，请调用 clear()。

注意#

如果组合框是可编辑的，则 model 也会设置为行编辑的完成器。

另请参阅

model() clear() setCompleter()

setModelColumn(visibleColumn)#
参数

visibleColumn – int

另请参阅

modelColumn()

属性 modelColumnᅟ 的设置器。

setPlaceholderText(placeholderText)#
参数

placeholderText – str

另请参阅

placeholderText()

属性 placeholderTextᅟ 的设置器。

setRootModelIndex(index)#
参数

index – QModelIndex

为组合框中的项设置根模型项 index。

另请参阅

rootModelIndex()

setSizeAdjustPolicy(policy)#
参数

policy – SizeAdjustPolicy

另请参阅

sizeAdjustPolicy()

属性 sizeAdjustPolicyᅟ 的设置器。

setValidator(v)#
参数

v – QValidator

将 validator 设置为当前验证器替代。

注意#

当 editable 属性变为 false 时，验证器将被移除。

另请参阅

validator()

setView(itemView)#
参数

itemView – QAbstractItemView

将用于组合框弹出窗口的视图设置为给定的 itemView。组合框将获得视图的所有权。

注意：如果您想使用方便的视图（如 QListWidget ， QTableWidget 或 QTreeWidget ），请确保在调用此函数之前在组合框上调用 setModel() 并带上方便小部件模型。

另请参阅

view()

showPopup()#

显示组合框中的项目列表。如果列表为空，则不会显示任何项。

如果您重新实现了此函数以显示自定义弹出窗口，请确保调用 hidePopup() 以重置内部状态。

另请参阅

hidePopup()

sizeAdjustPolicy()#
返回类型：:

SizeAdjustPolicy

另请参阅

setSizeAdjustPolicy()

属性 sizeAdjustPolicyᅟ 的获取器。

textActivated(arg__1)#
参数

arg__1 – str

当用户在组合框中选中一个项目时，发送此信号。传递了项目的 text。注意，即使选择没有改变，也会发送此信号。如果需要知道选择实际改变时，请使用信号 currentIndexChanged() 或 currentTextChanged() 。

textHighlighted(arg__1)#
参数

arg__1 – str

当用户突出显示组合框弹出列表中的项目时，发送此信号。传递了项目的 text。

validator()#
返回类型：:

QValidator

返回用于约束组合框文本输入的验证器。

另请参阅

setValidator() editable

view()#
返回类型：:

QAbstractItemView

返回用于组合框弹出窗口的列表视图。

另请参阅

setView()