标识模块

标识模块（Identified Modules）是指已安装并可由 QML 引擎通过点式标识符字符串形式的 URI 标识的模块，该字符串应由模块在其qmldir 文件中指定。这样，无论模块位于本地文件系统的哪个位置，都能用唯一的标识符导入模块。

在导入标识模块时，使用的是一个不带引号的标识符，以及一个可选的版本号：

import QtQuick
import com.nokia.qml.mymodule 1.0

标识模块必须安装到导入路径中，才能被 QML 引擎找到。

在语法上，URI 的每个点分隔段必须是格式良好的 ECMAScript 标识符名称。例如，这意味着这些段落不得以数字开头，也不得包含-（减号）字符。由于 URI 将被翻译成目录名称，因此应将其限制为拉丁字母的字母数字字符、下划线和点。

本地安装的识别模块

如果 QML 和/或 C++ 文件目录包含一个带有模块元数据的qmldir 文件，并已安装到 QML 导入路径中，则该目录可作为已识别模块共享。本地文件系统上的任何 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 导入路径中
• 模块标识符指令（module identifier directive）中指定的模块标识符必须与模块的安装路径相匹配（相对于 QML 导入路径，其中目录分隔符用句点字符代替）。
• 模块必须在模块标识符类型名称空间中注册其类型
• 模块不得在任何其他模块的命名空间中注册类型

例如，如果标识模块安装在$QML_IMPORT_PATH/ExampleModule 中，模块标识符指令必须是：

module ExampleModule

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

module com.example.CustomUi

这样，客户端就能通过以下 import 语句导入上述模块：

import com.example.CustomUi