QWebEnginePage 类

成员函数文档

运行 scriptSource 中的 JavaScript 代码，而不检查页面 DOM 是否已构建。如果需要更细粒度的脚本执行控制，请考虑使用 scripts()。

为了避免与其他在页面上执行的脚本冲突，指定执行脚本的世界是通过 worldId 来实现的。世界 ID 值与 QWebEngineScript::ScriptWorldId 提供的值相同，范围在 0 到 256 之间。如果您省略 world ID，脚本将在 MainWorld 中运行。

脚本执行完成后，将调用 resultCallback 并传入最后一个执行语句的结果。 resultCallback 可以是任何函数指针、仿函数或 lambda 表达式，并期望接受一个 QVariant 参数。例如

page.runJavaScript("document.title", [](const QVariant &v) { qDebug() << v.toString(); });

从 JavaScript 返回的结果值只能是纯数据。支持的数据类型包括所有 JSON 数据类型以及例如 Date 和 ArrayBuffer。不支持的数据类型包括例如 Function 和 Promise。

另请参阅 scripts()，QWebEngineScript::ScriptWorldId，以及脚本注入。

[显式] QWebEnginePage::QWebEnginePage(QObject *parent = nullptr)

使用指定的父对象parent构造一个空的QWebEnginePage。

QWebEnginePage::QWebEnginePage(QWebEngineProfile *profile, QObject *parent = nullptr)

在指定的Web引擎配置文件profile中创建一个空的Web页面，并使用指定的父对象parent。

如果配置文件不是默认配置，调用者必须确保配置文件与页面对象一样长生命。

[虚函数] QWebEnginePage::~QWebEnginePage()

销毁网页。

[虚保护] bool QWebEnginePage::acceptNavigationRequest(const QUrl &url, QWebEnginePage::NavigationType type, bool isMainFrame)

当收到请求使用指定的导航类型type导航到指定的url时调用此函数。如果isMainFrame指示请求对应于主框架或子框架，则函数返回true，接受导航请求并加载url。默认实现接受所有导航请求。

可以覆盖此函数将导航请求委派给Qt应用程序，而不是由HTML处理器引擎处理，从而处理导航请求。当HTML文档用作用户界面的一部分，而不是显示外部数据时（例如在显示结果列表时），需要这样做。

QWebEngineUrlRequestInterceptor类提供了进一步拦截和操纵请求的选项。

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

返回指定WebAction action的QAction。

操作由QWebEnginePage拥有，但您可以通过更改其属性来自定义外观。

QWebEnginePage::action(WebAction action) 方法没有默认样式的图标。请使用 QWebEngineView::pageAction() 来获取带有默认样式图标的操作。

QWebEnginePage 还负责实现操作，以便在页面上触发相应的操作。

另外参见triggerAction。

[信号] void QWebEnginePage::audioMutedChanged(bool muted)

当页面 muted 状态发生变化时，会发射此信号。

[信号] void QWebEnginePage::authenticationRequired(const QUrl &requestUrl, QAuthenticator *authenticator)

当访问 requestUrl 需要身份验证时，会发射此信号。应该使用 authenticator 来传递连接的用户名和密码。

[信号] void QWebEnginePage::certificateError(const QWebEngineCertificateError &certificateError)

在加载给定的请求期间，当发出无效证书错误时，会发射此信号。

certificateError 参数包含有关证书和错误详细信息的信息，并且还提供了忽略错误并完成请求或停止加载请求的方式。

另外参见QWebEngineCertificateError。

[虚保护] QStringList QWebEnginePage::chooseFiles(QWebEnginePage::FileSelectionMode mode, const QStringList &oldFiles, const QStringList &acceptedMimeTypes)

在网页内容请求文件名时调用此函数，例如，当用户在 HTML 表单中点击文件上传按钮时。

mode 表示是否期望返回一个或多个文件。

可以在 oldFiles 的第一个条目中提供建议的文件名。默认实现忽略 acceptedMimeTypes，但可能由覆盖使用。

[虚保护] QWebEnginePage *QWebEnginePage::createWindow(QWebEnginePage::WebWindowType type)

此函数用于创建指定 type 的新窗口。例如，当 JavaScript 程序请求在新的窗口中打开文档时。

如果可以创建新窗口，则返回新窗口的 QWebEnginePage；否则返回 null 指针。

如果与网页关联的视图是 QWebEngineView 对象，则默认实现将请求转发到 QWebEngineView::createWindow()；否则返回 null 指针。

如果此调用未实现或未返回新页面，则会发出newWindowRequested() 来处理请求。

另请参阅 QWebEngineView::createWindow() 和 newWindowRequested().

[since 6.6] QString QWebEnginePage::devToolsId() const

返回与此页面关联的开发者工具主机ID。

如果启用了远程调试（请参阅Qt WebEngine开发者工具），则可以使用ID构建连接到开发者工具WebSocket的URL：ws://localhost:<debugggin-port>/devtools/page/<id>)。可以使用WebSocket通过DevTools协议与页面进行交互。

此功能是在Qt 6.6中引入的。

QWebEnginePage *QWebEnginePage::devToolsPage() const

如果有的话，返回托管此页面开发者工具的页面。

如果没有设置开发者工具页面，则返回 nullptr。

另请参阅 setDevToolsPage() 和 inspectedPage().

void QWebEnginePage::download(const QUrl &url, const QString &filename = QString())

从由 url 指定的位置下载资源到本地文件。

如果提供了 filename，则用作建议的文件名。如果是相对路径的，则使用给定的名称保存到标准下载位置。如果为空或空 QString，则使用默认的文件名。

下载开始后，会发出 QWebEngineProfile::downloadRequested()。

[重写虚函数] bool QWebEnginePage::event(QEvent *e)

重写了: QObject::event(QEvent *e).

[信号] void QWebEnginePage::featurePermissionRequestCanceled(const QUrl &securityOrigin, QWebEnginePage::Feature feature)

当标识为 securityOrigin 的网站取消之前发出的用于使用 feature 的请求时，会发出此信号。

另请参阅 featurePermissionRequested() 和 setFeaturePermission().

[信号] void QWebEnginePage::featurePermissionRequested(const QUrl &securityOrigin, QWebEnginePage::Feature feature)

当标识为 securityOrigin 的网站请求使用由 feature 标识的资源或设备时，会发出此信号。

另请参阅 featurePermissionRequestCanceled() 和 setFeaturePermission().

[signal, since 6.4] void QWebEnginePage::fileSystemAccessRequested(QWebEngineFileSystemAccessRequest request)

当网页请求访问本地文件或目录时，会发出此信号。

可以使用请求对象 request 来接受或拒绝请求。

此函数自 Qt 6.4 开始引入。

void QWebEnginePage::findText(const QString &subString, QWebEnginePage::FindFlags options = {}, const std::function<void (const QWebEngineFindTextResult &)> &resultCallback = std::function<void(const QWebEngineFindTextResult &)>())

使用给定的 options 在页面中查找指定的字符串 subString。当字符串搜索完成时，会发出 findTextFinished() 信号。

为了清除搜索高亮显示，只需传递一个空字符串。

resultCallback 必须接受一个 QWebEngineFindTextResult 参数。

例如

    m_view->page()->findText(QStringLiteral("Qt"), QWebEnginePage::FindFlags(), [this](const QWebEngineFindTextResult &result) {
        if (result.numberOfMatches() == 0) QMessageBox::information(m_view, QString(), QStringLiteral("No occurrences found"));
    });

另请参阅findTextFinished。

[signal] void QWebEnginePage::findTextFinished(const QWebEngineFindTextResult &result)

当页面上的字符串搜索完成时，会发出此信号。result 是字符串搜索的结果。

另请参阅findText。

[signal] void QWebEnginePage::fullScreenRequested(QWebEngineFullScreenRequest fullScreenRequest)

当网页请求进入全屏模式时，通常是一个视频元素，会发出此信号。

可以使用请求对象 fullScreenRequest 来接受或拒绝请求。

如果请求被接受，请求全屏的元素将填满视口，但使视图全屏或移动页面到全屏视图取决于应用程序。

另请参阅QWebEngineSettings::FullScreenSupportEnabled。

[signal] void QWebEnginePage::geometryChangeRequested(const QRect &geom)

当文档想要将页面位置和大小更改为 geom 时，会发出此信号。这可能会通过 JavaScript 发生。

window->setGeometry(geom.marginsRemoved(window->frameMargins()));

QWebEngineHistory *QWebEnginePage::history() const

返回指向视图的历史记录导航网页的指针。

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

当与页面相关联的图标（“favicon”）变更时，将发射此信号。新的图标由icon指定。

另请参阅：icon()，iconUrl()，以及iconUrlChanged。

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

当与页面相关联的图标（“favicon”）的URL变更时，将发射此信号。新的URL由url指定。

另请参阅：iconUrl，icon，以及iconChanged。

QWebEnginePage *QWebEnginePage::inspectedPage() const

如果有的话，返回正在检查此页面的页面。

如果没有开发工具页面，返回nullptr。

另请参阅：setInspectedPage()和devToolsPage。

[虚拟受保护] void QWebEnginePage::javaScriptAlert(const QUrl &securityOrigin, const QString &msg)

每当在securityOrigin关联的帧中运行的JavaScript程序调用alert()函数并传递消息msg时，都会调用此函数。

默认实现使用QMessageBox::information显示消息msg。

[虚拟受保护] bool QWebEnginePage::javaScriptConfirm(const QUrl &securityOrigin, const QString &msg)

每当在securityOrigin关联的帧中运行的JavaScript程序调用confirm()函数并传递消息msg时，都会调用此函数。如果用户确认消息，则返回true；否则返回false。

当onbeforeunload处理程序在离开页面之前请求确认时，也会调用它。

默认实现使用带QMessageBox::Ok和QMessageBox::Cancel按钮的QMessageBox::information执行查询。

[虚拟受保护] void QWebEnginePage::javaScriptConsoleMessage(QWebEnginePage::JavaScriptConsoleMessageLevel level, const QString &message, int lineNumber, const QString &sourceID)

当JavaScript程序尝试将message输出到网页浏览器的控制台时，将调用此函数。

例如，在评估错误的情况下，源URL可能也包含在sourceID中以及lineNumber中。

等级表示触发消息的事件严重性。也就是说，是由错误还是较轻的事件触发的。

从Qt 5.6开始，默认实现将消息记录在js 日志类别中。

参见控制台日志。

[虚保护] bool QWebEnginePage::javaScriptPrompt(const QUrl & securityOrigin, const QString & msg, const QString & defaultValue, QString *result)

每当在关联于securityOrigin的框架中运行的JavaScript程序尝试提示用户输入时，都会调用此函数。程序可以提供一个可选消息msg，以及输入的默认值defaultValue。

如果提示被用户取消，则实现应返回false；否则应将结果写入result，并返回true。如果没有取消提示，则实现应返回true，且结果字符串不能为空。

默认实现使用QInputDialog::getText()。

[信号] void QWebEnginePage::linkHovered(const QString & url)

当鼠标悬停在链接上时，将发出此信号。 url包含链接的目标URL。

void QWebEnginePage::load(const QUrl & url)

将url加载到该页面。

参见 setUrl()，setHtml和setContent。

void QWebEnginePage::load(const QWebEngineHttpRequest & request)

发出指定的请求并加载响应。

参见 load()，setUrl()，url，urlChanged和QUrl::fromUserInput。

[信号] void QWebEnginePage::loadFinished(bool ok)

当页面完成内容加载时，将发出此信号。此信号独立于脚本执行或页面渲染。ok将指示加载是否成功或发生了任何错误。

参见 loadStarted()和acceptNavigationRequest。

[信号] void QWebEnginePage::loadProgress(int progress)

当全局进度状态改变时，会发出此信号。当前值由progress提供，并从0到100缩放，这是QProgressBar的默认范围。它累积来自所有子框架的变化。

[信号] void QWebEnginePage::loadStarted()

当页面开始加载内容时，会发出此信号。

另请参阅 loadFinished() 和 acceptNavigationRequest()。

[信号，自6.2版起] void QWebEnginePage::loadingChanged(const QWebEngineLoadingInfo &loadingInfo)

当加载由loadingInfo指定的页面开始、结束或失败时，会发出此信号。

此函数自Qt 6.2版引入。

[信号，自6.2版起] void QWebEnginePage::navigationRequested(QWebEngineNavigationRequest &request)

在调用acceptNavigationRequest时与导航一起发出此信号。它可以用来接受或忽略request。默认是接受。

此函数自Qt 6.2版引入。

另见 acceptNavigationRequest。

[信号，自6.2版起] void QWebEnginePage::newWindowRequested(QWebEngineNewWindowRequest &request)

当发出request以在单独的Web引擎窗口中加载页面时，会发出此信号。这可以是由于当前页面通过JavaScript调用window.open显式请求，或者用户在按下Shift、Ctrl或触发在 新窗口中打开页面的内置组合时点击链接。

通过在请求上调用openIn()并使用新页面处理该信号。如果没有处理此信号，请求将失败。

此函数自Qt 6.2版引入。

另请参阅 createWindow() 和 QWebEngineNewWindowRequest::openIn()。

[信号] void QWebEnginePage::pdfPrintingFinished(const QString &filePath, bool success)

当将网页打印成PDF文件完成时，会发出此信号。filePath将包含请求创建文件的路径，如果文件创建成功则success为true，否则为false。

另请参阅 printToPdf()。

[信号] void QWebEnginePage::printRequested()

当调用JavaScript方法window.print()或用户按下PDF查看器插件的打印按钮时，会发出此信号。通常，信号处理程序可以直接调用printToPdf()。

另请参阅 printToPdf()。

void QWebEnginePage::printToPdf(const QString &filePath, const QPageLayout &layout = QPageLayout(QPageSize(QPageSize::A4), QPageLayout::Portrait, QMarginsF()), const QPageRanges &ranges = {})

将当前页面的内容渲染成PDF文档，并保存到在filePath中指定的位置。生成的PDF文档的页大小和方向采用在layout中指定的值，而打印的页面范围则采用ranges中指定的值，默认为打印所有页面。

此方法向打印网页为PDF发出异步请求，并立即返回。要了解请求的结果，请连接到信号pdfPrintingFinished。

如果提供的文件路径中已存在文件，它将被覆盖。

另请参阅 pdfPrintingFinished。

void QWebEnginePage::printToPdf(const std::function<void (const QByteArray &)> &resultCallback, const QPageLayout &layout = QPageLayout(QPageSize(QPageSize::A4), QPageLayout::Portrait, QMarginsF()), const QPageRanges &ranges = {})

将当前页面的内容渲染成PDF文档，并将包含PDF数据的字节数组作为参数返回给resultCallback。生成的PDF文档的页大小和方向采用在layout中指定的值，而打印的页面范围则采用ranges中指定的值，默认为打印所有页面。

resultCallback必须接受一个对QByteArray的常量引用作为参数。如果打印成功，则此字节数组将包含PDF数据，否则，字节数组将为空。

QWebEngineProfile *QWebEnginePage::profile() const

返回页面属于的网页引擎配置文件。

[信号] void QWebEnginePage::proxyAuthenticationRequired(const QUrl &requestUrl, QAuthenticator *authenticator, const QString &proxyHost)

当通过proxyHost访问requestUrl需要代理认证时，会发出此信号。authenticator用于传递连接的用户名和密码。

[信号] void QWebEnginePage::recentlyAudibleChanged(bool recentlyAudible)

当页面的可听状态recentlyAudible由于音频播放或停止而改变时，会发出此信号。

[信号] void QWebEnginePage::registerProtocolHandlerRequested(QWebEngineRegisterProtocolHandlerRequest request)

当网页尝试使用registerProtocolHandler API注册自定义协议时，将发出此信号。

请求对象request可以用来接受或拒绝请求

void WebView::handleRegisterProtocolHandlerRequested(
        QWebEngineRegisterProtocolHandlerRequest request)
{
    auto answer = QMessageBox::question(window(), tr("Permission Request"),
                                        tr("Allow %1 to open all %2 links?")
                                                .arg(request.origin().host())
                                                .arg(request.scheme()));
    if (answer == QMessageBox::Yes)
        request.accept();
    else
        request.reject();
}

[signal] void QWebEnginePage::renderProcessPidChanged(qint64 pid)

当底层渲染进程PIDpid变化时，将发出此信号。

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

当渲染进程以非零退出状态终止时，将发出此信号。terminationStatus是进程的终止状态，而exitCode是以此状态终止进程的状态码。

void QWebEnginePage::replaceMisspelledWord(const QString &replacement)

用replacement替换当前拼错的单词。

当前拼错的单词可以在QWebEngineContextMenuRequest::misspelledWord()中找到，建议的替换可以在QWebEngineContextMenuRequest::spellCheckerSuggestions()中找到。

void QWebEnginePage::save(const QString &filePath, QWebEngineDownloadRequest::SavePageFormat format = QWebEngineDownloadRequest::MimeHtmlSaveFormat) const

将当前加载的网页保存到磁盘。

网页将被保存在指定的filePath中，以指定的format格式保存。

这是一个快捷方式，用于执行以下操作

• 触发“保存网页”动作。
• 接受下一个下载项并设置指定的文件路径和保存格式。

此函数对网页发出异步下载请求，并立即返回。

另请参阅QWebEngineDownloadRequest::SavePageFormat。

QWebEngineScriptCollection &QWebEnginePage::scripts()

返回注入到页面中的脚本集合。

此外，页面可能还会执行通过QWebEngineProfile::scripts()添加的脚本。

另请参阅QWebEngineScriptCollection、QWebEngineScript和脚本注入。

[signal] void QWebEnginePage::selectClientCertificate(QWebEngineClientCertificateSelection clientCertificateSelection)

当一个网站请求SSL客户端证书，并且在系统客户端证书存储中找到了一个或多个证书时，将发出此信号。

处理此信号是异步的，加载将等待直到选择了一个证书，或者最后一个clientCertificateSelection副本被销毁。

如果没有处理此信号，则将自动销毁clientCertificateSelection，并且加载将继续而不带客户端证书。

另请参阅QWebEngineClientCertificateSelection。

[信号] void QWebEnginePage::selectionChanged()

每次选择变化时，无论是交互式还是程序性地，都会发出此信号。例如，通过调用triggerAction()并传递一个选择操作。

另请参阅：selectedText()。

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

将网页的内容设置为data。如果mimeType参数为空，则假定内容为text/plain,charset=US-ASCII。

在内容中引用的外部对象位于相对于baseUrl的位置。对于有相对URL的外部对象，需要加载它们，baseUrl不能为空。

data将被立即加载；外部对象将异步加载。

另请参阅：toHtml() 和 setHtml()。

void QWebEnginePage::setDevToolsPage(QWebEnginePage *devToolsPage)

将devToolsPage绑定为此页的开发者工具。触发devToolsPage导航到包含开发者工具的内部URL。

这等同于在devToolsPage上调用setInspectedPage()并将this作为参数。

另请参阅：devToolsPage() 和 setInspectedPage()。

void QWebEnginePage::setFeaturePermission(const QUrl &securityOrigin, QWebEnginePage::Feature feature, QWebEnginePage::PermissionPolicy policy)

将标识为securityOrigin的网站使用feature的权限设置为policy。

另请参阅：featurePermissionRequested() 和 featurePermissionRequestCanceled()。

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

将此页面的内容设置为html。baseUrl是可选的，用于解析文档中的相对URL，例如引用的图像或样式表。

HTML代码会立即加载；外部对象会异步加载。

如果HTML中的脚本运行时间超过默认脚本超时时间（当前为10秒），例如被模态JavaScript提示对话框阻塞，该方法将在超时后尽快返回，并且在超时后的任何后续HTML将异步加载。

使用此方法时，网页引擎假定外部资源，例如JavaScript程序或样式表，是UTF-8编码的，除非另行指定。例如，可以通过HTML脚本的charset属性指定外部脚本的编码。也可以由网页服务器指定编码。

这是一个等同于setContent(html, "text/html", baseUrl)的便利函数。

另请参阅：toHtml()，setContent()和load()。

void QWebEnginePage::setInspectedPage(QWebEnginePage *page)

导航此页面到page的内部URL，即开发者工具。

这与在page上调用setDevToolsPage()并将this作为参数相同。

另请参阅：inspectedPage()和setDevToolsPage()。

void QWebEnginePage::setUrlRequestInterceptor(QWebEngineUrlRequestInterceptor *interceptor)

将请求拦截器interceptor注册为拦截URL请求。

页面不会拥有此指针。此拦截器在配置文件上的任何拦截器之后被调用，并且与配置文件拦截器不同，只有来自此页面的URL请求被拦截。如果原始请求已被配置文件拦截器阻止或重定向，则不会被此拦截。

要取消设置请求拦截器，设置nullptr。

另请参阅：QWebEngineUrlRequestInfo和QWebEngineProfile::setUrlRequestInterceptor。

void QWebEnginePage::setWebChannel(QWebChannel *channel, quint32 worldId = 0)

将此页面使用的Web通道实例设置为channel，并使用Chromium IPC消息将其连接到网引擎的传输。传输在JavaScript世界中以qt.webChannelTransport公开，当使用Qt WebChannel JavaScript API时，应该使用它。

另请参阅：webChannel()和QWebEngineScript::ScriptWorldId。

返回指向页面设置对象的指针。

返回页面设置对象的指针。

[信号] void QWebEnginePage::titleChanged(const QString &title)

每当页面标题更改时都会发出此信号。新标题由 title 字符串指定。

参见 title()。

void QWebEnginePage::toHtml(const std::function<void (const QString &)> &resultCallback) const

异步方法，用于以HTML形式检索页面内容，包含在HTML和BODY标签中。成功完成时，使用页面内容调用 resultCallback。

参见 setHtml() 和 toPlainText。

void QWebEnginePage::toPlainText(const std::function<void (const QString &)> &resultCallback) const

异步方法，用于获取转换为纯文本的页面内容，完全去除所有HTML格式。成功完成时，使用页面内容调用 resultCallback。

参见 toHtml。

[虚函数] void QWebEnginePage::triggerAction(QWebEnginePage::WebAction action, bool checked = false)

可以通过调用此函数来触发指定的 action。如果用户通过上下文菜单等触发操作，Qt WebEngine 也会调用此函数。

如果 action 是可切换的操作，则 checked 指定该操作是否被切换。

参见 action。

[信号] void QWebEnginePage::urlChanged(const QUrl &url)

当收到页面标题时，发出此信号，包含页面URL。新的URL由 url 指定。

参见 url。

[信号, 自6.7以来] void QWebEnginePage::webAuthUxRequested(QWebEngineWebAuthUxRequest *request)

当WebAuth验证器在认证过程中需要用户交互时发出此信号。这些请求通过向用户显示对话框来处理。

request 包含完成WebAuth UX请求所需的信息和API。

此功能自Qt 6.7引入。

参见 QWebEngineWebAuthUxRequest。

QWebChannel *QWebEnginePage::webChannel() const

返回该页面使用的网络通道实例的指针，如果没有设置则返回空指针。此通道自动使用内部的Chromium IPC传输机制，在页面JavaScript上下文中暴露为 qt.webChannelTransport。

另请参阅setWebChannel。

[信号] void QWebEnginePage::windowCloseRequested()

每当页面请求关闭浏览器窗口时，都会发出此信号，例如通过JavaScript的window.close()调用。

另请参阅RequestClose。