Back to Qt.io
Contact Us Blog Download Qt

QWebEngineFrame Class

QWebEngineFrame 类提供有关页面框架的信息和控制。更多

头文件： #include <QWebEngineFrame>
CMake： find_package(Qt6 REQUIRED COMPONENTS WebEngineCore)
target_link_libraries(mytarget PRIVATE Qt6::WebEngineCore)
qmake： QT += webenginecore
自Qt 6.8
在 QML 中： webEngineFrame

公共函数

QList<QWebEngineFrame> children() const
QString htmlName() const
bool isMainFrame() const
bool isValid() const
QString name() const
void printToPdf(const QString &filePath)
void printToPdf(const std::function<void (const QByteArray &)> &callback)
void runJavaScript(const QString &script, const std::function<void (const QVariant &)> &callback)
void runJavaScript(const QString &script, quint32 worldId = 0)
void runJavaScript(const QString &script, quint32 worldId, const std::function<void (const QVariant &)> &callback)
QSizeF size() const
QUrl url() const
bool operator!=(const QWebEngineFrame &left, const QWebEngineFrame &right)
bool operator==(const QWebEngineFrame &left, const QWebEngineFrame &right)

详细描述

网络引擎框架表示网页中的单个框架，例如由<frame> 或<iframe> HTML 元素创建的框架。一个活动的QWebEnginePage 有一个或多个以树形结构排列的框架。可以通过 mainFrame() 方法访问顶层框架，即该树的根，而children() 则提供了框架的直接后代。

一个框架的生命周期最多与生成它的QWebEnginePage 对象一样长。不过，框架可能会自发地动态创建和删除，例如通过导航和脚本执行。因此，许多 QWebEngineFrame 方法都会返回可选值，如果框架不再存在，这些可选值将被std::nullopt 。

成员函数文档

void QWebEngineFrame::runJavaScript(const QString &script, const std::function<void (const QVariant &)> &callback)

[invokable] void QWebEngineFrame::runJavaScript(const QString &script, quint32 worldId = 0)

void QWebEngineFrame::runJavaScript(const QString &script, quint32 worldId, const std::function<void (const QVariant &)> &callback)

在此框架上运行script 中包含的 JavaScript 代码，而不检查页面的 DOM 是否已构建。为避免与页面上执行的其他脚本冲突，运行脚本的世界由worldId 指定。世界 ID 值与QWebEngineScript::ScriptWorldId 以及0 和256 之间提供的值相同。如果省略world ID，脚本将在MainWorld 中运行。脚本执行完毕后，callback ，并调用最后执行语句的结果。callback 可以是函数指针、函数器或 lambda 中的任何一个，而且预计它将接受QVariant 参数。例如

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

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

警告： 请勿在回调函数中执行冗长的例程，因为这可能会阻止网络引擎页面的渲染。

警告：请勿在回调函数中执行冗长的例程，因为这可能会阻止网络引擎页面的渲染： 我们保证始终调用callback ，但可能会在页面销毁时调用。当QWebEnginePage 被删除时，回调函数会以无效值触发，在其中使用相应的QWebEnginePage 或QWebEngineView 实例是不安全的。

另请参阅 QWebEngineScript::ScriptWorldId,QWebEnginePage::runJavaScript, 和脚本注入。

QList<QWebEngineFrame> QWebEngineFrame::children() const

按任意顺序返回帧的子代列表。

如果找不到框架，则返回空列表。

QString QWebEngineFrame::htmlName() const

返回框架name HTML 属性的值，如果没有则返回空字符串。

如果找不到框架，则返回空值QString 。

注： 属性 htmlName 的获取函数。

另请参阅 name 。

bool QWebEngineFrame::isMainFrame() const

如果此对象代表页面的主框架，则返回true ；否则返回false 。

注： 属性 isMainFrame 的获取函数。

bool QWebEngineFrame::isValid() const

如果该对象代表一个现有帧，则返回true ；否则返回false 。

帧一旦无效，就永远不会再有效。

注： 属性 isValid 的获取函数。

QString QWebEngineFrame::name() const

返回框架名称，即 JavaScript 中window.name 所返回的名称。

如果找不到框架，则返回空值QString 。

注： 属性名称的获取函数。

另请参阅 htmlName 。

[invokable] void QWebEngineFrame::printToPdf(const QString &filePath)

将框架的当前内容渲染为 PDF 文档，并保存到filePath 中指定的位置。打印使用的页面尺寸为 A4，纵向布局，并包含全部页面。

该方法发出异步请求，将网页打印成 PDF，并立即返回。要了解请求结果，请连接QWebEnginePage::pdfPrintingFinished() 信号。

注意： QWebEnginePage::Stop 网页操作可用于中断此异步操作。

如果在提供的文件路径下已经存在文件，该文件将被覆盖。

注： 可通过元对象系统和 QML 调用此函数。参见Q_INVOKABLE 。

另请参阅 QWebEnginePage::pdfPrintingFinished() 。

void QWebEngineFrame::printToPdf(const std::function<void (const QByteArray &)> &callback)

将帧的当前内容渲染为 PDF 文档，并返回一个包含 PDF 数据的字节数组作为callback 的参数。打印使用的页面尺寸为 A4，纵向布局，并包含全部页面。

callback 必须将指向QByteArray 的常量引用作为参数。如果打印成功，该字节数组将包含 PDF 数据，否则字节数组将为空。

注意： QWebEnginePage::Stop 网页操作可用于中断此操作。

QSizeF QWebEngineFrame::size() const

返回视口中框架的大小。

如果找不到框架，则返回 QSizeF()。

注： 属性大小的获取函数。

QUrl QWebEngineFrame::url() const

返回该框架当前加载内容的 URL。

如果找不到框架，则返回空QUrl 。

注： 属性 url 的获取函数。

相关非成员

[noexcept] bool operator!=(const QWebEngineFrame &left, const QWebEngineFrame &right)

如果left 和right 代表同一网页中的不同框架，则返回true ，否则返回false 。

[noexcept] bool operator==(const QWebEngineFrame &left, const QWebEngineFrame &right)

如果left 和right 代表同一网页中的同一帧，则返回true ，否则返回false 。

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