QNetworkDiskCache Class
QNetworkDiskCache 类提供了一个非常基础的磁盘缓存。更多内容...
| 头文件： | #include <QNetworkDiskCache> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Network) target_link_libraries(mytarget PRIVATE Qt6::Network) |
| qmake： | QT += network |
| 继承自： | QAbstractNetworkCache |
公共函数
| QNetworkDiskCache(QObject *parent = nullptr) | |
| virtual | ~QNetworkDiskCache() |
| QString | cacheDirectory() const |
| QNetworkCacheMetaData | fileMetaData(const QString &fileName) const |
| qint64 | maximumCacheSize() const |
| void | setCacheDirectory(const QString &cacheDir) |
| void | setMaximumCacheSize(qint64 size) |
重新实现的公共函数
| virtual qint64 | cacheSize() const override |
| virtual QIODevice * | data(const QUrl &url) override |
| virtual void | insert(QIODevice *device) override |
| virtual QNetworkCacheMetaData | metaData(const QUrl &url) override |
| virtual QIODevice * | prepare(const QNetworkCacheMetaData &metaData) override |
| virtual bool | remove(const QUrl &url) override |
| virtual void | updateMetaData(const QNetworkCacheMetaData &metaData) override |
公共槽
| virtual void | clear() override |
受保护函数
| virtual qint64 | expire() |
详细说明
QNetworkDiskCache 使用 `QDataStream` 将每个 URL 存储在 `cacheDirectory ` 中的独立文件中。MIME 类型为文本的文件将通过 `qCompress` 进行压缩。数据仅在调用 `insert()` 和 `updateMetaData()` 时写入磁盘。
目前，您无法让多个磁盘缓存共享相同的缓存文件。
QNetworkDiskCache 默认将缓存占用的系统空间限制为 50MB。
请注意，必须先设置缓存目录，该功能才能生效。
可通过以下方式启用网络磁盘缓存：
QNetworkAccessManager *manager = new QNetworkAccessManager(this);
QNetworkDiskCache *diskCache = new QNetworkDiskCache(this);
QString directory = QStandardPaths::writableLocation(QStandardPaths::CacheLocation)
+ QLatin1StringView("/cacheDir/");
diskCache->setCacheDirectory(directory);
manager->setCache(diskCache);在发送请求时，若要控制何时使用缓存、何时使用网络，请考虑以下几点：
using namespace Qt::StringLiterals;
// do a normal request (preferred from network, as this is the default)
QNetworkRequest request(QUrl(u"http://qt-project.org"_s));
manager->get(request);
// do a request preferred from cache
QNetworkRequest request2(QUrl(u"http://qt-project.org"_s));
request2.setAttribute(QNetworkRequest::CacheLoadControlAttribute, QNetworkRequest::PreferCache);
manager->get(request2);要检查响应是来自缓存还是来自网络，可采用以下方法：
voidreplyFinished(QNetworkReply*reply) {
QVariant fromCache= reply->attribute(QNetworkRequest::SourceIsFromCacheAttribute);
qDebug() << "page from cache?" << fromCache.toBool();
}安全注意事项
QNetworkDiskCache 将 HTTP 响应正文和元数据（包括响应头）以未加密的形式存储到磁盘上。对文本内容进行的压缩仅用于提高存储效率，并不提供保密性保护。
哪些响应会被缓存，主要取决于服务器发送的 HTTP 缓存控制头。配置得当的服务器通常会阻止缓存来自经过身份验证会话且包含敏感数据的响应。但是，应用程序不能指望每个服务器都能正确执行此操作，而且服务器认为不敏感的内容可能与应用程序自身的要求不符。
对于服务器缓存策略不足的情况：
- 对于不应存储响应的请求，请将 `QNetworkRequest::CacheSaveControlAttribute ` 设置为 `
false`。 - 继承 `QAbstractNetworkCache ` 类，以实现针对哪些响应应被缓存的应用程序特定过滤。
缓存条目虽经过基本结构验证，但可能因磁盘损坏、应用程序异常关闭或其他原因而失效。应用程序在未进行独立验证的情况下，不应将缓存数据视为可信数据。
成员函数文档
[explicit] QNetworkDiskCache::QNetworkDiskCache(QObject *parent = nullptr)
创建一个新的磁盘缓存。参数parent 将传递给QAbstractNetworkCache 的构造函数。
[virtual noexcept] QNetworkDiskCache::~QNetworkDiskCache()
销毁缓存对象。这不会清除磁盘缓存。
QString QNetworkDiskCache::cacheDirectory() const
返回缓存文件的存储位置。
另请参阅 ` setCacheDirectory()`。
[override virtual] qint64 QNetworkDiskCache::cacheSize() const
重新实现了：QAbstractNetworkCache::cacheSize() const。
[override virtual slot] void QNetworkDiskCache::clear()
重写了：QAbstractNetworkCache::clear()。
[override virtual] QIODevice *QNetworkDiskCache::data(const QUrl &url)
重写了：QAbstractNetworkCache::data(const QUrl &url)。
[virtual protected] qint64 QNetworkDiskCache::expire()
清理缓存，使其大小低于最大缓存大小。返回缓存的当前大小。
当缓存的当前大小大于maximumCacheSize()返回的值时，将删除较旧的缓存文件，直到总大小小于maximumCacheSize()返回值的90%。删除时从最旧的文件开始，并根据文件创建日期来确定缓存文件的存留时间。
子类可以重写此函数，以根据应用程序所知而QNetworkDiskCache 所不知的信息（例如缓存被访问的次数）来更改缓存文件的删除顺序。
注意： 如果当前缓存大小未知，cacheSize() 会调用 expire。
另请参阅 maximumCacheSize() 和fileMetaData()。
QNetworkCacheMetaData QNetworkDiskCache::fileMetaData(const QString &fileName) const
返回缓存文件fileName 的QNetworkCacheMetaData 。
如果 `fileName ` 不是缓存文件，则 `QNetworkCacheMetaData ` 将无效。
[override virtual] void QNetworkDiskCache::insert(QIODevice *device)
重写了：QAbstractNetworkCache::insert(QIODevice *device)。
qint64 QNetworkDiskCache::maximumCacheSize() const
返回磁盘缓存的当前最大大小。
另请参阅 setMaximumCacheSize()。
[override virtual] QNetworkCacheMetaData QNetworkDiskCache::metaData(const QUrl &url)
重写了：QAbstractNetworkCache::metaData(const QUrl &url)。
[override virtual] QIODevice *QNetworkDiskCache::prepare(const QNetworkCacheMetaData &metaData)
重写了：QAbstractNetworkCache::prepare(const QNetworkCacheMetaData &metaData)。
[override virtual] bool QNetworkDiskCache::remove(const QUrl &url)
重写了：QAbstractNetworkCache::remove(const QUrl &url)。
void QNetworkDiskCache::setCacheDirectory(const QString &cacheDir)
将缓存文件的存储目录设置为cacheDir
QNetworkDiskCache 如果该目录不存在，则会创建该目录。
已准备好的缓存项在插入时将存储在新缓存目录中。
另请参阅 cacheDirectory() 和QStandardPaths::CacheLocation 。
void QNetworkDiskCache::setMaximumCacheSize(qint64 size)
将磁盘缓存的最大大小设置为size 。
如果新大小小于当前缓存大小，则缓存将调用expire() 函数。
另请参阅 maximumCacheSize()。
[override virtual] void QNetworkDiskCache::updateMetaData(const QNetworkCacheMetaData &metaData)
重写了：QAbstractNetworkCache::updateMetaData(const QNetworkCacheMetaData &metaData)。
© 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.
