QWebEngineDownloadRequest Class
La clase QWebEngineDownloadRequest proporciona información sobre una descarga. Más...
| Cabecera: | #include <QWebEngineDownloadRequest> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS WebEngineCore)target_link_libraries(mytarget PRIVATE Qt6::WebEngineCore) |
| qmake: | QT += webenginecore |
| En QML: | WebEngineDownloadRequest |
| Hereda: | QObject |
Tipos públicos
| enum | DownloadInterruptReason { NoReason, FileFailed, FileAccessDenied, FileNoSpace, FileNameTooLong, …, UserCanceled } |
| enum | DownloadState { DownloadRequested, DownloadInProgress, DownloadCompleted, DownloadCancelled, DownloadInterrupted } |
| enum | SavePageFormat { UnknownSaveFormat, SingleHtmlSaveFormat, CompleteHtmlSaveFormat, MimeHtmlSaveFormat } |
Propiedades
|
|
Funciones públicas
| 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 |
Ranuras públicas
Señales
| void | downloadDirectoryChanged() |
| void | downloadFileNameChanged() |
| void | interruptReasonChanged() |
| void | isFinishedChanged() |
| void | isPausedChanged() |
| void | receivedBytesChanged() |
| void | savePageFormatChanged() |
| void | stateChanged(QWebEngineDownloadRequest::DownloadState state) |
| void | totalBytesChanged() |
Descripción Detallada
QWebEngineDownloadRequest modela una descarga a lo largo de su ciclo de vida, comenzando con una solicitud de descarga pendiente y terminando con una descarga completada. Puede usarse, por ejemplo, para obtener información sobre nuevas descargas, monitorizar el progreso y pausar, reanudar y cancelar descargas.
Las descargas suelen activarse por la interacción del usuario en una página web. Es responsabilidad de QWebEngineProfile notificar a la aplicación de nuevas solicitudes de descarga, lo que hace emitiendo la señal downloadRequested junto con una QWebEngineDownloadRequest recién creada. La aplicación puede entonces examinar este elemento y decidir si lo acepta o no. Una vez tomada la decisión, la aplicación debe llamar explícitamente a accept() o cancel() sobre el elemento para que Qt WebEngine inicie realmente la descarga o rechace la solicitud.
Nota: Algunas propiedades, como la configuración de la ruta y el nombre del archivo donde se guardará (véase downloadDirectory() y downloadFileName()), sólo pueden modificarse antes de llamar a accept().
Ciclo de vida de los objetos
En todos y cada uno de los casos, QWebEngineProfile asume la propiedad del objeto. Sin embargo, la aplicación puede borrar el elemento en cualquier momento, excepto durante la gestión de la señal downloadRequested. Dado que QWebEngineProfile es un objeto longevo, se recomienda que la aplicación elimine los elementos que ya no le interesen.
Nota: Borrar un ítem también cancelará automáticamente una descarga desde 5.12.2, pero se recomienda cancelar manualmente antes de borrar por razones de portabilidad.
Descargas de páginas web
Además de las descargas normales de archivos, que consisten simplemente en recuperar algunos bytes en bruto de la red y escribirlos en el disco, Qt WebEngine también permite guardar páginas web completas, lo que implica analizar el HTML de la página, descargar cualquier recurso dependiente y, potencialmente, empaquetarlo todo en un formato de archivo especial (savePageFormat). Para comprobar si una descarga es de un archivo o de una página web, utiliza isSavePageDownload.
Las peticiones de guardado de páginas web se aceptan automáticamente y se inician desde el estado DownloadInProgress por razones de conveniencia. El primer gestor de señales directamente conectado a downloadRequested puede evitarlo llamando a cancel(), de lo contrario la operación de guardado comenzará a escribir datos en el disco.
Ver también QWebEngineProfile, QWebEngineProfile::downloadRequested, QWebEnginePage::download, y QWebEnginePage::save.
Documentación de tipos de miembros
enum QWebEngineDownloadRequest::DownloadInterruptReason
Describe el motivo por el que se ha interrumpido una descarga:
| Constante | Valor | Descripción |
|---|---|---|
QWebEngineDownloadRequest::NoReason | 0 | Razón desconocida o no interrumpida. |
QWebEngineDownloadRequest::FileFailed | 1 | Fallo general de la operación de archivo. |
QWebEngineDownloadRequest::FileAccessDenied | 2 | El archivo no se puede escribir localmente debido a restricciones de acceso. |
QWebEngineDownloadRequest::FileNoSpace | 3 | Espacio insuficiente en la unidad de destino. |
QWebEngineDownloadRequest::FileNameTooLong | 5 | El nombre del directorio o del archivo es demasiado largo. |
QWebEngineDownloadRequest::FileTooLarge | 6 | El tamaño del archivo supera la limitación del sistema de archivos. |
QWebEngineDownloadRequest::FileVirusInfected | 7 | El archivo está infectado por un virus. |
QWebEngineDownloadRequest::FileTransientError | 10 | Problema temporal (por ejemplo, el archivo está en uso, se ha quedado sin memoria o se han abierto demasiados archivos a la vez). |
QWebEngineDownloadRequest::FileBlocked | 11 | El fichero ha sido bloqueado debido a una política local. |
QWebEngineDownloadRequest::FileSecurityCheckFailed | 12 | Un intento de comprobar la seguridad de la descarga falló debido a razones inesperadas. |
QWebEngineDownloadRequest::FileTooShort | 13 | Se intentó buscar más allá del final de un archivo al abrir un archivo (como parte de la reanudación de una descarga interrumpida previamente). |
QWebEngineDownloadRequest::FileHashMismatch | 14 | El archivo parcial no coincidía con el hash esperado. |
QWebEngineDownloadRequest::NetworkFailed | 20 | Fallo general de la red. |
QWebEngineDownloadRequest::NetworkTimeout | 21 | Se ha agotado el tiempo de espera de la operación de red. |
QWebEngineDownloadRequest::NetworkDisconnected | 22 | Se ha interrumpido la conexión de red. |
QWebEngineDownloadRequest::NetworkServerDown | 23 | El servidor se ha caído. |
QWebEngineDownloadRequest::NetworkInvalidRequest | 24 | La solicitud de red no era válida (por ejemplo, la URL original o redirigida no es válida, tiene un esquema no compatible o no está permitida por la política). |
QWebEngineDownloadRequest::ServerFailed | 30 | Fallo general del servidor. |
QWebEngineDownloadRequest::ServerBadContent | 33 | El servidor no dispone de los datos solicitados. |
QWebEngineDownloadRequest::ServerUnauthorized | 34 | El servidor no autorizó el acceso al recurso. |
QWebEngineDownloadRequest::ServerCertProblem | 35 | Se ha producido un problema con el certificado del servidor. |
QWebEngineDownloadRequest::ServerForbidden | 36 | Acceso prohibido por el servidor. |
QWebEngineDownloadRequest::ServerUnreachable | 37 | Respuesta inesperada del servidor (puede indicar que el servidor que responde puede no ser el servidor previsto). |
QWebEngineDownloadRequest::UserCanceled | 40 | El usuario canceló la descarga. |
enum QWebEngineDownloadRequest::DownloadState
Este enum describe el estado de la descarga:
| Constante | Valor | Descripción |
|---|---|---|
QWebEngineDownloadRequest::DownloadRequested | 0 | Se ha solicitado la descarga, pero aún no se ha aceptado. |
QWebEngineDownloadRequest::DownloadInProgress | 1 | La descarga está en curso. |
QWebEngineDownloadRequest::DownloadCompleted | 2 | La descarga se ha completado correctamente. |
QWebEngineDownloadRequest::DownloadCancelled | 3 | Se ha cancelado la descarga. |
QWebEngineDownloadRequest::DownloadInterrupted | 4 | La descarga ha sido interrumpida (por el servidor o por pérdida de conectividad). |
enum QWebEngineDownloadRequest::SavePageFormat
Este enum describe el formato que se utiliza para guardar una página web.
| Constante | Valor | Descripción |
|---|---|---|
QWebEngineDownloadRequest::UnknownSaveFormat | -1 | No se trata de una solicitud para descargar una página web completa. |
QWebEngineDownloadRequest::SingleHtmlSaveFormat | 0 | La página se guarda como una única página HTML. Los recursos como las imágenes no se guardan. |
QWebEngineDownloadRequest::CompleteHtmlSaveFormat | 1 | La página se guarda como una página HTML completa, por ejemplo, un directorio que contenga la página HTML única y los recursos. |
QWebEngineDownloadRequest::MimeHtmlSaveFormat | 2 | La página se guarda como una página web completa en formato HTML MIME. |
Documentación de propiedades
downloadDirectory : QString
Esta propiedad contiene la ruta del directorio de descarga.
La ruta del directorio de descarga sólo puede establecerse en respuesta a la señal QWebEngineProfile::downloadRequested() antes de que se acepte la descarga. Después de ese momento, esta propiedad no tiene ningún efecto sobre el estado del elemento de descarga.
Funciones de acceso:
| QString | downloadDirectory() const |
| void | setDownloadDirectory(const QString &directory) |
Señal de notificador:
| void | downloadDirectoryChanged() |
downloadFileName : QString
Esta propiedad contiene el nombre de archivo en el que se descargará el archivo.
El nombre del archivo de descarga sólo puede establecerse en respuesta a la señal QWebEngineProfile::downloadRequested() antes de que se acepte la descarga. Después de ese momento, esta propiedad no tiene ningún efecto sobre el estado del elemento de descarga.
Funciones de acceso:
| QString | downloadFileName() const |
| void | setDownloadFileName(const QString &fileName) |
Señal del notificador:
| void | downloadFileNameChanged() |
[read-only] id : const quint32
Esta propiedad contiene el ID del elemento de descarga.
Funciones de acceso:
| quint32 | id() const |
[read-only] interruptReason : DownloadInterruptReason
Esta propiedad contiene la razón por la que se interrumpió la descarga.
Funciones de acceso:
| QWebEngineDownloadRequest::DownloadInterruptReason | interruptReason() const |
Señal del notificador:
| void | interruptReasonChanged() |
Véase también interruptReasonString.
[read-only] interruptReasonString : QString
Esta propiedad contiene una descripción legible por humanos del motivo por el que se interrumpe la descarga.
Funciones de acceso:
| QString | interruptReasonString() const |
Señal del notificador:
| void | interruptReasonChanged() |
Véase también interruptReason.
[read-only] isFinished : bool
Esta propiedad indica si la descarga ha finalizado (completada, cancelada o en estado de interrupción no reanudable).
Funciones de acceso:
| bool | isFinished() const |
Señal del notificador:
| void | isFinishedChanged() |
Véase también state().
[read-only] isPaused : bool
Esta propiedad indica si la descarga está en pausa.
Funciones de acceso:
| bool | isPaused() const |
Notificador de señal:
| void | isPausedChanged() |
Véase también pause() y resume().
[read-only] isSavePageDownload : const bool
Esta propiedad indica si se trata de una solicitud de descarga para guardar una página web.
Funciones de acceso:
| bool | isSavePageDownload() const |
Véase también savePageFormat.
[read-only] mimeType : QString
Esta propiedad contiene el tipo MIME de la descarga.
Funciones de acceso:
| QString | mimeType() const |
[read-only] receivedBytes : qint64
Esta propiedad contiene la cantidad de datos en bytes que se han descargado hasta el momento.
-1 significa que el tamaño es desconocido.
Funciones de acceso:
| qint64 | receivedBytes() const |
Señal del notificador:
| void | receivedBytesChanged() |
savePageFormat : SavePageFormat
Esta propiedad contiene el formato en el que se guardará la página web si se trata de una solicitud de descarga de una página web.
Funciones de acceso:
| QWebEngineDownloadRequest::SavePageFormat | savePageFormat() const |
| void | setSavePageFormat(QWebEngineDownloadRequest::SavePageFormat format) |
Señal del notificador:
| void | savePageFormatChanged() |
Véase también isSavePageDownload.
[read-only] state : DownloadState
Esta propiedad contiene el estado actual del elemento de descarga.
Funciones de acceso:
| QWebEngineDownloadRequest::DownloadState | state() const |
Señal del notificador:
| void | stateChanged(QWebEngineDownloadRequest::DownloadState state) |
Véase también DownloadState.
[read-only] suggestedFileName : const QString
Esta propiedad contiene el nombre de archivo sugerido.
Funciones de acceso:
| QString | suggestedFileName() const |
[read-only] totalBytes : qint64
Esta propiedad contiene la cantidad total de datos a descargar en bytes.
-1 significa que el tamaño es desconocido.
Funciones de acceso:
| qint64 | totalBytes() const |
Señal del notificador:
| void | totalBytesChanged() |
[read-only] url : const QUrl
Esta propiedad contiene la URL de origen de la descarga.
Funciones de acceso:
| QUrl | url() const |
Documentación de las funciones miembro
[slot] void QWebEngineDownloadRequest::accept()
Acepta la solicitud de descarga actual, que iniciará la descarga.
Si el elemento está en el estado DownloadRequested, entonces pasará al estado DownloadInProgress y comenzará la descarga. Si el elemento se encuentra en cualquier otro estado, no ocurrirá nada.
Véase también isFinished y stateChanged().
[slot] void QWebEngineDownloadRequest::cancel()
Cancela la descarga en curso.
Si el elemento se encuentra en el estado DownloadInProgress, pasará al estado DownloadCancelled, se detendrá la descarga y se borrarán del disco los archivos parcialmente descargados.
Si el elemento se encuentra en el estado DownloadCompleted, no ocurrirá nada. Si el elemento se encuentra en cualquier otro estado, pasará al estado DownloadCancelled sin más consecuencias.
Véase también isFinished y stateChanged().
[signal] void QWebEngineDownloadRequest::isPausedChanged()
Esta señal se emite cada vez que cambia isPaused.
Nota: Señal notificadora para la propiedad isPaused.
Véase también pause() y isPaused.
QWebEnginePage *QWebEngineDownloadRequest::page() const
Devuelve la página en la que se solicitó la descarga. Si la descarga no fue provocada por el contenido de una página, se devuelve nullptr.
[slot] void QWebEngineDownloadRequest::pause()
Detiene la descarga.
No tiene efecto si el estado no es DownloadInProgress. No cambia el estado.
Véase también resume() y isPaused().
[slot] void QWebEngineDownloadRequest::resume()
Reanuda la descarga en curso si se ha pausado o interrumpido.
No tiene efecto si el estado no es DownloadInProgress o DownloadInterrupted. No cambia el estado.
Véase también pause(), isPaused() y state().
[signal] void QWebEngineDownloadRequest::stateChanged(QWebEngineDownloadRequest::DownloadState state)
Esta señal se emite cada vez que cambia la dirección state de la descarga.
Nota: Señal notificadora para la propiedad state.
Véase también state() y DownloadState.
© 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.
