QWebEngineSettings Class
QWebEngineSettings 类提供了一个对象，用于存储QWebEnginePage 使用的设置。更多
| 头文件： | #include <QWebEngineSettings> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS WebEngineCore)target_link_libraries(mytarget PRIVATE Qt6::WebEngineCore) |
| qmake： | QT += webenginecore |
公共类型
| enum | FontFamily { StandardFont, FixedFont, SerifFont, SansSerifFont, CursiveFont, …, PictographFont } |
| enum | FontSize { MinimumFontSize, MinimumLogicalFontSize, DefaultFontSize, DefaultFixedFontSize } |
(since Qt 6.8) enum class | ImageAnimationPolicy { Allow, AnimateOnce, Disallow } |
(since Qt 5.11) enum | UnknownUrlSchemePolicy { DisallowUnknownUrlSchemes, AllowUnknownUrlSchemesFromUserInteraction, AllowAllUnknownUrlSchemes } |
| enum | WebAttribute { AutoLoadImages, JavascriptEnabled, JavascriptCanOpenWindows, JavascriptCanAccessClipboard, LinksIncludedInFocusChain, …, TouchEventsApiEnabled } |
公共函数
| QString | defaultTextEncoding() const |
| QString | fontFamily(QWebEngineSettings::FontFamily which) const |
| int | fontSize(QWebEngineSettings::FontSize type) const |
(since Qt 6.8) QWebEngineSettings::ImageAnimationPolicy | imageAnimationPolicy() const |
| void | resetAttribute(QWebEngineSettings::WebAttribute attribute) |
| void | resetFontFamily(QWebEngineSettings::FontFamily which) |
| void | resetFontSize(QWebEngineSettings::FontSize type) |
(since Qt 6.8) void | resetImageAnimationPolicy() |
(since Qt 5.11) void | resetUnknownUrlSchemePolicy() |
| void | setAttribute(QWebEngineSettings::WebAttribute attribute, bool on) |
| void | setDefaultTextEncoding(const QString &encoding) |
| void | setFontSize(QWebEngineSettings::FontSize type, int size) |
(since Qt 6.8) void | setImageAnimationPolicy(QWebEngineSettings::ImageAnimationPolicy policy) |
(since Qt 5.11) void | setUnknownUrlSchemePolicy(QWebEngineSettings::UnknownUrlSchemePolicy policy) |
| bool | testAttribute(QWebEngineSettings::WebAttribute attribute) const |
(since Qt 5.11) QWebEngineSettings::UnknownUrlSchemePolicy | unknownUrlSchemePolicy() const |
详细说明
QWebEngineSettings 允许配置浏览器属性（如字体大小和系列）和通用属性（如 JavaScript 支持）。单个属性可使用setAttribute() 函数设置。WebAttribute 枚举进一步描述了每个属性。
每个QWebEnginePage 对象都有自己的 QWebEngineSettings 对象，用于配置该页面的设置。如果某个设置没有为网络引擎页面配置，则会在该页面所属配置文件的设置中查找。
另请参阅 QWebEnginePage::settings() 和QWebEngineView::settings()。
成员类型文档
enum QWebEngineSettings::FontFamily
该枚举描述了 CSS 2 中定义的通用字体族，更多信息请参阅CSS 标准。
| 常量 | 值 | 说明 |
|---|---|---|
QWebEngineSettings::StandardFont | 0 | |
QWebEngineSettings::FixedFont | 1 | |
QWebEngineSettings::SerifFont | 2 | |
QWebEngineSettings::SansSerifFont | 3 | |
QWebEngineSettings::CursiveFont | 4 | |
QWebEngineSettings::FantasyFont | 5 | |
QWebEngineSettings::PictographFont | 6 | (在 Qt 5.7 中添加，已在 Qt 6.4 中弃用） |
enum QWebEngineSettings::FontSize
该枚举描述了可通过QWebEngineSettings 配置的字体大小：
| 常量 | 值 | 说明 |
|---|---|---|
QWebEngineSettings::MinimumFontSize | 0 | 硬最小字体大小。 |
QWebEngineSettings::MinimumLogicalFontSize | 1 | 缩放时应用的最小逻辑字体大小。 |
QWebEngineSettings::DefaultFontSize | 2 | 常规文本的默认字体大小。 |
QWebEngineSettings::DefaultFixedFontSize | 3 | 固定间距文本的默认字体大小。 |
[since Qt 6.8] enum class QWebEngineSettings::ImageAnimationPolicy
此枚举描述了在渲染图像帧动画时应如何处理图像动画。
| 常量 | 值 | 描述 |
|---|---|---|
QWebEngineSettings::ImageAnimationPolicy::Allow | 1 | 允许在渲染图像帧时制作图像动画。 |
QWebEngineSettings::ImageAnimationPolicy::AnimateOnce | 2 | 在渲染图像帧时为图像制作一次动画。 |
QWebEngineSettings::ImageAnimationPolicy::Disallow | 3 | 在渲染图像帧时禁止图像动画。 |
此枚举在 Qt 6.8 中引入。
另请参阅 imageAnimationPolicy,setImageAnimationPolicy, 和resetImageAnimationPolicy 。
[since Qt 5.11] enum QWebEngineSettings::UnknownUrlSchemePolicy
该枚举描述了如何处理对未知方案 URL 的导航请求。
| 常量 | 值 | 描述 |
|---|---|---|
QWebEngineSettings::DisallowUnknownUrlSchemes | 1 | 禁止所有指向未知方案 URL 的导航请求。 |
QWebEngineSettings::AllowUnknownUrlSchemesFromUserInteraction | 2 | 允许通过用户交互（如点击鼠标）向未知方案的 URL 发送导航请求，而抑制其他导航请求（如 JavaScript）。 |
QWebEngineSettings::AllowAllUnknownUrlSchemes | 3 | 允许对未知方案 URL 的所有导航请求。 |
此枚举在 Qt 5.11 中引入。
另请参阅 unknownUrlSchemePolicy,setUnknownUrlSchemePolicy, 和resetUnknownUrlSchemePolicy 。
enum QWebEngineSettings::WebAttribute
该枚举类型用于指定网页设置：
| 常量 | 值 | 说明 |
|---|---|---|
QWebEngineSettings::AutoLoadImages | 0 | 自动下载网页图像。禁用此设置时，将从缓存中加载图像。默认已启用。 |
QWebEngineSettings::JavascriptEnabled | 1 | 启用在MainWorld 中运行 JavaScript 程序。默认已启用。 |
QWebEngineSettings::JavascriptCanOpenWindows | 2 | 允许 JavaScript 程序在不与用户交互的情况下打开弹出窗口。默认已启用。 |
QWebEngineSettings::JavascriptCanAccessClipboard | 3 | 允许 JavaScript 程序将经过消毒的内容写入（复制）剪贴板。通过write 和writeText JavaScript 剪贴板 API 调用可进行消毒写入，且必须伴随用户操作。JavascriptCanPaste 可启用未经消毒的写入以及从剪贴板读取内容。在 Chromium 版本 81 之前，该设置启用了所有剪贴板写入操作。由于不受限制的剪贴板访问存在潜在的安全隐患，建议应用程序禁用此设置，并响应ClipboardReadWrite 功能权限请求。默认已禁用。 |
QWebEngineSettings::LinksIncludedInFocusChain | 4 | 在键盘焦点链中包含超链接。默认已启用。 |
QWebEngineSettings::LocalStorageEnabled | 5 | 启用对 HTML 5 本地存储功能的支持。默认已启用。 |
QWebEngineSettings::LocalContentCanAccessRemoteUrls | 6 | 允许本地源文档访问通常会被阻止的远程资源。默认已禁用。请注意，下面的 DnsPrefetchEnabled 与此设置无关，如果启用，可能会导致本地内容的远程访问。 |
QWebEngineSettings::XSSAuditingEnabled | 7 | 已过时，没有影响。 |
QWebEngineSettings::SpatialNavigationEnabled | 8 | 启用空间导航功能，即通过使用左、右、上、下方向键在网页上的超链接和表单控件等可聚焦元素之间导航的功能。举例来说，如果用户按下右键，启发式导航功能会判断他们是否想在右边找到某个元素，以及他们可能想要哪个元素。默认禁用。 |
QWebEngineSettings::LocalContentCanAccessFileUrls | 9 | 允许本地加载的文档访问其他本地 URL。禁用此功能后，QtWebEngine 的默认行为与 Chrome 和 Firefox 更为相似。默认已启用。 |
QWebEngineSettings::HyperlinkAuditingEnabled | 10 | 启用对超链接ping 属性的支持。默认已禁用。 |
QWebEngineSettings::ScrollAnimatorEnabled | 11 | 启用动画滚动。默认已禁用。 |
QWebEngineSettings::ErrorPageEnabled | 12 | 启用显示 Chromium 内置错误页面。默认已启用。 |
QWebEngineSettings::PluginsEnabled | 13 | 启用对 Pepper 插件（如 Flash 播放器）的支持。默认已禁用。 |
QWebEngineSettings::FullScreenSupportEnabled | 14 | 在应用程序中启用全屏支持。默认已禁用。(在 Qt 5.6 中添加） |
QWebEngineSettings::ScreenCaptureEnabled | 15 | 在应用程序中启用屏幕捕捉。默认已禁用。(已在 Qt 5.7 中添加） |
QWebEngineSettings::WebGLEnabled | 16 | 启用对 HTML 5 WebGL 的支持。如果可用，默认已启用。(在 Qt 5.7 中添加） |
QWebEngineSettings::Accelerated2dCanvasEnabled | 17 | 指定 HTML5 2D 画布是否应为 OpenGL 帧缓冲。这将加快许多绘制操作的速度，但会减慢像素访问速度。如果可用，默认已启用。(在 Qt 5.7 中添加） |
QWebEngineSettings::AutoLoadIconsForPage | 18 | 自动下载网页图标。默认已启用。(在 Qt 5.7 中添加） |
QWebEngineSettings::TouchIconsEnabled | 19 | 启用对触摸图标和预合成触摸图标的支持 默认已禁用。(在 Qt 5.7 中添加） |
QWebEngineSettings::FocusOnNavigationEnabled | 20 | 每当发生导航操作（加载、停止、重新加载、重新加载并绕过缓存、前进、后退、设置内容等）时，将焦点赋予与页面相关的视图。默认情况下禁用。(在 Qt 5.8 中添加） |
QWebEngineSettings::PrintElementBackgrounds | 21 | 打印网页时打开 CSS 背景打印。默认已启用。(在 Qt 5.8 中添加） |
QWebEngineSettings::AllowRunningInsecureContent | 22 | 默认情况下，HTTPS 页面不能从 HTTP URL 运行 JavaScript、CSS、插件或 web-sockets。这提供了一个重载功能，以获得旧的不安全行为。默认已禁用。(在 Qt 5.8 中添加） |
QWebEngineSettings::AllowGeolocationOnInsecureOrigins | 23 | 自 Qt 5.7 起，只有 HTTPS 等安全来源才能请求地理位置功能。此功能提供了一个覆盖，允许非安全起源再次访问 Geolocation。默认已禁用。(在 Qt 5.9 中添加） |
QWebEngineSettings::AllowWindowActivationFromJavaScript | 24 | 允许使用 window.focus() JavaScript 方法激活窗口。默认已禁用。(在 Qt 5.10 中添加） |
QWebEngineSettings::ShowScrollBars | 25 | 显示滚动条。默认已启用。(已在 Qt 5.10 中添加） |
QWebEngineSettings::PlaybackRequiresUserGesture | 26 | 在用户与页面交互之前禁止播放媒体内容。默认情况下，WebEngine 使用 Chromium 设置，如自动播放策略更改中所述。这与 Android 上 Chrome 浏览器的行为类似，而禁用后的默认行为则与台式机上的 Chrome 浏览器类似。要覆盖默认行为，请禁用此设置。(在 Qt 5.11 中添加） |
QWebEngineSettings::JavascriptCanPaste | 28 | 允许 JavaScript 程序从剪贴板读取（粘贴）和写入未经消毒的内容。经过消毒的写入是通过write 和writeText JavaScript 剪贴板 API 调用完成的，并且必须伴随用户操作；未经消毒的写入是指不符合这些标准的任何写入。JavascriptCanAccessClipboard 必须同时启用，该设置才能生效。由于不受限制地访问剪贴板存在潜在的安全隐患，因此建议应用程序禁用此设置，并响应ClipboardReadWrite 功能权限请求。默认已禁用。(在 Qt 5.11 中添加） |
QWebEngineSettings::WebRTCPublicInterfacesOnly | 27 | 仅将 WebRTC 限制为公共 IP 地址。禁用后，WebRTC 也可以使用本地网络 IP 地址，但远程主机也可以看到您的本地网络 IP 地址。默认已禁用。(在 Qt 5.11 中添加） |
QWebEngineSettings::DnsPrefetchEnabled | 29 | 指定WebEngine 是否会尝试预取 DNS 条目以加快浏览速度。默认已禁用。(已在 Qt 5.12 中添加） |
QWebEngineSettings::PdfViewerEnabled | 30 | 指定 PDF 文档将在内部 PDF 查看器中打开，而不是下载。默认已启用。(在 Qt 5.13 中添加） |
QWebEngineSettings::NavigateOnDropEnabled | 31 | 指定可通过在视图上拖放 URL 来触发导航。默认已启用。(在 Qt 6.4 中添加） |
QWebEngineSettings::ReadingFromCanvasEnabled | 32 | 指定启用从所有画布元素读取数据。此设置将影响所有 HTML5 画布元素，无论其来源如何，禁用此设置可防止画布指纹。默认已启用。(在 Qt 6.6 中添加） |
QWebEngineSettings::ForceDarkMode | 33 | 指定使用暗色主题渲染所有网页内容。更多信息，请参阅自动深色主题。默认已禁用。(已在 Qt 6.7 中添加） |
QWebEngineSettings::PrintHeaderAndFooter | 34 | 指定打印结果将在页眉和页脚区域包含基本页面信息（URL、标题、日期、页码）。嵌入者有责任通过设置适当的上下边距为这些文本提供足够的空间。默认已禁用。(在 Qt 6.9 中添加） |
QWebEngineSettings::PreferCSSMarginsForPrinting | 35 | 打开 CSS 边距优于指定QPageLayout 的边距。默认已禁用。(在 Qt 6.9 中添加） |
QWebEngineSettings::TouchEventsApiEnabled | 36 | 启用对 JavaScript 触摸事件 API 的支持，这意味着ontouchstart 、ontouchend 和ontouchmove 处理程序将出现在document.window 对象中。如果系统检测到触摸设备，则默认启用，否则禁用。(在 Qt 6.9 中添加）请注意，有些网站使用此 API 来决定是在移动设备上运行还是在桌面上运行，并以此为基础进行设计。这可能会在触摸屏笔记本电脑或其他模拟假触摸设备的设置上造成不必要的结果。 |
成员函数文档
QString QWebEngineSettings::defaultTextEncoding() const
返回默认文本编码。
另请参阅 setDefaultTextEncoding()。
QString QWebEngineSettings::fontFamily(QWebEngineSettings::FontFamily which) const
返回指定通用字体系列的实际字体系列，which 。
int QWebEngineSettings::fontSize(QWebEngineSettings::FontSize type) const
返回type 的默认字体大小（单位：像素）。
另请参阅 setFontSize().
[since Qt 6.8] QWebEngineSettings::ImageAnimationPolicy QWebEngineSettings::imageAnimationPolicy() const
返回当前选择的策略，用于在渲染图像帧时处理图像动画。默认值为QWebEngineSettings::ImageAnimationPolicy::Allow 。
此函数在 Qt 6.8 中引入。
另请参阅 setImageAnimationPolicy 和resetImageAnimationPolicy 。
void QWebEngineSettings::resetAttribute(QWebEngineSettings::WebAttribute attribute)
将attribute 的设置重置为页面所属配置文件中指定的值。
void QWebEngineSettings::resetFontFamily(QWebEngineSettings::FontFamily which)
将which 指定的实际字体族重置为页面所属配置文件中指定的字体族。
void QWebEngineSettings::resetFontSize(QWebEngineSettings::FontSize type)
将type 的字体大小重置为页面所属配置文件中指定的大小。
[since Qt 6.8] void QWebEngineSettings::resetImageAnimationPolicy()
删除处理图像动画的策略。
此函数在 Qt 6.8 中引入。
另请参阅 imageAnimationPolicy 和setImageAnimationPolicy 。
[since Qt 5.11] void QWebEngineSettings::resetUnknownUrlSchemePolicy()
移除处理未知方案 URL 导航请求的策略。
此函数在 Qt 5.11 中引入。
另请参阅 unknownUrlSchemePolicy 和setUnknownUrlSchemePolicy 。
void QWebEngineSettings::setAttribute(QWebEngineSettings::WebAttribute attribute, bool on)
根据on 的值，启用或禁用指定的attribute 功能。
void QWebEngineSettings::setDefaultTextEncoding(const QString &encoding)
指定默认文本编码系统。
encoding 的值必须是一个描述编码的字符串，如 "utf-8 "或 "iso-8859-1"。如果留空，将使用默认值。有关编码名称的更广泛列表，请参阅QTextCodec 。
另请参阅 defaultTextEncoding() 。
void QWebEngineSettings::setFontSize(QWebEngineSettings::FontSize type, int size)
以像素为单位设置type 至size 的字体大小。
另请参阅 fontSize().
[since Qt 6.8] void QWebEngineSettings::setImageAnimationPolicy(QWebEngineSettings::ImageAnimationPolicy policy)
设置在图像帧渲染到policy 时处理图像动画的策略。默认值为QWebEngineSettings::ImageAnimationPolicy::Allow 。
此函数在 Qt 6.8 中引入。
另请参阅 imageAnimationPolicy 和resetImageAnimationPolicy 。
[since Qt 5.11] void QWebEngineSettings::setUnknownUrlSchemePolicy(QWebEngineSettings::UnknownUrlSchemePolicy policy)
将处理未知方案 URL 导航请求的策略设置为policy 。默认值为QWebEngineSettings::AllowUnknownUrlSchemesFromUserInteraction 。
此函数在 Qt 5.11 中引入。
另请参阅 unknownUrlSchemePolicy 和resetUnknownUrlSchemePolicy 。
bool QWebEngineSettings::testAttribute(QWebEngineSettings::WebAttribute attribute) const
如果attribute 已启用，则返回true ；否则返回false 。
[since Qt 5.11] QWebEngineSettings::UnknownUrlSchemePolicy QWebEngineSettings::unknownUrlSchemePolicy() const
返回当前选择的策略，用于处理对未知方案 URL 的导航请求。默认值为QWebEngineSettings::AllowUnknownUrlSchemesFromUserInteraction 。
此函数在 Qt 5.11 中引入。
另请参阅 setUnknownUrlSchemePolicy 和resetUnknownUrlSchemePolicy 。
© 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.
