class QTextCursor#

类QTextCursor提供了一个用于访问和修改QTextDocuments的API。更多…

概述#

方法#

注意：

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

详细说明#

文本光标是指通过模拟文本编辑器中光标行为的编程接口来访问和修改文本内容及其底层结构的对象。 QTextCursor 包含有关光标在 QTextDocument 中的位置以及它所做的任何选择的信息。

QTextCursor 以文本编辑器中文本光标的行为模式建模，提供了一种通过用户界面执行标准操作的编程方式。可以将文档看作一个单一的字符字符串。那么，光标的当前 position() 则始终位于字符串中两个连续字符之间，或者在第一个字符的前面或最后一个字符的后面。文档除了包含文本外，还可以包含表格、列表、图像等其它对象，但是从开发者的角度来看，可以将文档视为一个长字符串。字符串的某些部分可以被认为是位于特定的块（例如段落）中，表格的单元格内，列表的项目中，或其它结构元素中。当我们提到“当前字符”时，意味着光标 position() 前面的字符。同样，“当前块”是指包含光标 position() 的块。

QTextCursor 也有一个 anchor() 位置。位于 anchor() 和 position() 之间的文本是被选定的文本。如果 anchor() 等于 position() ，则没有选择。

可以使用 setPosition() 和 movePosition() 方法来编程更改光标位置；后者还可以用来选择文本。关于选择，请参阅 selectionStart()、selectionEnd()、hasSelection()、clearSelection() 和 removeSelectedText() 方法。

如果 position() 在一个块的开始位置，atBlockStart() 返回 true；如果在块的末尾，atBlockEnd() 返回 true。由 charFormat() 返回当前字符的格式，由 blockFormat() 返回当前块的格式。

可以使用 setCharFormat()、mergeCharFormat()、setBlockFormat() 和 mergeBlockFormat() 函数对当前文本文档进行格式化。'set' 函数将替换光标当前字符或块格式，而 'merge' 函数将给定的格式属性添加到光标当前格式中。如果光标有选择，则应用给定的格式到当前选择上。注意，当只选择了块的一部分时，块格式应用于整个块。当前字符位置上的文本可以使用 createList() 转换为列表。

可以使用 deleteChar()、deletePreviousChar() 和 removeSelectedText() 实现删除。

可以使用 insertText() 函数将文本字符串插入到文档中，使用 insertBlock() 插入块（表示新段落）。

可以使用 insertFragment() 将现有的文本片段插入到文档中，但如果你想要插入包含不同格式的文本片段，通常仍然更轻松地使用 insertText() 并提供字符格式。

光标也可以将各种高级结构插入到文档中

  • 列表是有序的块元素序列，用项目符号或符号装饰。通过 insertList() 以指定格式插入。

  • 使用 insertTable() 函数插入表格，并可以提供可选的格式。这些包含单元格数组，可以使用光标遍历。

  • 使用 insertImage() 插入内联图像。可以使用图像格式或名称指定要使用的图像。

  • 通过调用指定格式的 insertFrame() 方法来插入框架。

可以使用 beginEditBlock() 和 endEditBlock() 将操作分组（即作为单个操作进行撤消/重做）。

光标移动限于有效光标位置。在拉丁语写作中，这表示文本中任意两个连续字符之间、第一个字符之前或最后一个字符之后。在某些其他书写系统中，光标移动限于“簇”（例如，达拉维语中的一个音节或基字母加上变音符号）。 movePosition() 和 deleteChar() 函数将光标移动限制在这些有效位置。

另请参阅

富文本处理

class MoveMode#

常量

描述

QTextCursor.MoveAnchor

将锚点移动到与光标本身相同的位置。

QTextCursor.KeepAnchor

保持锚点在其当前位置。

如果 anchor() 保持在其当前位置，并且 position() 移动，那么介于两者之间的文本将被选中。

class MoveOperation#

常量

描述

QTextCursor.NoMove

保持光标在当前位置

QTextCursor.Start

移动到文档的开始。

QTextCursor.StartOfLine

移动到当前行的开始。

QTextCursor.StartOfBlock

移动到当前块的开始。

QTextCursor.StartOfWord

移动到当前词的开始。

QTextCursor.PreviousBlock

移动到上一个块的开始。

QTextCursor.PreviousCharacter

移动到前一个字符。

QTextCursor.PreviousWord

移动到前一个词的开始。

QTextCursor.Up

向上移动一行。

QTextCursor.Left

向左移动一个字符。

QTextCursor.WordLeft

向左移动一个词。

QTextCursor.End

移动到文档的末尾。

QTextCursor.EndOfLine

移动到当前行的末尾。

QTextCursor.EndOfWord

移动到当前词的末尾。

QTextCursor.EndOfBlock

移动到当前块的末尾。

QTextCursor.NextBlock

移动到下一个块的开始。

QTextCursor.NextCharacter

移动到下一个字符。

QTextCursor.NextWord

移动到下一个词。

QTextCursor.Down

向下移动一行。

QTextCursor.Right

向右移动一个字符。

QTextCursor.WordRight

向右移动一个词。

QTextCursor.NextCell

将光标移动到当前表格内下一个表格单元格的开头。如果当前单元格是该行的最后一个单元格，光标将移动到下一行的第一个单元格。

QTextCursor.PreviousCell

将光标移动到当前表格内上一个表格单元格的开头。如果当前单元格是该行的第一个单元格，光标将移动到上一行的最后一个单元格。

QTextCursor.NextRow

移动到当前表格中下一行的第一个新单元格。

QTextCursor.PreviousRow

移动到当前表格中上一行的最后一个单元格。

另请参阅

movePosition()

class SelectionType#

This enum describes the types of selection that can be applied with the select() function.

常量

描述

QTextCursor.Document

Selects the entire document.

QTextCursor.BlockUnderCursor

Selects the block of text under the cursor.

QTextCursor.LineUnderCursor

Selects the line of text under the cursor.

QTextCursor.WordUnderCursor

Selects the word under the cursor. If the cursor is not positioned within a string of selectable characters, no text is selected.
__init__(document)#
参数：

document – QTextDocument

创建一个光标，该光标指向文档的开始。

__init__()

创建一个空光标。

__init__(cursor)
参数：

cursor – QTextCursor

创建一个新光标，该光标是 cursor 的副本。

__init__(frame)
参数：

frame – QTextFrame

创建一个光标，该光标指向 frame 的开始。

__init__(block)
参数：

block – QTextBlock

创建一个光标，该光标指向 block 的开始。

anchor()#
返回类型：

int

返回锚点位置；这和position()相同，除非在此处有选择，此时position()标记选择的起始位置，而anchor()标记选择的另一端。就像光标位置一样，锚点位置位于字符之间。

atBlockEnd()#
返回类型：

bool

如果光标位于段落末尾，则返回true，否则返回false。

另请参阅

atBlockStart() atEnd()

atBlockStart()#
返回类型：

bool

如果光标位于段落开头，则返回true，否则返回false。

另请参阅

atBlockEnd() atStart()

atEnd()#
返回类型：

bool

如果光标位于文档末尾，则返回true，否则返回false。

另请参阅

atStart() atBlockEnd()

atStart()#
返回类型：

bool

如果光标位于文档开头，则返回true，否则返回false。

另请参阅

atBlockStart() atEnd()

beginEditBlock()#

警告

本节包含自动从C++转换为Python的代码片段，可能包含错误。

指示对文档的编辑操作块的开始，应作为一个操作从撤销/重做点的观点显示。

例如

cursor = QTextCursor(textDocument)
cursor.beginEditBlock()
cursor.insertText("Hello")
cursor.insertText("World")
cursor.endEditBlock()
textDocument.undo()

调用undo()将会撤销两个插入操作，导致“世界”和“你好”都被移除。

可以嵌套调用beginEditBlock和endEditBlock。最顶层的成对调用将确定撤销/重做操作的范围。

另请参阅

endEditBlock()

block()#
返回类型：

QTextBlock

返回包含光标的块。

blockCharFormat()#
返回类型：

QTextCharFormat

返回光标所在块的块字符格式。

块字符格式是在在空块的开头插入文本时使用的格式。

另请参阅

setBlockCharFormat()

blockFormat()#
返回类型：

QTextBlockFormat

返回光标所在块的块格式。

blockNumber()#
返回类型：

int

返回光标所在块的编号，如果光标无效，则为0。

请注意，此功能仅在没有如表格或框架等复杂对象的文档中才有意义。

charFormat()#
返回类型：

QTextCharFormat

返回光标当前位置之前字符的格式position()。如果光标位于非空文本块的开始处，则返回光标之后字符的格式。

clearSelection()#

通过将锚点设置为光标位置来清除当前选择。

请注意，它不会删除选择文本。

columnNumber()#
返回类型：

int

返回光标在其包含行中的位置。

请注意，这是相对于换行符的列号，而不是相对于块（即段落）。

你可能想要调用positionInBlock()代替。

另请参阅

positionInBlock()

createList(style)#
参数：

style - Style

返回类型：

QTextList

这是一个重载函数。

创建并返回一个新的列表，该列表具有给定的style，并将光标当前段落作为第一个列表项。

使用的样式由Style枚举定义。

createList(format)
参数：

format - QTextListFormat

返回类型：

QTextList

创建并返回一个具有给定format的新列表，并将当前段落作为光标所在处的第一列表项。

currentFrame()#
返回类型：

QTextFrame

返回当前框架的指针。如果光标无效，返回None。

另请参阅

insertFrame()

currentList()#
返回类型：

QTextList

如果光标的position()位于列表的一部分块内，则返回当前列表；否则返回None。

另请参阅

insertList() createList()

currentTable()#
返回类型：

QTextTable

如果光标当前所在的块是表格的一部分，则返回当前表格的指针；否则返回None。

另请参阅

insertTable()

deleteChar()#

如果没有选中任何文本，则删除当前光标位置处的字符；否则删除选中的文本。

deletePreviousChar()#

如果没有选中任何文本，则删除当前光标位置之前处的字符；否则删除选中的文本。

另请参阅

deleteChar()

document()#
返回类型：

QTextDocument

返回与该光标关联的文档。

endEditBlock()#

表示文档上应被视为单个操作的编辑块的结束，从撤销/重做角度考虑。

另请参阅

beginEditBlock()

hasComplexSelection()#
返回类型：

bool

如果光标包含的选中区域不是简单的从selectionStart()

复杂选择是指跨越表格中至少两个单元格的选择；其范围由selectedTableCells()指定。

hasSelection()#
返回类型：

bool

如果光标包含选中区域，则返回true；否则返回false。

insertBlock(format, charFormat)#
参数：

这是一个重载函数。

在当前光标 position() 位置插入一个新的空段落，段落格式为 format，段落字符格式为 charFormat。

另请参阅

setBlockFormat()

insertBlock(format)
参数：

格式 – QTextBlockFormat

这是一个重载函数。

在当前光标 position() 位置插入一个新的空段落，段落格式为 format，段落字符格式为当前 charFormat()。

另请参阅

setBlockFormat()

insertBlock()

在当前光标 position() 位置插入一个新的空段落，段落格式为当前 blockFormat() 和 charFormat() 。

另请参阅

setBlockFormat()

insertFragment(fragment)#
参数：

fragment – QTextDocumentFragment

在当前光标 position() 位置插入文本 fragment。

insertFrame(format)#
参数：

format – QTextFrameFormat

返回类型：

QTextFrame

在当前光标 position() 位置插入具有给定 format 的框架，将光标移动到框架内部，并返回该框架。

如果光标有选择内容，则整个选择内容将被移动到框架内部。

另请参阅

hasSelection()

insertHtml(html)#
参数：

html – 字符串

在当前position()位置插入文本html。该文本被解释为HTML。

注意：

当与样式表一起使用此函数时，样式表将仅应用于文档中的当前块。若要应用整个文档的样式表，请使用setDefaultStyleSheet()。

insertImage(image[, name=""])#
参数：

  • image – QImage

  • name – str

这是一个重载函数。

这是一个为在当前position()位置插入给定图像并可选地设置名称的便捷函数。

insertImage(name)
参数：

name – str

警告

本节包含自动从C++转换为Python的代码片段，可能包含错误。

这是一个重载函数。

这是一个便捷方法，用于在当前position()位置插入具有给定名称的图像。

img = QImage()
textDocument.addResource(QTextDocument.ImageResource, QUrl("myimage"), img)
cursor.insertImage("myimage")
insertImage(format)
参数：

format – QTextImageFormat

在当前position()位置插入由format定义的图像。

insertImage(format, alignment)
参数：

这是一个重载函数。

在当前光标位置插入由指定alignment定义的图像。

另请参阅

position()

insertList(style)#
参数：

style - Style

返回类型：

QTextList

这是一个重载函数。

在当前位置插入新的块，并将其设置为具有给定style的新创建列表的第一个列表项。返回创建的列表。

insertList(format)
参数：

format - QTextListFormat

返回类型：

QTextList

在新位置插入一个新块，并将其设置为使用给定 format 创建的新列表的第一个列表项。返回创建的列表。

insertMarkdown(markdown[, features=QTextDocument.MarkdownDialectGitHub])#
参数：

在当前 position() 位置插入 markdown 文本，并使用指定的 Markdown features。默认为 GitHub 语法。

insertTable(rows, cols, format)#
参数：
返回类型：

QTextTable

以指定的 rows 和 columns 创建新表格，将其插入文档当前光标 position() 位置，并返回表格对象。光标将被移动到第一行的开头。

表格中至少必须有一行和一列。

另请参阅

currentTable()

insertTable(rows, cols)
参数：

  • rows – 整数

  • cols – 整数

返回类型：

QTextTable

这是一个重载函数。

以指定的 rows 和 columns 创建新表格，将其插入文档当前光标 position() 位置，并返回表格对象。光标将被移动到第一行的开头。

表格中至少必须有一行和一列。

另请参阅

currentTable()

insertText(text)#
参数：

text – 字符串

警告

本节包含自动从C++转换为Python的代码片段，可能包含错误。

使用当前字符格式在当前位置插入 text。

如果有选择，则删除选择并使用 text 替换，例如

cursor.clearSelection()
cursor.movePosition(QTextCursor.NextWord, QTextCursor.KeepAnchor)
cursor.insertText("Hello World")

这将清除任何现有的选择，选择光标处的单词（即从 position() 至前），并将选择替换为短语“Hello World”。

插入文本中任何ASCII回车符（\n）都被转换为Unicode块分隔符，对应于 insertBlock() 调用。

insertText(text, format)
参数：

这是一个重载函数。

在当前位置插入 text，并应用给定的 format。

isCopyOf(other)#
参数：

other – QTextCursor

返回类型：

bool

如果此光标和 other 是彼此的副本，即其中一个被创建为另一个的副本，并且都没有移动过，则返回 true。这比相等性要严格得多。

另请参阅

operator=() operator==()

isNull()#
返回类型：

bool

如果光标为空，则返回 true；否则返回 false。空光标是通过默认构造函数创建的。

joinPreviousEditBlock()#

警告

本节包含自动从C++转换为Python的代码片段，可能包含错误。

类似于 beginEditBlock() 表示一组编辑操作的开始，这组操作应被视为单个操作进行撤销/重做。然而，与 beginEditBlock() 不同，它并不开始一个新块，而是反转了之前对 endEditBlock() 的调用，因此使后续操作成为之前创建的编辑块的一部分。

例如

cursor = QTextCursor(textDocument)
cursor.beginEditBlock()
cursor.insertText("Hello")
cursor.insertText("World")
cursor.endEditBlock()
# ...
cursor.joinPreviousEditBlock()
cursor.insertText("Hey")
cursor.endEditBlock()
textDocument.undo()

调用撤销()将导致所有三次插入操作都被撤销。

keepPositionOnInsert()#
返回类型：

bool

返回当文本插入到光标位置时，光标是否应保持其当前位置。

默认为false;

mergeBlockCharFormat(modifier)#
参数：

modifier – QTextCharFormat

使用由 modifier 指定的块格式修改当前块的字符格式（或包含在选择中的所有块的字符格式）。

另请参阅

setBlockCharFormat()

mergeBlockFormat(modifier)#
参数：

modifier – QTextBlockFormat

使用由 modifier 指定的块格式修改当前块的格式（或包含在选择中的所有块的格式）。

mergeCharFormat(modifier)#
参数：

modifier – QTextCharFormat

将光标的当前字符格式与格式 modifier 描述的属性合并。如果光标有选择，则此函数将 modifier 中设置的属性应用于选择中所有字符格式。

movePosition(op[, arg__2=QTextCursor.MoveMode.MoveAnchor[, n=1]])#
参数：
返回类型：

bool

通过执行给定的 operation 操作 n 次，使用指定的 mode，移动光标，如果所有操作都成功完成，则返回 true；否则返回 false。

例如，如果这个函数被反复用于跳转到下一个单词的末尾，当到达文档末尾时最终会失败。

默认情况下，移动操作只执行一次（n = 1）。

如果 mode 是 KeepAnchor，则光标选择它所移动过的文本。这和使用者按下 Shift 键并使用光标键移动光标时达到的效果相同。

另请参阅

setVisualNavigation()

__ne__(rhs)#
参数：

rhs – QTextCursor

返回类型：

bool

如果 other 光标在文档中的位置与该光标不同，则返回 true；否则返回 false。

__lt__(rhs)#
参数：

rhs – QTextCursor

返回类型：

bool

如果 other 光标在文档中比该光标位置靠后，则返回 true；否则返回 false。

__le__(rhs)#
参数：

rhs – QTextCursor

返回类型：

bool

如果 other 光标在文档中的位置比该光标靠后或相同，则返回 true；否则返回 false。

__eq__(rhs)#
参数：

rhs – QTextCursor

返回类型：

bool

如果 other 光标在文档中的位置与该光标相同，则返回 true；否则返回 false。

__gt__(rhs)#
参数：

rhs – QTextCursor

返回类型：

bool

如果 other 光标在文档中的位置比该光标靠前，则返回 true；否则返回 false。

__ge__(rhs)#
参数：

rhs – QTextCursor

返回类型：

bool

如果 other 光标在文档中的位置比该光标靠前或相同，则返回 true；否则返回 false。

position()#
返回类型：

int

返回光标在文档中的绝对位置。光标位于字符之间。

注意：

本例中的“字符”指QChar对象的字符串，即16位Unicode字符，位置被视为对该字符串的索引。这不一定对应于书写系统中的单个语素，因为单个语素可能由多个Unicode字符表示，例如代理对、文字连接或变音符号。

另请参阅

setPosition() movePosition() anchor() positionInBlock()

positionInBlock()#
返回类型：

int

返回光标在块内的相对位置。光标位于字符之间。

等同于 position() - block().position()。

注意：

本例中的“字符”指QChar对象的字符串，即16位Unicode字符，位置被视为对该字符串的索引。这不一定对应于书写系统中的单个语素，因为单个语素可能由多个Unicode字符表示，例如代理对、文字连接或变音符号。

另请参阅

position()

removeSelectedText()#

如果存在选择，则删除其内容；否则不执行任何操作。

另请参阅

hasSelection()

select(selection)#
参数：

selection – SelectionType

根据给定的 selection 选择文档中的文本。

selectedTableCells()#
返回类型：

PyObject

如果选择跨越了表格单元格，firstRow 将填充选择中的第一行的编号，firstColumn 将填充选择中的第一列的编号，而 numRows 和 numColumns 将填充选择中的行数和列数。如果选择没有跨越任何表格单元格，则结果是无害但未定义的。

selectedText()#
返回类型：

str

返回当前选择的文本（可能为空）。这仅返回文本，不包含丰富的文本格式化信息。如果您想要文档片段（即格式化的丰富文本），请使用 selection() 代替。

注意：

如果从编辑器中获得的选择跨越了换行符，则文本将包含Unicode U+2029段分隔符字符而不是换行符 \n。请使用 QString::replace() 将这些字符替换为换行符。

selection()#
返回类型：

QTextDocumentFragment

返回当前选择的内容（可能是空的）及其所有格式信息。如果你只想获取选定的文本（即纯文本），请使用 selectedText()。

注意：

与toPlainText() 不同，selectedText() 可包含特殊的 Unicode 字符，例如 QChar::ParagraphSeparator。

另请参阅

toPlainText()

selectionEnd()#
返回类型：

int

返回选择内容的结尾，或者如果光标没有选择，则返回 position()。

selectionStart()#
返回类型：

int

返回选择内容的开始位置，如果光标没有选择，则返回 position()。

setBlockCharFormat(format)#
参数：

format – QTextCharFormat

设置当前块（或选择中包含的所有块）的块字符格式为 format。

另请参阅

blockCharFormat()

setBlockFormat(format)#
参数：

格式 – QTextBlockFormat

设置当前块（或选择中包含的所有块）的块格式为 format。

setCharFormat(format)#
参数：

format – QTextCharFormat

将光标的当前字符格式设置为给定的 format。如果光标有选择项，则给定的 format 将应用于当前选择的内容。

setKeepPositionOnInsert(b)#
参数：

b – bool

定义光标在插入文本时是否应保持其当前位置。

当 b 为真时，当文本在光标当前位置插入时，光标保持其当前位置。当 b 为假时，光标会跟随插入的文本一起移动。

默认值为 false。

请注意，当文本在光标当前位置之前插入时，光标总是会移动，而插入光标当前位置之后时，它总是保持当前位置。

另请参阅

keepPositionOnInsert()

setPosition(pos[, mode=QTextCursor.MoveMode.MoveAnchor])#
参数：

使用指定的 MoveMode 将光标移动到由 pos 指定的文档中的绝对位置。光标定位在字符之间。

注意：

这里的“字符”指的是 QChar 对象的序列，即 16 位 Unicode 字符，而 pos 被视为该字符串中的索引。这并不一定对应于某种书写系统中的单个字符图形，因为单个字符图形可能由多个 Unicode 字符表示，比如代理对、语言连字符或变音符号。为了更通用地遍历文档，请使用 movePosition()，它将尊重文本中的实际字符图形边界。

另请参阅

position() movePosition() anchor()

setVerticalMovementX(x)#
参数：

x – int

设置垂直光标移动的视觉X位置为 x。

当光标水平移动时，自动清除垂直移动的X位置，当光标垂直移动时保持不变。这种机制允许光标在比例字体中沿着视觉上的直线上下移动，并且可以轻柔地“跳过”短行。

-1的值表示没有预定义的X位置。然后在下一次光标上下移动时将其自动设置。

另请参阅

verticalMovementX()

setVisualNavigation(b)#
参数：

b – bool

设置视觉导航为 b。

视觉导航表示跳过隐藏的文本段落。默认为false。

swap(other)#
参数：

other – QTextCursor

与 other 交换此文本光标实例。此函数非常快，永远不会失败。

verticalMovementX()#
返回类型：

int

返回垂直光标移动的视觉X位置。

-1的值表示没有预定义的X位置。然后在下一次光标上下移动时将其自动设置。

另请参阅

setVerticalMovementX()

visualNavigation()#
返回类型：

bool

如果光标进行视觉导航，则返回 true；否则返回 false。

视觉导航表示跳过隐藏的文本段落。默认为false。