PySide6.QtWidgets.QComboBox

class QComboBox

QComboBox 小部件将按钮与下拉列表结合在一起。更多…

PySide6.QtWidgets.QComboBox 的继承图

继承者： QFontComboBox

概要

属性

方法

虚拟方法

插槽

信号

注意

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

详细描述

expanded_combobox2

折叠的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 参数。如果用户选择或高亮了一个 pixmap，则只发出 int 信号。每当可编辑组合框的文本发生变化时，editTextChanged() 信号就会发出。

模型/视图框架

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

注意

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

另请参阅

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。

Access functions:
property currentDataᅟ: object

此属性保存当前项目的数据。

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

Access functions:
property currentIndexᅟ: int

此属性保存组合框中当前项目的索引。

当前索引在插入或删除项目时可能会发生变化。

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

Access functions:
property currentTextᅟ: str

此属性保存当前文本。

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

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

另请参阅

editable setEditText()

Access functions:
property duplicatesEnabledᅟ: bool

此属性决定用户是否可以在组合框中输入重复项。

请注意，始终可以通过编程方式将重复项插入到组合框中。

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

Access functions:
property editableᅟ: bool

此属性保存组合框是否可由用户编辑。

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

注意

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

另请参阅

InsertPolicy

Access functions:
property frameᅟ: bool

此属性保存组合框是否绘制带有边框的自身。

如果启用（默认情况下），组合框会在框架内绘制自身，否则组合框会在没有任何框架的情况下绘制自身。

Access functions:
property iconSizeᅟ: QSize

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

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

Access functions:
property insertPolicyᅟ: QComboBox.InsertPolicy

此属性用于确定用户插入的项目应出现在组合框中的策略。

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

另请参阅

InsertPolicy

Access functions:
property maxCountᅟ: int

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

注意

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

默认情况下，此属性的值源自可用的最大有符号整数（通常为2147483647）。

Access functions:
property maxVisibleItemsᅟ: int

此属性保存组合框在屏幕上允许的最大尺寸，以项目为单位测量。

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

注意

对于在样式返回SH_ComboBox_Popup为true的情况下，例如Mac风格或Gtk+风格，此属性对于不可编辑的组合框将被忽略。

Access functions:
property minimumContentsLengthᅟ: int

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

默认值为0。

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

另请参阅

sizeAdjustPolicy

Access functions:
property modelColumnᅟ: int

此属性保存模型中可见的列。

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

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

注意

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

Access functions:
property placeholderTextᅟ: str

此属性设置当未设置有效索引时显示的placeholderText文本。

当设置了一个无效的索引时，placeholderText 将会显示。该文本在下拉列表中不可访问。如果在添加项目之前调用此函数，占位符文本将会显示，否则如果你想显示占位符文本，你必须以编程方式调用 setCurrentIndex (-1)。设置一个空的占位符文本以重置设置。

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

Access functions:
property sizeAdjustPolicyᅟ: QComboBox.SizeAdjustPolicy

此属性保存描述组合框大小在内容更改时如何更改的策略。

默认值为 AdjustToContentsOnFirstShow 。

另请参阅

SizeAdjustPolicy

Access functions:
__init__([parent=None])
Parameters:

父级 – QWidget

使用默认模型 QStandardItemModel 构造一个带有给定 parent 的组合框。

activated(index)
Parameters:

索引 – int

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

addItem(text[, userData=None])
Parameters:

  • 文本 – str

  • userData – 对象

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

addItem(icon, text[, userData=None])
Parameters:

  • 图标 – QIcon

  • 文本 – str

  • userData – 对象

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

addItems(texts)
Parameters:

文本 – 字符串列表

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

clear()

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

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

clearEditText()

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

completer()
Return type:

QCompleter

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

另请参阅

setCompleter() 可编辑

count()
Return type:

整数

属性 countᅟ 的获取器。

currentData([role=Qt.UserRole])
Parameters:

角色 – int

Return type:

对象

currentIndex()
Return type:

整数

另请参阅

setCurrentIndex()

属性 currentIndexᅟ 的获取器。

currentIndexChanged(index)
Parameters:

索引 – int

每当组合框中的currentIndex通过用户交互或编程方式更改时，都会发送此信号。项目的index会被传递，如果组合框变为空或currentIndex被重置，则传递-1。

属性 currentIndexᅟ 的通知信号。

currentText()
Return type:

字符串

另请参阅

setCurrentText()

属性 currentTextᅟ 的获取器。

currentTextChanged(text)
Parameters:

文本 – str

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

注意

如果currentText保持不变，即使currentIndex发生变化，也不会发出。

属性 currentTextᅟ 的通知信号。

duplicatesEnabled()
Return type:

布尔

另请参阅

setDuplicatesEnabled()

属性 duplicatesEnabledᅟ 的获取器。

editTextChanged(text)
Parameters:

文本 – str

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

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

  • data – 对象

  • role – int

  • flags – MatchFlag 的组合

Return type:

整数

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

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

findText(text[, flags=static_cast<Qt.MatchFlags>(Qt.MatchExactly|Qt.MatchCaseSensitive)])
Parameters:

  • 文本 – str

  • flags – MatchFlag 的组合

Return type:

整数

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

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

hasFrame()
Return type:

布尔

属性 frameᅟ 的获取器。

hidePopup()

如果当前可见，则隐藏组合框中的项目列表并重置内部状态，因此如果在重新实现的showPopup()中显示了自定义弹出窗口，则还需要重新实现hidePopup()函数以隐藏自定义弹出窗口，并在自定义弹出窗口小部件隐藏时调用基类实现以重置内部状态。

另请参阅

showPopup()

highlighted(index)
Parameters:

索引 – int

当用户在组合框弹出列表中高亮显示一个项目时，会发送此信号。项目的index会被传递。

iconSize()
Return type:

QSize

另请参阅

setIconSize()

属性 iconSizeᅟ 的获取器。

initStyleOption(option)
Parameters:

选项 – QStyleOptionComboBox

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

另请参阅

initFrom()

inputMethodQuery(query, argument)
Parameters:
Return type:

对象

insertItem(index, text[, userData=None])
Parameters:

  • index – 整数

  • 文本 – str

  • userData – 对象

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

如果索引等于或高于项目总数，新项目将附加到现有项目列表中。如果索引为零或负数，新项目将前置到现有项目列表中。

另请参阅

insertItems()

insertItem(index, icon, text[, userData=None])
Parameters:

  • index – 整数

  • 图标 – QIcon

  • 文本 – str

  • userData – 对象

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

如果索引等于或高于项目总数，则新项目将附加到现有项目列表中。如果索引为零或负数，则新项目将前置到现有项目列表中。

另请参阅

insertItems()

insertItems(index, texts)
Parameters:

  • index – 整数

  • texts – 字符串列表

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

如果索引等于或高于项目总数，新项目将附加到现有项目列表中。如果索引为零或负数，新项目将前置到现有项目列表中。

另请参阅

insertItem()

insertPolicy()
Return type:

InsertPolicy

另请参阅

setInsertPolicy()

属性 insertPolicyᅟ 的获取器。

insertSeparator(index)
Parameters:

索引 – int

在给定的index处将分隔符项插入组合框中。

如果索引等于或高于项目总数，则新项目将附加到现有项目列表中。如果索引为零或负数，则新项目将前置到现有项目列表中。

另请参阅

insertItem()

isEditable()
Return type:

布尔

属性 editableᅟ 的获取器。

itemData(index[, role=Qt.UserRole])
Parameters:

  • index – 整数

  • role – int

Return type:

对象

返回组合框中给定index的role的数据，如果没有此角色的数据，则返回无效的QVariant。

另请参阅

setItemData()

itemDelegate()
Return type:

QAbstractItemDelegate

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

另请参阅

setItemDelegate()

itemIcon(index)
Parameters:

索引 – int

Return type:

QIcon

返回组合框中给定index的图标。

另请参阅

setItemIcon()

itemText(index)
Parameters:

索引 – int

Return type:

字符串

返回组合框中给定index的文本。

另请参阅

setItemText()

lineEdit()
Return type:

QLineEdit

返回用于在组合框中编辑项目的行编辑器，如果没有行编辑器则返回None。

只有可编辑的组合框才有行编辑。

另请参阅

setLineEdit()

maxCount()
Return type:

整数

另请参阅

setMaxCount()

属性 maxCountᅟ 的获取器。

maxVisibleItems()
Return type:

整数

另请参阅

setMaxVisibleItems()

属性 maxVisibleItemsᅟ 的获取器。

minimumContentsLength()
Return type:

整数

另请参阅

setMinimumContentsLength()

属性 minimumContentsLengthᅟ 的获取器。

model()
Return type:

QAbstractItemModel

返回组合框使用的模型。

另请参阅

setModel()

modelColumn()
Return type:

整数

另请参阅

setModelColumn()

属性 modelColumnᅟ 的获取器。

placeholderText()
Return type:

字符串

另请参阅

setPlaceholderText()

属性 placeholderTextᅟ 的获取器。

removeItem(index)
Parameters:

索引 – int

从组合框中移除给定index处的项目。如果索引被移除，这将更新当前索引。

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

rootModelIndex()
Return type:

QModelIndex

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

另请参阅

setRootModelIndex()

setCompleter(c)
Parameters:

c – QCompleter

设置completer以替代当前的自动补全器。如果completer为None，则禁用自动补全功能。

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

注意

当editable属性变为false时，或者当行编辑被setLineEdit()调用替换时，自动补全器将被移除。在不可编辑的QComboBox上设置自动补全器将被忽略。

另请参阅

completer()

setCurrentIndex(index)
Parameters:

索引 – int

另请参阅

currentIndex()

属性 currentIndexᅟ 的设置器。

setCurrentText(text)
Parameters:

文本 – str

另请参阅

currentText()

属性 currentTextᅟ 的设置器。

setDuplicatesEnabled(enable)
Parameters:

enable – 布尔值

另请参阅

duplicatesEnabled()

属性 duplicatesEnabledᅟ 的设置器。

setEditText(text)
Parameters:

文本 – str

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

setEditable(editable)
Parameters:

editable – 布尔值

另请参阅

isEditable()

属性 editableᅟ 的设置器。

setFrame(arg__1)
Parameters:

arg__1 – 布尔值

另请参阅

hasFrame()

属性 frameᅟ 的设置器。

setIconSize(size)
Parameters:

大小 – QSize

另请参阅

iconSize()

属性 iconSizeᅟ 的设置器。

setInsertPolicy(policy)
Parameters:

策略 – InsertPolicy

另请参阅

insertPolicy()

属性 insertPolicyᅟ 的设置器。

setItemData(index, value[, role=Qt.UserRole])
Parameters:

  • index – 整数

  • value – 对象

  • role – int

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

另请参阅

itemData()

setItemDelegate(delegate)
Parameters:

delegate – QAbstractItemDelegate

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

任何现有的委托将被移除，但不会被删除。QComboBox 不拥有 delegate 的所有权。

警告

您不应在组合框、小部件映射器或视图之间共享同一个委托实例。这样做可能会导致不正确或不符合直觉的编辑行为，因为连接到给定委托的每个视图可能会接收到closeEditor()信号，并尝试访问、修改或关闭已经关闭的编辑器。

另请参阅

itemDelegate()

setItemIcon(index, icon)
Parameters:

  • index – 整数

  • 图标 – QIcon

为组合框中给定index上的项目设置icon。

另请参阅

itemIcon()

setItemText(index, text)
Parameters:

  • index – 整数

  • 文本 – str

设置组合框中给定index上的项目的text。

另请参阅

itemText()

setLineEdit(edit)
Parameters:

编辑 – QLineEdit

设置要使用的行edit，而不是当前的行编辑小部件。

组合框接管了行编辑的所有权。

注意

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

另请参阅

lineEdit()

setMaxCount(max)
Parameters:

max – 整数

另请参阅

maxCount()

属性 maxCountᅟ 的设置器。

setMaxVisibleItems(maxItems)
Parameters:

maxItems – int

另请参阅

maxVisibleItems()

属性 maxVisibleItemsᅟ 的设置器。

setMinimumContentsLength(characters)
Parameters:

字符 – int

另请参阅

minimumContentsLength()

属性 minimumContentsLengthᅟ 的设置器。

setModel(model)
Parameters:

模型 – QAbstractItemModel

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

注意

如果组合框是可编辑的，那么model也会设置在线编辑的自动完成器上。

另请参阅

model() clear() setCompleter()

setModelColumn(visibleColumn)
Parameters:

visibleColumn – int

另请参阅

modelColumn()

属性 modelColumnᅟ 的设置器。

setPlaceholderText(placeholderText)
Parameters:

placeholderText – str

另请参阅

placeholderText()

属性 placeholderTextᅟ 的设置器。

setRootModelIndex(index)
Parameters:

索引 – QModelIndex

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

另请参阅

rootModelIndex()

setSizeAdjustPolicy(policy)
Parameters:

策略 – SizeAdjustPolicy

另请参阅

sizeAdjustPolicy()

属性 sizeAdjustPolicyᅟ 的设置器。

setValidator(v)
Parameters:

v – QValidator

设置要使用的validator，以替代当前的验证器。

注意

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

另请参阅

validator()

setView(itemView)
Parameters:

itemView – QAbstractItemView

将组合框弹出窗口中使用的视图设置为给定的itemView。组合框将拥有该视图的所有权。

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

另请参阅

view()

showPopup()

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

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

另请参阅

hidePopup()

sizeAdjustPolicy()
Return type:

SizeAdjustPolicy

另请参阅

setSizeAdjustPolicy()

属性 sizeAdjustPolicyᅟ 的获取器。

textActivated(text)
Parameters:

文本 – str

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

textHighlighted(text)
Parameters:

文本 – str

当用户在组合框弹出列表中高亮显示一个项目时，会发送此信号。项目的 text 会被传递。

validator()
Return type:

QValidator

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

另请参阅

setValidator() 可编辑

view()
Return type:

QAbstractItemView

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

另请参阅

setView()