QML自定义模块及qmldir的使用

news2025/1/20 1:43:25

前言

在开发QtQuick项目中，当项目文件很多的情况下，可能会分成多级文件夹来进行分类，还有一些通用类型文件，如公共组件，通用配置等等，需要在各个不同的文件中进行调用，这种情况下，一种方式是在当前需要引用的文件中通过关键字import 加上相对路径，从而找到通用文件目录。另一种方式就是将通用文件目录设置成qml模块形式，通过import直接引入模块名称就可以直接调用相关qml了，这样的好处是在任何不同的目录中都可以随处导入模块，而不用考虑相对路径的问题。

这里要介绍的就是如何在qml项目中定义模块，针对大型项目中使用尤其方便。

正文

首先，模块的使用需要一个qmldir文件，这是一个纯文本文件（没有后缀），用来定义qml模块

文件格式：

module 模块名称       #声明模块的模块标识符，必须与模块的安装路径匹配，必须是文件的第一行
#依次为类型名称 | 类型的模块版本 | QML文件名（这里还有可选参数[singleton]用于声明单例类型）
singleton  模块  版本  qml文件
 
比如：
module Component   #声明模块的模块标识符
singleton Config 1.0 Config.qml
CusButton 1.0 CusButton.qml
...

注意：这里可以通过singleton来声明是否为单例类型，QML中的单例通常用在通用配置文件中。

下面来看示例：
创建一个演示demo
在这里插入图片描述
为方便演示，这里特意创建了多级文件夹，Component目录是我们设置的模块，包含的是一些自定义控件封装，以及通用配置文件，在模块目录中添加一个qmldir文件，qmldir内容如下：

module Component
singleton Config 1.0 Config.qml
CusButton 1.0 CusButton.qml
CusText 1.0 CusText.qml

接下来重要步骤，在pro文件中添加

# Additional import path used to resolve QML modules in Qt Creator's code model
QML_IMPORT_PATH = $$PWD/

注意 这里的路径要指到模块文件夹的上一级目录，由于演示demo的模块文件夹Component和工程文件pro是同一个目录，所以这里QML_IMPORT_PATH 就设置路径为当前路径即可。

然后在main文件中，找到engin定义的地方，添加设置addImportPath

engine.addImportPath("qrc:/");

这里qrc路径同样是要指到模块文件夹的上一级目录。

ok，接下来看看如何使用：
在任意目录的文件中如果需要引用模块内的文件，可以直接导入模块名 import Component 1.0：

import QtQuick 2.0
import Component 1.0

Rectangle {

    color: Config.subClr

    CusButton{
        //...
    }
}

由于Config文件设置的是单例，所以可以直接通过文件名来引用其中的属性，如：Config.subClr

Config文件内容如下，单例设置需要在文件最前面添加 pragma Singleton来进行声明：

pragma Singleton

import QtQuick 2.13
import QtQml 2.13

QtObject {

    readonly property color mainClr: "#AAAAAA"
    readonly property color subClr: "#666666"
    //....
}