PySide6.QtGui.QTextCursor

class QTextCursor

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

概要

方法

注意

本文档可能包含从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

此枚举描述了可以使用select()函数应用的选择类型。

常量

描述

QTextCursor.Document

选择整个文档。

QTextCursor.BlockUnderCursor

选择光标下的文本块。

QTextCursor.LineUnderCursor

选择光标下的文本行。

QTextCursor.WordUnderCursor

选择光标下的单词。如果光标没有定位在可选字符的字符串中，则不选择任何文本。
__init__()

构造一个空游标。

__init__(document)
Parameters:

文档 – QTextDocument

构造一个指向document开头的游标。

__init__(frame)
Parameters:

框架 – QTextFrame

构造一个指向frame开头的游标。

__init__(block)
Parameters:

块 – QTextBlock

构造一个指向block开头的游标。

__init__(cursor)
Parameters:

光标 – QTextCursor

构造一个新的游标，它是cursor的副本。

anchor()
Return type:

整数

返回锚点位置；这与position()相同，除非存在选择，在这种情况下position()标记选择的一端，而anchor()标记另一端。就像光标位置一样，锚点位置位于字符之间。

atBlockEnd()
Return type:

布尔

如果光标位于块的末尾，则返回true；否则返回false。

另请参阅

atBlockStart() atEnd()

atBlockStart()
Return type:

布尔

如果光标位于块的开始处，则返回true；否则返回false。

另请参阅

atBlockEnd() atStart()

atEnd()
Return type:

布尔

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

另请参阅

atStart() atBlockEnd()

atStart()
Return type:

布尔

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

另请参阅

atBlockStart() atEnd()

beginEditBlock()

警告

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

表示文档上编辑操作块的开始，这些操作从撤销/重做的角度来看应显示为单个操作。

例如：

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

调用undo()将导致两个插入操作被撤销，从而使“World”和“Hello”都被移除。

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

另请参阅

endEditBlock()

block()
Return type:

QTextBlock

返回包含光标的块。

blockCharFormat()
Return type:

QTextCharFormat

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

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

另请参阅

setBlockCharFormat()

blockFormat()
Return type:

QTextBlockFormat

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

blockNumber()
Return type:

整数

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

请注意，此函数仅在文档中没有复杂对象（如表格或框架）时才有意义。

charFormat()
Return type:

QTextCharFormat

返回光标前一个字符的格式position()。如果光标位于非空文本块的开头，则返回光标后一个字符的格式。

clearSelection()

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

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

columnNumber()
Return type:

整数

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

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

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

另请参阅

positionInBlock()

createList(style)
Parameters:

样式 – Style

Return type:

QTextList

这是一个重载函数。

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

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

createList(format)
Parameters:

格式 – QTextListFormat

Return type:

QTextList

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

currentFrame()
Return type:

QTextFrame

返回指向当前帧的指针。如果光标无效，则返回None。

另请参阅

insertFrame()

currentList()
Return type:

QTextList

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

另请参阅

insertList() createList()

currentTable()
Return type:

QTextTable

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

另请参阅

insertTable()

deleteChar()

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

deletePreviousChar()

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

document()
Return type:

QTextDocument

返回与此游标关联的文档。

endEditBlock()

表示文档上编辑操作块的结束，从撤销/重做的角度来看，这些操作应显示为单个操作。

另请参阅

beginEditBlock()

hasComplexSelection()
Return type:

布尔

如果光标包含的选择不仅仅是从selectionStart()到selectionEnd()的范围，则返回true；否则返回false。

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

hasSelection()
Return type:

布尔

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

insertBlock()

在光标position()处插入一个新的空块，使用当前的blockFormat()和charFormat()。

另请参阅

setBlockFormat()

insertBlock(format)
Parameters:

格式 – QTextBlockFormat

这是一个重载函数。

在光标position()处插入一个新的空块，使用块格式format和当前的charFormat()作为块字符格式。

另请参阅

setBlockFormat()

insertBlock(format, charFormat)
Parameters:

这是一个重载函数。

在光标position()处插入一个新的空块，块格式为format，块字符格式为charFormat。

另请参阅

setBlockFormat()

insertFragment(fragment)
Parameters:

片段 – QTextDocumentFragment

在当前position()插入文本fragment。

insertFrame(format)
Parameters:

格式 – QTextFrameFormat

Return type:

QTextFrame

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

如果光标包含一个选择，整个选择将被移动到框架内。

另请参阅

hasSelection()

insertHtml(html)
Parameters:

html – 字符串

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

注意

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

insertImage(name)
Parameters:

name – str

警告

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

这是一个重载函数。

用于在当前position()插入具有给定name的图像的便捷方法。

img = QImage()
textDocument.addResource(QTextDocument.ImageResource, QUrl("myimage"), img)
cursor.insertImage("myimage")
insertImage(format)
Parameters:

格式 – QTextImageFormat

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

insertImage(image[, name=""])
Parameters:

  • image – QImage

  • name – str

这是一个重载函数。

用于在当前position()插入给定image的便捷函数，可选择性地包含name。

insertImage(format, alignment)
Parameters:

这是一个重载函数。

在光标的当前位置插入由给定的format定义的图像，并使用指定的alignment对齐。

另请参阅

position()

insertList(style)
Parameters:

样式 – Style

Return type:

QTextList

这是一个重载函数。

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

insertList(format)
Parameters:

格式 – QTextListFormat

Return type:

QTextList

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

insertMarkdown(markdown[, features=QTextDocument.MarkdownDialectGitHub])
Parameters:

在当前position()插入markdown文本，使用指定的Markdownfeatures。默认为GitHub方言。

insertTable(rows, cols)
Parameters:

  • rows – int

  • cols – 整数

Return type:

QTextTable

这是一个重载函数。

创建一个具有给定行数和列数的新表格，将其插入文档中当前光标position()的位置，并返回表格对象。光标将移动到第一个单元格的开头。

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

另请参阅

currentTable()

insertTable(rows, cols, format)
Parameters:
Return type:

QTextTable

在指定的format中创建一个具有给定数量的rows和columns的新表格，将其插入到文档中当前光标position()的位置，并返回表格对象。光标将移动到第一个单元格的开头。

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

另请参阅

currentTable()

insertText(text)
Parameters:

文本 – str

警告

本节包含从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)
Parameters:

这是一个重载函数。

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

isCopyOf(other)
Parameters:

其他 – QTextCursor

Return type:

布尔

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

另请参阅

operator=() operator==()

isNull()
Return type:

布尔

如果游标为空，则返回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()

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

keepPositionOnInsert()
Return type:

布尔

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

默认值为 false;

mergeBlockCharFormat(modifier)
Parameters:

修饰符 – QTextCharFormat

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

另请参阅

setBlockCharFormat()

mergeBlockFormat(modifier)
Parameters:

修饰符 – QTextBlockFormat

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

mergeCharFormat(modifier)
Parameters:

modifier – QTextCharFormat

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

movePosition(op[, mode=QTextCursor.MoveMode.MoveAnchor[, n=1]])
Parameters:
Return type:

布尔

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

例如，如果此函数重复用于查找下一个单词的末尾，当到达文档末尾时，它最终将失败。

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

如果 mode 是 KeepAnchor，光标会选择它移动过的文本。这与用户按住 Shift 键并使用光标键移动光标时产生的效果相同。

另请参阅

setVisualNavigation()

__ne__(rhs)
Parameters:

rhs – QTextCursor

Return type:

布尔

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

__lt__(rhs)
Parameters:

rhs – QTextCursor

Return type:

布尔

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

__le__(rhs)
Parameters:

rhs – QTextCursor

Return type:

布尔

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

__eq__(rhs)
Parameters:

rhs – QTextCursor

Return type:

布尔

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

__gt__(rhs)
Parameters:

rhs – QTextCursor

Return type:

布尔

如果other光标在文档中的位置早于此光标，则返回true；否则返回false。

__ge__(rhs)
Parameters:

rhs – QTextCursor

Return type:

布尔

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

position()
Return type:

整数

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

注意

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

另请参阅

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

positionInBlock()
Return type:

整数

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

这相当于 position() - block().position()。

注意

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

另请参阅

position()

removeSelectedText()

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

另请参阅

hasSelection()

select(selection)
Parameters:

选择 – SelectionType

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

selectedTableCells()
Return type:

PyObject

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

selectedText()
Return type:

字符串

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

注意

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

selection()
Return type:

QTextDocumentFragment

返回当前选择（可能为空）及其所有格式信息。如果您只需要选定的文本（即纯文本），请改用selectedText()。

注意

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

另请参阅

toPlainText()

selectionEnd()
Return type:

整数

返回选择的结束位置，如果光标没有选择，则返回position()。

selectionStart()
Return type:

整数

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

setBlockCharFormat(format)
Parameters:

format – QTextCharFormat

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

另请参阅

blockCharFormat()

setBlockFormat(format)
Parameters:

格式 – QTextBlockFormat

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

setCharFormat(format)
Parameters:

format – QTextCharFormat

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

setKeepPositionOnInsert(b)
Parameters:

b – 布尔值

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

如果 b 为真，当文本插入到光标位置时，光标保持其当前位置。如果 b 为假，光标会随着插入的文本移动。

默认值为 false。

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

另请参阅

keepPositionOnInsert()

setPosition(pos[, mode=QTextCursor.MoveMode.MoveAnchor])
Parameters:

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

注意

在这种情况下，“字符”指的是QChar对象的字符串，即16位Unicode字符，pos被视为该字符串的索引。这不一定对应于书写系统中的单个字形，因为单个字形可能由多个Unicode字符表示，例如代理对、语言连字或变音符号。对于更通用的文档导航方法，请使用movePosition()，它将尊重文本中的实际字形边界。

另请参阅

position() movePosition() anchor()

setVerticalMovementX(x)
Parameters:

x – 整数

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

当光标水平移动时，垂直移动的x位置会自动清除，而当光标垂直移动时，垂直移动的x位置保持不变。这种机制允许光标在视觉上保持直线移动，即使使用比例字体，并且可以轻松地“跳过”短行。

值为-1表示没有预定义的x位置。它将在下次光标上下移动时自动设置。

另请参阅

verticalMovementX()

setVisualNavigation(b)
Parameters:

b – 布尔值

将视觉导航设置为 b。

视觉导航意味着跳过隐藏的文本段落。默认值为 false。

swap(other)
Parameters:

其他 – QTextCursor

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

verticalMovementX()
Return type:

整数

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

值为-1表示没有预定义的x位置。它将在下次光标上下移动时自动设置。

另请参阅

setVerticalMovementX()

visualNavigation()
Return type:

布尔

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

视觉导航意味着跳过隐藏的文本段落。默认值为 false。