Qt 资源系统

Qt 资源系统是一种用于在应用程序中分发资源文件的跨平台机制。如果您的应用程序始终需要一组特定的文件（如图标、翻译文件、图像），且您不希望使用特定于系统的手段来打包和定位这些资源，请使用该系统。

最常见的情况是，资源文件被嵌入到应用程序的可执行文件中，或者嵌入到由应用程序可执行文件加载的库和插件中。此外，资源文件也可以存储在外部资源文件中。

该资源系统基于 Qt 的 Resource Compiler、构建系统以及 Qt 运行时 API 之间的紧密协作。

Qt XML资源编译器（Resource Compiler ，rcc）

Resource Compiler （rcc）命令行工具用于读取资源文件，并生成 C++ 或 Python 源文件，或者生成.rcc 文件。

文件列表及相关元数据将以Qt 资源集合文件的形式传递给rcc 。

默认情况下，rcc 将生成 C++ 源代码，该源代码随后将作为可执行文件或库的一部分进行编译。-g python 选项则生成 Python 源代码。-binary 选项生成一个二进制存档，按照惯例，该存档将保存为.rcc 文件，并可在运行时加载。

Qt 资源集合文件 (.qrc)

.qrc 文件是一个 XML 文档，用于列举要作为运行时资源包含的本地文件。它作为rcc 的输入。

以下是一个.qrc 文件的示例：

<RCC>
    <qresource prefix="/">
        <file>images/copy.png</file>
        <file>images/cut.png</file>
        <file>images/new.png</file>
        <file>images/open.png</file>
        <file>images/paste.png</file>
        <file>images/save.png</file>
    </qresource>
</RCC>

XML 中的每个<file> 元素都标识应用程序源代码树中的一个文件。路径是相对于包含.qrc 文件的目录来解析的。

该路径在运行时也会被默认用于标识文件的内容。也就是说，文件copy.png 在资源系统中将作为:/images/copy.png 或qrc:/images/copy.png 提供。若要覆盖此默认运行时名称，请参阅“前缀 和别名”。

Qt Creator, Qt Design Studio, Qt Widgets Designer, Qt Extension for Visual Studio Code，以及 Qt Visual Studio Tools 允许您通过便捷的用户界面创建、查看和编辑.qrc 文件。除Qt Widgets Designer 外，它们还为使用Qt资源系统的项目提供了向导。

构建系统集成

使用rcc 处理资源文件通常在应用程序构建时进行。一些构建工具对此提供了专门的支持，包括CMake和 qmake。

CMake

如果启用了CMAKE_AUTORCC ，您只需将.qrc 文件作为源文件添加到可执行文件或库中。被引用的资源文件随后将被嵌入到二进制文件中：

set(CMAKE_AUTORCC ON)

qt_add_executable(my_app
    application.qrc
    main.cpp
)

有关 AUTORCC 的更多详细信息，请参阅CMake 的 AUTORCC 文档。

AUTORCC 的另一种替代方案是使用 Qt6Core 的 CMake 函数qt_add_resources，它能让您对资源的创建拥有更大的控制权。例如，它允许您直接在项目文件中指定资源的内容，而无需事先编写.qrc 文件：

qt_add_resources(my_app "app_images"
    PREFIX "/"
    FILES
        images/copy.png
        images/cut.png
        images/new.png
        images/open.png
        images/paste.png
        images/save.png
)

最后，qt_add_qml_module允许您将 `Qt Quick ` 资源嵌入到应用程序的资源系统中。该函数定义在Qt6 CMake 包的Qml 组件中。

qmake

qmake支持通过RESOURCES变量处理资源。如果您将.qrc 文件路径添加到该变量中，列出的资源文件将被嵌入到生成的库或可执行文件中：

RESOURCES = application.qrc

对于简单的应用程序，还可以让 qmake 为您自动生成 `.qrc ` 文件，从而无需维护额外的文件：

resources.files = \
    images/copy.png \
    images/cut.png \
    images/new.png \
    images/open.png \
    images/paste.png \
    images/save.png
resources.prefix = /

RESOURCES = resources

这会生成多个.png 文件，可通过以下方式访问：":/images/copy.png" 。

如果要嵌入到资源中的文件的目录结构与应用程序的预期不符，您可以指定 `resources.base`。`base ` 是一个路径前缀，表示文件别名的根点。在下面的示例中，如果将 `resources.base ` 设置为 `"images"`，那么 `copy.png ` 即可通过 `":/copy.png"` 进行访问。

运行时 API

处理文件遍历和读取的 Qt API 内置了对 Qt 资源系统的支持。您可以向QFile 和QDir 传递资源路径而非本地文件路径，也可以将其传递给QIcon 、QImage 和QPixmap 的构造函数：

    cutAct = new QAction(QIcon(":/images/cut.png"), tr("Cu&t"), this);

: 前缀明确表示“/images/cut.png”应从 Qt 资源系统中加载。

您还可以通过QUrl 引用 Qt 资源系统。此时请使用qrc 方案：

    QQmlApplicationEngine engine;
    engine.load(QUrl("qrc:/myapp/main.qml"));

高级主题

前缀

.qrc 文件可以通过<file> 元素设置一个前缀，该前缀将添加到每个本地文件名中，以此确定该文件在资源系统中的名称。

前缀可帮助您对资源进行结构化管理，从而避免不同库或插件中通过不同.qrc 文件添加的资源文件之间发生冲突。

别名

有时，在运行时将资源文件置于不同的路径下会比较方便。.qrc 文件通过设置alias 属性来实现这一点：

<file alias="cut-img.png">images/cut.png</file>

此时，该文件在应用程序中仅可通过:/cut-img.png 或qrc:/cut-img.png 访问。

丢弃文件内容

有时您希望向资源文件系统添加一个文件节点，但实际上并不希望添加文件内容。.qrc 文件通过将empty 属性设置为true 来实现这一点。

<file empty="true">Button.qml</file>

这样生成的文件仍可从应用程序中访问，但其内容为空。

这对于从应用程序二进制文件中移除 QML 源代码非常有用。

语言选择器

某些资源需要根据用户的区域设置进行调整，例如翻译文件或图标。资源集合文件通过qresource 标签中的lang 属性来支持此功能，该属性用于指定合适的区域设置字符串。例如：

<qresource>
    <file>cut.jpg</file>
</qresource>
<qresource lang="fr">
    <file alias="cut.jpg">cut_fr.jpg</file>
</qresource>

如果用户的区域设置为法语（即QLocale::system().language() 为法语），则:/cut.jpg 或qrc:/cut.jpg 将指向cut_fr.jpg 图片。对于其他区域设置，则使用cut.jpg 。

有关区域设置字符串的格式说明，请参阅QLocale 文档。

有关选择特定语言环境资源的额外机制，请参阅QFileSelector 。

嵌入大文件

默认情况下，rcc 会以 C++ 数组的形式将资源文件嵌入可执行文件中。这可能会带来问题，特别是对于大型资源而言。

如果编译器耗时过长，甚至因内存溢出而失败，您可以选择一种特殊模式，将资源作为两步过程的一部分进行嵌入。 C++ 编译器仅会在目标可执行文件或库中为资源预留足够的空间。资源文件的内容和元数据的实际嵌入，将在编译和链接阶段之后，通过另一次 rcc 调用完成。

对于 qmake，可通过在 `CONFIG ` 变量中添加 `resources_big ` 来启用此功能：

CONFIG += resources_big

对于 CMake，您需要使用qt_add_big_resources函数。

外部资源文件

除了将资源文件嵌入二进制文件外，另一种方法是将其存储在单独的.rcc 文件中。rcc 支持通过-binary 选项实现这一点。此类.rcc 文件必须在运行时通过QResource 进行加载。

例如，.qrc 文件中指定的一组资源数据可以按以下方式进行编译：

rcc -binary myresource.qrc -o myresource.rcc

在应用程序中，可通过如下代码注册该资源：

QResource::registerResource("/path/to/myresource.rcc");

如果使用 CMake，可以使用qt_add_binary_resources函数来安排上述rcc 的调用：

qt_add_binary_resources(resources application.qrc DESTINATION application.rcc)
add_dependencies(my_app resources)

Qt for Python 应用程序中的资源

资源集合文件通过 Resource Compiler 转换为 Python 模块：

rcc -g python mainwindow.qrc > mainwindow_rc.py

随后可在应用程序中导入该模块：

import mainwindow_rc.py

压缩

rcc 会尝试对内容进行压缩，以优化最终二进制文件中磁盘空间的使用。默认情况下，它会执行一次启发式检查来判断压缩是否值得，如果无法实现足够的压缩效果，则会以未压缩形式存储内容。 要控制该阈值，可以使用-threshold 选项，该选项会告知rcc ：必须节省原始文件大小的多少百分比，才会以压缩形式存储该文件。

rcc -threshold 25 myresources.qrc

默认值为“70”，表示压缩后的文件大小必须比原始文件小 70%（即不超过原始文件大小的 30%）。

如果需要，可以关闭压缩功能。当您的资源已采用压缩格式（例如.png 文件），且您不希望在构建时消耗 CPU 资源来确认其无法被压缩时，此功能会非常有用。 另一个原因是，如果磁盘空间不是问题，且应用程序希望在运行时将内容保留为干净的内存页。您可以通过提供-no-compress 命令行参数来实现这一点。

rcc -no-compress myresources.qrc

rcc 该命令还允许您控制压缩级别和压缩算法，例如：

rcc -compress 2 -compress-algo zlib myresources.qrc

还可以在 .qrc 文件中的file 标签中使用compress 和threshold 作为属性。若要选择算法，请设置compression-algorithm 属性。

<qresource>
    <file compress="1" compression-algorithm="zstd">data.txt</file>
</qresource>

上述设置将选择压缩级别为 1 的zstd 算法。

rcc 支持以下压缩算法和压缩级别：

• best：使用以下算法中最佳的一种，并采用其最高压缩级别，以实现最大压缩率，但代价是在编译过程中消耗大量 CPU 时间。在 XML 文件中使用此值可指示应将文件压缩到最大程度，无论rcc 支持哪些算法。
• zstd: 使用Zstandard库对内容进行压缩。有效的压缩级别范围为 1 到 19，其中 1 表示压缩率最低（CPU 时间最少），19 表示压缩率最高（CPU 时间最多）。默认级别为 14。特殊值 0 指示zstd 库选择由实现定义的默认值。
• zlib: 使用zlib库对内容进行压缩。有效的压缩级别范围为 1 到 9，其中 1 表示压缩程度最低（CPU 时间最少），9 表示压缩程度最高（CPU 时间最多）。 特殊值 0 表示“不压缩”，不应使用。默认值由实现定义，但通常为级别 6。
• none: 不进行压缩。这与-no-compress 选项的效果相同。

对 Zstandard 和 zlib 的支持均为可选。如果在编译时未检测到特定库，则尝试为该库传递-compress-algo 选项将导致错误。默认压缩算法为：若已启用，则为zstd ；若未启用，则为zlib 。

嵌入式资源的显式加载和卸载

嵌入在 C++ 可执行文件或库代码中的资源，会在内部全局变量的构造函数中自动注册到 Qt 资源系统中。由于全局变量在 main() 执行之前就被初始化，因此程序开始运行时这些资源即可使用。

在将资源嵌入静态库时，C++ 链接器可能会移除用于注册资源的静态变量。因此，若将资源嵌入静态库，则需要通过调用 `Q_INIT_RESOURCE()` 并传入 `.qrc ` 文件的基名，来显式注册资源。例如：

MyClass::MyClass() : BaseClass()
{
    Q_INIT_RESOURCE(resources);

    QFile file(":/myfile.dat");
    //...
}

您还可以显式地从应用程序中移除已注册的资源，例如在卸载插件时。为此请使用Q_CLEANUP_RESOURCE()。

注意：由于 rcc 生成的资源初始化程序声明在全局命名空间中，因此调用Q_INIT_RESOURCE() 和Q_CLEANUP_RESOURCE() 时，必须在任何命名空间之外进行。