QWebEngineView 类

QWebEngineView class provides a widget that is used to view and edit web documents. 更多...

Header: #include <QWebEngineView>
qmake: QT += webenginewidgets
Since: Qt 5.4
继承: QWidget



QWebEngineView (QWidget * parent = Q_NULLPTR)
virtual ~QWebEngineView ()
void findText (const QString & subString , QWebEnginePage::FindFlags options = ..., const QWebEngineCallback<bool> & resultCallback = ...)
bool hasSelection () const
QWebEngineHistory * history () const
QIcon icon () const
QUrl iconUrl () const
void load (const QUrl & url )
void load (const QWebEngineHttpRequest & request )
QWebEnginePage * page () const
QAction * pageAction (QWebEnginePage::WebAction action ) const
QString selectedText () const
void setContent (const QByteArray & data , const QString & mimeType = QString(), const QUrl & baseUrl = QUrl())
void setHtml (const QString & html , const QUrl & baseUrl = QUrl())
void setPage (QWebEnginePage * page )
void setUrl (const QUrl & url )
void setZoomFactor (qreal factor )
QWebEngineSettings * settings () const
QString title () const
void triggerPageAction (QWebEnginePage::WebAction action , bool checked = false)
QUrl url () const
qreal zoomFactor () const


virtual QSize sizeHint () const override


void back ()
void forward ()
void reload ()
void stop ()


void iconChanged (const QIcon & icon )
void iconUrlChanged (const QUrl & url )
void loadFinished (bool ok )
void loadProgress (int progress )
void loadStarted ()
void renderProcessTerminated (QWebEnginePage::RenderProcessTerminationStatus terminationStatus , int exitCode )
void selectionChanged ()
void titleChanged (const QString & title )
void urlChanged (const QUrl & url )


const QMetaObject staticMetaObject


virtual QWebEngineView * createWindow (QWebEnginePage::WebWindowType type )


virtual void contextMenuEvent (QContextMenuEvent * event ) override
virtual void dragEnterEvent (QDragEnterEvent * e ) override
virtual void dragLeaveEvent (QDragLeaveEvent * e ) override
virtual void dragMoveEvent (QDragMoveEvent * e ) override
virtual void dropEvent (QDropEvent * e ) override
virtual bool event (QEvent * ev ) override
virtual void hideEvent (QHideEvent * event ) override
virtual void showEvent (QShowEvent * event ) override



QWebEngineView class provides a widget that is used to view and edit web documents.

A Web 视图 是 Qt WebEngine Web 浏览模块的主要 Widget 组件。它可以被用于各种应用程序以实时显示来自 Internet 的 Web 内容。

A 网站 可以被加载到 Web 视图采用 load () 函数。GET 方法始终被用于加载 URL。

像所有 Qt Widget, show () 函数必须被援引以显示 Web 视图。以下代码片段阐明了这:

    QWebEngineView *view = new QWebEngineView(parent);

Alternatively, setUrl () can be used to load a web site. If you have the HTML content readily available, you can use setHtml () 代替。

loadStarted () signal is emitted when the view begins loading and the loadProgress () signal is emitted whenever an element of the web view completes loading, such as an embedded image or a script. The loadFinished () signal is emitted when the view has been loaded completely. Its argument, either true or false , indicates whether loading was successful or failed.

page () function returns a pointer to a web page object. A QWebEngineView contains a QWebEnginePage , which in turn allows access to the QWebEngineHistory in the page's context.

The title of an HTML document can be accessed with the title () property. Additionally, a web site may specify an icon, which can be accessed using the icon () 或其 URL 使用 iconUrl () 特性。若标题或图标改变,相应 titleChanged (), iconChanged () 和 iconUrlChanged () 信号会被发射。 zoomFactor () 特性使能够按比例因子缩放网页内容。

Widget 提供订制手边元素,并包括有用浏览器动作的上下文菜单。对于自定义上下文菜单,或把动作嵌入菜单或工具栏,单个动作是可用的通过 pageAction ()。Web 视图维护返回动作的状态,但允许修改动作特性,如 text or icon 。动作语义也可以被直接触发,透过 triggerPageAction ().

If you want to provide support for web sites that allow the user to open new windows, such as pop-up windows, you can subclass QWebEngineView and reimplement the createWindow () 函数。

另请参阅 WebEngine Widgets 简单浏览器范例 , WebEngine 内容操纵范例 ,和 WebEngine Markdown 编辑器范例 .


hasSelection : const bool

This property holds whether this page contains selected content or not.

默认情况下,此特性为 false .


bool hasSelection () const

另请参阅 selectionChanged ().

icon : const QIcon


默认情况下,此特性包含 null 图标。

This property was introduced in Qt 5.7.


QIcon icon () const


void iconChanged (const QIcon & icon )

另请参阅 iconChanged (), iconUrl (),和 iconUrlChanged ().

iconUrl : const QUrl

此特性保持关联目前查看页面的图标 URL。

默认情况下,此特性包含空 URL。


QUrl iconUrl () const


void iconUrlChanged (const QUrl & url )

另请参阅 iconUrlChanged (), icon (),和 iconChanged ().

selectedText : const QString




QString selectedText () const

另请参阅 findText () 和 selectionChanged ().

title : const QString

此特性保持页面的标题,定义通过 HTML <title> 元素。

相当于 QWebEnginePage::title ().


QString title () const

另请参阅 titleChanged ().

url : QUrl

此特性保持目前查看网页的 URL。

设置此特性清零视图并加载 URL。

默认情况下,此特性包含空的无效 URL。


QUrl url () const
void setUrl (const QUrl & url )

另请参阅 load () 和 urlChanged ().

zoomFactor : qreal


有效值范围从 0.25 to 5.0 。默认因子为 1.0 .


qreal zoomFactor () const
void setZoomFactor (qreal factor )


QWebEngineView:: QWebEngineView ( QWidget * parent = Q_NULLPTR)

构造空 Web 视图采用父级 parent .

另请参阅 load ().

[virtual] QWebEngineView:: ~QWebEngineView ()

销毁 Web 视图。

[slot] void QWebEngineView:: back ()




另请参阅 forward () 和 pageAction ().

[override virtual protected] void QWebEngineView:: contextMenuEvent ( QContextMenuEvent * event )

Reimplemented from QWidget::contextMenuEvent ().

[virtual protected] QWebEngineView *QWebEngineView:: createWindow ( QWebEnginePage::WebWindowType type )

此函数被调用从 createWindow() 方法的关联 QWebEnginePage 每次页面希望创建新窗口源于给定 type 。例如,当 JavaScript 请求在新窗口中打开文档被发出时。

注意: createWindow() 方法的关联页面被重实现,此方法不被调用,除非在重实现中明确这样做。

另请参阅 QWebEnginePage::createWindow ().

[override virtual protected] void QWebEngineView:: dragEnterEvent ( QDragEnterEvent * e )

Reimplemented from QWidget::dragEnterEvent ().

[override virtual protected] void QWebEngineView:: dragLeaveEvent ( QDragLeaveEvent * e )

Reimplemented from QWidget::dragLeaveEvent ().

[override virtual protected] void QWebEngineView:: dragMoveEvent ( QDragMoveEvent * e )

Reimplemented from QWidget::dragMoveEvent ().

[override virtual protected] void QWebEngineView:: dropEvent ( QDropEvent * e )

Reimplemented from QWidget::dropEvent ().

[override virtual protected] bool QWebEngineView:: event ( QEvent * ev )

Reimplemented from QWidget::event ().

void QWebEngineView:: findText (const QString & subString , QWebEnginePage::FindFlags options = ..., const QWebEngineCallback < bool > & resultCallback = ...)

查找指定字符串, subString , in the page, using the given options .


resultCallback must take a boolean parameter. It will be called with a value of true if subString was found; otherwise the callback value will be false .

警告: 我们保证回调 ( resultCallback ) 总是被调用,但它可能在页面销毁期间完成。当 QWebEnginePage 被删除,会采用无效值触发回调,因此它是不安全的,去使用相应 QWebEnginePage or QWebEngineView 实例在其中。

另请参阅 selectedText () 和 selectionChanged ().

[slot] void QWebEngineView:: forward ()




另请参阅 back () 和 pageAction ().

[override virtual protected] void QWebEngineView:: hideEvent ( QHideEvent * event )

Reimplemented from QWidget::hideEvent ().

QWebEngineHistory *QWebEngineView:: history () const




[signal] void QWebEngineView:: iconChanged (const QIcon & icon )

This signal is emitted when the icon ("favicon") associated with the view is changed. The new icon is specified by icon .

This function was introduced in Qt 5.7.

注意: 通知信号为特性 icon .

另请参阅 icon (), iconUrl (),和 iconUrlChanged ().

[signal] void QWebEngineView:: iconUrlChanged (const QUrl & url )

This signal is emitted when the URL of the icon ("favicon") associated with the view is changed. The new URL is specified by url .

注意: 通知信号为特性 iconUrl .

另请参阅 iconUrl (), icon (),和 iconChanged ().

void QWebEngineView:: load (const QUrl & url )

加载指定 url 并显示它。

注意: 视图保持不变,直到已达成足够数据才显示新的 URL。

另请参阅 load(), setUrl (), url (), urlChanged (),和 QUrl::fromUserInput ().

void QWebEngineView:: load (const QWebEngineHttpRequest & request )

发出指定 request 并加载响应。

This function was introduced in Qt 5.9.

另请参阅 load (), setUrl (), url (), urlChanged (),和 QUrl::fromUserInput ().

[signal] void QWebEngineView:: loadFinished ( bool ok )

此信号被发射当页面的加载已完成时。 ok 将指示加载成功 (或发生错误)。

另请参阅 loadStarted ().

[signal] void QWebEngineView:: loadProgress ( int progress )

此信号被发射每当 Web 视图中的某个元素加载完成 (如:嵌入式图像或脚本) 时。因此,它跟踪加载 Web 视图的集体进度。

当前值被提供由 progress 并缩放到 0 - 100,其是默认范围为 QProgressBar .

另请参阅 loadStarted () 和 loadFinished ().

[signal] void QWebEngineView:: loadStarted ()


另请参阅 loadProgress () 和 loadFinished ().

QWebEnginePage *QWebEngineView:: page () const

返回指向底层 Web 页面的指针。

另请参阅 setPage ().

QAction *QWebEngineView:: pageAction ( QWebEnginePage::WebAction action ) const

返回指针指向 QAction 封装指定的 Web 动作 action .

[slot] void QWebEngineView:: reload ()


另请参阅 stop (), pageAction (),和 loadStarted ().

[signal] void QWebEngineView:: renderProcessTerminated ( QWebEnginePage::RenderProcessTerminationStatus terminationStatus , int exitCode )

此信号被发射当渲染进程采用非零退出状态被终止时。 terminationStatus 是进程的终止状态,且 exitCode 是进程终止的状态码。

This function was introduced in Qt 5.6.

[signal] void QWebEngineView:: selectionChanged ()


注意: 当使用鼠标通过左键点击并拖曳以选择文本时,会为每个新选中字符发射信号,而不是在释放鼠标左键时。

另请参阅 selectedText ().

void QWebEngineView:: setContent (const QByteArray & data , const QString & mimeType = QString(), const QUrl & baseUrl = QUrl())

把 Web 视图内容设为 data 。若 mimeType argument is empty, it is assumed that the content is text/plain,charset=US-ASCII .

External objects referenced in the content are located relative to baseUrl . For external objects to be loaded, baseUrl cannot be empty.

The data is loaded immediately; external objects are loaded asynchronously.

另请参阅 load (), setHtml (),和 QWebEnginePage::toHtml ().

void QWebEngineView:: setHtml (const QString & html , const QUrl & baseUrl = QUrl())

Sets the content of the web view to the specified html content.

External objects, such as stylesheets or images referenced in the HTML document, are located relative to baseUrl . For external objects to be loaded, baseUrl cannot be empty. For example, if html is retrieved from http://www.example.com/documents/overview.html , which is the base URL, then an image referenced with the relative URL, diagram.png , should be at http://www.example.com/documents/diagram.png .

The HTML document is loaded immediately, whereas external objects are loaded asynchronously.

When using this method, Qt WebEngine assumes that external resources, such as JavaScript programs or style sheets, are encoded in UTF-8 unless otherwise specified. For example, the encoding of an external script can be specified through the charset attribute of the HTML script tag. Alternatively, the encoding can be specified by the web server.

This is a convenience function equivalent to setContent(html, "text/html;charset=UTF-8", baseUrl) .

警告: This function works only for HTML. For other MIME types (such as XHTML or SVG), setContent () should be used instead.

注意: Content larger than 2 MB cannot be displayed, because setHtml() converts the provided HTML to percent-encoding and places data : in front of it to create the URL that it navigates to. Thereby, the provided code becomes a URL that exceeds the 2 MB limit set by Chromium. If the content is too large, the loadFinished () signal is triggered with success=false .

另请参阅 load (), setContent (), QWebEnginePage::toHtml (),和 QWebEnginePage::setContent ().

void QWebEngineView:: setPage ( QWebEnginePage * page )

Makes page the new web page of the web view.

The parent QObject of the provided page remains the owner of the object. If the current page is a child of the web view, it will be deleted.

另请参阅 page ().

QWebEngineSettings *QWebEngineView:: settings () const

Returns a pointer to the view or page specific settings object.



另请参阅 QWebEngineSettings::globalSettings ().

[override virtual protected] void QWebEngineView:: showEvent ( QShowEvent * event )

Reimplemented from QWidget::showEvent ().

[override virtual] QSize QWebEngineView:: sizeHint () const

Reimplemented from QWidget::sizeHint ().

[slot] void QWebEngineView:: stop ()




另请参阅 reload (), pageAction (),和 loadFinished ().

[signal] void QWebEngineView:: titleChanged (const QString & title )

此信号被发射每当 title of the view changes.

另请参阅 title ().

void QWebEngineView:: triggerPageAction ( QWebEnginePage::WebAction action , bool checked = false)

触发指定 action 。若是可复选动作,指定 checked 假定状态。



另请参阅 pageAction ().

[signal] void QWebEngineView:: urlChanged (const QUrl & url )

此信号被发射当 url of the view changes.

另请参阅 url () 和 load ().