Back to Qt.io
Contact Us Blog Download Qt

QTextBrowser Class

QTextBrowser 类提供了一个具有超文本导航功能的富文本浏览器。更多

头文件： #include <QTextBrowser>
CMake： find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake： QT += widgets
继承： QTextEdit

属性

公共函数

QTextBrowser(QWidget *parent = nullptr)
int backwardHistoryCount() const
void clearHistory()
int forwardHistoryCount() const
QString historyTitle(int i) const
QUrl historyUrl(int i) const
bool isBackwardAvailable() const
bool isForwardAvailable() const
bool openExternalLinks() const
bool openLinks() const
QStringList searchPaths() const
void setOpenExternalLinks(bool open)
void setOpenLinks(bool open)
void setSearchPaths(const QStringList &paths)
QUrl source() const
QTextDocument::ResourceType sourceType() const

重新实现的公共函数

virtual QVariant loadResource(int type, const QUrl &name) override

公共插槽

virtual void backward()
virtual void forward()
virtual void home()
virtual void reload()
void setSource(const QUrl &url, QTextDocument::ResourceType type = QTextDocument::UnknownResource)

信号

void anchorClicked(const QUrl &link)
void backwardAvailable(bool available)
void forwardAvailable(bool available)
void highlighted(const QUrl &link)
void historyChanged()
void sourceChanged(const QUrl &src)

受保护函数

virtual void doSetSource(const QUrl &url, QTextDocument::ResourceType type = QTextDocument::UnknownResource)

重新实现的受保护函数

virtual bool event(QEvent *e) override
virtual bool focusNextPrevChild(bool next) override
virtual void focusOutEvent(QFocusEvent *ev) override
virtual void keyPressEvent(QKeyEvent *ev) override
virtual void mouseMoveEvent(QMouseEvent *e) override
virtual void mousePressEvent(QMouseEvent *e) override
virtual void mouseReleaseEvent(QMouseEvent *e) override
virtual void paintEvent(QPaintEvent *e) override

详细说明

该类扩展了QTextEdit （只读模式），增加了一些导航功能，以便用户可以在超文本文档中跟踪链接。

如果您想为用户提供可编辑的富文本编辑器，请使用QTextEdit 。如果您想要一个不带超文本导航功能的文本浏览器，请使用QTextEdit ，并使用QTextEdit::setReadOnly() 禁用编辑功能。如果只需要显示一小段富文本，请使用QLabel 。

文件来源和内容

QTextEdit 的内容是通过setHtml() 或setPlainText() 设置的，但 QTextBrowser 还实现了setSource() 函数，从而可以使用一个已命名的文档作为源文本。该名称会在搜索路径列表和当前文档工厂的目录中查找。

如果文档名称以锚结尾（例如"#anchor" ），文本浏览器会自动滚动到该位置（使用scrollToAnchor() ）。当用户点击超链接时，浏览器将以链接的href 值为参数调用setSource() 本身。您可以通过连接sourceChanged() 信号来跟踪当前来源。

QTextBrowser 提供了backward() 和forward() 插槽，您可以用它们来实现 "后退 "和 "前进 "按钮。home() 插槽将文本设置为显示的第一个文档。当用户点击锚点时，将发出anchorClicked() 信号。要覆盖浏览器的默认导航行为，请调用setSource() 函数，在与该信号相连的槽中提供新的文档文本。

如果要加载存储在 Qt 资源系统中的文档，请在要加载的 URL 中使用qrc 作为方案。例如，对于文档资源路径:/docs/index.html ，使用setSource() 将qrc:/docs/index.html 作为 URL。

另请参阅 QTextEdit 和QTextDocument 。

属性文档

[read-only] modified : const bool

该属性显示文本浏览器的内容是否已被修改

指定QTextBrowser 是否应使用QDesktopServices::openUrl() 自动打开外部链接，而不是发出anchorClicked 信号。如果链接方案既不是文件也不是 qrc，则视为外部链接。

默认值为 false。

访问函数：

bool openExternalLinks() const
void setOpenExternalLinks(bool open)

该属性指定QTextBrowser 是否会自动打开用户试图通过鼠标或键盘激活的链接。

无论该属性的值如何，anchorClicked 信号始终会发出。

默认值为 true。

访问功能：

bool openLinks() const
void setOpenLinks(bool open)

readOnly : const bool

该属性表示文本浏览器是否为只读。

默认情况下，此属性为true 。

searchPaths : QStringList

该属性包含文本浏览器用于查找支持内容的搜索路径。

QTextBrowser 使用此列表查找图片和文档。

默认情况下，该属性包含一个空字符串列表。

访问功能：

QStringList searchPaths() const
void setSearchPaths(const QStringList &paths)

source : QUrl

该属性包含显示文档的名称。

如果未显示文件或来源未知，则该 URL 无效。

设置该属性时，QTextBrowser 会尝试在searchPaths 属性和当前源目录的路径中查找具有指定名称的文档，除非该值是绝对文件路径。它还会检查可选的锚点，并相应地滚动文档

如果文档中的第一个标签是<qt type=detail> ，文档将以弹出窗口形式显示，而不是在浏览器窗口中以新文档形式显示。否则，文档将在文本浏览器中正常显示，并根据文件名是否以任何已知的 Markdown 文件扩展名结尾，用QTextDocument::setHtml() 或QTextDocument::setMarkdown() 将文本设置为已命名文档的内容。

如果您想避免自动类型检测并明确指定类型，请调用setSource() 而不是设置此属性。

默认情况下，该属性包含一个空 URL。

访问功能：

QUrl source() const
void setSource(const QUrl &url, QTextDocument::ResourceType type = QTextDocument::UnknownResource)

[read-only] sourceType : const QTextDocument::ResourceType

该属性用于保存所显示文件的类型

如果未显示文件或来源类型未知，则该属性为QTextDocument::UnknownResource 。否则，它将保存检测到的类型或调用setSource() 时指定的类型。

访问函数：

QTextDocument::ResourceType sourceType() const

undoRedoEnabled : const bool

该属性表示文本浏览器是否支持撤销/重做操作

默认情况下，该属性为false 。

成员函数文档

[explicit] QTextBrowser::QTextBrowser(QWidget *parent = nullptr)

构造一个空的 QTextBrowser，其父级parent 。

[signal] void QTextBrowser::anchorClicked(const QUrl &link)

当用户点击锚点时会发出该信号。锚点引用的 URL 在link 中传递。

请注意，浏览器将自动处理导航至link 指定的位置，除非openLinks 属性设置为 false 或在连接的槽中调用setSource() 。该机制用于覆盖浏览器的默认导航功能。

[virtual slot] void QTextBrowser::backward()

将显示的文档更改为通过导航链接建立的文档列表中的前一个文档。如果没有前一个文档，则不执行任何操作。

另请参阅 forward() 和backwardAvailable()。

[signal] void QTextBrowser::backwardAvailable(bool available)

当backward() 的可用性发生变化时，将发出该信号。当用户位于home() 时，available 为假；否则为真。

int QTextBrowser::backwardHistoryCount() const

返回历史记录中后退的位置数。

void QTextBrowser::clearHistory()

清除已访问文档的历史记录，并禁用向前和向后导航。

另请参阅 backward() 和forward() 。

[virtual protected] void QTextBrowser::doSetSource(const QUrl &url, QTextDocument::ResourceType type = QTextDocument::UnknownResource)

尝试在给定的url 处使用指定的type 加载文档。

setSource() 调用 doSetSource。在 Qt XML 5 中，setSource(constQUrl &url) 是虚拟的。在 Qt 6 中，doSetSource() 是虚拟的，因此可以在子类中重载。

[override virtual protected] bool QTextBrowser::event(QEvent *e)

重实现：QAbstractScrollArea::event(QEvent *event).

[override virtual protected] bool QTextBrowser::focusNextPrevChild(bool next)

重实现：QTextEdit::focusNextPrevChild(bool next）。

[override virtual protected] void QTextBrowser::focusOutEvent(QFocusEvent *ev)

重实现：QTextEdit::focusOutEvent(QFocusEvent *e)。

[virtual slot] void QTextBrowser::forward()

将显示的文档更改为通过导航链接建立的文档列表中的下一个文档。如果没有下一个文档，则不执行任何操作。

另请参阅 backward() 和forwardAvailable()。

[signal] void QTextBrowser::forwardAvailable(bool available)

当forward() 的可用性发生变化时，将发出该信号。用户浏览backward() 后，available 为 true；当用户浏览或进入forward() 时， 为 false。

int QTextBrowser::forwardHistoryCount() const

返回历史记录中前移位置的数量。

[signal] void QTextBrowser::highlighted(const QUrl &link)

当用户选择但未激活文档中的锚点时，就会发出该信号。锚点指向的 URL 在link 中传递。

[signal] void QTextBrowser::historyChanged()

历史记录发生变化时会发出该信号。

另请参阅 historyTitle() 和historyUrl()。

QString QTextBrowser::historyTitle(int i) const

返回 HistoryItem 的documentTitle() 值。

输入返回值
i < 0backward() 历史
i == 0当前，参见QTextBrowser::source()
i > 0forward() 历史记录
backaction.setToolTip(browser.historyTitle(-1));
forwardaction.setToolTip(browser.historyTitle(+1));

QUrl QTextBrowser::historyUrl(int i) const

返回 HistoryItem 的 url。

输入返回值
i < 0backward() 历史
i == 0当前，参见QTextBrowser::source()
i > 0forward() 历史记录

[virtual slot] void QTextBrowser::home()

将显示的文件更改为历史记录中的第一个文件。

bool QTextBrowser::isBackwardAvailable() const

如果文本浏览器可以使用backward() 回溯文档历史，则返回true 。

另请参阅 backwardAvailable() 和backward()。

bool QTextBrowser::isForwardAvailable() const

如果文本浏览器可以使用forward() 继续浏览文档历史，则返回true 。

另请参阅 forwardAvailable() 和forward()。

[override virtual protected] void QTextBrowser::keyPressEvent(QKeyEvent *ev)

重实现：QTextEdit::keyPressEvent(QKeyEvent *e)。

该事件ev 用于提供以下键盘快捷键：

按键操作
Alt+ 左箭头backward()
Alt+ 右箭头forward()
Alt+ 上箭头home()

[override virtual] QVariant QTextBrowser::loadResource(int type, const QUrl &name)

重实现：QTextEdit::loadResource(int type, const QUrl &name）。

该函数在加载文档时以及为文档中的每个图像调用。type 表示要加载的资源类型。如果无法加载资源，则返回无效的QVariant 。

默认实现会忽略type ，并尝试将name 解释为文件名来定位资源。如果不是绝对路径，则会尝试在searchPaths 属性的路径中以及与当前源相同的目录中查找文件。成功后，结果是一个QVariant ，其中存储了一个包含文件内容的QByteArray 。

如果重新实现此函数，可以返回其他QVariant 类型。下表显示了根据资源类型支持的变体类型：

资源类型QMetaType::Type
QTextDocument::HtmlResourceQString 或QByteArray
QTextDocument::ImageResourceQImage,QPixmap 或QByteArray
QTextDocument::StyleSheetResourceQString 或QByteArray
QTextDocument::MarkdownResourceQString 或QByteArray

[override virtual protected] void QTextBrowser::mouseMoveEvent(QMouseEvent *e)

重实现：QTextEdit::mouseMoveEvent(QMouseEvent *e)。

[override virtual protected] void QTextBrowser::mousePressEvent(QMouseEvent *e)

重实现：QTextEdit::mousePressEvent(QMouseEvent *e)。

[override virtual protected] void QTextBrowser::mouseReleaseEvent(QMouseEvent *e)

重实现：QTextEdit::mouseReleaseEvent(QMouseEvent *e)。

[override virtual protected] void QTextBrowser::paintEvent(QPaintEvent *e)

重实现：QTextEdit::paintEvent(QPaintEvent *event).

[virtual slot] void QTextBrowser::reload()

重新读取当前的设置源。

[slot] void QTextBrowser::setSource(const QUrl &url, QTextDocument::ResourceType type = QTextDocument::UnknownResource)

尝试用指定的type 加载给定url 上的文档。

如果type 是UnknownResource （默认值），则将检测文档类型：也就是说，如果 url 以.md 、.mkd 或.markdown 扩展名结尾，则将通过QTextDocument::setMarkdown() 加载文档；否则将通过QTextDocument::setHtml() 加载文档。可以通过明确指定type 来绕过这种检测。

注： 属性source 的设置函数。

另请参阅 source() 。

[signal] void QTextBrowser::sourceChanged(const QUrl &src)

源发生变化时会发出该信号，src 就是新的源。

源更改会在调用setSource(),forward(),backward() 或home() 或用户点击链接或按下相应按键序列时通过编程发生。

© 2025 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.