QWebEngineDownloadItem 类

QWebEngineDownloadItem 类提供了关于下载的信息。 更多...

头: #include <QWebEngineDownloadItem>
qmake: QT += webenginewidgets
Since: Qt 5.5
继承: QObject

该类在 Qt 5.5 引入。

公共类型

enum DownloadInterruptReason { NoReason, FileFailed, FileAccessDenied, FileNoSpace, FileNameTooLong, …, UserCanceled }
enum DownloadState { DownloadRequested, DownloadInProgress, DownloadCompleted, DownloadCancelled, DownloadInterrupted }
enum SavePageFormat { UnknownSaveFormat, SingleHtmlSaveFormat, CompleteHtmlSaveFormat, MimeHtmlSaveFormat }

公共函数

QString downloadDirectory () const
QString downloadFileName () const
quint32 id () const
QWebEngineDownloadItem::DownloadInterruptReason interruptReason () const
QString interruptReasonString () const
bool isFinished () const
bool isPaused () const
bool isSavePageDownload () const
QString mimeType () const
QWebEnginePage * page () const
qint64 receivedBytes () const
QWebEngineDownloadItem::SavePageFormat savePageFormat () const
void setDownloadDirectory (const QString & directory )
void setDownloadFileName (const QString & fileName )
void setSavePageFormat (QWebEngineDownloadItem::SavePageFormat format )
QWebEngineDownloadItem::DownloadState state () const
QString suggestedFileName () const
qint64 totalBytes () const
QUrl url () const

公共槽

void accept ()
void cancel ()
void pause ()
void resume ()

信号

void downloadProgress (qint64 bytesReceived , qint64 bytesTotal )
void finished ()
void isPausedChanged (bool isPaused )
void stateChanged (QWebEngineDownloadItem::DownloadState state )

详细描述

QWebEngineDownloadItem 在整个生命周期中对下载进行建模,从待决下载请求开始,到完成下载结束。例如:它可以被用于获取有关新下载的信息、监视下载进度、暂停 再继续及取消下载。

通常,下载由网页上的用户交互触发。它是 QWebEngineProfile 的职责,通知应用程序有新的下载请求,通过发射 downloadRequested signal together with a newly created QWebEngineDownloadItem. The application can then examine this item and decide whether to accept it or not. A signal handler must explicitly call accept () 在项,以便 Qt WebEngine 实际开始下载并把数据写入磁盘。若没有信号处理程序调用 accept (),那么下载请求将被自动拒绝,且什么都不会被写入磁盘。

注意: 某些特性,如设置文件保存路径和文件名 (见 downloadDirectory () 和 downloadFileName ()),才可以改变先于调用 accept ().

对象生命周期

所有项均保证有效,在发出期间为 downloadRequested 信号。若 accept () 是 not 被任何信号处理程序所调用,则项会被删除 immediately 在信号发出之后。这意味着应用程序 不必 对拒绝下载项保持引用。它也意味着应用程序不应对此信号使用队列连接。

accept () is 被信号处理程序所调用,那么 QWebEngineProfile 将获得项的所有权。不管怎样,应用程序随时删除项是安全的,除了在处理期间为 downloadRequested 信号。 QWebEngineProfile 是长期存活对象,事实上,推荐应用程序删除它不再感兴趣的任何项。

注意: 从 5.12.2 起删除项也会被自动取消下载,但为了可移植性,推荐在删除之前手动取消。

网页下载

除正常文件下载 (简单地从网络检索一些原生字节并把它们写入磁盘) 外,Qt WebEngine 还支持保存完整网页,涉及剖析页面的 HTML、下载任何从属资源及把潜在的一切打包进特殊文件格式 ( savePageFormat )。要检查下载的是文件还是网页,使用 isSavePageDownload .

另请参阅 QWebEngineProfile , QWebEngineProfile::downloadRequested , QWebEnginePage::download ,和 QWebEnginePage::save .

成员类型文档编制

enum QWebEngineDownloadItem:: DownloadInterruptReason

描述下载为什么被中断的原因:

常量 描述
QWebEngineDownloadItem::NoReason 0 未知原因或未中断。
QWebEngineDownloadItem::FileFailed 1 常规文件操作故障。
QWebEngineDownloadItem::FileAccessDenied 2 文件无法在本地写入,由于访问限定。
QWebEngineDownloadItem::FileNoSpace 3 目标驱动器空间不足。
QWebEngineDownloadItem::FileNameTooLong 5 目录或文件名太长。
QWebEngineDownloadItem::FileTooLarge 6 文件大小超过文件系统限制。
QWebEngineDownloadItem::FileVirusInfected 7 文件被病毒感染。
QWebEngineDownloadItem::FileTransientError 10 临时问题 (例如:文件在使用中、内存不足或一次打开太多文件)。
QWebEngineDownloadItem::FileBlocked 11 文件被阻塞由于本地策略。
QWebEngineDownloadItem::FileSecurityCheckFailed 12 试图检查下载失败的安全性,由于意外原因。
QWebEngineDownloadItem::FileTooShort 13 尝试寻址超出文件末尾,当打开文件时 (作为再继续先前被中断下载的一部分)。
QWebEngineDownloadItem::FileHashMismatch 14 部分文件不匹配预期哈希。
QWebEngineDownloadItem::NetworkFailed 20 常规网络故障。
QWebEngineDownloadItem::NetworkTimeout 21 网络操作已超时。
QWebEngineDownloadItem::NetworkDisconnected 22 网络连接已被终止。
QWebEngineDownloadItem::NetworkServerDown 23 服务器宕机。
QWebEngineDownloadItem::NetworkInvalidRequest 24 网络请求无效 (例如:原始或重定向 URL 无效,方案不受支持或被策略禁止)。
QWebEngineDownloadItem::ServerFailed 30 常规服务器故障。
QWebEngineDownloadItem::ServerBadContent 33 服务器没有请求的数据。
QWebEngineDownloadItem::ServerUnauthorized 34 服务器未授权访问资源。
QWebEngineDownloadItem::ServerCertProblem 35 服务器证书发生问题。
QWebEngineDownloadItem::ServerForbidden 36 访问被服务器禁止。
QWebEngineDownloadItem::ServerUnreachable 37 意外服务器响应 (可能指示响应服务器,可能不是企图服务器)。
QWebEngineDownloadItem::UserCanceled 40 用户取消下载。

该枚举在 Qt 5.9 引入或被修改。

enum QWebEngineDownloadItem:: DownloadState

此枚举描述下载的状态:

常量 描述
QWebEngineDownloadItem::DownloadRequested 0 下载已请求,但尚未接受。
QWebEngineDownloadItem::DownloadInProgress 1 下载正在进行中。
QWebEngineDownloadItem::DownloadCompleted 2 下载成功完成。
QWebEngineDownloadItem::DownloadCancelled 3 下载已被取消。
QWebEngineDownloadItem::DownloadInterrupted 4 下载已被中断 (由服务器或由于丢失连接)。

enum QWebEngineDownloadItem:: SavePageFormat

此枚举描述用于保存网页的格式。

常量 描述
QWebEngineDownloadItem::UnknownSaveFormat -1 这不是下载完整网页的请求。
QWebEngineDownloadItem::SingleHtmlSaveFormat 0 页面被另存为单 HTML 页面。图像等资源不被保存。
QWebEngineDownloadItem::CompleteHtmlSaveFormat 1 页面被另存为完整 HTML 页面,例如:目录包含单 HTML 页面和资源。
QWebEngineDownloadItem::MimeHtmlSaveFormat 2 页面以 MIME HTML 格式,被另存为完整网页。

该枚举在 Qt 5.7 引入或被修改。

成员函数文档编制

[slot] void QWebEngineDownloadItem:: accept ()

接受当前下载请求,将开始下载。

若项在 DownloadRequested 状态,那么它将过渡到 DownloadInProgress 状态,且下载会开始。若项在任何其它状态,则什么都不会发生。

另请参阅 finished () 和 stateChanged ().

[slot] void QWebEngineDownloadItem:: cancel ()

取消当前下载。

若项在 DownloadInProgress 状态,那么它将过渡到 DownloadCancelled 状态,下载会停止,且部分下载文件会从磁盘被删除。

若项在 DownloadCompleted 状态,则什么都不会发生。若项在任何其它状态,则它会过渡到 DownloadCancelled 状态,没有进一步影响。

另请参阅 finished () 和 stateChanged ().

[signal] void QWebEngineDownloadItem:: downloadProgress ( qint64 bytesReceived , qint64 bytesTotal )

此信号被发射,以指示下载请求的进度。

The bytesReceived 参数指示接收字节数,而 bytesTotal 指示期望要下载的总字节数。若要下载的文件大小不知道, bytesTotal 会为 0。

另请参阅 totalBytes () 和 receivedBytes ().

[signal] void QWebEngineDownloadItem:: finished ()

此信号被发射当下载完成时。

另请参阅 state () 和 isFinished ().

[signal] void QWebEngineDownloadItem:: isPausedChanged ( bool isPaused )

此信号发射每当 isPaused 改变。

该函数在 Qt 5.10 引入。

另请参阅 pause () 和 isPaused ().

[slot] void QWebEngineDownloadItem:: pause ()

暂停下载。

不起作用,若状态不是 DownloadInProgress 。不改变状态。

该函数在 Qt 5.10 引入。

另请参阅 resume () 和 isPaused ().

[slot] void QWebEngineDownloadItem:: resume ()

再继续当前下载,若它被暂停或中断。

不起作用,若状态不是 DownloadInProgress or DownloadInterrupted 。不改变状态。

该函数在 Qt 5.10 引入。

另请参阅 pause (), isPaused (),和 state ().

[signal] void QWebEngineDownloadItem:: stateChanged ( QWebEngineDownloadItem::DownloadState state )

此信号被发射每当下载的 state 改变。

另请参阅 state () 和 DownloadState .

QString QWebEngineDownloadItem:: downloadDirectory () const

返回下载目录路径。

该函数在 Qt 5.14 引入。

另请参阅 setDownloadDirectory ().

QString QWebEngineDownloadItem:: downloadFileName () const

返回要下载文件的文件名。

该函数在 Qt 5.14 引入。

另请参阅 setDownloadFileName ().

quint32 QWebEngineDownloadItem:: id () const

返回下载项 ID。

QWebEngineDownloadItem::DownloadInterruptReason QWebEngineDownloadItem:: interruptReason () const

返回下载为什么被中断的原因。

该函数在 Qt 5.9 引入。

另请参阅 interruptReasonString ().

QString QWebEngineDownloadItem:: interruptReasonString () const

返回人类可读的中断下载原因的描述。

该函数在 Qt 5.9 引入。

另请参阅 interruptReason ().

bool QWebEngineDownloadItem:: isFinished () const

返回此下载是否完成 (完成、取消或非再继续中断状态)。

另请参阅 finished () 和 state ().

bool QWebEngineDownloadItem:: isPaused () const

返回此下载是否被暂停。

另请参阅 pause () 和 resume ().

bool QWebEngineDownloadItem:: isSavePageDownload () const

返回 true 若这是用于保存网页的下载请求。

该函数在 Qt 5.11 引入。

另请参阅 savePageFormat () 和 setSavePageFormat ().

QString QWebEngineDownloadItem:: mimeType () const

返回下载的 MIME 类型。

该函数在 Qt 5.6 引入。

QWebEnginePage *QWebEngineDownloadItem:: page () const

返回请求下载的页面。若下载不由页面内容所触发, nullptr 被返回。

该函数在 Qt 5.12 引入。

qint64 QWebEngineDownloadItem:: receivedBytes () const

返回到目前为止已下载的数据数量 (以字节为单位)。

-1 意味着尺寸未知。

QWebEngineDownloadItem::SavePageFormat QWebEngineDownloadItem:: savePageFormat () const

返回保存网页的格式,如果这是用于网页的下载请求。

该函数在 Qt 5.7 引入。

另请参阅 setSavePageFormat () 和 isSavePageDownload ().

void QWebEngineDownloadItem:: setDownloadDirectory (const QString & directory )

设置 directory 作为要下载文件的目录路径。

下载目录才可以被设置为响应 QWebEngineProfile::downloadRequested () 信号在接受下载前。此后,此函数对下载项状态不起作用。

该函数在 Qt 5.14 引入。

另请参阅 downloadDirectory ().

void QWebEngineDownloadItem:: setDownloadFileName (const QString & fileName )

设置 fileName 作为要下载文件的文件名。

下载文件名才可以被设置为响应 QWebEngineProfile::downloadRequested () 信号在接受下载前。此后,此函数对下载项状态不起作用。

该函数在 Qt 5.14 引入。

另请参阅 downloadFileName ().

void QWebEngineDownloadItem:: setSavePageFormat ( QWebEngineDownloadItem::SavePageFormat format )

设置 format 为网页保存,若这是网页下载请求。

该函数在 Qt 5.7 引入。

另请参阅 savePageFormat () 和 isSavePageDownload ().

QWebEngineDownloadItem::DownloadState QWebEngineDownloadItem:: state () const

返回下载项的当前状态。

另请参阅 DownloadState .

QString QWebEngineDownloadItem:: suggestedFileName () const

返回建议的文件名。

该函数在 Qt 5.14 引入。

qint64 QWebEngineDownloadItem:: totalBytes () const

Returns the total amount of data to download in bytes.

-1 意味着尺寸未知。

QUrl QWebEngineDownloadItem:: url () const

返回下载的原始 URL。