概述-QML和C++集成

Overview - QML and C++ Integration

概述-QML和C++集成

QML is designed to be easily extensible through C++ code. The classes in the Qt QML module enable QML objects to be loaded and manipulated from C++, and the nature of QML engine's integration with Qt's meta object system enables C++ functionality to be invoked directly from QML. This allows the development of hybrid applications which are implemented with a mixture of QML, JavaScript and C++ code.

​QML被设计成可以通过C++代码轻松扩展。Qt-QML模块中的类允许从C++加载和操作QML对象，QML引擎与Qt的元对象系统集成的性质允许直接从QML调用C++功能。这就允许开发混合应用程序，混合使用QML、JavaScript和C++代码实现。

Integrating QML and C++ provides a variety of opportunities, including the ability to:

集成QML和C++提供了多种机会，包括：

• Separate the user interface code from the application logic code, by implementing the former with QML and JavaScript within QML documents, and the latter with C++
• ​通过在QML文档中使用QML和JavaScript实现用户界面代码和应用程序逻辑代码，以及使用C实现后者，将用户界面代码与应用程序逻辑代码分开++
• Use and invoke some C++ functionality from QML (for example, to invoke your application logic, use a data model implemented in C++, or call some functions in a third-party C++ library)
• 使用并调用QML中的某些C++功能（例如，要调用应用程序逻辑，请使用C++中实现的数据模型，或调用第三方C++库中的某些函数）
• Access functionality in the Qt QML or Qt Quick C++ API (for example, to dynamically generate images using QQuickImageProvider)
• ​访问Qt QML或Qt Quick C++API中的功能（例如，使用QQuickImageProvider动态生成图像）
• Implement your own QML object types from C++ — whether for use within your own specific application, or for distribution to others
• ​从C++中实现自己的QML对象类型——无论是在自己的特定应用程序中使用，还是分发给其他人

To provide some C++ data or functionality to QML, it must be made available from a QObject-derived class. Due to the QML engine's integration with the meta object system, the properties, methods and signals of any QObject-derived class are accessible from QML, as described in Exposing Attributes of C++ Types to QML. Once the required functionality is provided by such a class, it can be exposed to QML in a variety of ways:

​要向QML提供一些C++数据或功能，必须从QObject派生的类中提供。由于QML引擎与元对象系统集成，任何QObject派生类的属性、方法和信号都可以从QML访问，如向QML公开C++类型的属性中所述。一旦这样一个类提供了所需的功能，它就可以以多种方式暴露于QML中：

• The class can be registered as an instantiable QML type, so that it can be instantiated and used like any ordinary QML object type from QML code
• ​该类可以注册为可实例化的QML类型，这样就可以像QML代码中的任何普通QML对象类型一样对其进行实例化和使用
• The class can be registered as a Singleton Type so that a single instance of the class may be imported from QML code, allowing the instance's properties, methods and signals to be accessed from QML
• ​该类可以注册为单例类型，这样就可以从QML代码中导入该类的单个实例，从而允许从QML访问该实例的属性、方法和信号
• An instance of the class can be embedded into QML code as a context property or context object, allowing the instance's properties, methods and signals to be accessed from QML
• ​类的实例可以作为上下文属性或上下文对象嵌入到QML代码中，从而允许从QML访问实例的属性、方法和信号

These are the most common methods of accessing C++ functionality from QML code; for more options and details, see the main documentation pages that are described in the sections further below. Additionally, aside from the ability to access C++ functionality from QML, the Qt QML module also provides ways to do the reverse and manipulate QML objects from C++ code. See Interacting with QML Objects from C++ for more details.

​这些是从QML代码访问C++功能的最常见方法；有关更多选项和详细信息，请参阅下文各节中描述的主要文档页面。此外，除了能够从QML访问C++功能外，Qt-QML模块还提供了从C++代码反向操作QML对象的方法。有关更多详细信息，请参阅从C++与QML对象交互。

Finally, the C++ code may be integrated into either a C++ application or a C++ plugin depending on whether it is to be distributed as a standalone application or a library. A plugin can be integrated with a QML module that can then be imported and used by QML code in other applications; see Providing Types and Functionality in a C++ Plugin for more information.

​最后，C++代码可以集成到C++应用程序或C++插件中，具体取决于它是作为独立应用程序还是库分发。插件可以与QML模块集成，然后可以导入QML代码并在其他应用程序中使用；有关更多信息，请参阅在C++插件中提供类型和功能。

Choosing the Correct Integration Method Between C++ and QML

在C++和QML之间选择正确的集成方法

To quickly determine which integration method is appropriate for your situation, the following flowchart can be used:

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

For a description of the macros in the flowchart, see the Defining QML Types from C++ documentation.

​有关流程图中宏的描述，请参阅C++文档中的定义QML类型。

Exposing Attributes of C++ Classes to QML

向QML公开C++类的属性

QML can easily be extended from C++ due to the QML engine's integration with the Qt meta object system. This integration allows the properties, methods and signals of any QObject-derived class to be accessible from QML: properties can be read and modified, methods can be invoked from JavaScript expressions and signal handlers are automatically created for signals as necessary. Additionally, enumeration values of a QObject-derived class are accessible from QML.

​由于QML引擎与Qt元对象系统的集成，QML可以很容易地从C++扩展。这种集成允许从QML访问任何QObject派生类的属性、方法和信号：可以读取和修改属性，可以从JavaScript表达式调用方法，并根据需要自动为信号创建信号处理程序。此外，可以从QML访问QObject派生类的枚举值。

See Exposing Attributes of C++ Types to QML for more information.

​有关更多信息，请参阅向QML公开C++类型的属性。

Defining QML Types from C++

从C++定义QML类型

QML types can be defined in C++ and then registered with the QML type system. This allows a C++ class to be instantiated as a QML object type, enabling custom object types to be implemented in C++ and integrated into existing QML code. A C++ class may be also registered for other purposes: for example, it could be registered as a Singleton Type to enable a single class instance to be imported by QML code, or it could be registered to enable the enumeration values of a non-instantiable class to be accessible from QML.

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

Additionally, the Qt QML module provides mechanisms to define QML types that integrate with QML concepts like attached properties and default properties.

​此外，Qt QML模块提供了定义QML类型的机制，这些类型与附加属性和默认属性等QML概念集成。

For more information on registering and creating custom QML types from C++, see the Defining QML Types from C++ documentation.

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

Embedding C++ Objects into QML with Context Properties

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

C++ objects and values can be embedded directly into the context (or scope) of loaded QML objects using context properties and context objects. This is achieved through the QQmlContext class provided by the Qt QML module, which exposes data to the context of a QML component, allowing data to be injected from C++ into QML.

​C++对象和值可以使用上下文属性和上下文对象直接嵌入到已加载QML对象的上下文（或范围）中。这是通过Qt-QML模块提供的QQmlContext类实现的，该类将数据暴露到QML组件的上下文中，允许将数据从C++注入QML。

See Embedding C++ Objects into QML with Context Properties for more information.

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

Interacting with QML Objects from C++

与来自C++的QML对象交互

QML object types can be instantiated from C++ and inspected in order to access their properties, invoke their methods and receive their signal notifications. This is possible due to the fact that all QML object types are implemented using QObject-derived classes, enabling the QML engine to dynamically load and introspect objects through the Qt meta object system.

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

Warning: Although it is possible to access QML objects from C++ and manipulate them, it is not the recommended approach, except for testing and prototyping purposes. One of the strengths of QML and C++ integration is the ability to implement UIs in QML separate from the C++ logic and dataset backend, and this fails if the C++ side starts manipulating QML directly. Such an approach also makes changing the QML UI difficult without affecting its C++ counterpart.

警告：虽然可以从C++访问QML对象并对其进行操作，但除了用于测试和原型设计之外，这不是推荐的方法。QML和C++集成的优点之一是能够在QML中独立于C++逻辑和数据集后端实现UI，如果C++端开始直接操作QML，这将失败。这种方法还使得在不影响其C++对应项的情况下更改QML UI变得困难。

For more information on accessing QML objects from C++, see the documentation on Interacting with QML Objects from C++.

​有关从C++访问QML对象的更多信息，请参阅有关从C++与QML对象交互的文档。

Data Type Conversion Between QML and C++

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

When data values are exchanged between QML and C++, they are converted by the QML engine to have the correct data types as appropriate for use from QML or C++, providing the data types involved are known to the engine.

当在QML和C++之间交换数据值时，QML引擎会将它们转换为适合从QML或C++使用的正确数据类型，前提是引擎知道所涉及的数据类型。

See Data Type Conversion Between QML and C++ for information on the built-in types supported by the engine and how these types are converted for use when exchanged between QML and C++.

​有关引擎支持的内置类型以及在QML和C++之间交换时如何转换这些类型以供使用的信息，请参见QML和C++之间的数据类型转换。

© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.