【Qt笔记】QComboBox控件详解

在图形用户界面（GUI）开发中，下拉列表框是一种常见且实用的交互组件。Qt 框架中的 QComboBox 控件提供了丰富的功能和灵活的定制性，方便开发者创建各种类型的下拉选择界面。本文将详细介绍 QComboBox 控件的各个方面，包括其基本功能、常用属性、信号与槽机制、样式定制以及在实际应用中的使用示例等，帮助读者深入理解并熟练运用该控件进行高效的 GUI 开发。

一、外观

QComboBox通常表现为一个下拉列表框，包含一个文本标签区域和一个下拉箭头按钮。点击箭头时会显示出可供选择的项目列表。当不展开下拉列表时，仅显示当前选定项的文字，占用较少的屏幕空间。QComboBox结合了下拉列表的简洁性和按钮或文本框的易用性，既节省了屏幕空间，又提高了用户交互的效率。

二、概述

QComboBox 是 Qt 提供的一个复合控件，它将一个可编辑的文本框与一个下拉列表结合在一起。用户可以从下拉列表中选择一个预定义的选项，也可以在文本框中直接输入自定义内容（如果可编辑模式被启用）。这种设计使得 QComboBox 适用于多种场景，如选择特定的设置项、从一组数据中选取一个元素等。

三、基本功能

3.1 添加和删除项目

①添加项目：

使用 addItem() 函数可以向 QComboBox 中添加单个项目。例如：

cpp 复制代码

QComboBox *comboBox = new QComboBox(parent);
comboBox->addItem("Option 1");

还可以使用 addItems() 函数一次性添加多个项目，该函数接受一个 QStringList 作为参数。例如：

cpp 复制代码

QStringList items;
items << "Option 2" << "Option 3" << "Option 4";
comboBox->addItems(items);

②删除项目：

removeItem() 函数可根据指定的索引删除项目。例如，要删除索引为 2 的项目：

cpp 复制代码

comboBox->removeItem(2);

clear() 函数可以清空 QComboBox 中的所有项目。

3.2 获取当前选择

使用 currentIndex() 函数可以获取当前选中项目的索引。例如：

cpp 复制代码

int index = comboBox->currentIndex();

通过 currentText() 函数可以获取当前选中项目的文本内容。例如：

cpp 复制代码

QString selectedText = comboBox->currentText();

3.3 设置当前选择

setCurrentIndex() 函数可以根据索引设置当前选中的项目。例如，将索引为 1 的项目设置为当前选中项：

cpp 复制代码

comboBox->setCurrentIndex(1);

也可以使用 setCurrentText() 函数根据文本内容设置当前选中项，如果存在匹配的文本，则对应的项目将被选中；否则，没有项目会被选中。

四、常用属性

4.1 可编辑性

通过 setEditable() 函数可以设置 QComboBox 是否可编辑。例如，设置为可编辑：

cpp 复制代码

comboBox->setEditable(true);

当可编辑时，用户可以在文本框中输入自定义内容，并且可以通过 lineEdit() 函数获取关联的文本编辑框对象，以便进一步操作，如设置文本框的验证器等。

接下来以设置整数验证器为例：

①首先通过 isEditable() 函数判断组合框是否可由用户编辑。

只有返回为true后面的操作才有意义。

cpp 复制代码

if(isEditable()){

}

以下的代码都包含在if的大括号中！！！

②获取文本编辑框对象

当使用QComboBox的 lineEdit() 函数获取关联的文本编辑框对象后，就可以对这个对象进行一系列操作。例如，假设comboBox是一个QComboBox对象，通过以下代码获取文本编辑框对象：

cpp 复制代码

QLineEdit *lineEditObj = comboBox->lineEdit();

③设置整数验证器

如果希望用户在QComboBox的可编辑部分只能输入整数，可以使用QIntValidator。例如，限制输入的整数范围是 1 到 100，可以这样设置验证器：

cpp 复制代码

QIntValidator *intValidator = new QIntValidator(1, 100, this);
lineEditObj->setValidator(intValidator);

④总结

这样，当用户在QComboBox的可编辑部分输入非整数或者超出范围的整数时，输入将不会被接受。

4.2 最大可见项目数

使用 setMaxVisibleItems() 函数可以设置下拉列表中最大可见的项目数。例如，设置最多显示 5 个项目：

cpp 复制代码

comboBox->setMaxVisibleItems(5);

当项目数超过设定的最大可见数时，下拉列表会出现滚动条，方便用户浏览更多选项。

4.3 插入策略

QComboBox 有不同的插入策略，用于确定新添加的项目在下拉列表中的位置。通过 setInsertPolicy() 函数设置，常用的插入策略有：

**QComboBox::NoInsert：**不插入新项（默认值在某些情况下）。
**QComboBox::InsertAtTop：**将新项插入到列表顶部。
**QComboBox::InsertAtCurrent：**将新项插入到当前选中项的位置。
**QComboBox::InsertAtBottom：**将新项插入到列表底部。
**QComboBox::InsertAfterCurrent：**将新项插入到当前选中项之后。
**QComboBox::InsertBeforeCurrent：**将新项插入到当前选中项之前。

4.4 重复策略

setDuplicatesEnabled() 函数用于设置是否允许添加重复的项目。例如，禁止添加重复项目：

cpp 复制代码

comboBox->setDuplicatesEnabled(false);

bool duplicatesEnabled() const：判断用户是否可把重复项目输入到组合框中。

4.5 自动补全策略

void setCompleter(QCompleter *completer)：设置组合框的补全器。补全器提供了文本输入时的自动补全功能（仅当QComboBox可编辑时有效）。

QCompleter *completer() const：返回组合框的补全器。

以下是一个自定义补全数据源示例，定义一个自定义的补全数据源（例如，一个包含城市名称的列表）：

cpp 复制代码

QStringList cityNames;
cityNames << "北京" << "上海" << "广州";
QCompleter *customCompleter = new QCompleter(cityNames, this);
QComboBox *customComboBox = new QComboBox(this);
customComboBox->setEditable(true);
customComboBox->setCompleter(customCompleter);

在这个例子中，补全器会根据自定义的城市名称列表提供补全，而不是基于QComboBox初始添加的项目（因为此时还没有添加项目到customComboBox）。当用户输入城市名称的部分字符时，补全器会从cityNames列表中寻找匹配的选项进行补全。

五、信号与槽机制

QComboBox 提供了多个信号，方便开发者响应不同的用户交互事件。

5.1 currentIndexChanged 信号

当用户选择了下拉列表中的不同项目，或者通过代码改变了当前选中项的索引时，该信号会被发射。信号有两种重载形式：

void currentIndexChanged(int index)：传递当前选中项的新索引。
void currentIndexChanged(const QString &text)：传递当前选中项的文本内容。

例如，连接到槽函数来处理索引变化和文本内容变化，其中假设comboBox是一个QComboBox对象：

cpp 复制代码

// 创建用于显示索引变化的标签
QLabel *indexLabel = new QLabel("当前选中项索引: ", this);
// 创建用于显示文本内容变化的标签
QLabel *textLabel = new QLabel("当前选中项文本: ", this);

// 连接currentIndexChanged信号（以索引为参数的重载形式）到对应的槽函数
connect(comboBox, &QComboBox::currentIndexChanged, this, &MainWindow::onComboBoxIndexChanged);
// 连接currentIndexChanged信号（以文本内容为参数的重载形式）到对应的槽函数
connect(comboBox, &QComboBox::currentIndexChanged, this, &MainWindow::onComboBoxTextChanged);

// 处理索引变化的槽函数（接收索引参数形式）
void MainWindow::onComboBoxIndexChanged(int index)
{
    indexLabel->setText(QString("当前选中项索引: %1").arg(index));
}

// 处理索引变化的槽函数（接收文本内容参数形式）
void MainWindow::onComboBoxTextChanged(const QString &text)
{
    textLabel->setText(QString("当前选中项文本: %1").arg(text));
}

5.2 activated 信号

当用户通过点击下拉列表中的项目激活一个选项时，activated 信号会被发射。同样有两种重载形式：

void activated(int index)：传递被激活项目的索引。
void activated(const QString &text)：传递被激活项目的文本内容。

这个信号与 currentIndexChanged 信号的区别在于，activated 信号只有在用户交互激活项目时才发射，而 currentIndexChanged 信号在代码改变选中项时也会发射。

cpp 复制代码

// 创建用于显示activated信号触发时索引的标签
QLabel *activatedIndexLabel = new QLabel("Activated项目索引: ", this);
// 创建用于显示activated信号触发时文本内容的标签
QLabel *activatedTextLabel = new QLabel("Activated项目文本: ", this);

// 连接activated信号（以索引为参数的重载形式）到对应的槽函数
connect(comboBox, &QComboBox::activated, this, &MainWindow::onComboBoxActivatedIndex);
// 连接activated信号（以文本内容为参数的重载形式）到对应的槽函数
connect(comboBox, &QComboBox::activated, this, &MainWindow::onComboBoxActivatedText);

// 处理activated信号（以索引为参数的重载形式）的槽函数
void MainWindow::onComboBoxActivatedIndex(int index)
{
    activatedIndexLabel->setText(QString("Activated项目索引: %1").arg(index));
}

// 处理activated信号（以文本内容为参数的重载形式）的槽函数
void MainWindow::onComboBoxActivatedText(const QString &text)
{
    activatedTextLabel->setText(QString("Activated项目文本: %1").arg(text));
}

5.3 editTextChanged 信号

当可编辑的 QComboBox 中的文本内容发生改变时，该信号会被发射。例如：

cpp 复制代码

// 创建用于显示文本内容变化的标签
QLabel *textChangeLabel = new QLabel("当前文本内容: 初始内容", this);

// 连接editTextChanged信号到对应的槽函数
connect(comboBox, &QComboBox::editTextChanged, this, &MainWindow::onEditTextChanged);

// 处理editTextChanged信号的槽函数
void MainWindow::onEditTextChanged(const QString &text)
{
    textChangeLabel->setText(QString("当前文本内容: %1").arg(text));
}

在槽函数中可以对用户输入的文本进行实时验证或处理，上面代码只进行简单打印效果，还可以实现如限制输入长度、进行自动补全等。

六、样式定制

QComboBox 的外观可以通过样式表进行高度定制，以满足不同应用程序的风格需求。

6.1 基本样式设置

可以设置 QComboBox 的整体背景色、边框、字体等样式。例如：

cpp 复制代码

QComboBox {
    background-color: #f0f0f0;
    border: 1px solid #ccc;
    font-family: Arial;
    font-size: 12px;
}

对于下拉箭头的样式，可以使用 ::down-arrow 子控件选择器进行定制。例如：

cpp 复制代码

QComboBox::down-arrow {
    image: url(:/images/down_arrow.png);
    width: 16px;
    height: 16px;
}

6.2 不同状态的样式

QComboBox 有多种状态，如正常、悬停、按下、禁用等，可以分别为这些状态设置样式。例如：

cpp 复制代码

QComboBox:hover {
    background-color: #e0e0e0;
}
QComboBox:pressed {
    background-color: #d0d0d0;
}
QComboBox:disabled {
    background-color: #ccc;
    color: #999;
}

对于下拉列表中的项目，也可以设置不同状态的样式，如选中项目的背景色和文本颜色：

cpp 复制代码

QComboBox::item:selected {
    background-color: #336699;
    color: #fff;
}

七、实际应用示例

以下是一个简单的代码示例，展示了在可编辑的 QComboBox 中，当文本内容发生改变时，editTextChanged 信号是如何被发射以及对应的槽函数如何响应处理的。示例创建了一个包含可编辑 QComboBox 和一个 QLabel 的图形界面，QLabel 用于实时显示 QComboBox 中文本内容的变化情况。

7.1 头文件部分

cpp 复制代码

#ifndef MAINCOMBOBOX_H
#define MAINCOMBOBOX_H

#include <QMainWindow>
#include <QComboBox>
#include <QLabel>
#include <QVBoxLayout>
#include <QCompleter>

QT_BEGIN_NAMESPACE
namespace Ui {
class MainComboBox;
}
QT_END_NAMESPACE

class MainComboBox : public QMainWindow
{
    Q_OBJECT

public:
    MainComboBox(QWidget *parent = nullptr);
    ~MainComboBox();

private:
    QComboBox *comboBox;
    QLabel *resultLabel;

private slots:
    void onActivated(int index);
    void onCurrentIndexChanged(int index);
    void onCurrentTextChanged(const QString &text);
    void onEditTextChanged(const QString &text);

private:
    Ui::MainComboBox *ui;
};
#endif // MAINCOMBOBOX_H

7.2 源文件部分

cpp 复制代码

#include "maincombobox.h"
#include "ui_maincombobox.h"

MainComboBox::MainComboBox(QWidget *parent)
    : QMainWindow(parent)
    , ui(new Ui::MainComboBox)
{
    ui->setupUi(this);

    // 创建并设置窗口布局
    QWidget *centralWidget = new QWidget(this);
    QVBoxLayout *layout = new QVBoxLayout(centralWidget);
    setCentralWidget(centralWidget);

    // 创建可编辑的QComboBox并设置相关属性
    comboBox = new QComboBox(this);
    comboBox->setEditable(true);
    comboBox->setMaxVisibleItems(5);  // 设置最大可见项目数为5

    // 设置自动补全策略
    QStringList itemList;
    itemList << "Apple" << "Banana" << "Cherry" << "Date" << "Elderberry" << "Fig" << "Grape" << "Honeydew" << "Kiwi" << "Lemon";
    QCompleter *completer = new QCompleter(itemList, comboBox->model());
    completer->setFilterMode(Qt::MatchContains);
    completer->setCaseSensitivity(Qt::CaseInsensitive);
    completer->setCompletionMode(QCompleter::PopupCompletion);
    comboBox->setCompleter(completer);

    // 向QComboBox中添加一些项目
    comboBox->addItems(itemList);

    // 创建用于显示结果的标签
    resultLabel = new QLabel("当前选择: ", this);

    // 将QComboBox和标签添加到布局中
    layout->addWidget(comboBox);
    layout->addWidget(resultLabel);

    // 连接QComboBox的各种信号到对应的槽函数
    connect(comboBox, SIGNAL(activated(int)), this, SLOT(onActivated(int)));
    connect(comboBox, SIGNAL(currentIndexChanged(int)), this, SLOT(onCurrentIndexChanged(int)));
    connect(comboBox, SIGNAL(currentTextChanged(const QString &)), this, SLOT(onCurrentTextChanged(const QString &)));
    connect(comboBox, SIGNAL(editTextChanged(const QString &)), this, SLOT(onEditTextChanged(const QString &)));
}

MainComboBox::~MainComboBox()
{
    delete ui;
}

void MainComboBox::onActivated(int index)
{
    resultLabel->setText(QString("通过activated信号选择的项目索引: %1, 文本: %2").arg(index).arg(comboBox->itemText(index)));
}

void MainComboBox::onCurrentIndexChanged(int index)
{
    resultLabel->setText(QString("通过currentIndexChanged信号选择的项目索引: %1, 文本: %2").arg(index).arg(comboBox->itemText(index)));
}

void MainComboBox::onCurrentTextChanged(const QString &text)
{
    resultLabel->setText(QString("通过currentTextChanged信号选择的文本: %1").arg(text));
}

void MainComboBox::onEditTextChanged(const QString &text)
{
    resultLabel->setText(QString("编辑框中的文本发生改变: %1").arg(text));
}

7.3 主函数部分

cpp 复制代码

#include "maincombobox.h"

#include <QApplication>

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    MainComboBox w;
    w.show();
    return a.exec();
}

7.4 代码解析

在上述代码中：

①可编辑性

通过comboBox->setEditable(true);将QComboBox设置为可编辑状态，用户不仅可以从下拉列表中选择项目，还可以直接在组合框中输入自定义的文本.

②最大可见项目数

使用comboBox->setMaxVisibleItems(5);设置了QComboBox下拉列表中最大可见的项目数为 5，当项目数量超过 5 个时，下拉列表会出现滚动条以便查看其他项目.

③自动补全策略

创建了一个QCompleter对象，并设置了相关的属性来实现自动补全功能：

QCompleter *completer = new QCompleter(itemList, comboBox->model());：使用数据源itemList和QComboBox的模型来初始化QCompleter。

completer->setFilterMode(Qt::MatchContains);：设置匹配模式为包含，即只要输入的文本包含在列表项中就会显示匹配的结果。

completer->setCaseSensitivity(Qt::CaseInsensitive);：设置大小写不敏感，这样用户输入大写或小写字母都能匹配到相应的项目。

completer->setCompletionMode(QCompleter::PopupCompletion);：设置补全方式为弹出式补全，当用户输入文本时，会弹出一个包含匹配项的下拉列表供用户选择。

最后通过comboBox->setCompleter(completer);将QCompleter对象设置给QComboBox，使其具备自动补全功能。

④信号与槽函数

连接了QComboBox的多个信号到对应的槽函数：

activated信号：当用户通过点击下拉列表中的项目激活一个选项时发射，槽函数onActivated会根据激活项目的索引获取并显示对应的文本内容。

currentIndexChanged信号：当用户选择了下拉列表中的不同项目，或者通过代码改变了当前选中项的索引时发射，槽函数onCurrentIndexChanged会显示当前选中项目的索引和文本内容。

currentTextChanged信号：当QComboBox的当前文本内容发生改变时发射，槽函数onCurrentTextChanged会显示当前的文本内容。

editTextChanged信号：当可编辑的QComboBox中的文本内容发生改变时发射，槽函数onEditTextChanged会实时显示编辑框中正在输入或修改的文本内容。

7.5 运行效果展示

结语

QComboBox 控件是 Qt 框架中一个功能强大且灵活的组件，它在图形用户界面开发中具有广泛的应用。通过掌握其基本功能、常用属性、信号与槽机制以及样式定制方法，开发者可以创建出各种满足用户需求的下拉选择界面。无论是简单的设置选项还是复杂的数据筛选和交互场景，QComboBox 都能够提供高效且便捷的解决方案，为构建高质量的 GUI 应用程序奠定坚实的基础。在实际开发中，开发者可以根据具体的应用需求进一步探索和扩展 QComboBox 的功能，以实现更加个性化和丰富的用户体验。

如需更多信息，建议查阅Qt官方文档：

QComboBox Class | Qt Widgets 6.8.1