当前位置：首页 > news >正文

qt QCompleter详解

news 2025/7/22 17:12:20

1、概述

QCompleter是Qt框架中的一个类，用于为文本输入提供自动完成功能。它可以与Qt的输入控件（如QLineEdit、QTextEdit等）结合使用，根据用户的输入实时过滤数据源，并在输入控件下方或内部显示补全建议列表。用户可以通过键盘或鼠标选择其中一个建议项，或者继续输入以缩小补全范围。QCompleter能够减少用户输入的工作量，防止输入错误，并提供更好的用户体验。

2、重要方法

QCompleter(QObject *parent = nullptr) 或 QCompleter(const QStringList &wordList, QObject *parent = nullptr) 等，用于创建QCompleter对象。
void setModel(QAbstractItemModel *model)，用于设置数据源模型。可以使用QStringListModel、QSqlQueryModel等Qt提供的模型类，也可以自定义一个继承自QAbstractItemModel的模型类。
void setCompletionMode(QCompleter::CompletionMode mode)，用于设置补全模式。可以是QCompleter::PopupCompletion（在输入控件下方显示补全建议列表）或QCompleter::InlineCompletion（在输入控件内部显示补全建议）。
void setCompletionRole(int role)，用于设置补全策略，即根据哪个角色的数据进行补全匹配。可以使用Qt::DisplayRole、Qt::EditRole等预定义的角色，也可以自定义角色。
void setFilterMode(Qt::MatchFlags mode)，用于设置过滤模式。可以是Qt::MatchStartsWith（以输入开头进行匹配）或Qt::MatchContains（包含输入进行匹配）。
QWidget *popup() const，用于获取补全提示窗口的QListView对象，并对其进行自定义设置，如设置显示行数、行高、样式等。
void setModelSorting(QCompleter::ModelSorting sorting):设置模型排序方式。
void setCaseSensitivity(Qt::Casesensitivity caseSensitivity):设置大小写敏感性。
void setCompletionPrefix(const QString &prefix):设置补全前缀。
void setMaxVisibleltems(int maxItems):设置最大可见补全项数量。
void setwidget(QWidget *widget):设置需要自动补全的部件(如QLineEdit)。
void complete():显示补全项下拉列表。

3、重要信号

void activated(const Qstring &text):当用户选择一个补全项时发出信号。
void highlighted(const Qstring &text):当用户高亮一个补全项时发出信号。

4、匹配模式

QCompleter::CompletionMode枚举定义了自动补全的模式：

PopupCompletion:在输入框下显示补全项的下拉列表。
InlineCompletion:直接在输入框中显示补全项。
UnfilteredPopupCompletion:显示完整的补全项下拉列表，而不进行过滤。

MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent)
{setWindowTitle("QCompleter Example");resize(400, 200);// 创建候选项列表QStringList wordList = {"apple", "banana", "cherry", "date", "elderberry", "fig", "grape"};// 创建自动补全器QCompleter *completer = new QCompleter(wordList, this);completer->setCaseSensitivity(Qt::CaseInsensitive); // 不区分大小写completer->setCompletionMode(QCompleter::PopupCompletion); // 下拉列表补全模式// 创建输入框QLineEdit *lineEdit = new QLineEdit(this);lineEdit->setPlaceholderText("Type a fruit...");lineEdit->setCompleter(completer);// 布局管理QVBoxLayout *layout = new QVBoxLayout;layout->addWidget(lineEdit);QWidget *centralWidget = new QWidget;centralWidget->setLayout(layout);setCentralWidget(centralWidget);// 连接信号和槽connect(completer, QOverload<const QString &>::of(&QCompleter::activated), this, [&](const QString &text){qDebug() << "Completion activated:" << text;});}