QResource Class
QResource 类为直接读取资源提供了一个接口。更多
| 头文件： | #include <QResource> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake： | QT += core |
- 所有成员（包括继承成员）的列表
- QResource 是输入/输出和网络的一部分。
注意：该类中的所有函数都是可重入的。
公共类型
| enum | Compression { NoCompression, ZlibCompression, ZstdCompression } |
公共函数
| QResource(const QString &file = QString(), const QLocale &locale = QLocale()) | |
| ~QResource() | |
| QString | absoluteFilePath() const |
| QResource::Compression | compressionAlgorithm() const |
| const uchar * | data() const |
| QString | fileName() const |
| bool | isValid() const |
| QDateTime | lastModified() const |
| QLocale | locale() const |
| void | setFileName(const QString &file) |
| void | setLocale(const QLocale &locale) |
| qint64 | size() const |
| QByteArray | uncompressedData() const |
| qint64 | uncompressedSize() const |
静态公共成员
| bool | registerResource(const QString &rccFileName, const QString &mapRoot = QString()) |
| bool | registerResource(const uchar *rccData, const QString &mapRoot = QString()) |
| bool | unregisterResource(const QString &rccFileName, const QString &mapRoot = QString()) |
| bool | unregisterResource(const uchar *rccData, const QString &mapRoot = QString()) |
保护函数
详细说明
QResource 是一个对象，用于表示与单个资源实体相关的一组数据（可能还有子数据）。QResource 允许直接访问原始格式的字节。通过这种直接访问方式，读取数据时无需复制缓冲区或进行间接。当把资源实体当作文件与之交互时，间接访问通常很有用，这可以通过QFile 来实现。QResource 后面的数据和子资源通常编译到应用程序/库中，但也可以在运行时加载资源。在运行时加载资源文件时，资源文件将作为一个大数据集加载，然后通过资源树中的引用分块加载。
QResource 可以使用绝对路径加载，绝对路径可以被视为以/ 字符为根的文件系统，或者以: 字符为根的资源符号。也可以打开相对资源，该资源将在QDir::searchPaths() 返回的路径列表中找到。
代表文件的 QResource 将有数据作为其后盾，这些数据可能被压缩，在这种情况下，必须使用qUncompress() 来访问真实数据；通过QFile 访问时，这种情况会隐式发生。代表目录的 QResource 只有子目录，没有数据。
动态资源加载
通过使用registerResource() 函数，可以将资源从应用程序的二进制文件中分离出来，并在运行时需要时加载。传入registerResource() 的资源文件必须是由 rcc 创建的二进制资源。有关二进制资源的更多信息，请参阅Qt 资源系统文档。
在加载大量应用程序图标（这些图标可能会根据设置而改变，或可由用户编辑并在稍后重新创建）时，这通常非常有用。资源会立即加载到内存中，可以是单个文件读取操作的结果，也可以是内存映射文件。
事实证明，这种方法能显著提高性能，因为只需加载一个文件，数据片段将通过setFileName() 中请求的路径输出。
unregisterResource() 函数会删除对特定文件的引用。如果有 QResource 对象当前引用了与未注册文件相关的资源，它们将继续有效，但资源文件本身将从资源根中删除，因此无法再创建指向该资源数据的 QResource。当指向该资源的最后一个 QResource 被销毁时，资源本身将从内存中解除映射。
破坏和安全性
QResource 类会对传递的文件执行一些检查，以确定当前版本的 Qt 是否支持该文件。这些测试只是为了检查文件头是否请求了尚未编译的功能（如 Zstandard 解压缩），或者该文件是否属于未来版本的 Qt。它们并不确认整个文件的有效性。
QResource 不适用于来源不可信的文件。在设计应用程序时，应尽量只加载其来源至少与应用程序本身或其插件的来源同样可信的资源文件。
另请参阅 《Qt XML 资源系统》、QFile 、QDir 和QFileInfo 。
成员类型文档
enum QResource::Compression
compressionAlgorithm() 使用该枚举表示 RCC 工具使用哪种算法压缩有效载荷。
| 常量 | 值 | 说明 |
|---|---|---|
QResource::NoCompression | 0 | 内容未压缩 |
QResource::ZlibCompression | 1 | 内容使用zlib压缩，可使用qUncompress() 函数解压缩。 |
QResource::ZstdCompression | 2 | 内容使用zstd 压缩。要解压缩，请使用 zstd 库中的ZSTD_decompress 函数。 |
另请参阅 compressionAlgorithm().
成员函数文档
QResource::QResource(const QString &file = QString(), const QLocale &locale = QLocale())
构造一个指向file 的 QResource。locale 用于加载资源数据的特定本地化。
另请参阅 QFileInfo,QDir::searchPaths(),setFileName() 和setLocale() 。
[noexcept] QResource::~QResource()
释放QResource 对象的资源。
QString QResource::absoluteFilePath() const
返回QResource 所代表的真实路径，如果该资源是通过QDir::searchPaths() 找到的，路径中将标明。
另请参阅 fileName()。
[protected] QStringList QResource::children() const
返回该目录中所有资源的列表，如果资源代表文件，则列表为空。
另请参见 isDir()。
QResource::Compression QResource::compressionAlgorithm() const
返回该资源的压缩类型（如果有）。如果未压缩，则返回QResource::NoCompression 。
如果此函数返回QResource::ZlibCompression ，您可以使用qUncompress() 函数解压数据。在 Qt 5.13 之前，这是唯一可能的压缩算法。
如果此函数返回QResource::ZstdCompression ，则需要使用 Zstandard 库函数 (<zstd.h> header)。Qt 不提供封装器。
请参见Zstandard 手册。
const uchar *QResource::data() const
返回对该资源所代表的只读数据段的直接访问。如果资源是压缩的，返回的数据也是压缩的。调用者必须解压缩数据或使用uncompressedData() 。如果资源是目录，则返回nullptr 。
另请参阅 uncompressedData()、size() 和isFile()。
QString QResource::fileName() const
返回QResource 所代表文件的完整路径。
另请参阅 setFileName() 和absoluteFilePath()。
[protected] bool QResource::isDir() const
如果资源代表一个目录，因此其中可能包含children() ，则返回true ；如果代表一个文件，则返回 false。
另请参见 isFile()。
[protected] bool QResource::isFile() const
如果资源代表文件并因此有数据支持，则返回true ；如果代表目录，则返回 false。
另请参见 isDir().
bool QResource::isValid() const
如果资源确实存在于资源层次结构中，则返回true ，否则返回 false。
QDateTime QResource::lastModified() const
返回文件打包成资源前最后一次修改的日期和时间。
QLocale QResource::locale() const
返回用于定位QResource 数据的 locale。
另请参阅 setLocale()。
[static] bool QResource::registerResource(const QString &rccFileName, const QString &mapRoot = QString())
在mapRoot 指定的资源树位置用给定的rccFileName 注册资源，如果文件成功打开，则返回true ；否则返回false 。
另请参阅 unregisterResource() 。
[static] bool QResource::registerResource(const uchar *rccData, const QString &mapRoot = QString())
在mapRoot 指定的资源树位置用给定的rccData 注册资源，如果文件成功打开，则返回true ；否则返回false 。
警告： 数据必须在任何可能引用资源数据的QFile 的整个生命周期内保持有效。
另请参阅 unregisterResource() 。
void QResource::setFileName(const QString &file)
设置QResource ，使其指向file 。file 可以是绝对文件，在这种情况下将直接打开；如果是相对文件，则将尝试在QDir::searchPaths() 中找到该文件。
另请参阅 fileName() 和absoluteFilePath()。
void QResource::setLocale(const QLocale &locale)
将QResource 设置为只加载locale 的本地化资源。如果未找到特定语言版本的资源，则使用 C 语言版本。
另请参阅 locale() 和setFileName()。
qint64 QResource::size() const
返回支持资源的存储数据的大小。
如果资源已压缩，该函数将返回压缩数据的大小。有关未压缩的大小，请参见uncompressedSize() 。
另请参阅 data()、uncompressedSize() 和isFile()。
QByteArray QResource::uncompressedData() const
返回资源数据，如果数据是压缩存储的，则首先解压缩。如果资源是目录或解压时发生错误，则返回空QByteArray 。
注意： 如果数据是压缩的，则每次调用该函数都会解压缩。在两次调用之间不会缓存解压缩结果。
另请参阅 uncompressedSize()、size()、compressionAlgorithm() 和isFile()。
qint64 QResource::uncompressedSize() const
返回此资源中数据的大小。如果数据未压缩，则返回值与size() 相同。如果数据经过压缩，则该函数将从存储流中提取原始未压缩数据的大小。
另请参阅 size()、uncompressedData() 和isFile()。
[static] bool QResource::unregisterResource(const QString &rccFileName, const QString &mapRoot = QString())
在mapRoot 指定的资源树位置，用给定的rccFileName 取消注册资源，如果资源成功卸载且不存在引用，则返回true ；否则返回false 。
另请参阅 registerResource() 。
[static] bool QResource::unregisterResource(const uchar *rccData, const QString &mapRoot = QString())
在mapRoot 指定的资源树位置，用给定的rccData 取消注册资源，如果成功卸载资源且资源中不存在引用，则返回true ；否则返回false 。
另请参阅 registerResource() 。
© 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.
