QML 模块

QML 模块在类型命名空间中提供版本化类型和 JavaScript 资源，导入模块的客户端可使用这些资源。模块提供的类型可在插件中用 C++ 定义，也可在 QML 文档中定义。模块使用 QML 版本系统，允许模块独立更新。

定义 QML 模块可以

• 在一个项目中共享共同的 QML 类型--例如，不同窗口使用的一组用户界面组件
• 分发基于 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 模块》（Writing QML Modules）中的高级模块配置选项允许对模块行为进行细粒度控制。这包括在同一二进制文件中添加多个 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 引擎加载插件时会调用它。这个初始化函数必须注册插件提供的任何类型，但不能做任何其他事情（例如，不允许实例化 QObjects）。

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