QTextDocument Class

成员函数文档

[explicit] QTextDocument::QTextDocument(QObject *parent = nullptr)

使用给定的parent 创建一个空的QTextDocument。

[explicit] QTextDocument::QTextDocument(const QString &text, QObject *parent = nullptr)

创建一个 QTextDocument 对象，其中包含指定的纯文本（未格式化）text ，并应用给定的parent 。

[virtual noexcept] QTextDocument::~QTextDocument()

销毁该文件。

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

将资源resource 添加到资源缓存中，并使用type 和name 作为标识符。type 应为QTextDocument::ResourceType 中列出的值之一。

例如，您可以将一张图片作为资源添加，以便在文档内部引用它：

    document->addResource(QTextDocument::ImageResource,
        QUrl("mydata://image.png"), QVariant(image));

可以使用QTextCursor API 将图片插入文档：

    QTextImageFormat imageFormat;
    imageFormat.setName("mydata://image.png");
    cursor.insertImage(imageFormat);

此外，您还可以使用 HTMLimg 标签插入图片：

    editor->append("<img src=\"mydata://image.png\" />");

void QTextDocument::adjustSize()

将文档调整为合理大小。

另请参阅 idealWidth()，textWidth 以及size 。

QList<QTextFormat> QTextDocument::allFormats() const

返回一个文本格式列表，其中包含文档中使用过的所有格式。

int QTextDocument::availableRedoSteps() const

返回可用的重做步骤数。

另请参阅 isRedoAvailable()。

int QTextDocument::availableUndoSteps() const

返回可用的撤销步骤数量。

另请参阅 isUndoAvailable()。

[since 6.0] qreal QTextDocument::baselineOffset() const

返回文档布局中使用的基线偏移量（以百分比为单位）。

该函数于 Qt 6.0 中引入。

另请参阅 setBaselineOffset()、setSubScriptBaseline()、subScriptBaseline()、setSuperScriptBaseline() 以及superScriptBaseline()。

QTextBlock QTextDocument::begin() const

返回文档中的第一个文本块。

另请参阅 ` firstBlock()`。

[signal] void QTextDocument::blockCountChanged(int newBlockCount)

当文档中的文本块总数发生变化时，会触发此信号。传递给newBlockCount 的值即为新的总数。

QChar QTextDocument::characterAt(int pos) const

返回位于位置pos 处的字符；如果位置超出范围，则返回空字符。

另请参阅 characterCount()。

int QTextDocument::characterCount() const

返回该文档的字符数。

另请参阅 blockCount() 和characterAt()。

[virtual] void QTextDocument::clear()

清除文档内容。

void QTextDocument::clearUndoRedoStacks(QTextDocument::Stacks stacksToClear = UndoAndRedoStacks)

清除由stacksToClear 指定的堆栈。

此方法将清除撤销堆栈、重做堆栈或两者（默认）中的所有命令。如果清除了命令，则会发出相应的信号：QTextDocument::undoAvailable() 或QTextDocument::redoAvailable()。

另请参阅 QTextDocument::undoAvailable() 和QTextDocument::redoAvailable()。

QTextDocument *QTextDocument::clone(QObject *parent = nullptr) const

创建一个新的QTextDocument ，该文档是此文本文档的副本。parent 是返回的文本文档的父文档。

[signal] void QTextDocument::contentsChange(int position, int charsRemoved, int charsAdded)

每当文档内容发生变化时，都会发出此信号；例如，插入或删除文本时，或者应用格式时。

该信号会提供有关文档中发生更改的字符的position 、删除的字符数（charsRemoved ）以及添加的字符数（charsAdded ）的信息。

该信号在文档的布局管理器收到变更通知之前触发。此钩子允许您为文档实现语法高亮功能。

另请参阅 QAbstractTextDocumentLayout::documentChanged() 和contentsChanged()。

[signal] void QTextDocument::contentsChanged()

每当文档内容发生变化时，都会触发此信号；例如，插入或删除文本时，或者应用格式时。

另请参阅 contentsChange()。

[virtual protected] QTextObject *QTextDocument::createObject(const QTextFormat &format)

根据给定的format 创建并返回一个新的文档对象（QTextObject ）。

QTextObjects 总是通过此方法创建的，因此，如果您在文档中使用了自定义文本对象，则必须重写此方法。

[signal] void QTextDocument::cursorPositionChanged(const QTextCursor &cursor)

每当光标因编辑操作而发生位置变化时，都会触发此信号。发生变化的光标会作为参数传递给cursor 。如果文档与QTextEdit 类配合使用，且您需要在光标通过方向键移动时收到信号，可以使用QTextEdit 中的cursorPositionChanged()信号。

Qt::CursorMoveStyle QTextDocument::defaultCursorMoveStyle() const

所有从文档创建的QTextCursor 对象均使用默认的光标移动样式。默认设置为Qt::LogicalMoveStyle 。

另请参阅 setDefaultCursorMoveStyle()。

QFont QTextDocument::defaultFont() const

返回文档排版中要使用的默认字体。

另请参阅 ` setDefaultFont()`。

[static, since 6.1] QTextDocument::ResourceProvider QTextDocument::defaultResourceProvider()

返回默认资源提供程序。

该函数在 Qt 6.1 中引入。

另请参阅 setDefaultResourceProvider()、resourceProvider() 和loadResource()。

QTextOption QTextDocument::defaultTextOption() const

默认文本选项适用于文档中的所有QTextLayout 对象。这允许为文档设置全局属性，例如默认的自动换行模式。

另请参阅 setDefaultTextOption()。

QAbstractTextDocumentLayout *QTextDocument::documentLayout() const

返回该文档的布局。

另请参阅 setDocumentLayout()。

[signal] void QTextDocument::documentLayoutChanged()

当设置新的文档布局时，会发出此信号。

另请参阅 setDocumentLayout()。

void QTextDocument::drawContents(QPainter *p, const QRectF &rect = QRectF())

使用绘图器p 绘制文档内容，并裁剪至rect 。如果rect 为空矩形（默认），则文档将不进行裁剪地绘制。

QTextBlock QTextDocument::end() const

该函数返回一个块，用于在遍历文档时检测文档结尾。

for (QTextBlock it = doc->begin(); it != doc->end(); it = it.next())
    std::cout << it.text().toStdString() << "\n";

返回的代码块无效，它代表文档中最后一个代码块之后的代码块。您可以使用 `lastBlock()` 来获取文档中的最后一个有效代码块。

另请参阅 lastBlock()。

QTextCursor QTextDocument::find(const QRegularExpression &expr, const QTextCursor &cursor, QTextDocument::FindFlags options = FindFlags()) const

在文档的同一段落中查找下一个与给定正则表达式expr 匹配的出现位置。

搜索从给定的cursor 的位置开始，并沿文档向前进行，除非在搜索选项中另有指定。options 控制执行的搜索类型。

如果找到匹配项，则返回一个选中该匹配项的光标；否则返回一个空光标。

如果给定的cursor 有选区，则搜索从选区之后开始；否则从光标位置开始。

默认情况下，搜索不区分大小写，并且可以匹配文档中任何位置的文本。

QTextCursor QTextDocument::find(const QRegularExpression &expr, int from = 0, QTextDocument::FindFlags options = FindFlags()) const

在文档的同一段落中查找下一个与给定正则表达式expr 匹配的出现位置。

搜索从给定的from 位置开始，并沿文档向前进行，除非在搜索选项中另有指定。options 控制执行的搜索类型。

如果找到了匹配项，则返回一个已选中匹配项的光标；否则返回一个空光标。

如果from 位置为0（默认值），则从文档开头开始搜索；否则从指定位置开始。

QTextCursor QTextDocument::find(const QString &subString, const QTextCursor &cursor, QTextDocument::FindFlags options = FindFlags()) const

在文档中查找字符串subString 的下一次出现位置。搜索从给定的cursor 位置开始，并按文档顺序向前进行，除非在搜索选项中另有指定。options 控制执行的搜索类型。

如果找到了subString ，则返回一个选中匹配内容的光标；否则返回一个空光标。

如果给定的cursor 有选定内容，则从选定内容之后开始搜索；否则从光标位置开始搜索。

默认情况下，搜索不区分大小写，并且可以匹配文档中任何位置的文本。

QTextCursor QTextDocument::find(const QString &subString, int position = 0, QTextDocument::FindFlags options = FindFlags()) const

在文档中查找字符串subString 的下一次出现位置。搜索从给定的position 位置开始，并按文档顺序向前进行，除非在搜索选项中另有指定。options 控制执行的搜索类型。

如果找到了subString ，则返回一个已选中匹配结果的光标；否则返回一个空光标。

如果position 为 0（默认值），则搜索从文档开头开始；否则从指定位置开始。

QTextBlock QTextDocument::findBlock(int pos) const

返回包含pos 第-个字符的文本块。

QTextBlock QTextDocument::findBlockByLineNumber(int lineNumber) const

返回包含指定lineNumber 的文本块。

另请参阅 QTextBlock::firstLineNumber()。

QTextBlock QTextDocument::findBlockByNumber(int blockNumber) const

返回带有指定blockNumber 的文本块。

另请参阅 QTextBlock::blockNumber()。

QTextBlock QTextDocument::firstBlock() const

返回文档中的第一个文本块。

qreal QTextDocument::idealWidth() const

返回文本文档的理想宽度。理想宽度是指不考虑可选对齐方式时，文档实际占用的宽度。该值始终小于或等于size().width()。

另请参阅 adjustSize() 和textWidth 。

bool QTextDocument::isEmpty() const

如果文档为空，则返回true ；否则返回false 。

bool QTextDocument::isRedoAvailable() const

如果可重做，则返回true ；否则返回false 。

另请参阅 isUndoAvailable() 和availableRedoSteps()。

bool QTextDocument::isUndoAvailable() const

如果支持撤销，则返回true ；否则返回false 。

另请参阅 isRedoAvailable() 和availableUndoSteps()。

QTextBlock QTextDocument::lastBlock() const

返回文档的最后一个（有效的）文本块。

int QTextDocument::lineCount() const

返回该文档的行数（如果布局支持此功能）。否则，该值与块的数量相同。

另请参阅 blockCount() 和characterCount()。

[virtual protected invokable] QVariant QTextDocument::loadResource(int type, const QUrl &name)

从指定资源（name ）中加载指定type 的数据。

该函数由富文本引擎调用，用于请求那些虽未直接存储在QTextDocument 中，但仍与其相关的数据。例如，图像是通过QTextImageFormat 对象的name属性间接引用的。

当由 Qt XML 调用时，type 是QTextDocument::ResourceType 的值之一。

如果 `QTextDocument ` 是某个 `QObject ` 的子对象，且该 ` ` 具有可调用的 `loadResource` 方法（例如 `QTextEdit`、`QTextBrowser ` 或 `QTextDocument ` 本身），则默认实现会尝试从父对象中检索数据。

另请参阅 QTextDocument::ResourceProvider 。

void QTextDocument::markContentsDirty(int position, int length)

将由给定的position 和length 指定的内容标记为“已修改”，以此通知文档需要重新排版。

QString QTextDocument::metaInformation(QTextDocument::MetaInformation info) const

返回由info 指定的类型文档的相关元数据。

另请参阅 setMetaInformation()。

[signal] void QTextDocument::modificationChanged(bool changed)

每当文档内容发生变化且该变化影响修改状态时，都会触发此信号。如果 `changed ` 为真，则表示文档已被修改；否则为假。

例如，对文档调用setModified(false) 之后插入文本，会触发该信号。若撤销该操作，使文档恢复到原始未修改状态，该信号将再次被触发。

QTextObject *QTextDocument::object(int objectIndex) const

返回与给定的objectIndex 关联的文本对象。

QTextObject *QTextDocument::objectForFormat(const QTextFormat &f) const

返回与格式f 关联的文本对象。

int QTextDocument::pageCount() const

返回该文档的页数。

void QTextDocument::print(QPagedPaintDevice *printer) const

将文档打印到指定的printer 上。在使用此函数之前，必须先配置好QPagedPaintDevice 。

这仅是一个用于将整个文档打印到打印机的便捷方法。

如果文档已通过pageSize()属性按指定高度分页，则按原样打印。

如果文档未分页（例如在QTextEdit 中使用的文档），则会创建文档的临时副本，并根据绘图设备的 paperRect() 大小将副本分成多页。默认情况下，文档内容周围设置了 2 厘米的边距。 此外，每页底部都会打印当前页码。

另请参阅 QTextEdit::print()。

void QTextDocument::redo(QTextCursor *cursor)

如果redo is available ，则对文档重新执行上一次编辑操作。

所提供的cursor 将定位在重做编辑操作所在位置的末尾。

[slot] void QTextDocument::redo()

如果redo is available ，则重新执行对文档的最后一次编辑操作。

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        textDocument, qOverload<>(&QTextDocument::redo));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        textDocument, [receiver = textDocument]() { receiver->redo(); });

[signal] void QTextDocument::redoAvailable(bool available)

每当重做操作可用（available 为真）或不可用（available 为假）时，都会触发此信号。

QVariant QTextDocument::resource(int type, const QUrl &name) const

从具有给定name 的资源中返回指定type 的数据。

该函数由富文本引擎调用，用于请求那些虽未直接存储在QTextDocument 中，但与其相关的数据。例如，图像是通过QTextImageFormat 对象的name属性间接引用的。

资源会在文档内部进行缓存。如果缓存中找不到某个资源，则会调用loadResource 尝试加载该资源。随后，loadResource 应使用addResource 将该资源添加到缓存中。

如果loadResource 未能加载该资源，则将依次调用resourceProvider ，最后（若已设置）调用defaultResourceProvider 。请注意，提供程序返回的结果不会自动添加到缓存中。

另请参阅 QTextDocument::ResourceType 和resourceProvider()。

[since 6.1] QTextDocument::ResourceProvider QTextDocument::resourceProvider() const

返回此文本文档的资源提供程序。

该函数在 Qt 6.1 中引入。

另请参阅 setResourceProvider()、defaultResourceProvider() 和loadResource()。

int QTextDocument::revision() const

返回文档的修订版本（如果启用了“撤销”功能）。

当编辑未被修改的文档时，修订号保证会递增。

另请参阅 QTextBlock::revision() 和isModified()。

QTextFrame *QTextDocument::rootFrame() const

返回文档的根框架。

[since 6.0] void QTextDocument::setBaselineOffset(qreal baseline)

将基线设置为字体高度的百分比，用于文档排版，其范围为baseline 。默认值为 0。正值会将文本向上移动相应百分比的距离；负值则会将其向下移动。

该函数在 Qt 6.0 中引入。

另请参阅 baselineOffset()、setSubScriptBaseline()、subScriptBaseline()、setSuperScriptBaseline() 以及superScriptBaseline()。

void QTextDocument::setDefaultCursorMoveStyle(Qt::CursorMoveStyle style)

将默认光标移动样式设置为指定的style 。

另请参阅 defaultCursorMoveStyle()。

void QTextDocument::setDefaultFont(const QFont &font)

设置文档布局中要使用的默认font 。

另请参阅 defaultFont()。

[static, since 6.1] void QTextDocument::setDefaultResourceProvider(const QTextDocument::ResourceProvider &provider)

将默认资源提供程序设置为provider 。

所有未显式设置资源提供程序的 QTextDocument 对象都将使用该默认提供程序。

该函数在 Qt 6.1 中引入。

另请参阅 defaultResourceProvider()、setResourceProvider() 和loadResource()。

void QTextDocument::setDefaultTextOption(const QTextOption &option)

将默认文本选项设置为option 。

另请参阅 defaultTextOption()。

void QTextDocument::setDocumentLayout(QAbstractTextDocumentLayout *layout)

将文档设置为使用指定的layout 。之前的布局将被删除。

另请参阅 documentLayoutChanged()。

void QTextDocument::setHtml(const QString &html)

将文档的全部内容替换为html 字符串中给定的HTML格式文本。调用此函数时，撤销/重做历史记录将被重置。

HTML 格式将尽可能得到保留；例如，"<b>bold</b> text" 将生成这样的文本：第一个单词的字体粗细使其呈现为粗体："boldtext"。

若要选择默认“screen”规则以外的 CSS 媒体规则，请在调用setMetaInformation() 时将“info”参数设为 'CssMedia'。

另请参阅 setPlainText()、支持的 HTML 子集 以及setMetaInformation()。

void QTextDocument::setIndentWidth(qreal width)

设置用于文本列表和文本块缩进的width 。

QTextListFormat 和QTextBlockFormat 的缩进属性指定的是该值的倍数。默认缩进宽度为 40。

另请参阅 indentWidth()。

void QTextDocument::setMarkdown(const QString &markdown, QTextDocument::MarkdownFeatures features = MarkdownDialectGitHub)

将文档的全部内容替换为markdown 字符串中给定的Markdown格式文本，并支持给定的features 。默认情况下，包含所有受支持的GitHub风格Markdown功能；若需更基础的解析，请传入MarkdownDialectCommonMark 。

将尽可能保留 Markdown 格式；例如，“*粗体* 文本”将生成第一个单词字重增强、呈现强调效果的文本。

对markdown 字符串中包含的 HTML 的解析方式与setHtml 中的处理方式相同；但 HTML 块内的 Markdown 格式不被支持。

解析器的某些功能可通过features 参数启用或禁用。默认值为MarkdownDialectGitHub 。

调用此函数时，撤销/重做历史记录将被重置。

void QTextDocument::setMetaInformation(QTextDocument::MetaInformation info, const QString &string)

将文档中由info 指定的类型元数据设置为给定的string 。

另请参阅 metaInformation()。

void QTextDocument::setPlainText(const QString &text)

将文档的全部内容替换为给定的纯文本text 。调用此函数时，撤销/重做历史记录将被重置。

另请参阅 setHtml()。

[since 6.1] void QTextDocument::setResourceProvider(const QTextDocument::ResourceProvider &provider)

将文本文档的资源提供程序设置为provider 。

该函数自 Qt 6.1 起引入。

另请参阅 resourceProvider() 和loadResource()。

[since 6.0] void QTextDocument::setSubScriptBaseline(qreal baseline)

将默认下标的基线设置为字体高度的百分比，该值将在文档排版中用于baseline 。默认值为16.67%（高度的1/6）。

该函数在 Qt 6.0 中引入。

另请参阅 subScriptBaseline()、setSuperScriptBaseline()、superScriptBaseline()、setBaselineOffset() 和baselineOffset()。

[since 6.0] void QTextDocument::setSuperScriptBaseline(qreal baseline)

将默认上标的基线设置为字体高度的百分比，该值将在文档排版中作为baseline 使用。默认值为50%（即高度的1/2）。

该函数在 Qt 6.0 中引入。

另请参阅 superScriptBaseline()、setSubScriptBaseline()、subScriptBaseline()、setBaselineOffset() 以及baselineOffset()。

[since 6.0] qreal QTextDocument::subScriptBaseline() const

返回上标基线高度占文档布局中字体高度的百分比。

该函数在 Qt 6.0 中引入。

另请参阅 setSubScriptBaseline()、setSuperScriptBaseline()、superScriptBaseline()、setBaselineOffset() 和baselineOffset()。

[since 6.0] qreal QTextDocument::superScriptBaseline() const

返回上标基线高度占文档布局中字体高度的百分比。

该函数在 Qt 6.0 中引入。

另请参阅 setSuperScriptBaseline()、setSubScriptBaseline()、subScriptBaseline()、setBaselineOffset() 以及baselineOffset()。

QString QTextDocument::toHtml() const

返回一个包含该文档 HTML 表示形式的字符串。

文档内容指定其编码为 UTF-8。如果您稍后需要将返回的 HTML 字符串转换为字节数组以便通过网络传输或保存到磁盘，应使用 `QString::toUtf8()` 将字符串转换为 `QByteArray`。

另请参阅 “支持的 HTML 子集”。

QString QTextDocument::toMarkdown(QTextDocument::MarkdownFeatures features = MarkdownDialectGitHub) const

返回一个字符串，其中包含使用给定的features 格式化后的文档的Markdown表示形式；如果因任何原因写入失败，则返回空字符串。

另请参阅 setMarkdown 。

QString QTextDocument::toPlainText() const

返回文档中包含的纯文本。如果需要格式信息，请改用QTextCursor 函数。

此函数的返回结果与 `toRawText()` 相同，但会将某些 Unicode 字符替换为 ASCII 对应字符。 具体而言，不换行空格（U+00A0）将被替换为普通空格（U+0020），段落分隔符（U+2029）和行分隔符（U+2028）均将被替换为换行符（U+000A）。 如果您需要文档的精确内容，请改用toRawText()。

另请参阅 toHtml()。

QString QTextDocument::toRawText() const

返回文档中包含的原始文本，不包含任何格式信息。如果需要格式信息，请改用QTextCursor 。

另请参阅 toPlainText()。

void QTextDocument::undo(QTextCursor *cursor)

如果支持撤销功能，则撤销文档上的上一次编辑操作。提供的cursor 将定位在被撤销的编辑操作结束的位置。

详情请参阅Qt 撤销框架文档。

另请参阅 undoAvailable() 和isUndoRedoEnabled()。

[slot] void QTextDocument::undo()

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        textDocument, qOverload<>(&QTextDocument::undo));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        textDocument, [receiver = textDocument]() { receiver->undo(); });

[signal] void QTextDocument::undoAvailable(bool available)

每当撤销操作可用（available 为 true）或不可用（available 为 false）时，都会发出此信号。

详情请参阅Qt 撤销框架文档。

另请参阅 undo() 和isUndoRedoEnabled()。

[signal] void QTextDocument::undoCommandAdded()

每当向QTextDocument 添加一个新的撤销级别时，都会发出此信号。