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)

使用type 和name 作为标识符，将资源resource 添加到资源缓存中。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-th 字符的文本块。

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 是具有可调用 loadResource 方法（如QTextEdit 、QTextBrowser 或QTextDocument 本身）的QObject 的子对象，那么默认实现会尝试从父对象中检索数据。

另请参阅 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 为 true，则表示文档已被修改；否则为 false。

例如，在文档上调用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 ，重做文档上的最后一次编辑操作。

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

每当重做操作可用（available 为 true）或不可用（available 为 false）时，都会发出该信号。

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 。

所有未设置显式提供程序的 QTextDocuments 都将使用默认提供程序。

此函数在 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>粗体</b>文本 "将生成第一个单词字体加粗的文本："粗体文本"。

要选择默认 "screen "规则以外的 css 媒体规则，请使用setMetaInformation() 并将 "CssMedia"作为 "info "参数。

另请参阅 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 格式会尽可能得到尊重；例如，"*bold* text"（*粗体*文本）会产生第一个单词字体加重的文本。

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() 相同，但会用 ASCII 替代字符替换某些 unicode 字符。特别是，无分隔空格（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()

这是一个重载函数。

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

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

详情请参见Qt 撤消框架文档。

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

[signal] void QTextDocument::undoCommandAdded()

每次在QTextDocument 中添加新的撤销级别时，都会发出该信号。