已识别模块

已识别模块是安装并可通过点分隔的标识符字符串的 URI 识别给 QML 引擎的模块。该字符串应当由模块在其 qmldir 文件中指定。这允许这样的模块使用一个唯一标识符进行导入，无论该模块在本地文件系统中的位置如何，该标识符都保持不变。

导入已识别模块时，使用未引号的标识符，带可选的版本号码

import QtQuick
import com.nokia.qml.mymodule 1.0

为了被 QML 引擎找到，已识别模块必须安装到导入路径中。

语法上，URI 的每个点分隔部分必须是一个格式良好的 ECMAScript 标识符名称。这意味着，例如，部分不能以数字开头，并且它们不能包含 - (减号) 字符。因为 URI 将被转换为目录名称，所以您应该将其限制为拉丁字母表中的字母数字字符、下划线和点。

本地安装的已识别模块

如果包含具有模块元数据的 qmldir 文件并安装到 QML 导入路径中，则 QML 和/或 C++ 文件的目录可以作为一个已识别模块共享。本地文件系统上的任何 QML 文件都可以通过使用引用模块 URI 的导入语句来将该目录作为模块导入，从而使文件能够使用模块定义的 QML 对象类型和 JavaScript 资源。

模块的 qmldir 文件必须位于导入路径内的目录结构中，该结构反映了 URI 点分隔的标识符字符串，其中每个点 (".") 在标识符中反映了目录树中的子级别。例如，模块 com.mycompany.mymodule 的 qmldir 文件必须位于导入路径内的子路径 com/mycompany/mymodule/qmldir 中的某个地方。

可以在模块自己的子目录中存储模块的不同版本。例如，模块的一个 2.1 版本可以位于 com/mycompany/mymodule.2/qmldir 或 com/mycompany/mymodule.2.1/qmldir 之下。引擎将自动加载与最匹配的模块。

或者在 qmldir 文件内部定义不同类型的版本，但是这可能会使更新此类模块变得困难（因为 qmldir 文文的合并必须在更新过程的一部分中进行）。

示例

考虑以下 QML 项目的目录结构。在顶层目录 myapp 之下，有一个名为 mycomponents 的子目录，其中包含一组公共 UI 组件，以及一个名为 main 的子目录，其中包含主应用程序代码，如下所示

myapp
    |- mycomponents
        |- CheckBox.qml
        |- DialogBox.qml
        |- Slider.qml
    |- main
        |- application.qml

要将 mycomponents 目录作为已识别模块提供，该目录必须包含一个 qmldir 文件，该文件定义了模块标识符，并描述了模块提供的对象类型。例如，为了使其 CheckBox、DialogBox 和 Slider 类型在模块的 1.0 版本中可用，该 qmldir 文件将包含以下内容

module myapp.mycomponents
CheckBox 1.0 CheckBox.qml
DialogBox 1.0 DialogBox.qml
Slider 1.0 Slider.qml

此外，qmldir 文件的导入路径中的位置必须与模块的虚点标识符字符串匹配。例如，如果顶级 myapp 目录位于 C:\qml\projects，并且模块应被标识为 "myapp.mycomponents"，在这种情况下

C:\qml\projects 路径应添加到导入路径
qmldir 文件应位于 C:\qml\projects\myapp\mycomponents\qmldir

完成这些后，本地文件系统上的任何位置的 QML 文件都可以通过引用其 URI 和相应的版本来导入该模块

import myapp.mycomponents 1.0

DialogBox {
    CheckBox {
        // ...
    }
    Slider {
        // ...
    }
}

远程安装的已识别模块

已识别模块也可以作为网络资源访问。在上面的示例中，如果 C:\qml\projects 目录作为 http://www.some-server.com/qml/projects 提供托管，并且此 URL 已添加到 QML 导入路径，则模块的导入方式完全相同。

请注意，当文件通过网络导入模块时，它只能访问由模块提供的 QML 和 JavaScript 资源；它无法访问模块中由 C++ 插件定义的类型。

已识别模块的语义

QML 引擎为已识别模块提供以下保证

其他模块无法修改或覆盖模块名称空间中的类型
其他模块无法将新类型注册到模块的名称空间
客户端使用类型名称的解析将取决于指定和导入顺序

这确保了使用模块的客户端可以确信模块中定义的对象类型将按模块作者文档中的行为运行。

已识别模块对其有一些限制

已识别模块必须安装到 QML 导入路径
在模块标识符指令中指定的模块标识符必须与模块的安装路径匹配（相对于 QML 导入路径，其中目录分隔符用点字符替换）
模块必须将其类型注册到模块标识符类型名称空间
模块不得将其类型注册到任何其他模块的名称空间

例如，如果已识别模块安装到 $QML_IMPORT_PATH/ExampleModule，则模块标识符指令必须是

module ExampleModule

如果严格模块安装到 $QML_IMPORT_PATH/com/example/CustomUi，则模块标识符指令必须是

module com.example.CustomUi

然后，客户端可以使用以下导入语句导入上述模块

import com.example.CustomUi