Building a reusable QML module

构建可重用的QML模块

The example below demonstrates how to create a library which exposes C++ to QML. The directory structure for the example looks like this:

下面的示例演示如何创建一个将C++暴露给QML的库。示例的目录结构如下所示：

├── CMakeLists.txt
└── example
    └── mylib
        ├── CMakeLists.txt
        ├── mytype.cpp
        ├── mytype.h

The toplevel CMakeLists.txt file does some basic setup, and then uses add_subdirectory to include the one in mylib. The subdirectory structure corresponds to the QML module’s URI, but with the dots replaced by slashes. That’s the same logic the engine uses when it searches for a module in the import paths. mytype.h declares a class and uses the declarative registration macros to expose it to the engine.

​顶级的CMakeLists.txt文件进行一些基本设置，然后使用add_subdirectory将其包含在mylib中。子目录结构对应于QML模块的URI，但点被斜线替换。这与引擎在导入路径中搜索模块时使用的逻辑相同。mytype.h声明一个类，并使用声明注册宏将其暴露给引擎。

In the subdirectory’s CMakeLists.txt we again call qt6_add_qml_module. However, the invocation is slightly different:

在子目录的CmakeList.txt中。我们再次称之为qt6_add_qml_module。然而，调用略有不同：

qt6_add_qml_module(mylib
    URI example.mylib
    VERSION 1.0
    SOURCES
        mytype.h mytype.cpp
)

To add C++ types, the SOURCES parameter needs to be specified. The target for mylib is not created. Therefore, if the target passed to qt6_add_qml_module does not exist, a library target is automatically created, which is needed in this case.

要添加C++类型，需要指定SOURCES参数。mylib的目标尚未创建。因此，如果传递给qt6_add_qml_module的目标不存在，则会自动创建库目标，在这种情况下需要创建库目标。

When the project is built, in addition to the library, a QML plugin is also built. The plugin's auto-generated class extends from QQmlEngineExtensionPlugin. The mylib library itself already contains the code to register the types with the engine. However, that is only useful in cases where we can link against the library. To make the module usable in a QML file loaded by qml, the QML Runtime Tool, a plugin is needed that can be loaded. The plugin is then responsible for actually linking against the library, and ensuring that the types get registered.

​在构建项目时，除了库之外，还构建了一个QML插件。该插件自动生成的类从QQmlEngineExtensionPlugin扩展而来。mylib库本身已经包含了向引擎注册类型的代码。然而，这只有在我们可以链接到库的情况下才有用。为了使模块在QML运行时工具QML加载的QML文件中可用，需要一个可以加载的插件。然后，插件负责实际链接库，并确保类型得到注册。

Note that the automatic plugin generation is only possible if the module does not do anything besides registering the types. If it needs to do something more advanced like registering an image provider in initializeEngine, you still need to manually write the plugin. qt6_add_qml_module has support for this with NO_GENERATE_PLUGIN_SOURCE.

​请注意，只有当模块除了注册类型之外不做任何事情时，才能自动生成插件。如果它需要做一些更高级的事情，比如在initializeEngine中注册一个图像提供者，你仍然需要手动注册插件。qt6_add_qml_module通过添加NO_GENERATE_PLUGIN_SOURCE支持此功能。

Also, following the directory layout convention helps tooling. That layout is mirrored in the build directory. Which means that you can pass the path to your build directory to the QML tool (via the -I flag), and it will find the plugin.

此外，遵循目录布局约定有助于开发工具。该布局镜像在生成目录中。这意味着您可以将构建目录的路径传递给QML工具（通过-I标志），它将找到插件。

Before concluding add a QML file to the module. In the lib subfolder, add a Mistake.qml file

在结束之前，将QML文件添加到模块中。在lib子文件夹中，添加一个Mistake.qml文件

import example.mylib

MyType{
    answer: 43
}

and adjust the qt6_add_qml_module call:

并调整qt6_add_qml_module调用：

qt6_add_qml_module(mylib
    URI example.mylib
    VERSION 1.0
    SOURCES
        mytype.h mytype.cpp
    QML_FILES
        Mistake.qml
)

As mentioned, we made a mistake because answer is actually a read-only property. This illustrates qmllint integration: CMake creates a qmllint target, and once we run it, qmllint warns about the issue:

如前所述，我们犯了一个错误，因为answer实际上是只读属性。这说明了qmlint集成：CMake创建了一个qmlint目标，一旦我们运行它，qmlint就会警告这个问题：

$> cmake --build . --target mylib_qmllint
...
Warning: Mistake.qml:4:13: Cannot assign to read-only property answer
    answer: 43
            ^^