支持的 HTML 子集

Qt 的文本控件能够显示使用HTML 4标记子集指定的富文本。使用 `QTextDocument` 的控件（例如 `QLabel ` 和 `QTextEdit`）能够显示以此方式指定的富文本。

在文本控件中使用 HTML 标记

控件会自动检测 HTML 标记，并据此显示富文本。例如，将标签的text 属性设置为字符串"Hello Qt!" ，标签将显示如下文本：Hello Qt!

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

支持的标签

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

注意： 针对下列标签实现的功能 仅是完整的 HTML 4 规范的一个子集。并非所有属性都受支持，请参阅各标签的注释。

标签	描述	注释
`a`	锚点或链接	支持`href` 、`name` 和`title` 属性。
`address`	地址
`b`	粗体
`big`	较大字体
`blockquote`	缩进段落
`body`	文档正文	支持`bgcolor` 属性，该属性可以是Qt XML的color name ，也可以是`#RRGGBB` 的颜色规范。
`br`	换行
`center`	居中段落
`cite`	行内引用	与`i` 相同。
`code`	代码	与`tt` 相同。
`dd`	定义数据
`del`	已删除	与`s` 相同。自 Qt 6.11 起
`dfn`	定义	与`i` 相同。
`div`	文档分隔	支持标准的块属性。
`dl`	定义列表	支持标准的块属性。
`dt`	定义项	支持标准块属性。
`em`	强调	与`i` 相同。
`font`	字体大小、字体家族和/或颜色	支持以下属性：`size` 、`face` 和`color` （Qtcolor names 或`#RRGGBB` ）。
`h1`	一级标题	支持标准的块级属性。
`h2`	二级标题	支持标准块属性。
`h3`	三级标题	支持标准块属性。
`h4`	第 4 级标题	支持标准块属性。
`h5`	第 5 级标题	支持标准块属性。
`h6`	第 6 级标题	支持标准块属性。
`head`	文档标题
`hr`	水平线	支持`width` 属性，该属性可以指定为绝对值或相对值（`%` ）。
`html`	HTML文档
`i`	斜体
`img`	图像	支持`src` 、`width` 、`height` 、`style` 、`alt` 和`title` 属性。
`kbd`	用户输入的文本
`meta`	元信息	如果通过`meta` 标签指定了文本编码，Qt::codecForHtml()会自动识别该编码。同样地，如果向QTextDocument::toHtml()指定了编码，该编码将通过`meta` 标签进行存储，例如：`<meta http-equiv="Content-Type" content="text/html; charset=EUC-JP" />`
`li`	列表项
`nobr`	不可断行的文本
`ol`	有序列表	支持标准的列表属性。
`p`	段落	默认左对齐。支持标准块级元素属性。
`pre`	预格式化文本
`qt`	Qt 富文本文档	`html` 的同义词。为兼容早期版本的Qt而提供。
`s`	删除线
`samp`	示例代码	与`tt` 相同。
`small`	小号字体
`span`	分组元素
`strong`	加粗	与`b` 相同。
`sub`	下标
`sup`	上标
`table`	表格	支持以下属性：`border` 、`bgcolor` （Qtcolor names 或`#RRGGBB` ）、`cellspacing` 、`cellpadding` 、`width` （绝对或相对）以及`height` 。
`tbody`	表格主体	不执行任何操作。
`td`	表格数据单元格	支持标准的表格单元格属性。
`tfoot`	表格页脚	无作用。
`th`	表格页眉单元格	支持标准的表格单元格属性。
`thead`	表格页眉	如果指定了`thead` 标签，则在打印跨多页的表格时会使用该标签。
`title`	文档标题	使用`title` 标签指定的值可通过QTextDocument::metaInformation()获取。
`tr`	表格行	支持`bgcolor` 属性，该属性可以是 Qtcolor name 或`#RRGGBB` 颜色规范。
`tt`	打字机字体
`u`	下划线
`ul`	无序列表	支持标准列表属性。
`var`	Variable	与`i` 相同。

块属性

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)

此外，ol 标签还支持以下属性：

start

表格单元格属性

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

width (绝对、相对或无值)
bgcolor (Qt XMLcolor names 或#RRGGBB)
colspan
rowspan
align (left 、right 、center 、justify)
valign (top,middle,bottom)

CSS 属性

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

属性	取值	描述
`background-color`	<color>	元素的背景色
`background-image`	<uri>	元素的背景图片
`color`	<color>	文本前景色
`font-family`	<字体家族名称>	字体家族名称
`font-size`	[ small \| medium \| large \| x-large \| xx-large ] \| <size>pt \| <size>px	相对于文档字体的字号，或以点或像素为单位指定
`font-style`	[ 正常 \| 斜体 \| 倾斜 ]
`font-weight`	[ 正常 \| 粗体 \| 100 \| 200 \| 300 \| 400 \| 500 \| 600 \| 700 \| 800 \| 900 ]	指定文本所使用的字体粗细，其中`normal` 和`bold` 分别映射到QFont 中的对应粗细。数值是QFont 中等效粗细值的8倍。
`text-decoration`	none \| [ underline \|\| overline \|\| line-through ]	其他文本效果
`font`	[ [ <'font-style'> \|\| <'font-weight'> ]? <'font-size'> <'font-family'> ]	字体简写属性
`text-indent`	<length>px	首行文本缩进（单位：像素）
`white-space`	normal \| pre \| nowrap \| pre-wrap	声明如何处理 HTML 中的空白符。
`margin-top`	<length>px	段落顶部边距（单位：像素）
`margin-bottom`	<length>px	段落底部边距（单位：像素）
`margin-left`	<length>px	段落左边距（以像素为单位）
`margin-right`	<长度>px	段落右边距（单位：像素）
`padding-top`	<length>px	表格单元格顶部内边距（单位：像素）
`padding-bottom`	<length>px	表格单元格底部内边距（单位：像素）
`padding-left`	<长度>px	表格单元格左内边距（单位：像素）
`padding-right`	<长度>px	表格单元格右侧内边距（单位：像素）
`padding`	<长度>px	用于一次性设置所有内边距属性的简写形式。
`vertical-align`	基线 \| 下标 \| 上标 \| 中间 \| 上 \| 下	文本的垂直对齐方式。对于文本表格单元格的垂直对齐，仅“middle”、“top”和“bottom”有效。
`border-collapse`	collapse \| separate	文本表格的边框合并模式。若设置为“collapse”，则不会应用单元格间距。
`border-color`	<color>	文本表格及表格单元格的边框颜色。
`border-top-color`	<颜色>	表格单元格的顶部边框颜色。
`border-bottom-color`	<color>	表格单元格的底部边框颜色。
`border-left-color`	<color>	表格单元格的左边框颜色。
`border-right-color`	<color>	表格单元格的右边框颜色。
`border-style`	none \| dotted \| dashed \| dot-dash \| dot-dot-dash \| solid \| double \| groove \| ridge \| inset \| outset	文本表格和表格单元格的边框样式。
`border-top-style`	<border-style>	表格单元格的顶部边框样式。
`border-bottom-style`	<border-style>	表格单元格的底部边框样式。
`border-left-style`	<border-style>	表格单元格的左边框样式。
`border-right-style`	<border-style>	表格单元格的右边框样式。
`border-width`	<width>px	表格或单元格边框的宽度
`border-top-width`	<length>px	表格单元格的上边框宽度。
`border-bottom-width`	<length>px	表格单元格的底部边框宽度。
`border-left-width`	<length>px	表格单元格的左边框宽度。
`border-right-width`	<length>px	表格单元格的右边框宽度。
`border-top`	<width>px <border-style> <border-color>	用于设置顶部边框宽度、样式和颜色的简写形式
`border-bottom`	<宽度>px <边框样式> <边框颜色>	用于设置底部边框宽度、样式和颜色的简写语法
`border-left`	<width>px <border-style> <border-color>	用于设置左边框宽度、样式和颜色的简写形式
`border-right`	<宽度>px <边框样式> <边框颜色>	用于设置右边框宽度、样式和颜色的简写形式
`border-top`	<宽度>px <边框样式> <边框颜色>	用于设置顶边框宽度、样式和颜色的简写语法
`border-bottom`	<width>px <border-style> <border-color>	用于设置底部边框宽度、样式和颜色的简写形式
`border`	<宽度>px <边框样式> <边框颜色>	用于设置四边边框宽度、样式和颜色的简写语法
`background`	[ <'background-color'> \|\| <'background-image'> ]	背景简写属性
`page-break-before`	[ auto \| always ]	可在段落/表格之前强制插入分页符
`page-break-after`	[ auto \| always ]	允许在段落/表格之后强制插入分页符
`float`	[ left \| right \| none ]	指定图片或文本在另一个元素中的位置。请注意，`float` 属性仅支持表格和图片。
`text-transform`	[ 大写 \| 小写 ]	选择在显示文本之前对其进行的转换。
`font-kerning`	[ normal \| none ]	启用或禁用文本字符之间的字间距调整。
`font-variant`	small-caps	在显示文本前对其应用小写大写转换。
`word-spacing`	<宽度>px	指定单词之间的替代间距。
`line-height`	<数字>[% \| px \| pt \| cm]	指定行高。可以是以下值之一：以像素、点或厘米为单位的固定行高。当前字体大小的百分比。

注意：某些 CSS 属性仅在应用于块级标签（如 ``）时才受支持。例如，在 `` 上设置这些属性将不起作用。`margin` 就是此类属性的一个例子。有关 `QTextDocument` 中块级元素和 `span` 元素可用格式化选项的概述，请参阅QTextBlockFormat 和QTextCharFormat 。

Qt 特有的 CSS 属性

除了前面列出的标准 CSS 属性外，还可以使用以下 Qt 特有的属性来设置文本块的样式：

属性	取值	描述
`-qt-block-indent`	`<number>`	将文本块向右缩进指定数量的空格。
`-qt-list-indent`	`<number>`	将列表项向右缩进指定数量的空格。
`-qt-list-number-prefix`	`<string>`	在 HTML 有序列表中，在列表编号前添加给定的字符串。
`-qt-list-number-suffix`	<string>	在 HTML 有序列表的列表编号后添加给定字符串。
`-qt-paragraph-type`	`empty`	隐藏文本块。
`-qt-table-type`	`root \| frame`	`root` 将文本块以行内方式呈现，不带边框和缩进；而`frame` 则将其呈现为新行，并带有边框。
`-qt-user-state`	`<number>`	将其作为用户数据添加到文本块中。

支持的 CSS 选择器

除伪类选择器（如:first-child 、:visited 和:hover ）外，所有 CSS 2.1 选择器类均受支持。

高级富文本处理富文本处理 API

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.