PyQt（Python+Qt）学习随笔：富文本编辑器QTextEdit功能详解

• 专栏：Python基础教程目录
• 专栏：使用PyQt开发图形界面Python应用
• 专栏：PyQt入门学习
• 老猿Python博文目录

一、概述

QTextEdit是一个高级的所见即所得的文档查看器和编辑器，支持使用HTML4样式标记的富文本格式，可以显示图像、列表和表格。

PyQt的富文本处理提供了一系列丰富的类，包括QTextEdit、QTextDocument、QTextCharFormat、QTextCursor、QTextBlock、QTextList、QTextFrame、QTextTable、QTextBlockFormat、QTextListFormat、QTextFrameFormat、QTextTableFormat等，如果要介绍清楚需要花比较多的时间，同时鉴于HTML的处理方面，可以利用Python中BeautifulSoup模块强大的功能解析和编辑（可以参见老猿Python的爬虫专题），因此本部分不进行详细介绍。推荐大家按如下几篇文章了解：

• 《Qt富文本编辑器QTextDocument》
• QTextEdit和QTextDocument
• Qt之文本编辑

二、属性

文本编辑QTextEdit在Designer中可以设置的属性如下：

• autoFormatting：autoFormatting属性用于控制启用自动格式化功能，其类型为枚举类型AutoFormattingFlag，默认值为AutoNone即不起用，当设置为AutoBulletList时，当用户在最左边的列中输入星号（“*”）或在现有列表项中按Enter键时，自动创建项目符号列表，设置为AutoAll目前与AutoBulletList相同，以后可能会有更多的扩展。该属性可以使用方法autoFormatting() 、setAutoFormatting（）来访问。
• tabChangesFocus：tabChangesFocus属性控制tab键是否更改焦点还是接受为输入。在某些情况下，文本编辑不应允许用户使用Tab键输入制表符或更改缩进，因为这样会打断焦点链，默认值为False，可通过tabChangesFocus()和setTabChangesFocus（）方法来访问
• documentTitle：documentTitle属性保留从文本中分析的文档标题（ 通过HTML标记 ）。默认情况下，对于新创建的空文档，此属性包含空字符串。可以通过方法documentTitle()、setDocumentTitle()来访问。
• undoRedoEnabled：undoRedoEnabled属性用于控制是否启用undo和redo，默认是启用，可以通过方法isUndoRedoEnabled（）、setUndoRedoEnabled（）来访问
• lineWrapMode：lineWrapMode属性用于控制换行模式，其类型为枚举类型QTextEdit.LineWrapMode，缺省值为WidgetWidth，表示以词为单位在编辑器右边换行，换行出现在空白处，保持整个单词的完整性。可以调用方法lineWrapMode()、setLineWrapMode(）来访问该属性。如果设置换行模式为FixedPixelWidth 或 FixedColumnWidth ，同时需要调用setLineWrapColumnOrWidth()方法设置换行的像素宽度或字符数宽度，这两种模式不会保持单词的完整性
• readOnly：readOnly 用于控制编辑器内是否只读，默认为False，可以通过isReadOnly()、setReadOnly(）进行访问
• html：html属性提供一个将编辑器内的文本转换成html文本的接口，实际上在此设置的是一段具有完整head、html、body等tag要素的html格式化文字，如果内容不完整或语法错误就会用缺省的html文本代替。使用toHtml()将编辑器中的文字插入到html属性对应的html文本的body内，可能会根据编辑器显示文本的内容增加对应的标签，因此如果要在编辑器中输入HTML文本时，html文档基本格式的相关标签文本不要输入，输入了也没有用，因为编辑器会将相关手工输入内容全部作为纯文本处理。使用setHtml()可以修改该属性，但并不是简单将输入内容替换为该属性的值，而是将参数的内容进行解析去标签后存放在编辑器中，类似于浏览器读取html文档一样显示，同时将非显示内容的标准HTML文档基本框架格式保存到html属性中，期间大量参数中的html标签会去除，如div的标签中的内容是纯文字，则div可能就不会保存，文字作为普通文字显示，再调用toHtml时也不会恢复这个div标签，而是可能将其换成了p标签。具体情况比较复杂，老猿也没有仔细研究
• overwriteMode：overwriteMode属性用于控制用户输入文本是否替换现有文本，如果为True，则输入字符从当前光标位置开始逐一替换当前的字符，为False则在光标处插入输入字符。缺省值为False，可以通过方法overwriteMode()、setOverwriteMode(）进行访问
• tabStopWidth：tabStopWidth属性用于控制编辑器中输入tab键时移动的像素数，默认值为80像素，可以通过方法tabStopWidth()、setTabStopWidth（）来访问，不过该属性在Qt 5.10以后版本中被下面的tabStopDistance所替代，在5.13的文档中就没有该属性，但实际上类方法还是支持的，tabStopWidth与tabStopDistance的唯一区别是前者为整型、后者为浮点数，更精确，在Designer中二者的值也是联动的，tabStopWidth改变直接修改tabStopDistance为tabStopWidth的值，如果tabStopDistance值改变，则将tabStopDistance四舍五入后的值作为tabStopWidth的值，最终生成的代码使用的是tabStopDistance
• acceptRichText：acceptRichText属性用于控制编辑器是否接受用户的富文本插入（例如通过剪贴板或拖放），当此属性设置为False文本时，编辑器只接受来自用户的纯文本输入。缺省值为True，可以通过acceptRichText() 、setAcceptRichText（）方法访问
• cursorWidth：cursorWidth用于设置编辑器光标的像素为单位的宽度，缺省值为1，可通过方法cursorWidth() 、setCursorWidth（）来访问
• textInteractionFlags：textInteractionFlags属性用于控制编辑器怎么响应用户的输入，其类型为Qt.TextInteractionFlags，用于控制编辑器是否可键盘或鼠标选择文本、是否可编辑、链接是否鼠标或键盘访问等，缺省值依赖于编辑器是否只读或者是否派生类QTextBrowser对象，可通过textInteractionFlags()、setTextInteractionFlags（）方法访问，具体枚举类型值参考官方文档
• placeholderText：placeholderText为编辑器的占位符，当编辑器中无文字时以灰色显示在编辑器中，一旦输入字符自动清除，可通过方法placeholderText（）、setPlaceholderText（）访问

除了Designer中可以设置的属性外，QLineEdit还有个plainText属性：

• plainText：plainText属性用于保存编辑器中的纯文本，调用toPlainText()会返回编辑器中的纯文本，如果文本编辑具有其他内容类型（如html标记），调用toPlainText（）不会将内容转换为纯文本，唯一例外是会将 （non-break space， 在HTML中表示1个空格）替换为空格，可以调用setPlainText（）方法修改该属性的值。请参考《PyQt（Python+Qt）学习随笔：QTextEdit的setText、setHtml、setPlainText之间的区别》

三、重要方法

下面复杂的方法会介绍调用语法，不复杂的方法就不介绍调用语法，大家可以官方文档速查：

• append方法
  append方法是个槽方法，该方法是在编辑器的最后新加一段参数对应的文本，该段文本的格式与当前光标所在段相同。调用语法：append(str text)
• canPaste()方法：用于返回是否可以从剪切板中粘贴文本到编辑器中
• clear()方法：槽方法，清楚编辑器中所有文本，redo/undo历史也会被清除
• copy方法：槽方法，用于将编辑器中选中文本拷贝到剪切板中
• createStandardContextMenu方法：
  这个方法都用于创建在编辑器中使用鼠标右键时显示的弹出菜单，只不过有带参和不带参的两种调用方式，带参数的是在文档中指定位置弹出，这样可以实现在编辑器的不同位置会弹出不同的快捷菜单。调用语法：createStandardContextMenu()、createStandardContextMenu(QPoint position)
• currentCharFormat()方法：返回当前的字符格式，其类型为QTextCharFormat，QTextCharFormat用于控制QTextEdit中的文本格式（这些文本的存储类型为QTextDocument对象，可以通过QTextEdit的document()方法获取，关于QTextCharFormat和QTextDocument对象在本文中不详细介绍），这些文本格式控制信息用于指定文本的一些可视化格式，如同超文本中的可视化格式控制信息
• cursorForPosition()方法：返回指定位置的QTextCursor文本光标对象，QTextCursor文本光标是通过模拟文本编辑器中光标行为的编程接口，用于访问和修改文本文档的内容和底层结构的对象。QTextCursor包含有关光标在QTextDocument中的位置及其所做的任何选择的信息。QTextCursor是根据文本光标在文本编辑器中的行为方式建模的，它提供了通过用户界面执行标准操作的编程方法。
• document()方法：document方法返回文本编辑器依赖的QTextDocument文档管理对象，通过该对象可以对文本进行丰富的操作
• ensureCursorVisible()方法：使用该方法确保编辑器中的光标可见，如果当前不可见则可以滚动文本
• find（）方法：在编辑器中查找指定字符串，调用语法：
• bool find(str exp, QTextDocument.FindFlags options =
  QTextDocument.FindFlags())
• bool find(QRegExp exp, QTextDocument.FindFlags options =
  QTextDocument.FindFlags())

其中的exp可以是普通字符串，也可是QRegExp 类型的正则表达式，其中options用于指定是向前或向后查找、查找时是否匹配大小写、是否整词匹配，具体取值请参考官方文档。当exp为正则表达式则是否匹配大小写的选项被忽略，而是由正则表达式来控制是否匹配大小写

• insertHtml()方法：将参数给定文本按照HTML文本处理插入当前位置
• insertPlainText()方法：将参数给定文本插入当前位置
• moveCursor()方法：控制编辑器中光标进行移动，调用语法：moveCursor(operation, mode = QTextCursor.MoveAnchor)，其中operation为枚举类型QTextCursor.MoveOperation，用于控制光标的移动方式，如移动到文档开始、移动到行首等，具体取值参考官方文档，mode 为枚举类型QTextCursor.MoveMode，具体取值参考官方文档
• paste()方法：paste是槽方法，将剪切板的文本拷贝到当前位置
• redo()、undo()方法：undo、redo是槽方法，undo（）方法执行后可以使用redo重新执行最后一次的操作
• selectAll()方法：selectAll是槽方法，选择所有文本
• setCurrentCharFormat（）方法：设置文本格式控制信息，调用语法：setCurrentCharFormat(QTextCharFormat format)
• setTextBackgroundColor（）方法：setTextBackgroundColor是槽方法，设置背景色，可以通过textBackgroundColor（）方法获取对应值
• setTextColor（）方法：setTextColor是槽方法，设置文本颜色，可以通过textColor()获取对应值
• • setTextCursor（）方法：setTextCursor方法用于设置当前可见的光标对象，调用语法：setTextCursor(QTextCursor cursor)，当前光标对象可通过textCursor()方法获取
• zoomIn（）、zoomOut（）方法：两者都是槽方法，放大或缩小文本字体的大小指定参数大小，基本字体大小可以通过setFontPointSize设置

四、信号

• copyAvailable(bool yes)：当文本被选中或去选中时发射该信号，表示是否可拷贝，选中是yes为True，去选中时为False
• currentCharFormatChanged(QTextCharFormat f)：当前文本格式控制被改变时发射本信号
• cursorPositionChanged()：光标位置改变时发射该信号
• redoAvailable(bool available)：当redo的状态发生变化时发射该信号
• :selectionChanged（）：当选择文本发生变化时发射该信号
• textChanged()：当文本内容发生变化时发射该信号
• undoAvailable(bool available)：当undo的状态发生变化时发射该信号

五、小结

QTextEdit是一个所见即能得的富文本编辑器，可以使用setHtml（）设置或替换文本，可以使用clear（）删除整个文本。文本本身可以使用QTextCursor类或使用便利函数insertHtml（）、insertPlainText（）、append（）或paste（）插入。QTextCursor还可以将复杂的对象（如表或列表）插入到文档中，默认情况下，文本编辑以空白换行以适应文本编辑部件。
QTextEdit中的文本对象依赖于QTextDocument类进行管理，QTextDocument类借助QTextCursor可以对文本进行丰富的操作。但限于时间和篇幅，本文并没有对QTextDocument和QTextCursor进行详细介绍。大家可以参考老猿提供的参考文档或者官网文档。

老猿Python，跟老猿学Python!

• 专栏：Python基础教程目录
• 专栏：使用PyQt开发图形界面Python应用
• 专栏：PyQt入门学习
• 老猿Python博文目录