QTextDocument 入门

一、QTextDocument

QTextDocument 是 Qt 中用于处理富文本文档的核心类，支持文本格式、图片、表格等复杂内容。

1. QTextDocument 入门

1.1 基本概念

QTextDocument 是 Qt 中用于处理富文本内容的核心类，它提供了：

• 结构化文本存储（段落、列表、表格等）

• 文本格式支持（字体、颜色、对齐等）

• 文档布局管理

• 撤销/重做功能

• HTML/纯文本/Markdown 支持

1.2 创建方式

// 方式1：直接创建
QTextDocument *doc = new QTextDocument(parent);// 方式2：从QTextEdit获取
QTextEdit *editor = new QTextEdit;
QTextDocument *doc = editor->document();// 方式3：从内容创建
QTextDocument *doc = new QTextDocument("初始内容", parent);

2. 核心属性表

属性	类型	访问	描述
baseUrl	QUrl	读写	解析相对URL的基础地址
blockCount	int	只读	文档中的文本块数量
characterCount	int	只读	文档字符总数
defaultFont	QFont	读写	默认字体设置
documentMargin	qreal	读写	文档页边距
indentWidth	qreal	读写	缩进宽度
isEmpty	bool	只读	是否为空文档
modified	bool	读写	文档是否被修改
pageSize	QSizeF	读写	页面尺寸
textWidth	qreal	读写	文本宽度限制
title	QString	读写	文档标题
undoRedoEnabled	bool	读写	是否启用撤销/重做

3. 重要方法分类

3.1 内容操作

// 设置/获取内容
void setPlainText(const QString &text)
QString toPlainText() const
void setHtml(const QString &html)
QString toHtml() const
void setMarkdown(const QString &markdown)
QString toMarkdown() const// 清空文档
void clear()

3.2 文本查找

QTextCursor find(const QString &subString, const QTextCursor &from = QTextCursor(),FindFlags flags = FindFlags()) constQTextCursor find(const QRegularExpression &expr,const QTextCursor &from = QTextCursor(),FindFlags flags = FindFlags()) const

3.3 撤销/重做

void undo()
void redo()
void clearUndoRedoStacks()
bool isUndoAvailable() const
bool isRedoAvailable() const

3.4 文档结构

// 获取文档部分
QTextBlock firstBlock() const
QTextBlock lastBlock() const
QTextFrame *rootFrame() const// 迭代器
QTextBlock begin() const
QTextBlock end() const

3.5 资源管理

QVariant loadResource(int type, const QUrl &name)
void addResource(int type, const QUrl &name, const QVariant &resource)

3.6 打印输出

void drawContents(QPainter *painter, const QRectF &rect = QRectF())
void print(QPagedPaintDevice *printer) const

4. 信号系统

信号	描述
contentsChanged()	文档内容发生改变时触发
contentsChange(int from, int charsRemoved, int charsAdded)	详细内容变化信号
undoAvailable(bool available)	撤销状态变化
redoAvailable(bool available)	重做状态变化
modificationChanged(bool changed)	修改状态变化
blockCountChanged(int newBlockCount)	块数量变化
cursorPositionChanged(const QTextCursor &cursor)	光标位置变化

5. 实用示例

5.1 基本使用

QTextDocument doc;
doc.setPlainText("Hello World!");// 设置格式
QTextCursor cursor(&doc);
cursor.movePosition(QTextCursor::Start);
QTextCharFormat fmt;
fmt.setFontWeight(QFont::Bold);
cursor.insertText("Formatted ", fmt);

5.2 HTML处理

doc.setHtml("<b>Bold</b> and <i>italic</i> text");
QString html = doc.toHtml();

5.3 响应变化

connect(&doc, &QTextDocument::contentsChanged, [](){qDebug() << "Document modified";
});

6. 高级功能

6.1 自定义文档布局

class CustomLayout : public QAbstractTextDocumentLayout {/* 实现布局逻辑 */
};doc->setDocumentLayout(new CustomLayout(doc));

6.2 文本对象接口

class CustomTextObject : public QObject, public QTextObjectInterface {/* 实现自定义文本对象 */
};QTextCharFormat format;
format.setObjectType(QTextFormat::UserObject + 1);
doc->documentLayout()->registerHandler(format.objectType(), new CustomTextObject);

7. 性能优化技巧

1. 批量操作：在大量修改前调用 blockSignals(true)，完成后恢复

2. 资源管理：对大型文档使用分页加载

3. 格式重用：复用 QTextFormat 对象减少内存分配

4. 布局控制：合理设置 textWidth 和页面尺寸

二、QTextCursor

QTextCursor 是 Qt 框架中用于操作 QTextDocument 的核心类，提供了对富文本内容的编辑、选择和格式控制功能。它类似于文本编辑器中的光标，可以移动、插入、删除文本，并控制文本格式。

1. QTextCursor 基本概念

1.1 主要用途

• 文本插入和删除：在 QTextDocument 中插入或删除文本。

• 文本选择：选择文本范围，进行复制、剪切或格式修改。

• 格式控制：设置字符格式（字体、颜色等）和段落格式（对齐、缩进等）。

• 表格和列表操作：插入表格、列表，并控制其结构。

1.2 创建 QTextCursor

// 方式1：基于 QTextDocument 创建
QTextDocument *doc = new QTextDocument;
QTextCursor cursor(doc);// 方式2：基于现有 QTextCursor 复制
QTextCursor anotherCursor(cursor);// 方式3：基于 QTextEdit 获取（适用于 GUI 应用）
QTextEdit *textEdit = new QTextEdit;
QTextCursor editCursor = textEdit->textCursor();

2. QTextCursor 属性

QTextCursor 本身没有直接可访问的属性（如 property()），但可以通过方法获取或修改其状态：

属性（概念）	获取方法	设置方法
位置	position()	setPosition(int pos)
是否有选择	hasSelection()	clearSelection()
选择范围	selectionStart(), selectionEnd()	setPosition(pos, mode)
当前块（段落）	block()	movePosition()
当前字符格式	charFormat()	setCharFormat()
当前段落格式	blockFormat()	setBlockFormat()
是否可撤销/重做	isUndoAvailable() / isRedoAvailable()	undo() / redo()

---

3. QTextCursor 常用方法

3.1 光标移动

方法	说明
movePosition(MoveOperation op, MoveMode mode = MoveAnchor, int n = 1)	移动光标（如 StartOfLine, EndOfDocument）
setPosition(int pos, MoveMode mode = MoveAnchor)	设置光标位置
atStart(), atEnd()	是否在文档开头/结尾
atBlockStart(), atBlockEnd()	是否在段落开头/结尾

示例：

cursor.movePosition(QTextCursor::StartOfLine);  // 移动到行首
cursor.movePosition(QTextCursor::End, QTextCursor::KeepAnchor);  // 选择到文档末尾

3.2 文本操作

方法	说明
insertText(const QString &text)	插入纯文本
insertText(const QString &text, const QTextCharFormat &format)	插入带格式的文本
insertHtml(const QString &html)	插入 HTML
insertFragment(const QTextDocumentFragment &fragment)	插入文档片段
insertImage(const QTextImageFormat &format)	插入图片
removeSelectedText()	删除选中文本
deleteChar(), deletePreviousChar()	删除字符

示例：

QTextCharFormat boldFormat;
boldFormat.setFontWeight(QFont::Bold);
cursor.insertText("Hello, World!", boldFormat);

3.3 选择操作

方法	说明
select(SelectionType selection)	选择文本（如 LineUnderCursor）
hasSelection()	是否有选中文本
selectedText()	获取选中文本
selectionStart(), selectionEnd()	获取选择范围
clearSelection()	清除选择

示例：

cursor.select(QTextCursor::WordUnderCursor);  // 选中光标下的单词
QString selected = cursor.selectedText();    // 获取选中内容

3.4 格式控制

方法	说明
setCharFormat(const QTextCharFormat &format)	设置字符格式
mergeCharFormat(const QTextCharFormat &format)	合并字符格式
charFormat()	获取当前字符格式
setBlockFormat(const QTextBlockFormat &format)	设置段落格式
blockFormat()	获取当前段落格式

示例：

QTextCharFormat redFormat;
redFormat.setForeground(Qt::red);
cursor.mergeCharFormat(redFormat);  // 合并格式（不影响其他属性）

3.5 表格和列表操作

方法	说明
insertTable(int rows, int cols, const QTextTableFormat &format)	插入表格
currentTable()	获取当前表格
insertList(const QTextListFormat &format)	插入列表
createList(const QTextListFormat &format)	创建列表

示例：

QTextTableFormat tableFormat;
tableFormat.setCellSpacing(5);
cursor.insertTable(3, 2, tableFormat);  // 插入 3 行 2 列的表格

4. QTextCursor 信号

QTextCursor 本身不直接发出信号，但它的操作会触发关联的 QTextDocument 或 QTextEdit 的信号，例如：

• QTextDocument::contentsChanged()（内容变化时）

• QTextEdit::cursorPositionChanged()（光标移动时）

示例（连接信号）：

QObject::connect(textEdit, &QTextEdit::cursorPositionChanged, [=]() {qDebug() << "Cursor moved to position:" << textEdit->textCursor().position();
});

5. 总结

功能	方法
创建光标	QTextCursor(doc)
移动光标	movePosition(), setPosition()
插入文本	insertText(), insertHtml()
选择文本	select(), selectedText()
格式控制	setCharFormat(), setBlockFormat()
表格/列表	insertTable(), insertList()

三、QTextTable

1. QTextTable 入门

1.1 基本概念

QTextTable 是 QTextDocument 中用于表示表格的类，它：

• 继承自 QTextFrame，是文档中的特殊框架结构

• 提供行、列操作和单元格管理

• 支持表格格式设置（边框、间距等）

• 可以与 QTextCursor 配合进行表格编辑

1.2 创建方式

// 通过QTextCursor创建表格
QTextCursor cursor(textDocument);
QTextTableFormat tableFormat;
tableFormat.setCellSpacing(2);
tableFormat.setCellPadding(4);
QTextTable *table = cursor.insertTable(rows, cols, tableFormat);// 从现有文档获取表格
QTextFrame::iterator it;
for (it = textDocument->rootFrame()->begin(); !it.atEnd(); ++it) {if (QTextTable *table = qobject_cast<QTextTable*>(it.currentFrame())) {// 获取到表格}
}

2. 核心属性表

属性	类型	访问	描述
format	QTextTableFormat	读写	表格的格式设置
rows	int	只读	表格行数
columns	int	只读	表格列数

3. 重要方法分类

3.1 表格结构操作

// 调整表格大小
void resize(int rows, int columns)// 插入/删除行列
void insertRows(int pos, int num)
void insertColumns(int pos, int num)
void removeRows(int pos, int num)
void removeColumns(int pos, int num)// 合并/拆分单元格
void mergeCells(int row, int column, int numRows, int numColumns)
void mergeCells(const QTextCursor &cursor)
void splitCell(int row, int column, int numRows, int numColumns)

3.2 单元格操作

// 获取单元格信息
QTextTableCell cellAt(int row, int column) const
QTextTableCell cellAt(const QTextCursor &cursor) const
QTextTableCell cellAt(int position) const// 获取单元格范围
QTextCursor rowStart(const QTextCursor &cursor) const
QTextCursor rowEnd(const QTextCursor &cursor) const

3.3 格式设置

// 设置表格格式
void setFormat(const QTextTableFormat &format)// 设置单元格格式
void setCellFormat(int row, int column, const QTextCharFormat &format)

4. 信号系统

QTextTable 本身不直接发出信号，但表格变化会触发关联 QTextDocument 的信号：

• contentsChanged()

• contentsChange(int from, int charsRemoved, int charsAdded)

5. 实用示例

5.1 创建格式化表格

QTextCursor cursor(document);
QTextTableFormat tableFormat;
tableFormat.setBackground(QColor("#f0f0f0"));
tableFormat.setBorder(1);
tableFormat.setBorderStyle(QTextFrameFormat::BorderStyle_Solid);
tableFormat.setCellPadding(5);
tableFormat.setCellSpacing(0);QTextTable *table = cursor.insertTable(3, 4, tableFormat);// 设置表头格式
QTextCharFormat headerFormat;
headerFormat.setBackground(Qt::gray);
headerFormat.setFontWeight(QFont::Bold);for (int col = 0; col < 4; ++col) {QTextTableCell cell = table->cellAt(0, col);QTextCursor cellCursor = cell.firstCursorPosition();cellCursor.insertText(QString("Header %1").arg(col+1), headerFormat);
}

5.2 动态修改表格

// 添加新行
table->insertRows(table->rows(), 1);// 合并单元格
table->mergeCells(1, 0, 1, 2);// 设置单元格格式
QTextCharFormat highlightFormat;
highlightFormat.setBackground(Qt::yellow);QTextTableCell cell = table->cellAt(2, 1);
QTextCursor cellCursor = cell.firstCursorPosition();
cellCursor.insertText("Important", highlightFormat);

5.3 遍历表格内容

for (int row = 0; row < table->rows(); ++row) {for (int col = 0; col < table->columns(); ++col) {QTextTableCell cell = table->cellAt(row, col);QTextCursor cellCursor = cell.firstCursorPosition();QString text = cellCursor.block().text();qDebug() << "Cell[" << row << "," << col << "]: " << text;}
}

6. 高级功能

6.1 自定义表格边框

QTextTableFormat customFormat;
QTextLength width(QTextLength::PercentageLength, 100);
customFormat.setColumnWidthConstraints({width, width, width});QVector<QTextFormat> formats;
QTextFrameFormat borderFormat;
borderFormat.setBorder(2);
borderFormat.setBorderBrush(QBrush(Qt::darkGreen));
borderFormat.setBorderStyle(QTextFrameFormat::BorderStyle_Dotted);
customFormat.setBorderCollapse(true);
customFormat.setProperty(QTextFormat::TableBorderBrush, QBrush(Qt::darkBlue));table->setFormat(customFormat);

6.2 表格数据导出

QString html = "<table border='1'>";
for (int row = 0; row < table->rows(); ++row) {html += "<tr>";for (int col = 0; col < table->columns(); ++col) {html += "<td>";QTextTableCell cell = table->cellAt(row, col);html += cell.firstCursorPosition().block().text();html += "</td>";}html += "</tr>";
}
html += "</table>";

7.设置 QTextTable 的高度

在 Qt 中，QTextTable 的高度可以通过几种方式设置。以下是设置表格高度的常用方法：

1）. 设置表格整体高度

QTextTable *table = cursor.insertTable(rows, cols); // 创建表格// 获取表格格式
QTextTableFormat tableFormat = table->format();// 设置固定高度
tableFormat.setHeight(300); // 像素值
// 或者使用百分比
tableFormat.setHeight(QTextLength(QTextLength::PercentageLength, 50));// 应用格式
table->setFormat(tableFormat);

2）. 设置行高

// 设置特定行的高度
QTextTable *table = cursor.insertTable(rows, cols);// 获取表格格式
QTextTableFormat tableFormat = table->format();// 设置行高（影响所有行）
QVector<QTextLength> constraints;
for (int i = 0; i < rows; ++i) {constraints << QTextLength(QTextLength::FixedLength, 50); // 每行50像素
}
tableFormat.setRowHeightConstraints(constraints);// 应用格式
table->setFormat(tableFormat);

3）. 设置单元格高度

// 设置特定单元格的高度
QTextTable *table = cursor.insertTable(rows, cols);// 获取单元格格式
QTextTableCell cell = table->cellAt(row, col);
QTextCharFormat cellFormat = cell.format();// 设置单元格高度（通过设置最小高度）
cellFormat.setProperty(QTextFormat::BlockMinimumHeight, 100); // 100像素
cell.setFormat(cellFormat);

注意事项

1. 表格高度设置可能会受到内容的影响，如果内容超过设置的高度，表格可能会自动扩展

2. 使用 QTextLength 可以指定不同类型的长度：

   • QTextLength::FixedLength - 固定像素值

   • QTextLength::PercentageLength - 相对于父容器的百分比

3. 要确保表格在文档中有足够的空间显示设置的高度

8. 性能优化建议

1. 批量操作：在修改大量单元格前调用 document()->blockSignals(true)

2. 格式重用：复用 QTextFormat 对象减少内存分配

3. 合理合并单元格：避免过度复杂的表格结构

4. 延迟布局：大规模修改后手动调用 document()->markContentsDirty()

四、QTextTableCell

1. QTextTableCell 入门

1.1 基本概念

QTextTableCell 表示 QTextTable 中的单个单元格，它：

• 是表格的基本组成单元

• 可以包含文本、格式和其他文档元素

• 具有行/列位置信息和格式属性

• 可以跨越多行多列（合并单元格）

1.2 获取单元格的方式

// 通过表格获取
QTextTable *table = ...;
QTextTableCell cell = table->cellAt(row, column);// 通过光标位置获取
QTextCursor cursor = ...;
QTextTableCell cell = table->cellAt(cursor);// 通过文档位置获取
int position = ...;
QTextTableCell cell = table->cellAt(position);

2. 核心属性表

属性	类型	访问	描述
row	int	只读	单元格起始行索引
column	int	只读	单元格起始列索引
rowSpan	int	只读	单元格跨越的行数
columnSpan	int	只读	单元格跨越的列数
format	QTextCharFormat	读写	单元格字符格式
tableCellFormat	QTextTableCellFormat	读写	单元格特有格式

3. 重要方法分类

3.1 内容访问

// 获取单元格内的光标
QTextCursor firstCursorPosition() const
QTextCursor lastCursorPosition() const// 检查有效性
bool isValid() const

3.2 格式操作

// 设置/获取格式
void setFormat(const QTextCharFormat &format)
QTextCharFormat format() const// 单元格特有格式
void setTableCellFormat(const QTextTableCellFormat &format)
QTextTableCellFormat tableCellFormat() const

3.3 布局信息

// 获取单元格在文档中的位置范围
int firstPosition() const
int lastPosition() const

4. 信号系统

QTextTableCell 本身不直接发出信号，单元格变化会触发：

• 关联 QTextDocument 的 contentsChanged()

• 父表格的结构变化

5. 实用示例

5.1 基本单元格操作

// 获取单元格
QTextTableCell cell = table->cellAt(1, 2);// 检查有效性
if (cell.isValid()) {// 获取光标并插入内容QTextCursor cellCursor = cell.firstCursorPosition();cellCursor.insertText("Cell Content");// 设置格式QTextCharFormat format;format.setBackground(Qt::yellow);cell.setFormat(format);
}

5.2 遍历单元格内容

for (int row = 0; row < table->rows(); ++row) {for (int col = 0; col < table->columns(); ++col) {QTextTableCell cell = table->cellAt(row, col);if (cell.isValid() && !cell.rowSpan() && !cell.columnSpan()) {QString text = cell.firstCursorPosition().block().text();qDebug() << "Cell[" << row << "," << col << "]: " << text;}}
}

5.3 合并单元格操作

// 获取要合并的起始单元格
QTextTableCell startCell = table->cellAt(0, 0);// 检查是否已经是合并单元格
if (startCell.rowSpan() == 1 && startCell.columnSpan() == 1) {// 合并2行2列table->mergeCells(startCell.row(), startCell.column(), 2, 2);// 在新合并的单元格中添加内容QTextCursor mergeCursor = startCell.firstCursorPosition();mergeCursor.insertText("Merged Cell");// 设置合并单元格格式QTextTableCellFormat mergeFormat;mergeFormat.setBackground(QColor("#e0e0e0"));mergeFormat.setVerticalAlignment(QTextCharFormat::AlignMiddle);startCell.setTableCellFormat(mergeFormat);
}

6. 高级应用

6.1 自定义单元格边框

QTextTableCell cell = table->cellAt(1, 1);
QTextTableCellFormat cellFormat = cell.tableCellFormat();// 设置自定义边框
cellFormat.setTopBorder(2);
cellFormat.setBottomBorder(2);
cellFormat.setLeftBorder(1);
cellFormat.setRightBorder(1);
cellFormat.setTopBorderStyle(QTextFrameFormat::BorderStyle_Dashed);
cellFormat.setBorderBrush(QBrush(Qt::darkBlue));cell.setTableCellFormat(cellFormat);

6.2 单元格数据导出

QString exportCellData(const QTextTableCell &cell) {if (!cell.isValid()) return QString();QString content;QTextCursor cursor = cell.firstCursorPosition();while (cursor.position() <= cell.lastPosition()) {content += cursor.block().text();cursor.movePosition(QTextCursor::NextBlock);}return content.trimmed();
}

7. 使用建议

1. 有效性检查：始终检查 isValid() 避免无效单元格操作

2. 格式重用：创建 QTextFormat 对象重复使用提高性能

3. 合并单元格注意：

   • 合并后原单元格变为无效

   • 只有左上角单元格保持有效

4. 性能优化：

   • 批量操作前禁用文档信号

   • 避免频繁的格式更改

五、QTextBlockFormat

1. QTextBlockFormat 简介

QTextBlockFormat 是 Qt 富文本框架 (QTextDocument) 的一部分，用于控制文本块（段落）的格式，包括：

• 对齐方式

• 缩进和边距

• 背景颜色

• 行高

• 分页控制

• 制表位设置

它通常与 QTextCursor 和 QTextDocument 一起使用，用于格式化段落。

2. 主要属性

属性	类型	默认值	描述
alignment	Qt::Alignment	Qt::AlignLeft	段落对齐方式（左对齐、居中、右对齐等）
leftMargin	qreal	0.0	左缩进（像素或磅值）
rightMargin	qreal	0.0	右缩进（像素或磅值）
topMargin	qreal	0.0	段落上方间距
bottomMargin	qreal	0.0	段落下方间距
textIndent	qreal	0.0	首行缩进
lineHeight	qreal	1.0	行高倍数（1.0 = 单倍行距）
lineHeightType	QTextBlockFormat::LineHeightTypes	SingleHeight	行高类型（单倍、固定值等）
background	QBrush	Qt::NoBrush	段落背景颜色
pageBreakPolicy	QTextFormat::PageBreakFlags	QTextFormat::PageBreak_Auto	分页策略
headingLevel	int	0	标题级别（1-6，0 表示普通段落）

3. 常用方法

3.1 设置方法

方法	参数	描述
setAlignment(Qt::Alignment alignment)	Qt::AlignLeft / Qt::AlignCenter / Qt::AlignRight	设置对齐方式
setLeftMargin(qreal margin)	缩进值（如 20.0）	设置左缩进
setRightMargin(qreal margin)	缩进值（如 20.0）	设置右缩进
setTopMargin(qreal margin)	间距值（如 10.0）	设置段落上边距
setBottomMargin(qreal margin)	间距值（如 10.0）	设置段落下边距
setTextIndent(qreal indent)	缩进值（如 30.0）	设置首行缩进
setLineHeight(qreal height, int type)	height（行高倍数或固定值），type（SingleHeight / FixedHeight）	设置行高
setBackground(QBrush brush)	QBrush(Qt::yellow)	设置背景颜色
setPageBreakPolicy(QTextFormat::PageBreakFlags policy)	PageBreak_Auto / PageBreak_AlwaysBefore	设置分页策略

3.2 获取方法

方法	返回值	描述
alignment()	Qt::Alignment	获取对齐方式
leftMargin()	qreal	获取左缩进
rightMargin()	qreal	获取右缩进
topMargin()	qreal	获取上边距
bottomMargin()	qreal	获取下边距
textIndent()	qreal	获取首行缩进
lineHeight()	qreal	获取行高
lineHeightType()	QTextBlockFormat::LineHeightTypes	获取行高类型
background()	QBrush	获取背景画刷
pageBreakPolicy()	QTextFormat::PageBreakFlags	获取分页策略

---

4. 信号

QTextBlockFormat 本身不直接发出信号，但它的修改会触发 QTextDocument 的信号：

• contentsChanged()：当段落格式被修改时触发。

• contentsChange(int position, int charsRemoved, int charsAdded)：提供更详细的修改信息。

5. 示例代码

// 创建一个 QTextBlockFormat 对象
QTextBlockFormat blockFormat;// 设置对齐方式（居中）
blockFormat.setAlignment(Qt::AlignCenter);// 设置缩进和边距
blockFormat.setLeftMargin(20.0);
blockFormat.setRightMargin(20.0);
blockFormat.setTextIndent(30.0);  // 首行缩进// 设置行高（1.5 倍行距）
blockFormat.setLineHeight(1.5, QTextBlockFormat::ProportionalHeight);// 设置背景颜色（黄色）
blockFormat.setBackground(QBrush(Qt::yellow));// 应用格式到 QTextCursor
QTextCursor cursor = textEdit->textCursor();
cursor.setBlockFormat(blockFormat);

6. 总结

功能	方法/属性
对齐方式	setAlignment() / alignment()
缩进和边距	setLeftMargin() / setRightMargin() / setTextIndent()
行高	setLineHeight() / lineHeight()
背景颜色	setBackground() / background()
分页控制	setPageBreakPolicy() / pageBreakPolicy()

六、QTextCharFormat

概述

QTextCharFormat 是 Qt 框架中用于描述文本字符格式的类，属于 QtGui 模块。它用于设置和获取文本的视觉属性，如字体、颜色、背景等。

主要属性

属性	描述	类型
font() / setFont()	获取/设置字体	QFont
fontFamily() / setFontFamily()	获取/设置字体家族	QString
fontSize() / setFontSize()	获取/设置字体大小	int
fontWeight() / setFontWeight()	获取/设置字体粗细	int (QFont::Weight)
fontItalic() / setFontItalic()	获取/设置是否斜体	bool
fontUnderline() / setFontUnderline()	获取/设置下划线	bool
fontStrikeOut() / setFontStrikeOut()	获取/设置删除线	bool
foreground() / setForeground()	获取/设置前景色(文本颜色)	QBrush
background() / setBackground()	获取/设置背景色	QBrush
textOutline() / setTextOutline()	获取/设置文本轮廓	QPen
underlineColor() / setUnderlineColor()	获取/设置下划线颜色	QColor
underlineStyle() / setUnderlineStyle()	获取/设置下划线样式	QTextCharFormat::UnderlineStyle
verticalAlignment() / setVerticalAlignment()	获取/设置垂直对齐方式	QTextCharFormat::VerticalAlignment
toolTip() / setToolTip()	获取/设置工具提示文本	QString
anchorHref() / setAnchorHref()	获取/设置超链接URL	QString
anchorNames() / setAnchorNames()	获取/设置锚点名称	QStringList
isAnchor()	检查是否为锚点	bool

常用方法

方法	描述
clearBackground()	清除背景设置
clearForeground()	清除前景设置
merge(const QTextCharFormat &other)	合并另一个格式的属性
isValid()	检查格式是否有效
objectType()	获取对象类型

信号

QTextCharFormat 本身不直接发出信号，因为它是一个数据类。但是，当它的属性在 QTextDocument 或 QTextEdit 中被修改时，相关的文本编辑组件会发出信号，如：

• QTextEdit::currentCharFormatChanged(const QTextCharFormat &format)

• QTextDocument::contentsChange(int position, int charsRemoved, int charsAdded)

使用示例

// 创建 QTextCharFormat 对象
QTextCharFormat format;// 设置字体属性
format.setFont(QFont("Arial", 12));
format.setFontWeight(QFont::Bold);
format.setFontItalic(true);// 设置颜色
format.setForeground(Qt::blue);
format.setBackground(Qt::yellow);// 设置下划线
format.setUnderlineStyle(QTextCharFormat::SingleUnderline);
format.setUnderlineColor(Qt::red);// 在 QTextEdit 中应用格式
QTextCursor cursor = textEdit->textCursor();
cursor.mergeCharFormat(format);

注意事项

1. QTextCharFormat 通常与 QTextCursor 或 QTextDocument 一起使用

2. 修改格式后需要手动应用到文本或光标

3. 可以使用 merge() 方法合并多个格式属性

4. 格式属性是叠加的，未设置的属性会保持原样

七、QTextImageFormat

1. QTextImageFormat 简介

QTextImageFormat 是 Qt 富文本框架 (QTextDocument) 的一部分，用于在文本中插入和控制图像格式。它是 QTextCharFormat 的子类，可以设置图像大小、名称、质量等属性。

2. 主要属性

属性	类型	默认值	描述
name	QString	""	图像资源路径（如 ":/images/logo.png"）
width	qreal	0	图像显示宽度（像素）
height	qreal	0	图像显示高度（像素）
quality	int	-1	图像质量（0-100，-1 表示默认）
devicePixelRatio	qreal	1.0	高 DPI 缩放比例
imageUrl	QUrl	QUrl()	图像 URL（支持本地/网络路径）
imageData	QByteArray	QByteArray()	图像的原始数据

3. 常用方法

3.1 设置方法

方法	参数	描述
setName(const QString &name)	图像路径（如 "logo.png"）	设置图像资源
setWidth(qreal width)	宽度值（如 200.0）	设置显示宽度
setHeight(qreal height)	高度值（如 150.0）	设置显示高度
setQuality(int quality)	质量值（0-100）	设置压缩质量
setDevicePixelRatio(qreal ratio)	缩放比例（如 2.0）	适配高 DPI 屏幕
setImageUrl(const QUrl &url)	QUrl("file:///path/to/image.png")	设置图像 URL
setImageData(const QByteArray &data)	QByteArray（PNG/JPG 数据）	直接设置图像二进制数据

3.2 获取方法

方法	返回值	描述
name()	QString	获取图像资源路径
width()	qreal	获取显示宽度
height()	qreal	获取显示高度
quality()	int	获取图像质量
devicePixelRatio()	qreal	获取设备像素比例
imageUrl()	QUrl	获取图像 URL
imageData()	QByteArray	获取原始图像数据
isValid()	bool	检查格式是否有效

4. 信号

QTextImageFormat 本身不直接发出信号，但它的修改会触发 QTextDocument 的信号：

• contentsChanged()：当图像被插入或修改时触发。

• contentsChange(int position, int charsRemoved, int charsAdded)：提供更详细的修改信息。

5. 示例代码

5.1 插入图像

// 创建图像格式
QTextImageFormat imageFormat;
imageFormat.setName(":/images/logo.png");
imageFormat.setWidth(200);
imageFormat.setHeight(100);// 使用 QTextCursor 插入图像
QTextCursor cursor = textEdit->textCursor();
cursor.insertImage(imageFormat);// 或者直接插入（自动创建 QTextImageFormat）
cursor.insertImage(":/images/logo.png", 200, 100);

5.2 从文件加载图像

QTextImageFormat imageFormat;
imageFormat.setImageUrl(QUrl::fromLocalFile("C:/path/to/image.jpg"));
imageFormat.setWidth(300);
textCursor.insertImage(imageFormat);

5.3 调整图像质量

QTextImageFormat imageFormat;
imageFormat.setName("photo.jpg");
imageFormat.setQuality(80);  // 设置 JPEG 质量为 80
textCursor.insertImage(imageFormat);

6. 总结

功能	方法/属性
设置图像源	setName() / setImageUrl()
调整尺寸	setWidth() / setHeight()
控制质量	setQuality()
高 DPI 支持	setDevicePixelRatio()
直接插入二进制数据	setImageData()

适用场景

• 富文本编辑器（如 Markdown 图片插入）

• 报告生成（嵌入图表或 Logo）

• 聊天应用（显示表情/图片）

注意事项

1. 如果只设置 width 或 height，另一个维度会自动按比例缩放。

2. name 通常用于 Qt 资源文件（:/prefix/path），而 imageUrl 支持本地/网络路径。

3. 在打印或导出 PDF 时，quality 会影响输出清晰度。