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 。
属性文档
[read-only] children : QList<QWebEngineFrame>
该属性按任意顺序保存框架的子代列表。
如果找不到框架，则返回空列表。
访问函数
| QList<QWebEngineFrame> | children() const |
[read-only] htmlName : QString
该属性包含框架name HTML 属性的值，如果没有，则返回空字符串。
如果找不到框架，则返回空值QString 。
访问函数：
| QString | htmlName() const |
另请参阅 name 。
[read-only] isMainFrame : bool
此属性表示此对象是否代表页面的主框架。
访问功能：
| bool | isMainFrame() const |
[read-only] isValid : bool
该属性表示该对象是否代表一个已存在的帧。
帧一旦失效，就永远不会再生效。
访问功能：
| bool | isValid() const |
[read-only] name : QString
该属性包含框架名称，即 JavaScript 中window.name 返回的名称。
如果找不到框架，则返回空值QString 。
访问函数：
| QString | name() const |
另请参阅 htmlName 。
[read-only] size : QSizeF
此属性表示视口中框架的大小，单位为逻辑像素。
在缩放系数不是 100%的设备上，它与屏幕尺寸不一致，而是缩放前的尺寸。在这种情况下，尺寸可能包含分数值。
如果找不到帧，则返回 QSizeF()。
访问函数
| QSizeF | size() const |
[read-only] url : QUrl
该属性包含当前加载到该框架中的内容的 URL。
如果找不到框架，则返回空QUrl 。
访问函数：
| QUrl | url() const |
成员函数文档
[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 网页操作可用于中断此操作。
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 参数。例如
从 JavaScript 返回的结果值只能是纯数据。支持的数据类型包括所有 JSON 数据类型以及Date 和ArrayBuffer 等。不支持的数据类型包括Function 和Promise 等。
警告： 请勿在回调函数中执行冗长的例程，因为这可能会阻止网络引擎页面的渲染。
警告：请勿在回调函数中执行冗长的例程，因为这可能会阻止网络引擎页面的渲染： 我们保证始终调用callback ，但可能会在页面销毁时调用。当QWebEnginePage 被删除时，回调函数会以无效值触发，在其中使用相应的QWebEnginePage 或QWebEngineView 实例是不安全的。
另请参阅 QWebEngineScript::ScriptWorldId,QWebEnginePage::runJavaScript, 和脚本注入。
相关非成员
[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 。
© 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.
