如何从QRC资源文件中正确导入QML文件？

问题背景 #

开发小型应用时，从QRC资源文件导入QML组件遇到困难：资源文件已被正确加载（QFileInfo(":/qml/ProductionPane").exists()返回true），但QML导入语句运行时报错，且QT Creator需要本地路径导入才能识别组件。

QRC配置 #

<RCC>
    <qresource prefix="/qml">
        <file alias="ProductionPane">qml/view/ProductionPane.qml</file>
        <file alias="SideBar">qml/view/SideBar.qml</file>
        <file alias="TestingView">qml/view/TestingView.qml</file>
        <file alias="LogView">qml/view/LogView.qml</file>
        <file alias="StatsView">qml/view/StatsView.qml</file>
        <file alias="MyButton">qml/comp/MyButton.qml</file>
    </qresource>
    <qresource prefix="/assets">
        <file alias="Logo">assets/img/logo.png</file>
    </qresource>
    <qresource prefix="/">
        <file>main.qml</file>
    </qresource>
</RCC>

文件物理结构 #

main.qml
main.py
rc_resources.py

qml/view/LogView.qml
qml/view/ProductionPane.qml
qml/view/SideBar.qml
qml/view/StatsView.qml
qml/view/TestingView.qml

qml/comp/MyButton.qml

assets/img/logo.png

main.py代码 #

import sys
from pathlib import Path

from PySide6.QtGui import QGuiApplication
from PySide6.QtQml import QQmlApplicationEngine
from PySide6.QtCore import QUrl

import rc_resources

if __name__ == "__main__":
    app = QGuiApplication(sys.argv)
    engine = QQmlApplicationEngine()
    
    engine.addImportPath("qrc:/view")

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

    if not engine.rootObjects():
        sys.exit(-1)
    sys.exit(app.exec())

main.qml代码 #

import QtQuick
import QtQuick.Window
import QtQuick.Controls

import "qrc:/qml/ProductionPane"
import "qml/view"

Window {
    id: mainWindow
    minimumWidth: 1024
    minimumHeight: 768
    width: 1920
    height: 1080
    title: qsTr("FooBar")

    ProductionPane {
        id: productionPane
        anchors.fill: parent
    }

    SideBar {
        onViewChanged: productionPane.loaderSource = view
    }
}

错误现象 #

• 运行时执行import "qrc:/qml/ProductionPane"会报错：qrc:/main.qml:4:1: "qrc:/qml/ProductionPane": no such directory
• 使用import ":/qml/ProductionPane"时，QT Creator提示File or directory not found.
• 必须添加import "qml/view"本地路径导入，QT Creator才能识别组件，但这不符合资源文件的使用预期

解决建议 #

1. 调整QRC资源的组织方式 #

QML的import语句指向的是目录而非单个文件，当前QRC中给单个文件设置别名的方式，仅适用于直接加载文件（如Loader组件），无法用于导入。修改QRC，保留原目录结构，去掉单个文件的别名：

<RCC>
    <qresource prefix="/qml">
        <!-- 保留原文件路径，不设置alias -->
        <file>qml/view/ProductionPane.qml</file>
        <file>qml/view/SideBar.qml</file>
        <file>qml/view/TestingView.qml</file>
        <file>qml/view/LogView.qml</file>
        <file>qml/view/StatsView.qml</file>
        <file>qml/comp/MyButton.qml</file>
    </qresource>
    <qresource prefix="/assets">
        <file alias="Logo">assets/img/logo.png</file>
    </qresource>
    <qresource prefix="/">
        <file>main.qml</file>
    </qresource>
</RCC>

如果使用Qt 5.14+，可以用通配符简化配置：<file>qml/view/*.qml</file>和<file>qml/comp/*.qml</file>

2. 修正main.py中的导入路径 #

将添加的导入路径改为QRC中qml前缀对应的路径：

engine.addImportPath("qrc:/qml")

3. 修正main.qml的导入语句 #

导入QRC中的目录，而非单个文件：

import QtQuick
import QtQuick.Window
import QtQuick.Controls

// 导入QRC中的view目录
import "qrc:/qml/view"
// 若需要导入comp目录，添加：import "qrc:/qml/comp"

Window {
    id: mainWindow
    minimumWidth: 1024
    minimumHeight: 768
    width: 1920
    height: 1080
    title: qsTr("FooBar")

    ProductionPane {
        id: productionPane
        anchors.fill: parent
    }

    SideBar {
        onViewChanged: productionPane.loaderSource = view
    }
}

4. 解决QT Creator的识别问题 #

• 确保QRC文件已添加到Qt Creator项目中，在项目视图中能看到rc_resources.qrc
• 执行菜单Build > Run qmake，然后Build > Rebuild Project，刷新Qt Creator的索引
• 若仍有识别问题，可以在项目设置中，将qml目录添加为QML导入路径（Settings > Projects > QML/JS > Import Paths）

内容的提问来源于stack exchange，提问作者shortnr