QWebEnginePage Class

QWebEnginePage 类提供了一个用于查看和编辑网络文档的对象。更多

Header: #include <QWebEnginePage>
CMake: find_package(Qt6 REQUIRED COMPONENTS WebEngineCore)
target_link_libraries(mytarget PRIVATE Qt6::WebEngineCore)
qmake: QT += webenginecore
继承: QObject

公共类型

enum FileSelectionMode { FileSelectOpen, FileSelectOpenMultiple, FileSelectUploadFolder, FileSelectSave }
enum FindFlag { FindBackward, FindCaseSensitively }
flags FindFlags
enum JavaScriptConsoleMessageLevel { InfoMessageLevel, WarningMessageLevel, ErrorMessageLevel }
enum class LifecycleState { Active, Frozen, Discarded }
enum NavigationType { NavigationTypeLinkClicked, NavigationTypeTyped, NavigationTypeFormSubmitted, NavigationTypeBackForward, NavigationTypeReload, …, NavigationTypeOther }
enum RenderProcessTerminationStatus { NormalTerminationStatus, AbnormalTerminationStatus, CrashedTerminationStatus, KilledTerminationStatus }
enum WebAction { NoWebAction, Back, Forward, Stop, Reload, …, ChangeTextDirectionRTL }
enum WebWindowType { WebBrowserWindow, WebBrowserTab, WebDialog, WebBrowserBackgroundTab }

属性

公共函数

QWebEnginePage(QObject *parent = nullptr)
QWebEnginePage(QWebEngineProfile *profile, QObject *parent = nullptr)
virtual ~QWebEnginePage()
QAction *action(QWebEnginePage::WebAction action) const
QColor backgroundColor() const
QSizeF contentsSize() const
(since 6.6) QString devToolsId() const
QWebEnginePage *devToolsPage() const
void download(const QUrl &url, const QString &filename = QString())
(since 6.8) std::optional<QWebEngineFrame> findFrameByName(QAnyStringView name)
void findText(const QString &subString, QWebEnginePage::FindFlags options = {}, const std::function<void (const QWebEngineFindTextResult &)> &resultCallback = std::function<void(const QWebEngineFindTextResult &)>())
bool hasSelection() const
QWebEngineHistory *history() const
QIcon icon() const
QUrl iconUrl() const
QWebEnginePage *inspectedPage() const
bool isAudioMuted() const
bool isLoading() const
bool isVisible() const
QWebEnginePage::LifecycleState lifecycleState() const
void load(const QUrl &url)
void load(const QWebEngineHttpRequest &request)
(since 6.8) QWebEngineFrame mainFrame()
void printToPdf(const QString &filePath, const QPageLayout &layout = QPageLayout(QPageSize(QPageSize::A4), QPageLayout::Portrait, QMarginsF()), const QPageRanges &ranges = {})
void printToPdf(const std::function<void (const QByteArray &)> &resultCallback, const QPageLayout &layout = QPageLayout(QPageSize(QPageSize::A4), QPageLayout::Portrait, QMarginsF()), const QPageRanges &ranges = {})
QWebEngineProfile *profile() const
bool recentlyAudible() const
QWebEnginePage::LifecycleState recommendedState() const
qint64 renderProcessPid() const
void replaceMisspelledWord(const QString &replacement)
QUrl requestedUrl() const
void runJavaScript(const QString &scriptSource, const std::function<void (const QVariant &)> &resultCallback)
void runJavaScript(const QString &scriptSource, quint32 worldId = 0, const std::function<void (const QVariant &)> &resultCallback = {})
void save(const QString &filePath, QWebEngineDownloadRequest::SavePageFormat format = QWebEngineDownloadRequest::MimeHtmlSaveFormat) const
QWebEngineScriptCollection &scripts()
QPointF scrollPosition() const
QString selectedText() const
void setAudioMuted(bool muted)
void setBackgroundColor(const QColor &color)
void setContent(const QByteArray &data, const QString &mimeType = QString(), const QUrl &baseUrl = QUrl())
void setDevToolsPage(QWebEnginePage *devToolsPage)
void setHtml(const QString &html, const QUrl &baseUrl = QUrl())
void setInspectedPage(QWebEnginePage *page)
void setLifecycleState(QWebEnginePage::LifecycleState state)
void setUrl(const QUrl &url)
void setUrlRequestInterceptor(QWebEngineUrlRequestInterceptor *interceptor)
void setVisible(bool visible)
void setWebChannel(QWebChannel *channel, quint32 worldId = 0)
void setZoomFactor(qreal factor)
QWebEngineSettings *settings() const
QString title() const
void toHtml(const std::function<void (const QString &)> &resultCallback) const
void toPlainText(const std::function<void (const QString &)> &resultCallback) const
virtual void triggerAction(QWebEnginePage::WebAction action, bool checked = false)
QUrl url() const
QWebChannel *webChannel() const
qreal zoomFactor() const

重新实现的公共函数

virtual bool event(QEvent *e) override

信号

void audioMutedChanged(bool muted)
void authenticationRequired(const QUrl &requestUrl, QAuthenticator *authenticator)
void certificateError(const QWebEngineCertificateError &certificateError)
void contentsSizeChanged(const QSizeF &size)
(since 6.7) void desktopMediaRequested(const QWebEngineDesktopMediaRequest &request)
(since 6.4) void fileSystemAccessRequested(QWebEngineFileSystemAccessRequest request)
void findTextFinished(const QWebEngineFindTextResult &result)
void fullScreenRequested(QWebEngineFullScreenRequest fullScreenRequest)
void geometryChangeRequested(const QRect &geom)
void iconChanged(const QIcon &icon)
void iconUrlChanged(const QUrl &url)
void lifecycleStateChanged(QWebEnginePage::LifecycleState state)
void linkHovered(const QString &url)
void loadFinished(bool ok)
void loadProgress(int progress)
void loadStarted()
(since 6.2) void loadingChanged(const QWebEngineLoadingInfo &loadingInfo)
(since 6.2) void navigationRequested(QWebEngineNavigationRequest &request)
(since 6.2) void newWindowRequested(QWebEngineNewWindowRequest &request)
void pdfPrintingFinished(const QString &filePath, bool success)
(since 6.8) void permissionRequested(QWebEnginePermission permission)
void printRequested()
(since 6.8) void printRequestedByFrame(QWebEngineFrame frame)
void proxyAuthenticationRequired(const QUrl &requestUrl, QAuthenticator *authenticator, const QString &proxyHost)
void recentlyAudibleChanged(bool recentlyAudible)
void recommendedStateChanged(QWebEnginePage::LifecycleState state)
void registerProtocolHandlerRequested(QWebEngineRegisterProtocolHandlerRequest request)
void renderProcessPidChanged(qint64 pid)
void renderProcessTerminated(QWebEnginePage::RenderProcessTerminationStatus terminationStatus, int exitCode)
void scrollPositionChanged(const QPointF &position)
void selectClientCertificate(QWebEngineClientCertificateSelection clientCertificateSelection)
void selectionChanged()
void titleChanged(const QString &title)
void urlChanged(const QUrl &url)
void visibleChanged(bool visible)
(since 6.7) void webAuthUxRequested(QWebEngineWebAuthUxRequest *request)
void windowCloseRequested()
(since 6.8) void zoomFactorChanged(qreal factor)

受保护函数

virtual bool acceptNavigationRequest(const QUrl &url, QWebEnginePage::NavigationType type, bool isMainFrame)
virtual QStringList chooseFiles(QWebEnginePage::FileSelectionMode mode, const QStringList &oldFiles, const QStringList &acceptedMimeTypes)
virtual QWebEnginePage *createWindow(QWebEnginePage::WebWindowType type)
virtual void javaScriptAlert(const QUrl &securityOrigin, const QString &msg)
virtual bool javaScriptConfirm(const QUrl &securityOrigin, const QString &msg)
virtual void javaScriptConsoleMessage(QWebEnginePage::JavaScriptConsoleMessageLevel level, const QString &message, int lineNumber, const QString &sourceID)
virtual bool javaScriptPrompt(const QUrl &securityOrigin, const QString &msg, const QString &defaultValue, QString *result)

详细说明

网络引擎页面包含 HTML 文档的内容、导航链接的历史记录以及操作。

QWebEnginePage 的应用程序接口与QWebEngineView 非常相似,仍然提供action() (在QWebEngineView 中称为pageAction() )、triggerAction() 和findText() 等常用函数。

可以使用load() 或setUrl() 加载页面。另外,如果有现成的 HTML 内容,也可以使用setHtml() 。加载 URL 时始终使用 GET 方法。

QWebEnginePage 类还提供了一些方法,用于检索页面当前加载的 URL(请参阅url() )以及最初请求加载的 URL(请参阅requestedUrl() )。这些方法可以在加载过程中发生 DNS 解析或重定向之前和之后检索 URL。如果加载成功,requestedUrl() 还可以匹配添加到页面历史记录中的 URL (QWebEngineHistory)。

可以使用title() 属性访问 HTML 页面的标题。此外,页面还可以指定一个图标,可以使用icon() 或iconUrl() 属性访问其 URL。如果标题或图标发生变化,将发出相应的titleChanged(),iconChanged() 和iconUrlChanged() 信号。通过zoomFactor() 属性,可以按比例因子缩放网页内容。

loadStarted() 信号在网页开始加载时发出,而loadProgress() 信号则在网页元素(如嵌入式图像或脚本)加载完成时发出。loadFinished() 信号在页面内容完全加载完毕时发出,与脚本执行或页面渲染无关。它的参数是truefalse ,表示加载操作是否成功。

HTML 文档在网页的主框架中加载。如果它引用了子框架(由<frame><iframe> 元素定义),这些子框架将被视为内容的一部分。子框架只能通过 JavaScript 单独访问。

网站会定义安全原点,以便安全地访问对方的资源,用于客户端脚本或数据库。原点由主机名、方案和端口号组成。例如,在 HTML 框架集和 JavaScript 中使用时,网站http://www.example.com/my/page.htmlhttp://www.example.com/my/overview.html 可共享同一个数据库或访问对方的文档。同时,http://www.malicious.com/evil.html 无法访问http://www.example.com/ 的资源,因为它们的安全起源不同。默认情况下,本地方案(如file://qrc:// )被视为处于同一安全源,可以访问对方的资源。本地资源在访问远程内容时默认受到限制,这意味着file:// 将无法访问http://domain.com/foo.html

脚本可以通过runJavaScript() 在网页上执行,既可以在主 JavaScript世界中与来自网页内容的其他 JavaScript 一起执行,也可以在自己的独立世界中执行。虽然可以从任何世界访问页面的 DOM,但在一个世界中定义的函数的 JavaScript 变量却不能从另一个世界访问。QWebEngineScript::ScriptWorldId 为此提供了一些预定义 ID。使用不带世界 ID 的runJavaScript() 版本与在MainWorld 中运行脚本是一样的。

FocusOnNavigationEnabled 设置可用于在发生导航操作(如加载或重新加载页面或浏览历史记录)时使与页面相关的视图自动获得焦点。

成员类型文档

enum QWebEnginePage::FileSelectionMode

该枚举表示chooseFiles() 函数的实现应只返回一个文件,还是可以返回多个文件:

常量说明
QWebEnginePage::FileSelectOpen0只返回一个文件名。
QWebEnginePage::FileSelectOpenMultiple1返回多个文件名。
QWebEnginePage::FileSelectUploadFolder2允许用户指定用于上传的单个现有文件夹。
QWebEnginePage::FileSelectSave3指定要创建的新文件。

另请参阅 chooseFiles().

枚举 QWebEnginePage::FindFlag
flags QWebEnginePage::FindFlags

该枚举描述了findText() 函数可用的选项。这些选项可以从以下列表中进行 OR 编辑:

常量说明
QWebEnginePage::FindBackward1向后搜索,而不是向前搜索。
QWebEnginePage::FindCaseSensitively2默认情况下,findText() 不区分大小写。指定该选项后,查找操作将区分大小写。

FindFlags 类型是QFlags<FindFlag> 的类型定义。它存储 FindFlag 值的 OR 组合。

enum QWebEnginePage::JavaScriptConsoleMessageLevel

该枚举描述了 JavaScript 控制台消息的不同严重性级别:

常量说明
QWebEnginePage::InfoMessageLevel0该消息纯粹是信息性的,可以放心忽略。
QWebEnginePage::WarningMessageLevel1该消息会告知需要注意的意外行为或错误。
QWebEnginePage::ErrorMessageLevel2该信息表示发生了错误。

enum class QWebEnginePage::LifecycleState

该枚举描述页面的生命周期状态:

常量描述
QWebEnginePage::LifecycleState::Active0正常状态。
QWebEnginePage::LifecycleState::Frozen1CPU 占用率低的状态,此时大部分 HTML 任务源被暂停。
QWebEnginePage::LifecycleState::Discarded2资源使用率极低的状态,整个浏览上下文被丢弃。

另请参阅 lifecycleState页面生命周期 APIWebEngine 生命周期示例

该枚举描述导航请求的类型:

常量描述
QWebEnginePage::NavigationTypeLinkClicked0导航请求来自点击的链接。
QWebEnginePage::NavigationTypeTyped1导航请求来自明确加载的 URL。
QWebEnginePage::NavigationTypeFormSubmitted2导航请求来自表单提交。
QWebEnginePage::NavigationTypeBackForward3导航请求来自后退或前进操作。
QWebEnginePage::NavigationTypeReload4导航请求来自重新加载操作。
QWebEnginePage::NavigationTypeRedirect (since Qt 5.14)6导航请求来自内容或服务器控制的重定向。这也包括自动重载。
QWebEnginePage::NavigationTypeOther5导航请求由上述未涵盖的其他方式触发。

另请参阅 acceptNavigationRequest()。

enum QWebEnginePage::RenderProcessTerminationStatus

该枚举描述了渲染进程的终止状态:

常量描述
QWebEnginePage::NormalTerminationStatus0呈现进程正常终止。
QWebEnginePage::AbnormalTerminationStatus1呈现进程以非 0 的退出状态结束。
QWebEnginePage::CrashedTerminationStatus2呈现进程崩溃,例如由于分段故障。
QWebEnginePage::KilledTerminationStatus3渲染进程被杀死,例如被SIGKILL 或任务管理器 kill。

enum QWebEnginePage::WebAction

该枚举描述了可在网页上执行的操作类型。

操作只有在适用时才会生效。

可以通过检查action() 返回的操作isEnabled() 来确定操作是否可用。

常量说明
QWebEnginePage::NoWebAction- 1不触发任何操作。
QWebEnginePage::Back0在历史导航链接中向前导航。
QWebEnginePage::Forward1在历史导航链接中向前导航。
QWebEnginePage::Stop2停止加载当前页面。
QWebEnginePage::Reload3重新加载当前页面。
QWebEnginePage::ReloadAndBypassCache10重新加载当前页面,但不使用任何本地缓存。
QWebEnginePage::Cut4剪切当前选中的内容到剪贴板。
QWebEnginePage::Copy5将当前选中的内容复制到剪贴板。
QWebEnginePage::Paste6从剪贴板粘贴内容
QWebEnginePage::Undo7撤销上次编辑操作。
QWebEnginePage::Redo8重做上次编辑操作。
QWebEnginePage::SelectAll9选择所有内容。只有当页面内容处于焦点状态时,才能启用此操作。可以通过 JavaScriptwindow.focus() 调用强制对焦,或者启用FocusOnNavigationEnabled 设置自动对焦。
QWebEnginePage::PasteAndMatchStyle11以当前样式从剪贴板粘贴内容。
QWebEnginePage::OpenLinkInThisWindow (since Qt 5.6)12在当前窗口中打开当前链接
QWebEnginePage::OpenLinkInNewWindow (since Qt 5.6)13在新窗口中打开当前链接需要执行createWindow() 或newWindowRequested()。
QWebEnginePage::OpenLinkInNewTab (since Qt 5.6)14在新标签页中打开当前链接。需要执行createWindow() 或newWindowRequested()。
QWebEnginePage::OpenLinkInNewBackgroundTab (since Qt 5.7)31在新的背景选项卡中打开当前链接。需要执行createWindow() 或newWindowRequested()。
QWebEnginePage::CopyLinkToClipboard (since Qt 5.6)15将当前链接复制到剪贴板。
QWebEnginePage::CopyImageToClipboard (since Qt 5.6)17将点击的图片复制到剪贴板。
QWebEnginePage::CopyImageUrlToClipboard (since Qt 5.6)18将点击图片的 URL 复制到剪贴板。
QWebEnginePage::CopyMediaUrlToClipboard (since Qt 5.6)20将悬停的音频或视频的 URL 复制到剪贴板。
QWebEnginePage::ToggleMediaControls (since Qt 5.6)21在显示和隐藏悬停的音频或视频元素的控件之间切换。
QWebEnginePage::ToggleMediaLoop (since Qt 5.6)22切换悬停的音频或视频是否应在完成后循环播放。
QWebEnginePage::ToggleMediaPlayPause (since Qt 5.6)23切换悬浮音频或视频元素的播放/暂停状态。
QWebEnginePage::ToggleMediaMute (since Qt 5.6)24将悬停的音频或视频元素静音或取消静音。
QWebEnginePage::DownloadLinkToDisk (since Qt 5.6)16将当前链接下载到磁盘。需要downloadRequested() 插槽。
QWebEnginePage::DownloadImageToDisk (since Qt 5.6)19将突出显示的图像下载到磁盘。需要downloadRequested() 插槽。
QWebEnginePage::DownloadMediaToDisk (since Qt 5.6)25将悬停的音频或视频下载到磁盘。需要downloadRequested() 插槽。
QWebEnginePage::InspectElement (since Qt 5.6)26触发任何附加的 Web 检查器来检查高亮显示的元素。
QWebEnginePage::ExitFullScreen (since Qt 5.6)27退出全屏模式。
QWebEnginePage::RequestClose (since Qt 5.6)28请求关闭网页。如果已定义,将运行window.onbeforeunload 处理程序,用户可以确认或拒绝关闭网页。如果确认关闭请求,windowCloseRequested
QWebEnginePage::Unselect (since Qt 5.7)29清除当前选择。
QWebEnginePage::SavePage (since Qt 5.7)30将当前页面保存到磁盘。MHTML 是用于将网页保存到磁盘的默认格式。需要一个downloadRequested() 插槽。
QWebEnginePage::ViewSource (since Qt 5.8)32在新标签页中显示当前页面的源文件。需要执行createWindow() 或newWindowRequested()。
QWebEnginePage::ToggleBold (since Qt 5.10)33切换选中或光标位置的粗体。需要contenteditable="true"
QWebEnginePage::ToggleItalic (since Qt 5.10)34为选中内容或光标位置切换斜体。需要contenteditable="true"
QWebEnginePage::ToggleUnderline (since Qt 5.10)35切换选中内容或光标位置处的下划线。需要contenteditable="true"
QWebEnginePage::ToggleStrikethrough (since Qt 5.10)36切换选中内容或光标位置上的横线。需要contenteditable="true"
QWebEnginePage::AlignLeft (since Qt 5.10)37将包含选区或光标的行向左对齐。需要contenteditable="true"
QWebEnginePage::AlignCenter (since Qt 5.10)38将包含选区或光标的行居中对齐。需要contenteditable="true"
QWebEnginePage::AlignRight (since Qt 5.10)39将包含选中内容或光标的行向右对齐。需要contenteditable="true"
QWebEnginePage::AlignJustified (since Qt 5.10)40拉伸包含选区或光标的行,使每行宽度相等。需要contenteditable="true"
QWebEnginePage::Indent (since Qt 5.10)41缩进包含选区或光标的行。需要contenteditable="true"
QWebEnginePage::Outdent (since Qt 5.10)42缩进包含选区或光标的行。需要contenteditable="true"
QWebEnginePage::InsertOrderedList (since Qt 5.10)43在当前光标位置插入有序列表,删除当前选区。需要contenteditable="true"
QWebEnginePage::InsertUnorderedList (since Qt 5.10)44在当前光标位置插入无序列表,删除当前选区。需要contenteditable="true"
QWebEnginePage::ChangeTextDirectionLTR (since Qt 6.6)45在聚焦的输入元素中将文字方向改为从左到右。
QWebEnginePage::ChangeTextDirectionRTL (since Qt 6.6)46在聚焦的输入元素中将文字方向改为从右向左。

enum QWebEnginePage::WebWindowType

该枚举描述了createWindow() 函数可创建的窗口类型:

常量说明
QWebEnginePage::WebBrowserWindow0一个完整的网络浏览器窗口。
QWebEnginePage::WebBrowserTab1网页浏览器标签页。
QWebEnginePage::WebDialog2无装饰的窗口。
QWebEnginePage::WebBrowserBackgroundTab (since Qt 5.7)3不隐藏当前可见WebEngineView 的网页浏览器选项卡。

属性文档

audioMuted : bool

此属性表示当前页面音频是否静音。

默认值为false

访问功能:

bool isAudioMuted() const
void setAudioMuted(bool muted)

Notifier 信号:

void audioMutedChanged(bool muted)

另请参阅 recentlyAudible

backgroundColor : QColor

该属性用于保存文档正文后面的页面背景颜色。

您可以将背景色设置为Qt::transparent 或半透明色,以便透过文档查看,也可以将其设置为与混合应用程序中的网页内容相匹配,以防止在加载过程中出现白色闪烁。

默认值为白色。

访问功能:

QColor backgroundColor() const
void setBackgroundColor(const QColor &color)

[read-only] contentsSize : const QSizeF

该属性表示页面内容的大小。

访问功能:

QSizeF contentsSize() const

通知信号:

void contentsSizeChanged(const QSizeF &size)

[read-only] hasSelection : const bool

此属性表示该页面是否包含所选内容。

访问功能:

bool hasSelection() const

另请参见 selectionChanged().

[read-only] icon : const QIcon

该属性包含与当前查看的页面相关联的图标。

默认情况下,该属性包含一个空图标。如果禁用了触摸图标(参见QWebEngineSettings::TouchIconsEnabled ),则会提供两种尺寸(16x16 和 32x32 像素)的 favicon,封装在QIcon 中。否则,将提供最大可用尺寸的单个图标。

访问功能:

QIcon icon() const

Notifier 信号:

void iconChanged(const QIcon &icon)

另请参阅 iconChanged(),iconUrl(),iconUrlChanged() 和QWebEngineSettings::TouchIconsEnabled

[read-only] iconUrl : const QUrl

该属性包含与当前查看的页面相关联的图标的 URL。

默认情况下,该属性包含一个空 URL。

访问功能:

QUrl iconUrl() const

Notifier 信号:

void iconUrlChanged(const QUrl &url)

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

lifecycleState : LifecycleState

该属性保存页面当前的生命周期状态。

设置器执行以下限制:

  • visible 页面必须保持Active 状态。
  • 如果页面正由devToolsPage 检查,则两个页面都必须保持Active 状态。
  • 处于Discarded 状态的页面只能过渡到Active 状态。这将导致页面重新加载。

这些是对生命周期状态的唯一硬性限制,但建议的软性限制也请参见recommendedState

访问功能:

QWebEnginePage::LifecycleState lifecycleState() const
void setLifecycleState(QWebEnginePage::LifecycleState state)

通知信号:

void lifecycleStateChanged(QWebEnginePage::LifecycleState state)

另请参阅 recommendedState页面生命周期 APIWebEngine 生命周期示例

[read-only, since 6.2] loading : const bool

此属性表示页面是否正在加载。

该属性在 Qt 6.2 中引入。

访问函数:

bool isLoading() const

Notifier 信号:

void loadingChanged(const QWebEngineLoadingInfo &loadingInfo)

另请参阅 QWebEngineLoadingInfo,loadStarted, 和loadFinished

[read-only] recentlyAudible : const bool

该属性保存当前页面的声音状态,即最近是否播放过音频。

默认值为false

访问功能:

bool recentlyAudible() const

Notifier 信号:

void recentlyAudibleChanged(bool recentlyAudible)

另请参阅 audioMuted

[read-only] recommendedState : const LifecycleState

此属性保存页面生命周期状态的建议限制。

将生命周期状态设置为比推荐状态更低的资源使用状态可能会导致副作用,如停止背景音频播放或丢失 HTML 表单输入。不过,将生命周期状态设置为较高的资源使用状态是完全安全的。

访问功能:

QWebEnginePage::LifecycleState recommendedState() const

Notifier 信号:

void recommendedStateChanged(QWebEnginePage::LifecycleState state)

另请参阅 lifecycleState页面生命周期 APIWebEngine 生命周期示例

[read-only] renderProcessPid : const qint64

此属性保存分配给当前页面主框架的呈现进程的进程 ID (PID)。

如果还没有可用的呈现进程,则返回0

访问功能:

qint64 renderProcessPid() const

Notifier 信号:

void renderProcessPidChanged(qint64 pid)

[read-only] requestedUrl : const QUrl

该属性包含当前查看的页面最初请求加载的 URL。

注意: 该 URL 可能与url() 返回的 URL 不同,后者是 DNS 解析或重定向后的实际 URL。

访问功能:

QUrl requestedUrl() const

另请参阅 url() 和setUrl()。

[read-only] scrollPosition : const QPointF

该属性用于保存页面内容的滚动位置。

访问功能:

QPointF scrollPosition() const

通知信号:

void scrollPositionChanged(const QPointF &position)

[read-only] selectedText : const QString

该属性用于保存当前选中的文本。

默认情况下,该属性包含一个空字符串。

访问函数:

QString selectedText() const

另请参阅 selectionChanged()。

[read-only] title : const QString

该属性包含 HTML<title> 元素定义的页面标题。

如果页面没有<title> 元素,则使用 URL 代替。对于file:// URL,只使用文件名而不使用完整路径。

默认情况下,在加载任何内容之前,该属性包含一个空字符串。

访问功能:

QString title() const

Notifier 信号:

void titleChanged(const QString &title)

另请参见 titleChanged().

url : QUrl

该属性包含当前查看页面的 URL。

设置该属性可清除视图并加载 URL。

默认情况下,该属性包含一个空的无效 URL。

访问功能:

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

Notifier 信号:

void urlChanged(const QUrl &url)

另请参见 urlChanged().

visible : bool

在页面可见性 API 中,页面是否可见由该属性决定。

设置该属性可更改 JavaScript 中的Document.hiddenDocument.visibilityState 属性,如果用户不可见,网站可使用这些属性主动减少资源使用量。

如果页面与视图相连,则视图将根据自身的可见性自动管理该属性。

访问功能:

bool isVisible() const
void setVisible(bool visible)

Notifier 信号:

void visibleChanged(bool visible)

另请参见 lifecycleState

zoomFactor : qreal

该属性用于保存页面内容的缩放因子。

有效值范围为0.255.0 。默认系数为1.0

访问功能:

qreal zoomFactor() const
void setZoomFactor(qreal factor)

Notifier 信号:

void zoomFactorChanged(qreal factor)

另请参阅 zoomFactorChanged().

成员函数文档

void QWebEnginePage::runJavaScript(const QString &scriptSource, const std::function<void (const QVariant &)> &resultCallback)

void QWebEnginePage::runJavaScript(const QString &scriptSource, quint32 worldId = 0, const std::function<void (const QVariant &)> &resultCallback = {})

运行scriptSource 中的 JavaScript 代码,而不检查页面的 DOM 是否已构建。如果需要对脚本的运行方式进行更多控制,可以考虑使用scripts() 代替。

为避免与页面上执行的其他脚本发生冲突,运行脚本的世界由worldId 指定。世界 ID 值与QWebEngineScript::ScriptWorldId 以及0256 之间提供的值相同。如果省略world ID,脚本将在MainWorld 中运行。

当脚本执行完毕后,resultCallback 会被调用,并得到最后执行语句的结果。resultCallback 可以是函数指针、函数式或 lambda 中的任意一种,并且它应该接受一个QVariant 参数。例如

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

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

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

警告: 我们保证回调 (resultCallback) 始终被调用,但在页面销毁时可能会被调用。当QWebEnginePage 被删除时,回调函数会以无效值触发,在其中使用相应的QWebEnginePageQWebEngineView 实例是不安全的。

另请参阅 scripts(),QWebEngineScript::ScriptWorldId,QWebEngineFrame::runJavaScript, 和脚本注入

[explicit] QWebEnginePage::QWebEnginePage(QObject *parent = nullptr)

用父parent 构建一个空的 QWebEnginePage。

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

在网络引擎配置文件profile 与父配置文件parent 中构建一个空的网络引擎页面。

如果该配置文件不是默认配置文件,调用者必须确保该配置文件与页面一样保持有效。

[virtual noexcept] QWebEnginePage::~QWebEnginePage()

销毁网页。

[virtual protected] bool QWebEnginePage::acceptNavigationRequest(const QUrl &url, QWebEnginePage::NavigationType type, bool isMainFrame)

当收到通过指定导航类型type 导航到指定url 的请求时,将调用该函数。isMainFrame 表示该请求对应的是主框架还是子框架。如果函数返回true ,则接受导航请求并加载url 。默认实现接受所有导航请求。

通过重载该函数,可以将导航请求委托给 Qt 应用程序,而不是由 HTML 处理引擎来处理。当 HTML 文档被用作用户界面的一部分,而不是用于显示外部数据(例如,显示结果列表)时,就有必要这样做。

注意: 在同一页面上进行片段导航时不会调用此函数。例如,通过点击页面中的 "#fragment "链接就可以进行这种导航。它不会触发加载到不同的文档,尽管它会更改页面的网址并添加历史记录条目。它只是在页面内滚动的快捷方式。因此,预计不会发生这种导航类型的委托。

注意: 请求被接受或拒绝之前,加载过程已经启动,并发出loadStarted() 信号。因此,即使在委托请求后,也会出现返回falseloadFinished() 信号。

注意: 在使用setHtmlsetContent 相对链接时,请务必指定一个基本 URL,否则链接将被视为无效,并且不会发出导航请求。

QWebEngineUrlRequestInterceptor 类为拦截和处理请求提供了更多选项。

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

返回指定WebActionQAction action

该操作归QWebEnginePage 所有,但您可以通过更改其属性来定制其外观。

返回的动作没有默认样式图标。使用QWebEngineView::pageAction() 可获得具有默认样式图标的动作。

QWebEnginePage 还将负责执行动作,以便在触发时在页面上执行相应的动作。

另请参阅 triggerAction()。

[signal] void QWebEnginePage::audioMutedChanged(bool muted)

当页面的muted 状态发生变化时会发出该信号。

注: 不能与特定 HTML5 音频或视频元素被静音混淆。

注: 属性audioMuted 的通知信号。

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

当访问requestUrl 需要身份验证时,会发出该信号。authenticator 应用于传递连接的用户名和密码。

[signal] void QWebEnginePage::certificateError(const QWebEngineCertificateError &certificateError)

该信号在加载给定请求时出现无效证书错误时发出。

certificateError 参数包含证书信息和错误详情,还提供了忽略错误、完成请求或停止加载请求的方法。

另请参阅 QWebEngineCertificateError

[virtual protected] QStringList QWebEnginePage::chooseFiles(QWebEnginePage::FileSelectionMode mode, const QStringList &oldFiles, const QStringList &acceptedMimeTypes)

当网络内容请求一个文件名时(例如,用户点击 HTML 表单中的文件上传按钮),该函数将被调用。

mode 如果用户点击 HTML 表单中的文件上传按钮,则调用该函数。

建议的文件名可作为oldFiles 的第一个条目提供。默认实现会忽略acceptedMimeTypes ,但重载可能会使用它。

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

调用该函数可创建一个指定type 的新窗口。例如,当 JavaScript 程序请求在新窗口中打开文档时。

如果新窗口可以创建,则返回新窗口的QWebEnginePage ;否则返回一个空指针。

如果与网页关联的视图是QWebEngineView 对象,那么默认实现会将请求转发到QWebEngineView::createWindow() ;否则会返回一个空指针。

如果未执行该调用或未返回新页面,则会发出newWindowRequested() 来处理请求。

注: 在 JavaScript 触发窗口创建的情况下,应用程序除了重新实现该方法外,还必须将QWebEngineSettings::JavascriptCanOpenWindows 设置为true ,才能调用该方法。

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

[signal, since 6.7] void QWebEnginePage::desktopMediaRequested(const QWebEngineDesktopMediaRequest &request)

当网络应用程序请求访问显示内容时,就会发出该信号。

request 参数包含可用于捕获的窗口和屏幕的数据模型引用。要接受请求,信号处理程序可调用QWebEngineDesktopMediaRequest::selectScreen() 或QWebEngineDesktopMediaRequest::selectWindow() 。

此函数在 Qt 6.7 中引入。

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

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

如果启用了远程调试(请参阅Qt WebEngine 开发人员工具),则可使用该 ID 创建 URL 以连接到开发人员工具 websocket:ws://localhost:<debugging-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() 信号。

[override virtual] bool QWebEnginePage::event(QEvent *e)

重实现:QObject::event(QEvent *e)。

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

该信号在网页请求访问本地文件或目录时发出。

请求对象request 可用于接受或拒绝请求。

此函数在 Qt 6.4 中引入。

[since 6.8] std::optional<QWebEngineFrame> QWebEnginePage::findFrameByName(QAnyStringView name)

返回名称为name 的框架。如果存在多个同名框架,则任意返回其中一个。如果找不到框架,则返回std::nullopt

此函数在 Qt 6.8 中引入。

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 参数。

警告: 我们保证回调 (resultCallback) 始终会被调用,但它可能会在页面销毁时被调用。当QWebEnginePage 被删除时,回调将以无效值触发,在其中使用相应的QWebEnginePageQWebEngineView 实例是不安全的。

例如

    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 来实现。

注意: setGeometry() 期望的大小不包括窗口装饰,而geom 则包括窗口装饰。您必须从geom 中移除框架边距的大小,才能正确处理此信号。

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

QWebEngineHistory *QWebEnginePage::history() const

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

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

当与页面相关的图标("favicon")发生变化时,就会发出该信号。新图标由icon 指定。

注: 属性icon 的通知信号。

另请参阅 icon()、iconUrl() 和iconUrlChanged()。

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

当与页面关联的图标("favicon")的 URL 发生变化时,就会发出该信号。新 URL 由url 指定。

注: 属性iconUrl 的通知信号。

另请参阅 iconUrl()、icon() 和iconChanged()。

QWebEnginePage *QWebEnginePage::inspectedPage() const

返回此页面正在检查的页面(如果有)。

如果此页面不是开发工具页面,则返回nullptr

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

[virtual protected] void QWebEnginePage::javaScriptAlert(const QUrl &securityOrigin, const QString &msg)

每当运行在securityOrigin 关联框架中的 JavaScript 程序调用alert() 函数时,都会调用该函数,并显示信息msg

默认的实现方式是通过QMessageBox::information 显示信息msg

[virtual protected] bool QWebEnginePage::javaScriptConfirm(const QUrl &securityOrigin, const QString &msg)

每当运行在securityOrigin 关联框架中的 JavaScript 程序调用confirm() 函数并发送msg 消息时,都会调用该函数。如果用户确认信息,则返回true ;否则返回false

onbeforeunload 处理程序在离开页面前请求确认时,也会调用该函数。

默认实现是使用QMessageBox::informationQMessageBox::OkQMessageBox::Cancel 按钮执行查询。

[virtual protected] void QWebEnginePage::javaScriptConsoleMessage(QWebEnginePage::JavaScriptConsoleMessageLevel level, const QString &message, int lineNumber, const QString &sourceID)

当 JavaScript 程序尝试将message 打印到网络浏览器控制台时,就会调用该函数。

例如,在评估错误的情况下,源 URL 可在sourceID 以及lineNumber 中提供。

level 表示触发消息的事件的严重程度。也就是说,它是由错误触发的,还是由不太严重的事件触发的。

自 Qt 5.6 起,默认实现将消息记录在js logging category 中。

另请参阅 控制台日志记录

[virtual protected] bool QWebEnginePage::javaScriptPrompt(const QUrl &securityOrigin, const QString &msg, const QString &defaultValue, QString *result)

每当运行在securityOrigin 关联框架中的 JavaScript 程序尝试提示用户输入时,都会调用该函数。程序可提供一条可选信息(msg ),以及输入的默认值(defaultValue )。

如果用户取消了提示,执行程序应返回false ;否则应将结果写入result 并返回true 。如果用户没有取消提示,执行程序应返回true ,且结果字符串不得为空。

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

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

url 包含链接的目标 URL。

void QWebEnginePage::load(const QUrl &url)

url 载入该页面。

注: 视图保持不变,直到有足够的数据显示新的 URL。

另请参阅 setUrl()、setHtml() 和setContent()。

void QWebEnginePage::load(const QWebEngineHttpRequest &request)

发出指定的request 并加载响应。

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

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

该信号在页面完成加载内容时发出。该信号与脚本执行或页面渲染无关。ok 将显示加载是否成功或发生任何错误。

注: 导航请求可通过重载acceptNavigationRequest() 函数委托给 Qt XML 应用程序处理,而不是由 HTML 处理引擎处理。由于加载过程是在请求被接受或拒绝之前启动的,而且loadStarted() 信号也是在请求被接受或拒绝之前发出的,因此,即使委托了请求,也会出现返回falseloadFinished() 信号。

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

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

当全局进度状态发生变化时会发出该信号。当前值由progress 提供,范围从 0 到 100,也就是QProgressBar 的默认范围。它会累计所有子帧的变化。

[signal] void QWebEnginePage::loadStarted()

该信号在页面开始加载内容时发出。

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

[signal, since 6.2] void QWebEnginePage::loadingChanged(const QWebEngineLoadingInfo &loadingInfo)

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

注: 用于属性loading 的 Notifier 信号。

此函数在 Qt 6.2 中引入。

[since 6.8] QWebEngineFrame QWebEnginePage::mainFrame()

页面的顶层主框架。页面上的所有其他框架都可以作为主框架的子框架访问。

此函数在 Qt 6.8 中引入。

该信号在导航时与acceptNavigationRequest() 一起发出。它可用于接受或忽略request 。默认为接受。

该函数在 Qt 6.2 中引入。

另请参阅 acceptNavigationRequest()。

[signal, since 6.2] void QWebEnginePage::newWindowRequested(QWebEngineNewWindowRequest &request)

request 在单独的网络引擎窗口中加载页面时,会发出该信号。这可能是因为当前页面通过 JavaScript 调用window.open 明确请求加载页面,也可能是因为用户按住 Shift、Ctrl 或内置组合键时点击了链接,从而触发页面在新窗口中打开。

处理该信号的方法是在请求中调用新页面的 openIn() 函数。如果未处理该信号,请求的加载将失败。

注意: 如果createWindow() 先处理了请求,则不会发出该信号。

此函数在 Qt 6.2 中引入。

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

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

filePath 将包含请求创建文件的路径,如果文件创建成功,success 将为true ,否则为false

另请参阅 printToPdf() 。

[signal, since 6.8] void QWebEnginePage::permissionRequested(QWebEnginePermission permission)

当网站请求使用某项功能(如地理位置访问、发送通知的权限)时,就会发出该信号。permission 对象可查询请求 URL 和请求的QWebEnginePermission::Feature ,以及授予或拒绝权限。

此功能在 Qt 6.8 中引入。

[signal] void QWebEnginePage::printRequested()

当调用主框架上的 JavaScriptwindow.print() 方法或用户按下 PDF 浏览器插件的打印按钮时,就会发出该信号。通常情况下,信号处理程序只需调用printToPdf() 即可。

自 6.8 版起,只有主帧才会发出该信号,而不是任何请求打印的帧都会发出该信号。

另请参阅 printToPdf() 和printRequestedByFrame()。

[signal, since 6.8] void QWebEnginePage::printRequestedByFrame(QWebEngineFrame frame)

frame 上调用 JavaScriptwindow.print() 方法时,会发出该信号。如果该帧是主帧,则会发出printRequested

此函数在 Qt 6.8 中引入。

另请参见 printRequested()、printToPdf() 和QWebEngineFrame::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() 。

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

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

另请参阅 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 数据,否则字节数组将为空。

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

警告: 我们保证回调 (resultCallback) 始终会被调用,但在页面销毁时可能会被调用。当QWebEnginePage 被删除时,回调会以无效值触发,在其中使用相应的QWebEnginePageQWebEngineView 实例是不安全的。

QWebEngineProfile *QWebEnginePage::profile() const

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

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

当通过proxyHost 访问requestUrl 需要对代理进行身份验证时,将发出该信号。authenticator 应用于传递连接的用户名和密码。

[signal] void QWebEnginePage::recentlyAudibleChanged(bool recentlyAudible)

当页面的可听状态recentlyAudible 因音频播放或停止而发生变化时,将发出该信号。

注: 调用setAudioMuted() 方法时也会发出该信号。

注: 属性recentlyAudible 的通知信号。

[signal] void QWebEnginePage::registerProtocolHandlerRequested(QWebEngineRegisterProtocolHandlerRequest request)

当网页尝试使用registerProtocolHandlerAPI 注册自定义协议时,就会发出该信号。

请求对象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 发生变化时,会发出该信号。

注: 属性renderProcessPid 的通知信号。

[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

[signal] 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 会立即加载;外部对象会异步加载。

注意: 此方法不会影响页面的会话或全局历史记录。

警告: 在通过 IPC 发送到呈现器之前,内容将进行百分比编码。这可能会增加内容的大小。百分比编码内容的最大大小为 2 兆字节减去 6 个字节再加上 MIME 类型字符串的长度。

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

void QWebEnginePage::setDevToolsPage(QWebEnginePage *devToolsPage)

devToolsPage 绑定为本页面的开发工具。触发devToolsPage 使用开发工具导航到内部 URL。

这与以this 为参数在devToolsPage 上调用setInspectedPage() 相同。

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

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

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

html 会立即加载;外部对象会异步加载。

如果html 中的脚本运行时间超过默认脚本超时时间(目前为 10 秒),例如由于被模式 JavaScript 警告对话框阻塞,则该方法将在超时后尽快返回,随后的任何html 将以异步方式加载。

使用此方法时,除非另有说明,否则网络引擎会假定外部资源(如 JavaScript 程序或样式表)是以 UTF-8 编码的。例如,可以通过 HTML 脚本标签的 charset 属性指定外部脚本的编码。编码也可以由网络服务器指定。

这是一个方便的函数,相当于setContent(html, "text/html", baseUrl)。

注意: 此方法不会影响页面的会话或全局历史记录。

警告: 此函数仅适用于 HTML,对于其他 MIME 类型(如 XHTML 和 SVG),应使用setContent() 代替。

警告 在通过 IPC 发送到呈现器之前,内容将进行百分比编码。这可能会增加内容的大小。百分比编码内容的最大大小为 2 兆字节减 30 字节。

另请参阅 toHtml()、setContent() 和load()。

void QWebEnginePage::setInspectedPage(QWebEnginePage *page)

将本页导航到一个内部 URL,该 URL 是page 的开发工具。

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

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

void QWebEnginePage::setUrlRequestInterceptor(QWebEngineUrlRequestInterceptor *interceptor)

注册请求拦截器interceptor 以拦截 URL 请求。

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

要取消设置请求拦截器,请设置nullptr

另请参阅 QWebEngineUrlRequestInfoQWebEngineProfile::setUrlRequestInterceptor() 。

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

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

注意: 页面不拥有通道对象的所有权。

注意: 每个页面只能安装一个网络通道,即使在另一个 JavaScript 世界中设置一个网络通道,也会卸载任何已安装的网络通道。

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

QWebEngineSettings *QWebEnginePage::settings() const

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

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

每当页面标题发生变化时,就会发出该信号。title 字符串指定新标题。

注: 属性title 的通知信号。

另请参阅 title().

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

异步方法,以 HTML 和 BODY 标记括起来的 HTML 格式获取页面内容。成功完成后,resultCallback 与页面内容一起被调用。

注意: resultCallback 可以是函数指针、函数器或 lambda 中的任意一个,而且它应该接受一个QString 参数。

警告: 我们保证回调 (resultCallback) 始终会被调用,但它可能会在页面销毁时被调用。当QWebEnginePage 被删除时,回调会以无效值触发,在其中使用相应的QWebEnginePageQWebEngineView 实例是不安全的。

另请参阅 setHtml() 和toPlainText()。

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

异步方法,用于获取转换为纯文本的页面内容,完全去除所有 HTML 格式。成功完成后,resultCallback 将与页面内容一起被调用。

注意: resultCallback 可以是函数指针、funcctor 或 lambda 中的任意一个,而且它应该接受一个QString 参数。

警告: 我们保证回调 (resultCallback) 始终会被调用,但它可能会在页面销毁时被调用。当QWebEnginePage 被删除时,回调会以无效值触发,在其中使用相应的QWebEnginePageQWebEngineView 实例是不安全的。

另请参阅 toHtml() 。

[virtual] void QWebEnginePage::triggerAction(QWebEnginePage::WebAction action, bool checked = false)

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

如果action 是一个可检查的操作,那么checked 将指定是否切换该操作。

另请参阅 action() 。

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

当收到页面标题时,该信号将与页面的 URL 一起发出。新 URL 由url 指定。

注: 属性url 的通知信号。

另请参阅 url() 。

[signal, since 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().

[signal] void QWebEnginePage::windowCloseRequested()

每当页面请求关闭网页浏览器窗口(例如通过 JavaScriptwindow.close() 调用)时,就会发出该信号。

另请参阅 RequestClose

[signal, since 6.8] void QWebEnginePage::zoomFactorChanged(qreal factor)

每当页面缩放factor 发生变化时,就会发出该信号。

注: 用于属性zoomFactor 的 Notifier 信号。

此函数在 Qt 6.8 中引入。

另请参阅 zoomFactor() 和setZoomFactor()。

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