您可以使用 QCompleter 在任何 Qt 小部件中提供自动完成，例如 QLineEdit 和 QComboBox 。当用户开始输入一个单词时，基于一个单词表，QCompleter 会建议完成单词的可能方式。单词表作为 QAbstractItemModel 提供。（对于单词表静态的简单应用程序，您可以将 QStringList 传递给 QCompleter 构造函数。）

基本用法#

QCompleter 通常与 QLineEdit 或 QComboBox 一起使用。例如，下面是如何在 QLineEdit 中提供来自简单单词列表的自动完成：

wordList = QStringList()
wordList << "alpha" << "omega" << "omicron" << "zeta"
lineEdit = QLineEdit(self)
completer = QCompleter(wordList, self)
completer.setCaseSensitivity(Qt.CaseInsensitive)
lineEdit.setCompleter(completer)

可以使用 QFileSystemModel 来提供文件名的自动完成。例如

completer = QCompleter(self)
completer.setModel(QFileSystemModel(completer))
lineEdit.setCompleter(completer)

要设置 QCompleter 应该操作的模型，请调用 setModel() 方法。默认情况下，QCompleter 将尝试将 completionPrefix（即用户已经输入的单词）与模型中第 0 列存储的 Qt::EditRole 数据进行敏感匹配。这可以通过使用 setCompletionRole() 、 setCompletionColumn() 和 setCaseSensitivity() 来改变。

如果模型是根据用于补全的列和角色进行排序的，您可以调用setModelSorting()方法，参数为CaseSensitivelySortedModel或CaseInsensitivelySortedModel。在大规模模型中，这可以带来显著的性能提升，因为此时QCompleter可以使用二分搜索代替线性搜索。只有当filterMode设置为Qt::MatchStartsWith时，二分搜索才能工作。

模型可以是列表模型、表格模型或树模型。在树模型上进行补全稍微复杂一些，下面将详细介绍。

completionMode()方法确定用于向用户提供补全的方式。

遍历补全

要获取单个候选字符串，请使用需要补全的文本调用setCompletionPrefix()方法，然后调用currentCompletion()方法。您可以像下面这样遍历补全列表：

for (int i = 0; completer.setCurrentRow(i); i++)
    print(completer.currentCompletion(), " is match number ", i)

方法completionCount()返回当前前缀的所有补全总数。在可能的情况下应避免使用completionCount()，因为它需要扫描整个模型。

Completion 模型

方法completionModel()返回一个列表模型，包含当前补全前缀的所有可能的补全，其顺序与模型中出现的顺序相同。这个模型可以用来自定义视图中的当前补全。调用setCompletionPrefix()方法会自动刷新补全模型。

处理树模型

在假定任何项目（或子项目或子子项目）可以通过指定项目路径无歧义地表示为字符串的情况下，QCompleter可以在树模型中查找补全。然后，补全会逐级进行。

让我们以用户在文件系统路径中输入为例。该模型是一个（层次结构的）QFileSystemModel。对于路径中的每个元素都进行补全。例如，如果当前文本是 C:\Wind，则 QCompleter 可能会建议 Windows 来补全当前路径元素。同样，如果当前文本是 C:\Windows\Sy，则 QCompleter 可能会建议 System。

为了让这种补全生效，QCompleter 需要能够将路径拆分成字符串列表，在每个级别都有匹配项。对于 C:\Windows\Sy，它需要拆分为“C:”，“Windows”和“Sy”。默认实现中，splitPath() 使用 QDir::separator() 来拆分 completionPrefix，如果模型是 QFileSystemModel。

为了提供补全，QCompleter 需要知道索引处的路径。这由 pathFromIndex() 提供。默认实现中，pathFromIndex() 返回列表模型的编辑角色数据，如果模式是 QFileSystemModel，则返回绝对文件路径。

见 anche

QLineEdit QComboBox Completer Example

class CompletionMode#

该枚举指定了如何向用户提供补全。

常量

描述

QCompleter.PayloadCompletion

当前补全将在弹出窗口中显示。

QCompleter.XMLCompletion

补全长直 (作为选定的文本) 显示。

QCompleter.UnfilteredXMLCompletion

所有可能的补全将在弹出窗口中显示，最可能的建议将指示为当前。

见 anche

setCompletionMode()

常量	描述
QCompleter.PayloadCompletion	当前补全将在弹出窗口中显示。
QCompleter.XMLCompletion	补全长直 (作为选定的文本) 显示。
QCompleter.UnfilteredXMLCompletion	所有可能的补全将在弹出窗口中显示，最可能的建议将指示为当前。

class ModelSorting#

该枚举指定了模型中项目是如何排序的。

常量

描述

QCompleter.UnsortedModel

模型未排序。

QCompleter.CaseSensitivelySortedModel

模型按字母顺序排序。

QCompleter.CaseInsensitivelySortedModel

模型不区分大小写排序。

见 anche

setModelSorting()

常量	描述
QCompleter.UnsortedModel	模型未排序。
QCompleter.CaseSensitivelySortedModel	模型按字母顺序排序。
QCompleter.CaseInsensitivelySortedModel	模型不区分大小写排序。

注意

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

属性caseSensitivity： Qt.CaseSensitivity#

此属性存储匹配的大小写敏感度。

默认值是 Qt::CaseSensitive。

见 anche

completionColumn completionRole modelSorting filterMode

访问函数

caseSensitivity()
setCaseSensitivity()

属性completionColumn： int#

此属性存储完成搜索的模型中的列。

如果 popup() 是 QListView，它将自动配置为显示此列。

默认情况下，匹配列是0。

见 anche

completionRole caseSensitivity

访问函数

completionColumn()
setCompletionColumn()

属性completionMode： QCompleter.CompletionMode#

此属性存储向用户提供的补全方式。

默认值是 PopupCompletion。

访问函数

completionMode()
setCompletionMode()

属性completionPrefix： str#

此属性存储用于提供补全的完成前缀。

completionModel() 更新以反映 prefix 的可能匹配列表。

访问函数

completionPrefix()
setCompletionPrefix()

属性completionRole： int#

此属性存储用于查询匹配内容的项角色的项。

默认的角色是Qt::EditRole。

见 anche

completionColumn caseSensitivity

访问函数

completionRole()
setCompletionRole()

属性 filterMode: Qt.MatchFlag 的组合#

此属性控制如何进行过滤。

如果filterMode设置为Qt::MatchStartsWith，则仅显示以输入字符开始的条目。Qt::MatchContains将显示包含输入字符的条目，Qt::MatchEndsWith将显示以输入字符结尾的条目。

将filterMode设置为其他任意Qt::MatchFlag将会发出警告，并且不会执行任何操作。因此，Qt::MatchCaseSensitive标志没有效果。使用caseSensitivity属性来控制大小写敏感度。

默认模式是Qt::MatchStartsWith。

见 anche

caseSensitivity

访问函数

filterMode()
setFilterMode()

属性 maxVisibleItems: int#

此属性表示完完整齐器在屏幕上的最大可接受大小，以项为单位计算。

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

访问函数

maxVisibleItems()
setMaxVisibleItems()

属性 modelSorting: QCompleter.ModelSorting#

此属性表示模型排序的方式。

默认情况下，不会对提供完整建议的模型的项的顺序做任何假设。

如果为completionColumn和completionRole排序的数据是按升序排序的，可以将该属性设置为CaseSensitivelySortedModel或CaseInsensitivelySortedModel 。在大型模型上，这可以提高性能，因为完完整齐器对象可以使用二分搜索算法而不是线性搜索算法。

模型的排序顺序（即升序或降序）是通过检查模型的内函来确定。

注意

当完完整齐器的caseSensitivity与模型排序时使用的大小写敏感度不同时，上述性能改进无法发生。

见 anche

setCaseSensitivity() ModelSorting

访问函数

modelSorting()
setModelSorting()

property wrapAround: bool#

此属性表示在遍历项时，完成项是否能够环绕。

默认值为 true。

访问函数

wrapAround()
setWrapAround()

__init__([parent=None])#

参数:: parent – QObject

使用给定的 parent 构造 completer 对象。

__init__(model[, parent=None])

参数:

model – QAbstractItemModel
parent – QObject

使用指定的 model 提供的补全项构造 completer 对象，并将该对象利用给定的 parent。

__init__(completions[, parent=None])

参数:

completions – 字符串列表
parent – QObject

使用给定的 parent，使用指定的字符串列表作为可能的补全源构造 QCompleter 对象。

activated(index)#

参数:: index – QModelIndex

当用户通过点击或按回车键激活 popup() 中的项时，会发送此信号。提供的该项的 index 是在 completionModel() 中的。

activated(text)

参数:: text – str

当用户通过点击或按回车键激活 popup() 中的项时，会发送此信号。提供的该项的 text 是该项的文本。

caseSensitivity()#

返回类型:: CaseSensitivity

见 anche

setCaseSensitivity()

属性caseSensitivity的获取器。

complete([rect=QRect()])#

参数:: rect – QRect

对于PopupCompletion和UnfilteredPopupCompletion模式，调用此函数将显示当前补全的弹出窗口。默认情况下，如果未指定rect，弹出窗口将显示在widget()的底部。如果指定了rect，则弹出窗口显示在矩形的左边。

对于InlineCompletion模式，将引发带有当前补全的highlighted()信号。

completionColumn()#

返回类型:: int

见 anche

setCompletionColumn()

属性completionColumn的获取器。

completionCount()#

返回类型:: int

返回当前前缀的补全数。对于具有大量项的未排序模型，此操作可能很昂贵。使用setCurrentRow()和currentCompletion()迭代所有补全内容。

completionMode()#

返回类型:: CompletionMode

见 anche

setCompletionMode()

属性completionMode的获取器。

completionModel()#

返回类型:: QAbstractItemModel

返回补全模型。补全模型是一个只读列表模型，包含当前补全前缀的所有可能的匹配项。补全模型将自动更新以反映当前的补全内容。

注意

此函数的返回值定义为QAbstractItemModel，纯粹是为了通用性。实际上返回的模型是QAbstractProxyModel子类的一个实例。

见 anche

completionPrefix model()

completionPrefix()#

返回类型:: 字符串

见 anche

setCompletionPrefix()

属性 completionPrefix 的获取器。

completionRole()#

返回类型:: int

见 anche

setCompletionRole()

属性 completionRole 的获取器。

currentCompletion()#

返回类型:: 字符串

返回当前补全字符串。这包括 completionPrefix . 当与 setCurrentRow() 一起使用时，它可以遍历所有匹配项。

见 anche

setCurrentRow() currentIndex()

currentIndex()#

返回类型:: QModelIndex

返回当前补全字符串在 completionModel() 中的模型索引。

见 anche

setCurrentRow() currentCompletion() model()

currentRow()#

返回类型:: int

返回当前行。

见 anche

setCurrentRow()

filterMode()#

返回类型:: MatchFlag 组合

见 anche

setFilterMode()

属性 filterMode 的获取器。

highlighted(index)#

参数:: index – QModelIndex

当用户突出显示popup()中的某个项目时，会发送此信号。如果以completionMode()设为InlineCompletion的方式调用complete()，也会发送此信号。此时会提供项目在completionModel()中的索引。

highlighted(text)

参数:: text – str

当用户突出显示popup()中的某个项目时，会发送此信号。如果以completionMode()设为InlineCompletion的方式调用complete()，也会发送此信号。此时会提供项目的文本。

maxVisibleItems()#

返回类型:: int

见 anche

setMaxVisibleItems()

属性maxVisibleItemsᅟ的获取器。

model()#

返回类型:: QAbstractItemModel

返回提供完整字符串的模型。

见 anche

setModel() / completionModel()

modelSorting()#

返回类型:: 模型排序

见 anche

setModelSorting()

属性modelSortingᅟ的获取器。

pathFromIndex(index)#

参数:: index – QModelIndex
返回类型:: 字符串

返回给定index的路径。完成器对象使用此路径从底层模型中获取补全文本。

默认实现返回列表模型中项目的编辑角色。如果模型是QFileSystemModel，则返回绝对文件路径。

见 anche

splitPath()

popup()#

返回类型:: QAbstractItemView

返回用于显示完整字符串的弹出窗口。

见 anche

setPopup()

setCaseSensitivity(caseSensitivity)#

参数:: caseSensitivity – CaseSensitivity

见 anche

caseSensitivity()

设置 caseSensitivity 属性的值。

setCompletionColumn(column)#

参数:: column – int

见 anche

completionColumn()

设置 completionColumn 属性的值。

setCompletionMode(mode)#

参数:: mode – CompletionMode

见 anche

completionMode()

设置 completionMode 属性的值。

setCompletionPrefix(prefix)#

参数:: prefix – str

见 anche

completionPrefix()

设置 completionPrefix 属性的值。

setCompletionRole(role)#

参数:: role – int

见 anche

completionRole()

设置 completionRole 属性的值。

setCurrentRow(row)#

参数:: row – int
返回类型:: bool

设置当前行为指定的 row。如果成功返回 true，否则返回 false。

此函数可以与 currentCompletion() 一起使用，以遍历所有可能的完成条目。

见 anche

currentRow() currentCompletion() completionCount()

setFilterMode(filterMode)#

参数:: filterMode – MatchFlag的组合

见 anche

filterMode()

设置属性filterMode的值。

setMaxVisibleItems(maxItems)#

参数:: maxItems – int

见 anche

maxVisibleItems()

设置属性maxVisibleItems的值。

setModel(c)#

参数:: c – QAbstractItemModel

设置提供补全内容的模型至model。该模型可以是列表模型或树模型。如果已设置过模型并且它是具有QCompleter作为其父级的模型，它将被删除。

为方便起见，如果model是QFileSystemModel，QCompleter将它在其他平台上的大小写敏感度设置为Qt::CaseSensitive，并设置为Qt::CaseInsensitive。

见 anche

completionModel() modelSorting 处理树模型

setModelSorting
参数:: sorting – ModelSorting

见 anche

modelSorting()

设置属性modelSorting的值。

setPopup
参数:: popup – QAbstractItemView

将用于显示补全的弹出框设置为 popup。 QCompleter 拥有视图的所有权。

当 completionMode() 设置为 PopupCompletion 或 UnfilteredPopupCompletion 时，会自动创建一个 QListView。默认弹出框显示 completionColumn()。

请在修改视图设置之前调用此函数。这是必需的，因为视图的属性可能需要视图上有一个模型（例如，在视图中隐藏列需要视图设置模型）。

见 anche

popup()

setWidget(widget)#

参数:: widget – QWidget

将提供补全的部件设置为 widget。此函数在将 QCompleter 设置到一个使用 QLineEdit 的 setCompleter() 或使用 QComboBox 的 setCompleter() 时自动调用。提供自定义部件的补全时需要显式设置部件。

见 anche

widget() setModel() setPopup()

setWrapAround(wrap)#

参数:: wrap – bool

见 anche

wrapAround()

属性 wrapAround 的设置器。

splitPath(path)#

参数:: path – 字符串
返回类型:: 字符串列表

将指定的 path 分割成字符串，这些字符串用于在 model() 的每个级别进行匹配。

splitPath() 函数的默认实现根据 QDir::separator() 将文件系统路径分割，当 sourceModel() 是 QFileSystemModel 时。

与列表模型一起使用时，返回列表中的第一个项用于匹配。

见 anche

pathFromIndex() 处理树模型

widget()#

返回类型:: QWidget

返回提供补全的 completer 对象的控件。

见 anche

setWidget()

wrapAround()#

返回类型:: bool

见 anche

setWrapAround()

wrapAround 属性的获取器。