Qt开发专栏：开发技术（点击传送门）

《Qt开发技术：Qt富文本（一）富文本介绍、文档结构》

《Qt开发技术：Qt富文本（二）Qt文本光标操作、文档布局、富文本编辑、处理和Demo》

《Qt开发技术：Qt富文本（三）Qt支持的HTML子集（查询手册）以及涉及的类》

前话

     红胖子，来也！

     Qt的富文本技术介绍，Qt5.9支持的HTML子集，留存当作查询工具，附带开发富文本使用到的Qt类列表。

支持的HTML子集

概述

Qt的文本小部件能够显示富文本，这是使用HTML 4标记的子集指定的。使用QTextDocument的小部件（如QLabel和QTextEdit）能够以这种方式显示指定的富文本。

在文本小部件中使用HTML标记

小部件自动检测HTML标记并相应地显示富文本。例如，使用字符串“<b>Hello</b><i>Qt！</i>”设置标签的文本属性，显示如下文本：“Hello Qt！”。

当HTML标记用于文本时，Qt遵循HTML4规范定义的规则。这包括文本布局的默认属性，例如文本流的方向（从左到右），可以通过将dir属性应用于文本块来更改。

支持的标记

     下表列出了Qt的富文本引擎支持的HTML标记：

块属性

     div、dl、dt、h1、h2、h3、h4、h5、h6、p标记支持以下属性：

• align (left, right, center, justify)
• dir (ltr, rtl)

列表属性

ol和ul标记支持以下属性：

• type (1, a, A, square, disc, circle)

表单元格属性

td和th标记支持以下属性：

• width (absolute, relative, or no-value)
• bgcolor (Qt color names or #RRGGBB)
• colspan
• rowspan
• align (left, right, center, justify)
• valign (top, middle, bottom)

CSS属性

下表列出了Qt的富文本引擎支持的CSS属性：

富文本处理相关类

Qt为解析、呈现、操作和编辑富文本提供了大量的类集合。

QTextBlock

概述

QTextDocument类保存格式化文本。

QTextDocument是结构化富文本文档的容器，为样式文本和各种类型的文档元素（如列表、表、框架和图像）提供支持。它们可以创建为在QTextEdit中使用，也可以单独使用。

每个文档元素都由关联的格式对象描述。QTextDocuments将每个format对象视为唯一的对象，并可以将其传递给objectForFormat()以获取要应用到的document元素。

可以使用QTextCursor以编程方式编辑QTextDocument，还可以通过遍历文档结构来检查其内容。整个文档结构存储为根框架下的文档元素层次结构，根框架是通过rootFrame()函数找到的。或者，如果只想遍历文档的文本内容，可以使用begin()、end()和findBlock()来检索可以检查和遍历的文本块。

文档的布局由documentLayout()决定；如果要使用自己的布局逻辑，可以创建自己的QAbstractTextDocumentLayout子类并使用setDocumentLayout()设置它。通过调用metaInformation()函数可以获得文档的标题和其他元信息。对于通过QTextEdit类向用户公开的文档，还可以通过QTextEdit::documentTitle()函数使用文档标题。

toPlainText()和toHtml()函数允许以纯文本和HTML的形式检索文档内容。可以使用find()函数搜索文档的文本。

可以使用setUndoRedoEnabled()函数控制对文档执行的操作的撤消/重做。undo/redo系统可以由编辑器小部件通过undo()和redo()插槽控制；文档还提供contentsChanged()、undoAvailable()和redoAvailable()信号，通知连接的编辑器小部件undo/redo系统的状态。以下是QTextDocument的撤消/重做操作：

• 插入或删除字符。同一文本块中的插入或删除序列被视为单个撤消/重做操作。
• 插入或删除文本块。单个操作中的插入或删除序列（例如，通过选择然后删除文本）被视为单个撤消/重做操作。
• 文本字符格式更改。
• 文本块格式更改。
• 文本块组格式更改。

枚举

enum QTextDocument::FindFlag

     此枚举描述QTextDocument的find函数可用的选项。这些选项可以从以下列表中选择或组合在一起：

FindFlags类型是QFlags<FindFlag>的typedef。它存储FindFlag值的一个或多个组合。

enum QTextDocument::MetaInformation

     此枚举描述可以添加到文档中的不同类型的元信息。

enum QTextDocument::ResourceType

     此枚举描述QTextDocument的loadResource()函数可以加载的资源类型。

enum QTextDocument::Stacks

QTextFrame

概述

QTextFrame类表示QTextDocument中的文本框架。

文本框架为文档中的文本提供了结构。它们用作其他文档元素的通用容器。框架通常使用QTextCursor::insertFrame()创建。

QTextFrame可用于在富文本文档中创建层次结构。每个文档都有一个根框架(QTextDocument::rootFrame())，根框架下的每个框架都有一个父框架和一个（可能是空的）子框架列表。父文本框架可以通过parentFrame()找到，childFrames()函数提供子文本框架列表。

每个框架至少包含一个文本块，使文本光标能够在其中插入新的文档元素。因此，QTextFrame::iterator类用于遍历给定文本框架中的块和子文本框架。框架中的第一个子元素和最后一个子元素可以用begin()和end()找到。

框架还有一种格式（使用QTextFrameFormat指定），可以用setFormat()设置，也可以用format()读取。

可以获得指向文本框架中第一个和最后一个有效光标位置的文本光标；为此，请使用firstCursorPosition()和lastCursorPosition()函数。文档中框架的范围可以使用firstPosition()和lastPosition()找到。

可以使用QTextFrame::iterator类迭代文本框架的内容：这提供了对其内部文本块和子文本框架列表的只读访问。

QTextTable

概述

     QTextTable类表示QTextDocument中的表。

     表是按行和列排序的一组单元格。每个表至少包含一行和一列。每个单元格包含一个块，并由一个框架包围。

     表通常使用QTextCursor::insertTable()函数创建并插入到文档中。例如，可以使用以下代码行在编辑器中的当前光标位置插入一个包含三行和两列的表：

QTextCursor cursor(editor->textCursor());
cursor.movePosition(QTextCursor::Start);
QTextTable *table = cursor.insertTable(rows, columns, tableFormat);

表格式是在创建表时定义的，或者使用setFormat()更改。

通过QTextCursor::currentTable()找到当前由游标编辑的表。这允许在将其插入文档后更改其格式或维度。

可以使用resize()更改表的大小，也可以使用insertRows()、insertColumns()、removeRows()或removeColumns()更改表的大小。使用cellAt()检索表单元格。

通过在表中移动光标，并使用rowStart()和rowEnd()函数在每行的开始和结束处获取光标，可以找到表行的开始和结束位置。

可以使用mergeCells()和splitCell()函数合并和拆分QTextTable中的行和列。但是，只能拆分跨多行或多列的单元格。（合并或拆分不会增加或减少行数和列数。）

请注意，如果已将多个列和行合并到一个单元格中，则无法将合并的单元格拆分为跨越多个行或列的新单元格。要能够拆分跨越多个行和列的单元格，您需要在多个迭代中执行此操作。

     有一个2x3的名称和地址表。

为了合并第一行中的两列，调用了mergeCells()，row=0，column=0，numRows=1，numColumns=2。

table->mergeCells(0, 0, 1, 2);

     若要将表的第一行拆分为两个单元格，请使用numRows和numCols=1调用splitCell()函数。

table->splitCell(0, 0, 1, 1);

恢复原始表：

QTextList

概述

     QTextList类提供QTextDocument中项目的修饰列表。

列表包含一系列文本块，每个文本块都用项目符号或其他符号标记。可以使用多个级别的列表，并且自动编号功能支持顺序数字和字母列表。

列表是通过使用文本光标在当前位置插入空列表或将现有文本移动到新列表中来创建的。函数的作用是：在文档的光标位置插入一个空块，使其成为列表中的第一项。

QTextListFormat listFormat;
if (list)
{
    listFormat = list->format();
    listFormat.setIndent(listFormat.indent() + 1);
}
listFormat.setStyle(QTextListFormat::ListDisc);
cursor.insertList(listFormat);

QTextCursor::createList()函数的作用是：获取光标当前块的内容，并将其转换为新列表的第一项。

光标的当前列表使用QTextCursor::currentList()找到。

列表中的项数由count()给定。使用item()函数可以通过列表中的索引获取每个项。类似地，可以使用itemNumber()找到给定项的索引。使用itemText()函数可以找到每个项的文本。

请注意，列表中的项可能不是文档中的相邻元素。例如，多级列表中的顶级项将由列表中较低级别的项分隔。

可以使用removeItem()函数通过索引删除列表项。remove()删除列表中的指定项。

列表的格式用setFormat()设置，用format()读取。格式描述的是列表本身的属性，而不是单个项。

QTextFragment

概述

     QTextFragment类以单个QTextCharFormat保存QTextDocument中的一段文本。

     文本片段描述以单个字符格式存储的文本片段。字符格式改变的文本可以用不同格式的文本片段序列表示。

     如果用户在片段中编辑文本并引入不同的字符格式，则片段的文本将在格式更改的每个点处拆分，并创建新的片段。例如，在句子中间更改某个文本的样式将导致该片段分成三个独立的片段：第一个和第三个片段的格式与之前相同，第二个片段的格式与之前相同。第一个片段将包含句子开头的文本，第二个片段将包含中间的文本，第三个片段从句子结尾获取文本。

片段的文本和字符格式可以通过text()和charFormat()函数获得。Length()函数的作用是：给出片段中文本的长度。position()给出片段开始在文档中的位置。使用contains()函数确定片段是否包含文档中的特定位置。

QTextImageFormat

概述

QTextImageFormat类为qtext文档中的图像提供格式信息。

内联图像由Unicode值U+FFFC（对象替换字符）表示，该值具有关联的QTextImageFormat。图像格式使用setName()指定用于定位图像的名称。图像将占用的矩形的大小是使用setWidth()和setHeight()指定的。

图像可以以Qt有图像阅读器的任何格式提供，因此SVG图形可以与PNG、TIFF和其他位图格式一起提供。

QTextCursor

概述

QTextCursor类提供了访问和修改QTextDocuments的API。

文本光标是通过模拟文本编辑器中光标行为的编程接口访问和修改文本文档的内容和底层结构的对象。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()等函数将光标移动限制在这些有效位置。

枚举

enum QTextCursor::MoveMode：移动模式

如果anchor()保持在原来的位置，并且position()移动，则将选择介于两者之间的文本。

enum QTextCursor::MoveOperation：移动操作

QTextLayout

概述

     QTextLayout类用于布局和呈现文本。

它提供了许多现代文本布局引擎所需的功能，包括符合Unicode的呈现、换行和光标定位处理。它还可以生成和呈现与设备无关的布局，这对所见即所得应用程序非常重要。

这个类有一个相当低级的API，除非您打算为某个特定的小部件实现自己的文本呈现，否则您可能不需要直接使用它。

QTextLayout可以与纯文本和富文本一起使用。

QTextLayout可用于创建具有给定宽度的QTextLine实例序列，并可在屏幕上独立定位它们。一旦布局完成，就可以在绘制设备上绘制这些线。

要布局的文本可以在构造函数中提供，也可以使用setText()设置。

布局可以看作一系列QTextLine对象；使用createLine()创建QTextLine实例，使用lineAt()或lineForTextPosition()检索创建的行。

下面是布局阶段的代码片段示例：

int leading = fontMetrics.leading();
qreal height = 0;
textLayout.setCacheEnabled(true);
textLayout.beginLayout();
while (1)
{
    QTextLine line = textLayout.createLine();
    if (!line.isValid())
    {
        break;
    }
    line.setLineWidth(lineWidth);
    height += leading;
    line.setPosition(QPointF(0, height));
    height += line.height();
}
textLayout.endLayout();

然后可以通过调用布局的draw()函数来呈现文本：

对于文本中的给定位置，可以使用isValidCursorPosition()、nextCursorPosition()和previousCursorPosition()找到有效的光标位置。

QTextLayout本身可以使用setPosition()定位；它有boundingRect()和minimumWidth()和maximumWidth()。

枚举

enum QTextLayout::CursorMode：