PySide6.QtWidgets.QCompleter

class QCompleter

QCompleter 类基于项目模型提供补全功能。更多…

PySide6.QtWidgets.QCompleter 的继承图

概要

属性

方法

虚拟方法

插槽

信号

注意

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

详细描述

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

你可以使用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将尝试区分大小写地匹配completion prefix（即用户开始输入的单词）与模型中第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()，因为它需要扫描整个模型。

完成模型

completionModel() 返回一个列表模型，该模型包含当前完成前缀的所有可能完成项，按照它们在模型中出现的顺序排列。此模型可用于在自定义视图中显示当前完成项。调用 setCompletionPrefix() 会自动刷新完成模型。

处理树模型

QCompleter 可以在树模型中查找补全项，假设任何项目（或子项目或子子项目）都可以通过指定项目的路径明确表示为字符串。然后逐级执行补全。

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

为了使这种补全功能正常工作，QCompleter需要能够将路径拆分为一系列字符串，以便在每个级别进行匹配。对于C:\Windows\Sy，它需要被拆分为“C:”、“Windows”和“Sy”。如果模型是QFileSystemModel，splitPath()的默认实现会使用QDir::separator()来拆分completionPrefix。

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

另请参阅

QLineEdit QComboBox 自动完成示例

class CompletionMode

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

常量

描述

QCompleter.PopupCompletion

当前的补全结果显示在弹出窗口中。

QCompleter.InlineCompletion

补全内容以内联方式显示（作为选中的文本）。

QCompleter.UnfilteredPopupCompletion

所有可能的补全选项都会显示在一个弹出窗口中，最可能的建议会显示为当前选项。

另请参阅

setCompletionMode()

class ModelSorting

此枚举指定模型中项目的排序方式。

常量

描述

QCompleter.UnsortedModel

模型未排序。

QCompleter.CaseSensitivelySortedModel

模型是区分大小写排序的。

QCompleter.CaseInsensitivelySortedModel

模型不区分大小写排序。

另请参阅

setModelSorting()

注意

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

property caseSensitivityᅟ: Qt.CaseSensitivity

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

默认值为 Qt::CaseSensitive。

Access functions:
property completionColumnᅟ: int

此属性保存模型中用于搜索补全的列。

如果popup()是一个QListView，它会自动设置为显示此列。

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

Access functions:
property completionModeᅟ: QCompleter.CompletionMode

此属性决定了如何向用户提供补全建议。

默认值为 PopupCompletion 。

Access functions:
property completionPrefixᅟ: str

此属性保存用于提供补全的补全前缀。

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

Access functions:
property completionRoleᅟ: int

此属性保存用于查询项目内容以进行匹配的项目角色。

默认角色是Qt::EditRole。

Access functions:
property filterModeᅟ: Combination of Qt.MatchFlag

此属性控制过滤的执行方式。

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

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

默认模式是 Qt::MatchStartsWith。

另请参阅

caseSensitivity

Access functions:
property maxVisibleItemsᅟ: int

此属性保存了自动补全器在屏幕上允许的最大尺寸，以项目数衡量。

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

Access functions:
property modelSortingᅟ: QCompleter.ModelSorting

此属性保存模型的排序方式。

默认情况下，不会对提供补全的模型中的项目顺序做出任何假设。

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

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

注意

当补全器的caseSensitivity与模型在排序时使用的大小写敏感性不同时，上述性能改进无法实现。

另请参阅

setCaseSensitivity() ModelSorting

Access functions:
property wrapAroundᅟ: bool

此属性控制在导航项目时完成项的环绕。

默认值为 true。

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

父对象 – QObject

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

__init__(model[, parent=None])
Parameters:

使用给定的parent构造一个完成器对象，该对象从指定的model提供完成建议。

__init__(completions[, parent=None])
Parameters:

  • completions – 字符串列表

  • parent – QObject

使用给定的parent构造一个QCompleter对象，该对象使用指定的list作为可能的补全来源。

activated(index)
Parameters:

索引 – QModelIndex

当用户激活popup()中的项目时（通过点击或按下回车键），会发送此信号。项目在completionModel()中的index会被给出。

activated(text)
Parameters:

文本 – str

当用户激活popup()中的项目时（通过点击或按下回车键），会发送此信号。项目的text会被给出。

caseSensitivity()
Return type:

CaseSensitivity

另请参阅

setCaseSensitivity()

属性 caseSensitivityᅟ 的获取器。

complete([rect=QRect()])
Parameters:

rect – QRect

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

对于InlineCompletion模式，highlighted()信号会随着当前完成项触发。

completionColumn()
Return type:

整数

另请参阅

setCompletionColumn()

属性 completionColumnᅟ 的获取器。

completionCount()
Return type:

整数

返回当前前缀的完成数量。对于一个包含大量项目的未排序模型，这可能会很昂贵。使用setCurrentRow()和currentCompletion()来遍历所有完成项。

completionMode()
Return type:

CompletionMode

另请参阅

setCompletionMode()

属性 completionModeᅟ 的获取器。

completionModel()
Return type:

QAbstractItemModel

返回完成模型。完成模型是一个只读的列表模型，包含当前完成前缀的所有可能匹配项。完成模型会自动更新以反映当前的完成情况。

注意

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

另请参阅

completionPrefix model()

completionPrefix()
Return type:

字符串

另请参阅

setCompletionPrefix()

属性 completionPrefixᅟ 的获取器。

completionRole()
Return type:

整数

另请参阅

setCompletionRole()

属性 completionRoleᅟ 的获取器。

currentCompletion()
Return type:

字符串

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

currentIndex()
Return type:

QModelIndex

返回当前完成项在completionModel()中的模型索引。

currentRow()
Return type:

整数

返回当前行。

另请参阅

setCurrentRow()

filterMode()
Return type:

MatchFlag的组合

另请参阅

setFilterMode()

属性 filterModeᅟ 的获取器。

highlighted(index)
Parameters:

索引 – QModelIndex

当用户高亮显示popup()中的项目时，会发送此信号。如果调用complete()时completionMode()设置为InlineCompletion，也会发送此信号。项目在completionModel()中的index会被给出。

highlighted(text)
Parameters:

文本 – str

当用户高亮显示popup()中的项目时，会发送此信号。如果调用complete()时completionMode()设置为InlineCompletion，也会发送此信号。项目的text会被提供。

maxVisibleItems()
Return type:

整数

另请参阅

setMaxVisibleItems()

属性 maxVisibleItemsᅟ 的获取器。

model()
Return type:

QAbstractItemModel

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

modelSorting()
Return type:

ModelSorting

另请参阅

setModelSorting()

属性 modelSortingᅟ 的获取器。

pathFromIndex(index)
Parameters:

索引 – QModelIndex

Return type:

字符串

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

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

另请参阅

splitPath()

popup()
Return type:

QAbstractItemView

返回用于显示补全的弹出窗口。

另请参阅

setPopup()

setCaseSensitivity(caseSensitivity)
Parameters:

caseSensitivity – CaseSensitivity

另请参阅

caseSensitivity()

属性 caseSensitivityᅟ 的设置器。

setCompletionColumn(column)
Parameters:

列 – int

另请参阅

completionColumn()

属性 completionColumnᅟ 的设置器。

setCompletionMode(mode)
Parameters:

mode – CompletionMode

另请参阅

completionMode()

属性 completionModeᅟ 的设置器。

setCompletionPrefix(prefix)
Parameters:

prefix – str

另请参阅

completionPrefix()

属性 completionPrefixᅟ 的设置器。

setCompletionRole(role)
Parameters:

角色 – int

另请参阅

completionRole()

属性 completionRoleᅟ 的设置器。

setCurrentRow(row)
Parameters:

行 – 整数

Return type:

布尔

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

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

setFilterMode(filterMode)
Parameters:

filterMode – MatchFlag 的组合

另请参阅

filterMode()

属性 filterModeᅟ 的设置器。

setMaxVisibleItems(maxItems)
Parameters:

maxItems – int

另请参阅

maxVisibleItems()

属性 maxVisibleItemsᅟ 的设置器。

setModel(c)
Parameters:

c – QAbstractItemModel

设置提供补全的模型为model。model可以是列表模型或树模型。如果之前已经设置了一个模型，并且它已将QCompleter作为其父对象，则该模型将被删除。

为了方便起见，如果model是QFileSystemModel，QCompleter会在Windows上将caseSensitivity切换为Qt::CaseInsensitive，在其他平台上切换为Qt::CaseSensitive。

另请参阅

completionModel() modelSorting 处理 树 模型

setModelSorting(sorting)
Parameters:

排序 – ModelSorting

另请参阅

modelSorting()

属性 modelSortingᅟ 的设置器。

setPopup(popup)
Parameters:

弹出窗口 – QAbstractItemView

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

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

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

另请参阅

popup()

setWidget(widget)
Parameters:

widget – QWidget

设置提供补全功能的小部件为widget。当使用setCompleter()在QLineEdit或QComboBox上设置QCompleter时，此函数会自动调用。在为自定义小部件提供补全功能时，需要显式设置小部件。

setWrapAround(wrap)
Parameters:

wrap – 布尔值

另请参阅

wrapAround()

属性 wrapAroundᅟ 的设置器。

splitPath(path)
Parameters:

路径 – 字符串

Return type:

字符串列表

将给定的path分割成字符串，用于在model()的每一级进行匹配。

splitPath() 的默认实现在 sourceModel() 是 QFileSystemModel 时，基于 QDir::separator() 分割文件系统路径。

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

另请参阅

pathFromIndex() 处理 树 模型

widget()
Return type:

QWidget

返回补全对象正在提供补全的小部件。

另请参阅

setWidget()

wrapAround()
Return type:

布尔

另请参阅

setWrapAround()

属性 wrapAroundᅟ 的获取器。