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()）。当用户点击超链接时，浏览器会自行调用setSource()，并将链接的href 值作为参数传入。您可以通过连接到sourceChanged()信号来跟踪当前源文本。

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

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

另请参阅 QTextEdit 和QTextDocument 。

属性文档

[read-only] modified : bool

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

指定QTextBrowser 是否应使用QDesktopServices::openUrl()自动打开指向外部资源的链接，而不是触发anchorClicked 信号。如果链接的方案既不是file也不是qrc，则该链接被视为外部链接。

默认值为 false。

访问函数：

bool openExternalLinks() const
void setOpenExternalLinks(bool open)

此属性用于指定QTextBrowser 是否应自动打开用户尝试通过鼠标或键盘激活的链接。

无论此属性的值为何，anchorClicked 信号都会始终被触发。

默认值为 true。

访问函数：

bool openLinks() const
void setOpenLinks(bool open)

readOnly : bool

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

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

searchPaths : QStringList

该属性存储了文本浏览器用于查找辅助内容的搜索路径

QTextBrowser 使用此列表来定位图像和文档。

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

访问函数：

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

source : QUrl

该属性存储所显示文档的名称。

如果未显示任何文档，或者来源未知，则该 URL 无效。

设置此属性时，QTextBrowser 会尝试在searchPaths 属性的路径以及当前源的目录中查找指定名称的文档，除非该值为绝对文件路径。它还会检查可选的锚点，并据此滚动文档

如果文档中的第一个标签是 `<qt type=detail>`，则该文档将作为弹出窗口显示，而非在浏览器窗口中作为新文档显示。否则，文档将在文本浏览器中正常显示，其文本内容将通过 `QTextDocument::setHtml()` 或 `QTextDocument::setMarkdown()` 设置为指定文档的内容，具体取决于文件名是否以已知的 Markdown 文件扩展名结尾。

若要避免自动类型检测并显式指定类型，请调用setSource() 而不是设置此属性。

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

访问函数：

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

[read-only] sourceType : QTextDocument::ResourceType

该属性存储所显示文档的类型

如果未显示任何文档，或者源文档的类型未知，则该属性值为QTextDocument::UnknownResource 。否则，它将存储检测到的类型，或者在调用setSource()时指定的类型。

访问函数：

QTextDocument::ResourceType sourceType() const

undoRedoEnabled : bool

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

默认情况下，此属性的值为false 。

成员函数文档

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

创建一个父容器为parent 的空QTextBrowser。

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

当用户点击锚点时，会触发此信号。锚点所指向的 URL 将通过link 传递进来。

请注意，除非将openLinks 属性设置为false，或者您在关联的插槽中调用setSource()，否则浏览器会自动处理跳转至link 指定的位置。此机制用于覆盖浏览器的默认导航功能。

[virtual slot] void QTextBrowser::backward()

将当前显示的文档切换为通过导航链接生成的文档列表中的上一份文档。若不存在上一份文档，则不执行任何操作。

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

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

当backward() 的可用状态发生变化时，会触发此信号。当用户位于home() 时，available 为 false；否则为 true。

int QTextBrowser::backwardHistoryCount() const

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

void QTextBrowser::clearHistory()

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

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

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

尝试使用指定的type 加载位于给定url 的文档。

setSource() 会调用 doSetSource。在 Qt 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() history
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 的setter 函数。

另请参阅 source()。

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

当源发生变化时会发出此信号，此时src 即为新源。

源的变更既可能通过调用setSource()、forward()、backward() 或home() 等方法在程序中实现，也可能发生在用户点击链接或按下相应的键盘快捷键时。

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