QComboBox 库详细介绍

QComboBox 是 PyQt5 中用于创建下拉选择框的控件，允许用户从预定义列表中选择一个或多个选项（若支持多选）。它支持文本、图标、自定义数据绑定及可编辑输入，是表单和配置界面中常用的交互组件。以下是详细介绍及常用方法：

一、核心功能

• ​下拉列表：显示可折叠的选项列表。
• ​可编辑性：允许用户输入自定义内容。
• ​项管理：动态添加、删除、插入选项。
• ​数据存储：为每个项关联自定义数据（如 ID）。
• ​信号反馈：监听选项变化并触发逻辑。
• ​样式定制：支持 CSS 修改外观。

 

二、常用方法

​1. 添加与删除项

方法	说明	示例
addItem(text: str, userData: Any = None)	添加单个项（可绑定数据）	combo.addItem("北京", "bj")
addItems(texts: Iterable[str])	批量添加文本项	combo.addItems(["上海", "广州"])
insertItem(index: int, text: str, userData: Any = None)	在指定位置插入项	combo.insertItem(0, "深圳")
removeItem(index: int)	删除指定位置的项	combo.removeItem(2)
clear()	清空所有项	combo.clear()

​2. 获取与设置当前项

方法	说明	示例
currentText() -> str	获取当前选中项的文本	city = combo.currentText()
currentIndex() -> int	获取当前项的索引（从0开始）	idx = combo.currentIndex()
currentData(role: int = Qt.UserRole) -> Any	获取当前项绑定的数据	data = combo.currentData()
setCurrentIndex(index: int)	设置当前选中项	combo.setCurrentIndex(1)
setCurrentText(text: str)	通过文本设置当前项	combo.setCurrentText("广州")

​3. 可编辑性控制

方法	说明	示例
setEditable(enable: bool)	启用/禁用输入编辑	combo.setEditable(True)
lineEdit()	获取编辑框对象（用于输入验证）	edit = combo.lineEdit()

​4. 项查询与遍历

方法	说明
itemText(index: int) -> str	获取指定索引的项文本
itemData(index: int, role: int = Qt.UserRole) -> Any	获取指定索引的项数据
count() -> int	获取项的总数
findText(text: str) -> int	根据文本查找项索引（返回首个匹配项的索引，未找到返回-1）

---

​三、信号

信号	说明
currentIndexChanged(index: int)	当前选中项索引变化时触发
currentTextChanged(text: str)	当前文本变化时触发（包括编辑输入）
editTextChanged(text: str)	编辑框内容变化时触发（仅可编辑模式下）

python

combo.currentIndexChanged.connect(lambda idx: print(f"选中索引: {idx}"))
combo.currentTextChanged.connect(lambda text: print(f"当前文本: {text}"))

四、代码示例

​基础使用

python

from PyQt5.QtWidgets import QApplication, QWidget, QComboBox, QVBoxLayout

class MyWindow(QWidget):
    def __init__(self):
        super().__init__()
        self.initUI()

    def initUI(self):
        layout = QVBoxLayout()
        self.combo = QComboBox()
        
        # 添加项并绑定数据
        self.combo.addItem("北京", "bj")
        self.combo.addItems(["上海", "广州"])
        
        # 监听信号
        self.combo.currentIndexChanged.connect(self.on_index_changed)
        
        layout.addWidget(self.combo)
        self.setLayout(layout)
        self.show()

    def on_index_changed(self, index):
        print(f"选中城市ID: {self.combo.currentData()}")

if __name__ == "__main__":
    app = QApplication([])
    window = MyWindow()
    app.exec_()

 

可编辑下拉框

python

combo = QComboBox()
combo.setEditable(True)
combo.addItems(["苹果", "香蕉", "橙子"])

# 设置输入验证（仅允许字母）
combo.lineEdit().setValidator(QRegExpValidator(QRegExp("[a-zA-Z]+")))

​带图标的项

python

from PyQt5.QtGui import QIcon

combo = QComboBox()
combo.addItem(QIcon("home.png"), "主页")
combo.addItem(QIcon("settings.png"), "设置")

五、注意事项

1. ​数据绑定：
   使用 addItem(text, userData) 或 setItemData(index, data) 存储额外信息（如数据库 ID）。

2. ​性能优化：
   批量添加项时，优先使用 addItems() 而非循环调用 addItem()。

3. ​输入验证：
   可编辑模式下，通过 lineEdit().setValidator() 限制用户输入格式。

4. ​动态更新：
   修改项列表后，注意更新当前选中状态（如调用 setCurrentIndex(-1) 清空选中）。

---

​六、与 QListWidget 的对比

​QComboBox	​QListWidget
紧凑的下拉列表，适合少量选项	显示完整列表，适合大量选项
支持可编辑输入	仅支持选择预定义项
通常用于表单或配置	适合文件列表、目录导航等场景

---

通过 QComboBox，可以快速构建灵活的下拉选择功能，结合数据绑定和信号机制，轻松实现动态交互！