QWebEngineDownloadRequest Class
QWebEngineDownloadRequest 类提供有关下载的信息。更多
| Header： | #include <QWebEngineDownloadRequest> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS WebEngineCore)target_link_libraries(mytarget PRIVATE Qt6::WebEngineCore) |
| qmake： | QT += webenginecore |
| 在 QML 中： | WebEngineDownloadRequest |
| 继承： | QObject |
公共类型
| enum | DownloadInterruptReason { NoReason, FileFailed, FileAccessDenied, FileNoSpace, FileNameTooLong, …, UserCanceled } |
| enum | DownloadState { DownloadRequested, DownloadInProgress, DownloadCompleted, DownloadCancelled, DownloadInterrupted } |
| enum | SavePageFormat { UnknownSaveFormat, SingleHtmlSaveFormat, CompleteHtmlSaveFormat, MimeHtmlSaveFormat } |
属性
- isFinished : const bool
- isPaused : const bool
公共功能
| QString | downloadDirectory() const |
| QString | downloadFileName() const |
| quint32 | id() const |
| QWebEngineDownloadRequest::DownloadInterruptReason | interruptReason() const |
| QString | interruptReasonString() const |
| bool | isFinished() const |
| bool | isPaused() const |
| bool | isSavePageDownload() const |
| QString | mimeType() const |
| QWebEnginePage * | page() const |
| qint64 | receivedBytes() const |
| QWebEngineDownloadRequest::SavePageFormat | savePageFormat() const |
| void | setDownloadDirectory(const QString &directory) |
| void | setDownloadFileName(const QString &fileName) |
| void | setSavePageFormat(QWebEngineDownloadRequest::SavePageFormat format) |
| QWebEngineDownloadRequest::DownloadState | state() const |
| QString | suggestedFileName() const |
| qint64 | totalBytes() const |
| QUrl | url() const |
公共插槽
信号
| void | downloadDirectoryChanged() |
| void | downloadFileNameChanged() |
| void | interruptReasonChanged() |
| void | isFinishedChanged() |
| void | isPausedChanged() |
| void | receivedBytesChanged() |
| void | savePageFormatChanged() |
| void | stateChanged(QWebEngineDownloadRequest::DownloadState state) |
| void | totalBytesChanged() |
详细说明
QWebEngineDownloadRequest 对下载的整个生命周期进行建模，从等待下载请求开始，到完成下载结束。例如，它可用于获取有关新下载的信息、监控下载进度，以及暂停、恢复和取消下载。
下载通常由用户在网页上的交互触发。QWebEngineProfile 有责任将新的下载请求通知应用程序，它的做法是发出downloadRequested 信号和新创建的 QWebEngineDownloadRequest。然后，应用程序可以检查该请求，并决定是否接受。做出决定后，应用程序必须在项目上明确调用accept() 或cancel() 以让Qt WebEngine 实际开始下载或拒绝请求。
注： 某些属性，如设置文件保存路径和文件名（见downloadDirectory() 和downloadFileName() ），只能在调用accept() 之前更改。
对象生命周期
在每种情况下，QWebEngineProfile 都拥有项目的所有权。不过，应用程序在任何时候删除项目都是安全的，除非是在处理downloadRequested 信号期间。QWebEngineProfile 是一个长期存在的对象，因此建议应用程序删除它不再感兴趣的任何项目。
注： 自 5.12.2 版起，删除项目也会自动取消下载，但为了便于移植，建议在删除前手动取消下载。
网页下载
除了普通的文件下载（只需从网络上获取一些原始字节并写入磁盘）外，Qt WebEngine 还支持保存完整的网页，这涉及到解析网页的 HTML、下载任何依赖的资源，并可能将所有内容打包成一种特殊的文件格式 (savePageFormat)。要检查下载的是文件还是网页，请使用isSavePageDownload 。
出于方便考虑，网页保存请求会被自动接受，并从DownloadInProgress 状态启动。第一个直接连接的downloadRequested 信号处理器可以通过调用cancel() 来阻止这种情况，否则保存操作将开始向磁盘写入数据。
另请参见 QWebEngineProfile,QWebEngineProfile::downloadRequested,QWebEnginePage::download, 和QWebEnginePage::save 。
成员类型文档
enum QWebEngineDownloadRequest::DownloadInterruptReason
描述下载中断的原因：
| 常量 | 值 | 说明 |
|---|---|---|
QWebEngineDownloadRequest::NoReason | 0 | 原因不明或未中断。 |
QWebEngineDownloadRequest::FileFailed | 1 | 一般文件操作失败。 |
QWebEngineDownloadRequest::FileAccessDenied | 2 | 由于访问限制，无法在本地写入文件。 |
QWebEngineDownloadRequest::FileNoSpace | 3 | 目标驱动器空间不足。 |
QWebEngineDownloadRequest::FileNameTooLong | 5 | 目录或文件名太长。 |
QWebEngineDownloadRequest::FileTooLarge | 6 | 文件大小超过文件系统限制。 |
QWebEngineDownloadRequest::FileVirusInfected | 7 | 文件感染了病毒。 |
QWebEngineDownloadRequest::FileTransientError | 10 | 临时问题（例如文件正在使用中、内存不足或同时打开的文件过多）。 |
QWebEngineDownloadRequest::FileBlocked | 11 | 文件因本地策略而被阻止。 |
QWebEngineDownloadRequest::FileSecurityCheckFailed | 12 | 由于意外原因，检查下载安全性的尝试失败。 |
QWebEngineDownloadRequest::FileTooShort | 13 | 在打开文件时（作为恢复先前中断下载的一部分），试图寻找文件的末尾。 |
QWebEngineDownloadRequest::FileHashMismatch | 14 | 部分文件与预期哈希值不匹配。 |
QWebEngineDownloadRequest::NetworkFailed | 20 | 一般网络故障。 |
QWebEngineDownloadRequest::NetworkTimeout | 21 | 网络操作超时。 |
QWebEngineDownloadRequest::NetworkDisconnected | 22 | 网络连接已终止。 |
QWebEngineDownloadRequest::NetworkServerDown | 23 | 服务器宕机。 |
QWebEngineDownloadRequest::NetworkInvalidRequest | 24 | 网络请求无效（例如，原始或重定向 URL 无效、方案不支持或策略不允许）。 |
QWebEngineDownloadRequest::ServerFailed | 30 | 一般服务器故障。 |
QWebEngineDownloadRequest::ServerBadContent | 33 | 服务器没有请求的数据。 |
QWebEngineDownloadRequest::ServerUnauthorized | 34 | 服务器未授权访问资源。 |
QWebEngineDownloadRequest::ServerCertProblem | 35 | 服务器证书出现问题。 |
QWebEngineDownloadRequest::ServerForbidden | 36 | 服务器禁止访问。 |
QWebEngineDownloadRequest::ServerUnreachable | 37 | 服务器响应出乎意料（可能表明响应的服务器可能不是预定的服务器）。 |
QWebEngineDownloadRequest::UserCanceled | 40 | 用户取消下载。 |
enum QWebEngineDownloadRequest::DownloadState
该枚举描述下载的状态：
| 常量 | 值 | 说明 |
|---|---|---|
QWebEngineDownloadRequest::DownloadRequested | 0 | 已请求下载，但尚未被接受。 |
QWebEngineDownloadRequest::DownloadInProgress | 1 | 下载正在进行。 |
QWebEngineDownloadRequest::DownloadCompleted | 2 | 下载已成功完成。 |
QWebEngineDownloadRequest::DownloadCancelled | 3 | 下载已取消。 |
QWebEngineDownloadRequest::DownloadInterrupted | 4 | 下载已中断（服务器中断或连接中断）。 |
enum QWebEngineDownloadRequest::SavePageFormat
该枚举描述用于保存网页的格式。
| 常量 | 值 | 说明 |
|---|---|---|
QWebEngineDownloadRequest::UnknownSaveFormat | -1 | 这不是下载完整网页的请求。 |
QWebEngineDownloadRequest::SingleHtmlSaveFormat | 0 | 网页保存为单个 HTML 页面。不保存图片等资源。 |
QWebEngineDownloadRequest::CompleteHtmlSaveFormat | 1 | 页面保存为完整的 HTML 页面，例如包含单个 HTML 页面和资源的目录。 |
QWebEngineDownloadRequest::MimeHtmlSaveFormat | 2 | 页面以 MIME HTML 格式保存为完整网页。 |
属性文档
[read-only] isFinished : const bool
该属性表示下载是否已完成（完成、取消或不可重置的中断状态）。
访问功能：
| bool | isFinished() const |
Notifier 信号：
| void | isFinishedChanged() |
另请参阅 state().
[read-only] isPaused : const bool
此属性表示下载是否暂停。
访问功能：
| bool | isPaused() const |
通知信号：
| void | isPausedChanged() |
成员函数文档
[slot] void QWebEngineDownloadRequest::accept()
接受当前下载请求，开始下载。
如果项目处于DownloadRequested 状态，则会过渡到DownloadInProgress 状态并开始下载。如果项目处于其他状态，则不会发生任何事情。
另请参阅 isFinished 和stateChanged()。
[slot] void QWebEngineDownloadRequest::cancel()
取消当前下载。
如果项目处于DownloadInProgress 状态，则将过渡到DownloadCancelled 状态，下载将停止，部分下载的文件将从磁盘中删除。
如果项目处于DownloadCompleted 状态，则什么也不会发生。如果项目处于任何其他状态，则会过渡到DownloadCancelled 状态，不会有任何影响。
另请参阅 isFinished 和stateChanged()。
QString QWebEngineDownloadRequest::downloadDirectory() const
返回下载目录路径。
注： 属性 downloadDirectory 的获取函数。
另请参阅 setDownloadDirectory().
QString QWebEngineDownloadRequest::downloadFileName() const
返回要下载文件的文件名。
注： 属性 downloadFileName 的获取函数。
另请参阅 setDownloadFileName().
quint32 QWebEngineDownloadRequest::id() const
返回下载项目的 ID。
注： 属性 id 的获取函数。
QWebEngineDownloadRequest::DownloadInterruptReason QWebEngineDownloadRequest::interruptReason() const
返回下载中断的原因。
注： 属性 interruptReason 的获取函数。
另请参阅 interruptReasonString().
QString QWebEngineDownloadRequest::interruptReasonString() const
返回中断下载原因的可读描述。
注： 属性 interruptReasonString 的获取函数。
另请参阅 interruptReason().
[signal] void QWebEngineDownloadRequest::isPausedChanged()
只要isPaused 发生变化，就会发出该信号。
注： 属性isPaused 的通知信号。
bool QWebEngineDownloadRequest::isSavePageDownload() const
如果是保存网页的下载请求，则返回true 。
注： 属性 isSavePageDownload 的获取函数。
另请参阅 savePageFormat() 和setSavePageFormat()。
QString QWebEngineDownloadRequest::mimeType() const
返回下载的 MIME 类型。
注： 属性 mimeType 的获取函数。
QWebEnginePage *QWebEngineDownloadRequest::page() const
返回请求下载的页面。如果下载不是由页面内容触发的，则返回nullptr 。
[slot] void QWebEngineDownloadRequest::pause()
暂停下载。
如果状态不是DownloadInProgress ，则不起作用。不改变状态。
qint64 QWebEngineDownloadRequest::receivedBytes() const
返回目前已下载的数据量（以字节为单位）。
-1 表示大小未知。
注：receivedBytes 属性的获取函数。
[slot] void QWebEngineDownloadRequest::resume()
如果当前下载暂停或中断，则恢复下载。
如果状态不是DownloadInProgress 或DownloadInterrupted ，则不起作用。不改变状态。
另请参阅 pause()、isPaused() 和state()。
QWebEngineDownloadRequest::SavePageFormat QWebEngineDownloadRequest::savePageFormat() const
如果是网页下载请求，则返回网页的保存格式。
注： 属性 savePageFormat 的获取函数。
另请参阅 setSavePageFormat() 和isSavePageDownload()。
void QWebEngineDownloadRequest::setDownloadDirectory(const QString &directory)
将directory 设置为下载文件的目录路径。
下载目录路径只能在接受下载之前响应QWebEngineProfile::downloadRequested() 信号时设置。在此之后，该函数对下载项目的状态没有任何影响。
注： 属性downloadDirectory 的设置函数。
另请参阅 downloadDirectory() 。
void QWebEngineDownloadRequest::setDownloadFileName(const QString &fileName)
将fileName 设置为下载文件的文件名。
下载文件名只能在接受下载之前响应QWebEngineProfile::downloadRequested() 信号时设置。在此之后，该函数对下载项目的状态没有任何影响。
注： 属性downloadFileName 的设置函数。
另请参阅 downloadFileName() 。
void QWebEngineDownloadRequest::setSavePageFormat(QWebEngineDownloadRequest::SavePageFormat format)
如果这是一个网页下载请求，则设置format 网页的保存位置。
注： 属性savePageFormat 的设置函数。
另请参阅 savePageFormat() 和isSavePageDownload()。
QWebEngineDownloadRequest::DownloadState QWebEngineDownloadRequest::state() const
返回下载项目的当前状态。
注： 属性状态的获取函数。
另请参阅 DownloadState 。
[signal] void QWebEngineDownloadRequest::stateChanged(QWebEngineDownloadRequest::DownloadState state)
每当下载的state 发生变化时，就会发出该信号。
注： 属性state 的通知信号。
另请参阅 state() 和DownloadState 。
QString QWebEngineDownloadRequest::suggestedFileName() const
返回建议的文件名。
注： 属性 suggestedFileName 的获取函数。
qint64 QWebEngineDownloadRequest::totalBytes() const
以字节为单位返回要下载的数据总量。
-1 表示大小未知。
注： 属性 totalBytes 的获取函数。
QUrl QWebEngineDownloadRequest::url() const
返回下载的源 URL。
注： 属性 url 的获取函数。
© 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.
