qt_add_qml_plugin

定义与 QML 模块关联的插件。

该命令定义在Qt6 软件包的Qml 组件中，可按如下方式加载：

find_package(Qt6 REQUIRED COMPONENTS Qml)

用法

qt_add_qml_plugin(
    target
    [BACKING_TARGET backing_target]
    [STATIC | SHARED]
    [OUTPUT_DIRECTORY]
    [URI]
    [CLASS_NAME]
    [NO_GENERATE_PLUGIN_SOURCE]
    [NAMESPACE namespace]
)

如果禁用了无版本号的命令，请改用qt6_add_qml_plugin() 。它支持与本命令相同的参数集。

描述

该命令用于创建与 QML 模块关联的插件目标。通常由qt_add_qml_module()在内部调用该命令，以创建或更新与其底层目标关联的插件。除非存在特殊情况需要以特殊方式创建该目标，否则不应直接调用此函数。

qt_add_qml_module()的文档中描述了 QML 模块相关 CMake 目标的多种结构模式。 请注意，即使 QML 模块没有独立的后端目标，且所有功能都直接在插件中实现（不推荐这种安排），您仍应调用qt_add_qml_module()，而非qt_add_qml_plugin() 。

参数

target 指定了 QML 插件要使用的目标名称。如果该目标尚不存在，则会自动创建。

BACKING_TARGET 指定插件关联的后端目标名称。 后端目标可以与插件的target 相同，在这种情况下只有一个合并后的目标，但这通常不推荐（有关更多信息，请参阅qt_add_qml_module()）。除非有特殊情况需要先创建插件目标再创建后端目标，否则应始终提供BACKING_TARGET 。 如果未提供BACKING_TARGET ，则必须指定URI 选项。

默认情况下，插件将以与底层目标兼容的类型创建。如果底层目标是静态库，则插件也将作为静态库创建；如果底层目标是共享库，则插件将作为模块库创建。 如果未提供后端目标，或者插件没有单独的后端目标，则可以使用STATIC 或SHARED 关键字指定插件类型。如果插件类型无法通过上述任何条件确定，则当 Qt 作为静态库构建时将创建静态插件；否则将创建模块库插件。

OUTPUT_DIRECTORY 指定将创建插件库的目录。该目录应始终与 QML 模块的qmldir文件所在位置一致。当未指定 `OUTPUT_DIRECTORY ` 时，将从 `BACKING_TARGET` 中获取该信息（如果可用）。 请注意，此目录可能与底层目标自身库的目录不同。如果无法从底层目标获取输出目录，则默认使用CMAKE_CURRENT_BINARY_DIR 。

URI 声明了此插件关联的 QML 模块的模块标识符。 模块标识符是 QML 模块的（点分隔 URI 表示法）标识符。如果未提供URI ，则必须提供BACKING_TARGET ，并且后端目标上必须已记录其 URI（通常通过之前对qt_add_qml_module() 的调用实现）。

每个插件都应有一个 C++ 类，用于将模块注册到 QML 引擎中。默认情况下，qt_add_qml_plugin() 会自动生成该 C++ 类的源代码，并将其添加到target 的源文件列表中。生成的插件类满足插件可选的要求（参见“模块定义 qmldir 文件”）。 类名的确定方式如下：

• 如果已指定CLASS_NAME ，则使用该名称。该名称必须与 QML 模块的qmldir 文件中使用的名称一致。
• 如果未指定CLASS_NAME ，但指定了BACKING_TARGET ，则 C++ 类名将取自该后端目标上记录的详细信息。这些详细信息通常由之前对qt_add_qml_module() 的调用记录，且将与生成的qmldir 文件中使用的名称一致。在大多数情况下，这是提供类名的推荐方法。
• 如果仍无法确定类名，则将其设置为模块的 URI，其中将点替换为下划线，并在末尾附加Plugin 。

如果通过NAMESPACE 关键字指定了命名空间，生成的插件代码将位于该名称的 C++ 命名空间中。

某些插件可能需要手动编写插件类。例如，插件可能需要执行额外的初始化操作，或注册默认插件类未实现的功能。在这种情况下，可以使用NO_GENERATE_PLUGIN_SOURCE 选项。 此时，您需要自行编写 C++ 插件类，并将其添加到 `target` 中。请注意，如果您需要编写自己的插件类，该插件极不可能被设为可选。 这意味着在定义 QML 模块时，调用 `qt_add_qml_module()` 函数时应包含 `NO_PLUGIN_OPTIONAL ` 关键字，否则生成的 `qmldir ` 文件将不正确。请确保您的插件类使用与上述逻辑确定的类名相同的类名。