已识别模块

已标识模块是指已安装且可通过点分隔标识符字符串形式的 URI 被 QML 引擎识别的模块，该 URI 应由模块在其 `qmldir ` 文件中指定。这使得此类模块能够通过一个唯一标识符被导入，无论该模块在本地文件系统中的位置如何，该标识符均保持不变。

导入已标识模块时，应使用未加引号的标识符，并可选地包含版本号：

import QtQuick
import com.mycompany.qml.mymodule 1.0

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

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

本地安装的标识模块

如果某个包含 QML 和/或 C++ 文件的目录中包含一个带有模块元数据的qmldir 文件，并且已安装到 QML 导入路径中，则该目录可作为已标识模块共享。 本地文件系统上的任何 QML 文件都可以通过使用引用该模块 URI 的import语句将该目录作为模块导入，从而使该文件能够使用该模块定义的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

如果 strict 模块安装在$QML_IMPORT_PATH/com/example/CustomUi 目录下，则模块标识符指令必须为：

module com.example.CustomUi

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

import com.example.CustomUi