QML 模块

QML 模块在类型命名空间中提供带版本的类型和 JavaScript 资源，供导入该模块的客户端使用。模块提供的类型可以在插件中的 C++ 代码中定义，也可以在 QML 文档中定义。模块利用 QML 版本控制系统，从而能够独立进行更新。

定义 QML 模块可实现：

• 在项目内共享通用的 QML 类型——例如，一组被不同窗口使用的 UI 组件
• 分发基于 QML 的库
• 将不同功能模块化，以便应用程序仅加载满足其特定需求所需的库
• 对类型和资源进行版本控制，以便在更新模块时不会破坏客户端代码

现代 QML 模块

QML 模块最好通过 CMake API 进行定义，特别是qt_add_qml_module。以下各节将详细介绍创建现代 QML 模块的各个方面。

通过 QML 文档定义对象类型

QML 类型可直接在 QML 文档中定义，这是创建可复用组件的最简单方法。每个以大写字母开头的 QML 文件都会自动定义一种类型，该类型可在同一模块中的其他 QML 文件中使用。

从 C++ 定义 QML 类型

为了获得更好的性能或访问低级 API，可以在C++ 中定义类型并将其暴露给 QML。C++ 类型在提供对属性、方法和信号的完全控制的同时，还具备静态类型和编译的优势。

使用 CMake 将一切整合起来

qt_add_qml_module CMake命令将QML文件、C++类型和资源整合为一个紧密耦合的模块。它会自动处理类型注册、资源编译以及QML工具集的集成，因此是现代QML模块开发的推荐方法。

QML 模块现代化

本指南旨在帮助将基于旧版 CMake 的 QML 模块迁移到新版 Qt。它介绍了如何适应新的 CMake 规范，并避免使用过时的技术。

QML 模块的精细调整

《编写 QML 模块》中的高级模块配置选项可对模块行为进行精细控制。这包括将多个 QML 模块添加到同一个二进制文件中、版本管理、自定义目录布局，以及有关 QML 插件的高级主题。

旧版 QML 模块

模块通过模块定义文件 qmldir 进行定义。每个模块都关联一个类型命名空间，该命名空间即为模块的标识符。模块可以提供 QML 对象类型（由 QML 文档或通过 C++ 插件定义）和 JavaScript 资源，并可被客户端导入。

要定义一个模块，开发者应将属于该模块的各种 QML 文档、JavaScript 资源和 C++ 插件集中到一个目录中，并编写一个相应的模块定义 qmldir 文件，该文件也应放置在该目录中。随后，该目录即可作为模块安装到QML 导入路径中。

请注意，定义模块并不是在项目内共享通用 QML 类型的唯一方法——简单的QML 文档目录导入也可用于此目的。

支持的 QML 模块类型

QML 支持两种不同的模块类型：

• 标识模块
• 传统模块（已弃用）

已标识模块会显式定义其标识符，并被安装到 QML 导入路径中。 已标识模块更易于维护（得益于类型版本控制），并且 QML 引擎为其提供了类型注册保证，而这些保证在旧版模块中并不存在。旧版模块仅出于让旧代码能够继续与最新版本的 QML 兼容的目的而予以支持，客户端应尽可能避免使用。

客户端可以在 QML 文档或 JavaScript 文件中导入 QML 模块。有关此主题的更多信息，请参阅关于导入 QML 模块的文档。

在 C++ 插件中提供类型和功能

对于大量逻辑由 C++ 实现，或者在 C++ 中定义类型并将其暴露给 QML 的应用程序，可能需要实现一个 QML 插件。QML 扩展模块开发者可能希望在 C++ 插件中实现某些类型（而非通过 QML 文档定义），以获得更好的性能或更大的灵活性。

每个 QML 的 C++ 插件都包含一个初始化函数，该函数会在 QML 引擎加载插件时被调用。此初始化函数必须注册插件提供的所有类型，但不得执行其他任何操作（例如，不允许实例化 QObject）。

更多信息请参阅《为 QML 创建 C++ 插件》。