Back to Qt.io
Contact Us Blog Download Qt
本页内容

WebView QML Type

用于显示网页内容的组件。更多...

Import Statement: import QtWebView

属性

信号

方法

详细说明

WebView 是一个用于显示网页内容的组件，在支持原生 API 的平台上，它通过原生 API 实现，因此应用程序并不一定需要包含完整的网页浏览器栈。

为了使Qt WebView 模块在所有平台上都能正常运行，必须在创建QGuiApplication 实例后立即调用QtWebView::initialize()。

注意：由于 平台限制，不支持将 WebView 与其他 QML 组件重叠。

属性文档

canGoBack : bool [read-only]

如果当前可以在网页历史记录中向后导航，则该属性值为true 。

canGoForward : bool [read-only]

如果当前可以在网页历史记录中向前浏览，则返回true 。

httpUserAgent : url [since QtWebView 1.14]

当前使用的用户代理。

该属性在 QtWebView 1.14 中引入。

loadProgress : int [read-only]

网页内容的当前加载进度，以0到100之间的整数表示。

loading : bool [read-only]

如果WebView 当前正在加载新内容，则返回true ；否则返回false 。

另请参阅 loadingChanged()。

settings : WebViewSettings [read-only, since QtWebView 6.5]

WebView 的设置对象。

该属性自 QtWebView 6.5 起引入。

另请参阅 WebViewSettings 。

title : string [read-only]

当前加载的网页的标题。

url : url

当前加载的网页的 URL。修改此项将触发新内容的加载。

该 URL 将原样使用。源自用户输入的 URL 应通过QUrl::fromUserInput() 进行解析。

注意： WebView 不支持通过 Qt 资源系统加载内容。

信号文档

cookieAdded(string domain, string name)

当添加一个 Cookie 时，会发出此信号。

这些参数提供了关于已添加 Cookie 的domain 和name 的信息。

注意：当 使用Qt WebEngine 模块作为后端时 ，对于添加到底层QWebEngineCookieStore 中的任何 Cookie（包括由网站添加的 Cookie），都会触发 cookieAdded 信号。在其他情况下，cookieAdded 信号仅在通过setCookie() 显式添加 Cookie 时触发。

注意： 对应的处理程序 是onCookieAdded 。

cookieRemoved(string domain, string name)

当一个 Cookie 被删除时，会发出此信号。

这些参数提供了关于被删除 Cookie 的domain 和name 的信息。

注意： 相应的处理程序 为onCookieRemoved 。

httpUserAgentChanged(string userAgent)

每当视图的userAgent 发生变化时，都会触发此信号。

注意： 相应的处理程序 为onHttpUserAgentChanged 。

另请参阅 httpUserAgent 。

loadProgressChanged(int loadProgress)

在网页加载过程中，该信号会持续发出。loadProgress 参数的取值范围为0到100，表示网页已加载的百分比。该信号的用途是向用户显示进度条。

注意：某些 后端不支持加载进度的小数变化，仅会在加载开始和结束时发出此信号，此时的值分别为 0 和 100。

注意： 对应的处理程序 是 `onLoadProgressChanged`。

另请参阅 loadingChanged 。

loadingChanged(WebViewLoadRequest loadRequest)

当网页内容的加载状态发生变化时，会发出此信号。通过处理此信号，可以实现对页面加载错误等情况的响应。

loadRequest 参数包含请求的URL和状态，以及一个errorString字段，其中包含请求失败时的错误消息。

注意： 相应的处理程序 为 `onLoadingChanged`。

另请参阅 WebViewLoadRequest 。

titleChanged(string title)

每当视图的“title ”发生变化时，都会触发此信号。

注意： 相应的处理程序 为onTitleChanged 。

另请参阅 title 。

urlChanged(url url)

每当视图的url 发生变化时，都会触发此信号。

注意： 相应的处理程序 为onUrlChanged 。

另请参阅 url 。

方法文档

[since QtWebView 6.3] void deleteAllCookies()

删除所有 Cookie。

该方法自 QtWebView 6.3 起引入。

[since QtWebView 6.3] void deleteCookie(string domain, string name)

删除具有指定domain 和name 的Cookie。

当 Cookie 被删除时，将触发cookieRemoved 信号。

此方法自 QtWebView 6.3 起引入。

void goBack()

在网页历史记录中向后浏览。

void goForward()

在网页历史记录中向前浏览。

void loadHtml(string html, url baseUrl)

将指定的html 内容加载到Web视图中。

该方法提供了url 属性的低级替代方案，该属性通过URL引用HTML页面。

HTML 文档中引用的样式表或图像等外部对象应位于baseUrl 的相对路径下。例如，如果html 是从http://www.example.com/documents/overview.html （即基 URL）获取的，那么使用相对 URLdiagram.png 引用的图像应位于http://www.example.com/documents/diagram.png 。

注意： WebView 不支持通过 Qt 资源系统加载内容。

另请参阅 url 。

void reload()

重新加载当前的url 。

void runJavaScript(string script, variant callback)

执行指定的 JavaScript 代码。如果提供了 `callback ` 函数，则会在 `script ` 执行完毕后调用该函数。

runJavaScript("document.title", function(result) { console.log(result); });

[since QtWebView 6.3] void setCookie(string domain, string name, string value)

添加一个包含指定domain 、name 和value 的Cookie。

当添加该 Cookie 时，将触发cookieAdded 信号。

该方法自 QtWebView 6.3 起引入。

void stop()

停止加载当前的url 。

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