概述——QML 与 C++ 的集成

QML的设计旨在通过C++代码实现轻松扩展。 Qt Qml 模块中的类支持从 C++ 加载和操作 QML 对象，而 Qt Qml元对象系统的集成特性，使得 C++ 功能可直接从 QML 中调用。这使得能够开发混合应用程序，这些应用程序由 QML、JavaScript 和 C++ 代码混合实现。

QML 与 C++ 的集成提供了多种可能性，包括以下能力：

• 将用户界面代码与应用程序逻辑代码分离：前者通过 QML 及QML 文档中的 JavaScript 实现，后者则通过 C++ 实现
• 从 QML 中使用和调用某些 C++ 功能（例如，调用您的应用程序逻辑、使用用 C++ 实现的数据模型，或调用第三方 C++ 库中的某些函数）
• 访问 Qt Qml 或 Qt Quick C++ API 中的功能（例如，使用 `QQuickImageProvider` 动态生成图像）
• 从 C++ 实现您自己的QML 对象类型——无论用于您自己的特定应用程序，还是分发给他人

要向 QML 提供某些 C++ 数据或功能，必须通过一个QObject 的派生类来提供。 由于 QML 引擎与元对象系统的集成，任何从QObject 派生的类的属性、方法和信号均可从 QML 访问，具体请参阅《将 C++ 类型的属性暴露给 QML》。一旦此类类提供了所需的功能，就可以通过多种方式将其暴露给 QML：

• 该类可 注册为可实例化的 QML 类型，从而能在 QML 代码中像普通QML 对象类型一样进行实例化并使用
• 该类可注册为单例类型（Singleton Type），从而允许从 QML 代码导入该类的单个实例，使 QML 能够访问该实例的属性、方法和信号

这些是从 QML 代码访问 C++ 功能最常见的方法。QML Type Registration Macros 还提供了许多其他选项和变体。此外，除了能够从 QML 访问 C++ 功能外， Qt Qml 该模块还提供了反向操作的方法，即从 C++ 代码中操作 QML 对象。更多详细信息请参阅《从 C++ 与 QML 对象交互》。

通常，将某些状态作为全局属性暴露给 QML 是非常有用的。《将 C++ 状态暴露给 QML》介绍了如何实现这一点。

C++ 代码可集成到 C++ 应用程序或独立的 QML 模块中，具体取决于其是作为独立应用程序还是库进行分发。 一个 QML 模块可以包含一个 C++ 插件，该插件随后可由 QML 引擎动态加载。这使得应用程序能够使用未链接到二进制文件中的 QML 模块。

您也可以手动创建独立插件。有关更多信息，请参阅《在 C++ 插件中提供类型和功能》。但不建议采用此方法。

最后，该类的实例可以作为上下文属性或上下文对象 嵌入到 QML 代码中，从而允许从 QML 访问该实例的属性、方法和信号。应尽量避免使用上下文属性。

选择正确的 C++ 与 QML 集成方法

要快速确定哪种集成方法适合您的情况，可参考以下流程图：

有关流程图中宏的说明，请参阅《从 C++ 定义 QML 类型》文档。

将 C++ 类的属性暴露给 QML

由于 QML 引擎与 Qt 元对象系统的集成，QML 可以轻松地从 C++ 进行扩展。这种集成使得任何从QObject 派生的类的属性、方法和信号均可从 QML 中访问：属性可以被读取和修改，方法可以从 JavaScript 表达式中调用，并且会根据需要自动为信号创建信号处理程序。 此外，QObject 派生类的枚举值也可在QML中访问。

更多信息请参阅《将 C++ 类型的属性暴露给 QML》。

从 C++ 定义 QML 类型

QML 类型可以在 C++ 中定义，然后在QML 类型系统中注册。这使得 C++ 类能够作为QML 对象类型进行实例化，从而允许在 C++ 中实现自定义对象类型并将其集成到现有的 QML 代码中。 C++ 类还可以出于其他目的进行注册：例如，可以将其注册为单例类型（Singleton Type），以便 QML 代码导入该类的单个实例；或者将其注册为枚举类型，以便从 QML 访问不可实例化类的枚举值。

此外， Qt Qml 该模块还提供了机制，用于定义与 QML 概念（如附加属性与默认属性）集成的 QML 类型。

有关从 C++ 注册和创建自定义 QML 类型的更多信息，请参阅《从 C++ 定义 QML 类型》文档。

使用上下文属性将 C++ 对象嵌入 QML

QQmlContext C++ 对象和值可以通过上下文属性与上下文对象直接嵌入到已加载的 QML 对象的上下文（或作用域）中。这是通过由 Qt Qml 模块提供的xml-ph-0000@deepl.internal类实现，该类将数据暴露给QML组件的上下文，从而允许将数据从C++注入到QML中。

有关更多信息，请参阅《使用上下文属性将 C++ 对象嵌入 QML》。

从 C++ 与 QML 对象交互

可以从 C++ 实例化 QML 对象类型并对其进行检查，从而访问其属性、调用其方法以及接收其信号通知。这是因为所有 QML 对象类型都是使用QObject 的派生类实现的，这使得 QML 引擎能够通过 Qt 元对象系统动态加载和检查对象。

有关从 C++ 访问 QML 对象的更多信息，请参阅《从 C++ 与 QML 对象交互》文档，以及“最佳实践”页面中的“将数据从 C++ 暴露给 QML”一节。

QML 与 C++ 之间的数据类型转换

当数据值在 QML 和 C++ 之间交换时，QML 引擎会根据 QML 或 C++ 的使用需求，将数据值转换为正确的数据类型，前提是引擎已识别相关数据类型。

有关引擎支持的内置类型以及这些类型在QML 与 C++ 之间交换时如何进行转换的信息，请参阅《QML 与 C++ 之间的数据类型转换》。