開篇

在《如何導入QML文檔目錄》一文中，描述了如何導入QML目錄。對于應用程序內組件集來說，在實際開發中，導入本地QML目錄非常方便。但是如果模塊目錄移動到了另一個位置，那么所有與導入此模塊的代碼（與導入相關的語句）都必須更新，這將是一個非常麻煩且糟糕的事情。本文將繼續該文中留下的話題：如何以模塊的方式導入。

使用QML模塊的優點如下：

（1）在一個項目中可以共享公共的QML類型。

（2）可用于發布基于QML的庫。

（3）可以模塊化開發，使應用程序只加載各自需要的庫。

（4）可以對QML類型和資源進行版本控制，這樣可以很容易的更新模塊。

從0到1

創建一個工程

首先使用QtCreator創建一個工程，這里命名為：CusModule，工程目錄結構如下圖所示：

上圖中，有一個描述qml應用的main.qml文件，還有一個main.cpp文件用于描述一個Qt應用，并創建QGuiApplication應用和QQmlApplicationEngineqml解析引擎。

創建模塊

假如我們需要創建一個模塊，將該模塊命名為CusComponent，該模塊里包含一組qml文件：MyRect10.qml、MyRect20.qml、MyText10.qml、MyRect30.qml文件。

在文件中分別寫上以下簡單的代碼：

//MyRect10.qml
importQtQuick2.0

Rectangle{
height:50
width:50
color:"blue"
}

//MyRect20.qml
importQtQuick2.0

Rectangle{
height:50
width:50
color:"red"
}

//MyRect30.qml
importQtQuick2.0

Rectangle{
height:50
width:50
color:"black"
}

//MyText10.qml
importQtQuick2.0
importQtQuick.Controls1.4

Label{
text:qsTr("iriczhao|自定義QML模塊");
}

接著在CusComponent目錄下添加一個qmldir文件，注意該文件名只能是qmldir，在該文件中放入以下代碼：

moduleCusComponent
CusMyRect1.0MyRect10.qml
CusMyText1.0MyText10.qml
CusMyRect2.0MyRect20.qml
CusMyRect3.0MyRect30.qml

qmldir文件是一個純文本文件，該文件內容由命令組成，用于描述組成該模塊的文件和'資源。語法如下（此處只列出兩條命令）：

module

該命令用于聲明模塊的模塊標識符，是模塊的標識符，它必須與模塊的安裝路徑匹配。模塊標識符指令必須位于qml文件的第一行。

[singleton]

該命令用于聲明模塊可用的QML對象類型。

『singleton』用于聲明單列類型，該參數可選。

『TypeName』可用的類型名稱。

『InitialVersion』可用類型對應的模塊版本。

『File』是定義類型的QML文件的(相對)文件名。

qmldir文件中可以存在零個或多個對象類型聲明，但是每個對象類型在模塊的特定版本中必須有一個唯一的類型名稱。

完成后目錄結構如下：

在QtCreator中的目錄結構如下圖所示：

注，qmldir文件也要添加到資源管理中。

導入模塊

在main.qml文件中使用import語言導入模塊，語法如下：

import模塊名版本號

本文則使用import CusComponent 1.0導入，然后我們設計一個簡單的界面顯示，完整代碼如下：

importQtQuick2.15
importQtQuick.Window2.15
importQtQuick.Controls2.15

importCusComponent1.0

Window{
width:640
height:480
visible:true
color:"#89c3f6"
title:qsTr("HelloWorld")

//MyRect10.qml
CusMyRect{}

//MyText10.qml
CusMyText{
x:200
y:10
}
}

這時候，在QtCreator代碼編輯器中，我們可以看見幾個錯誤的地方：

接著，我們運行一下程序，將會報錯：module "CusComponent" is not installed

出現這三個問題的原因提示已經很明顯啦：那就是模塊沒有安裝，接下來讓我們來安裝模塊啦。

安裝模塊

當我們的模塊設計好后，需要安裝。安裝的本質就是將QML的解析路徑告訴QtCreator和QML解析引擎。

（1）將QML的解析路徑告訴QML解析引擎 這一點，使用qputenv(模塊路徑)或addImportPath(模塊路徑)函數實現，在本文中，如果使用qputenv，則需要在main()函數的開始處添加如下代碼：

qputenv("QML2_IMPORT_PATH",":/");

如果使用addImportPath()，則需要在QML解析引擎下添加如下代碼：

注，上述路徑是相對于資源系統的，

我們可以使用QQmlApplicationEngine的importPathList()函數查看當前QML解析引擎導入的路徑都包含了哪些，是否包含了我們需要的模塊路徑。

好啦，至此，我們已經將QML的解析路徑告訴了QML解析引擎。這時候，應用軟件是可以啟動運行了，如下圖所示：

但是，QtCreator代碼編輯器中的問題依然存在：QML module not found(CusComponent)和對象類型不高亮顯示。這時候，還需要我們將QML的解析路徑告訴QtCreator：在.pro工程描述文件中，添加如下代碼：

即可解決。

注意：路徑與在QML的解析路徑告訴QML解析引擎時設置的路徑相同

備注

（1）在設置導入模塊路徑時需要注意路徑的寫法，例如，如果本例寫成/CusComponet是無法正確安裝模塊的。這一點，我們可以理解成：QML模塊是需要一個模塊名的，在寫模塊導入路徑時，寫到模塊名上一級目錄就可以了，不能寫到模塊名，本文模塊名則是：CusComponet。

（2）編寫模塊描述文件qmldir時，是可以指定qml組件類型的版本號的，這一點則是創建QML模塊的一個重要優點，例如，如果將本文的模塊導入語句改成：import CusComponent 2.0，就會報：CusMyText is not a type信息了且應用無法啟動運行。（模塊的版本控制將在后續文章中寫到啦）

（3）在QtCreator中，如果導入語句語法和用法都正常，且能正常啟動運行qml程序，但是在代碼編輯器中依然會報：QT Unknown component（M300）錯誤。

這是因為QtCreator的代碼模型沒有重置更新。可按照下列步驟解決：

依次點擊：工具 --> QML/JS --> 重置代碼模型，重置更新一下代碼模型即可解決。

審核編輯：劉清