创建您的第一个插件

本节描述了如何使用 Qt Creator 提供的插件模板创建一个 Qt Creator 插件，以及了解插件由什么组成以及其一般结构。

创建插件项目

Qt Creator 随附一个用于创建 Qt Creator 插件的向导，该向导为您创建一个可运行的、最小的插件。我们强烈建议您在开发和测试插件时使用两个不同的 Qt Creator 实例。否则，在插件不稳定的情况下，您的插件也将加载到开发环境中，这可能会导致环境不稳定。您只需创建 Qt Creator 构建版本的一个副本，一个用于实际开发，另一个用于测试您的插件。

您需要确保使用您想开发的相同的 Qt Creator 版本来创建插件。由于 Qt Creator 的二进制和源代码兼容性规则，Qt Creator 插件向导创建的插件可能只能使用创建它的同一个 Qt Creator 版本进行编译和运行。

选择文件 > 新建项目 > 库 > Qt Creator 插件 > 选择。
$"Choose the \QC Plugin Wizard"$
将打开 简介和项目位置 对话框。
给您的项目命名，并指定此项目将在哪个路径下创建。实际的插件名称可以与项目名称不同。您将在向导中稍后选择该名称。
继续到 插件信息 对话框。
在 插件名称 字段中，键入示例。插件名称用作其标识符，也是代码中文件和类的名称基础。
以下字段的值主要是信息性的，并在 Qt Creator 的插件概述详细视图中显示（帮助 > 关于插件，或者在 macOS 上的 Qt Creator > 关于插件）。
- 供应商名称 是创建插件的公司或组织的简短单字名称。这也用于插件部署到的路径名称。
- 版权是一行简短的版权字符串。
- 许可是许可文本。
- 描述是对插件功能的简要描述。
- URL 是用户可以找到有关插件和/或提供该插件的组织的更多信息网站。
将 Qt Creator 构建 字段设置为要用于测试插件测试的 Qt Creator 实例的构建目录。如果您这样做不正确，您的插件将出现编译错误，并且您的插件可能根本不会显示在 Qt Creator 中。
继续到 翻译文件 对话框。
选择一个语言将插件本地化到。这为所选语言设置翻译支持。
继续到 套件选择 对话框。
选择要构建和运行您项目的套件。对于 Qt Creator 插件，这需要是具有桌面设备类型和与您 Qt Creator 构建的 Qt 版本兼容的 Qt 版本（最好是与构建完全相同的版本）。如果您使用与构建插件不兼容的 Qt 版本，则在 Qt Creator 尝试加载您的插件时将出现错误。
继续到 项目管理 对话框。
查看将要创建的文件，为您的项目选择 Qt Creator 应该使用的版本控制系统（总是好主意！），然后完成向导。

构建和运行插件

如果您在项目向导中通过了正确的 Qt Creator 构建路径，则在按下构建按钮时，您的插件应该可以正常构建。在运行项目之前，选择 构建 & 运行 > 运行以指定运行设置

"Specify the Executable to Run"

从项目向导中指定的构建中的 Qt Creator 可执行文件路径选择到 Qt Creator 构建 字段，并将 命令行参数 字段的值设置为 -pluginpath %{buildDir}。

当您点击确定时，Qt Creator 启动，您可以通过查找菜单项工具 > 示例或在帮助 > 关于插件 对话框中查找插件来验证您的插件是否成功加载。

文件结构

插件向导创建了一组插件需要或应该拥有的基本文件。我们将在以下部分中详细查看其中的一些，这里是一个简短的概述

文件	角色
`README.md`	描述了如何构建和运行插件。
`Example.json.in`	插件元数据模板。CMake 从此文件创建 `Example.json` 文件，并将其编译进插件，作为元数据。元数据由 Qt Creator 读取以了解插件。
`CMakeLists.txt`	项目文件，由 CMake 使用以生成构建文件和构建插件。
`example_global.h`	包含当此插件应导出符号到其他插件时有用的宏定义。
`exampleconstants.h`	定义插件代码使用的常量的头文件。
`example.h, example.cpp`	定义将由 Qt Creator 的插件管理器实例化和运行的插件类的 C++ 头文件和源文件。
`build_cmake.yml`	添加一个 GitHub 操作和工作流，在您将提交推送到 GitHub 的 Windows、Linux 和 macOS 上构建您的插件。更多信息，请参阅 `.github\workflow\README.md`。

CMake 项目

CMake 项目文件 CMakeLists.txt 定义了您的插件应该如何编译。Qt Creator 插件需要在其中设置特定的配置，除了告诉 CMake 哪些文件需要编译（或由 moc 或 uic 处理）之外。让我们详细查看项目向导为您生成的配置。

# Remove when sharing with others.
list(APPEND CMAKE_PREFIX_PATH "/Users/example/qt-creator/build")

list(APPEND ...) 调用告诉 CMake 在它的依赖项搜索路径中包含您在向导中指定的 Qt Creator 构建路径。由于这包含您本地机器上的绝对路径，当您与其他人共享项目时应删除此行。

没有这一行，您需要在配置插件的同时，显式地将 Qt Creator 构建的路径添加到 CMAKE_PREFIX_PATH。

project(Example)

set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTORCC ON)
set(CMAKE_AUTOUIC ON)
set(CMAKE_CXX_STANDARD 17)

本节对Qt/CMake项目进行一些标准设置。除了设置项目名称和要使用的C++标准外，它还打开自动检测需要通过moc、《code translate="no">rcc或uic处理的文件。

find_package(QtCreator COMPONENTS Core REQUIRED)
find_package(QT NAMES Qt6 Qt5 COMPONENTS Widgets REQUIRED)
set(QtX Qt${QT_VERSION_MAJOR})

本节告诉CMake定位Qt Creator和Qt。如果你的插件需要额外的Qt模块，你需要将它们添加到本节中相应的find_package调用中。

为了找到Qt Creator和Qt，配置插件使用CMake时，Qt Creator和Qt的安装路径必须存在于CMAKE_PREFIX_PATH中。

add_qtc_plugin(Example
  PLUGIN_DEPENDS
    QtCreator::Core
  DEPENDS
    ${QtX}::Widgets
    QtCreator::ExtensionSystem
    QtCreator::Utils
  SOURCES
    .github/workflows/build_cmake.yml
    .github/workflows/README.md
    README.md
    example.cpp
    example.h
    example_global.h
    exampleconstants.h
    examplefunctions.h
)

add_qtc_plugin调用为指定的名称创建了一个插件目标。

在PLUGIN_DEPENDS子节中，你需要指定你的插件依赖的Qt Creator插件。有效值是一个以QtCreator::为前缀的插件名称。

在DEPENDS子节中，你需要指定你的插件依赖的库。使用以$\{QtX\}::为前缀的Qt模块名称来链接到额外的Qt模块。要链接到额外的Qt Creator库，用QtCreator::作为前缀。在本子节中，你还需要指定其他你的插件依赖的库。

在SOURCES子节中，你指定属于你的插件项目的所有文件。CMake将它们自动分类为源文件和头文件。本节中的其他文件被CMake忽略，但例如在Qt Creator这类IDE中显示的项目树中可见，以便更容易访问。

插件元数据模板

.json文件是一个JSON文件，其中包含插件管理器所需的信息，以便在实际加载插件库文件之前找到你的插件并解决其依赖关系。在这里我们只是简要地看看它。更多信息请参阅插件元数据。

向导不会直接创建一个.json文件，而是创建一个.json.in文件。qmake使用此文件来生成实际的插件.json元数据文件，用实际的值替换像QTCREATOR_VERSION这样的变量。因此，你需要转义.json.in文件中的所有反斜杠和引号（即，你需要使用\来得到反斜杠，使用\"来得到引号，以便在生成的插件JSON元数据中使用）。

    "Name" : "Example",
    "Version" : "0.0.1",
    "CompatVersion" : "0.0.1",

向导创建的元数据中的第一个条目定义了插件名称、其版本以及与哪个插件版本的二进制兼容。

    "Vendor" : "MyCompany",
    "Copyright" : "(C) MyCompany",
    "License" : "Put short license information here",
    "Description" : "Put a short description of your plugin here.",
    "Url" : "https://www.mycompany.com",

之后你会找到在项目向导中给出的有关插件的信息。

    ${IDE_PLUGIN_DEPENDENCIES}

IDE_PLUGIN_DEPENDENCIES变量会自动替换为你插件.pro文件中的QTC_PLUGIN_DEPENDS和QTC_PLUGIN_RECOMMENDS中的依赖信息。

插件类

example.h和example.cpp文件定义了你的小型插件的插件实现。在这里我们将关注一些亮点，并提供更多详细信息的指针。

头文件

头文件example.h定义了插件类的接口。

namespace Example {
namespace Internal {

插件定义在一个名为Example::Internal的命名空间中，这符合Qt Creator源代码中的namespacing编码规则。

class ExamplePlugin : public ExtensionSystem::IPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QtCreatorPlugin" FILE "Example.json")

所有 Qt Creator 插件都必须从 ExtensionSystem::IPlugin 派生，并且是 QObjects。要创建有效的 Qt 插件，必须使用 Q_PLUGIN_METADATA 宏。宏中给出的 IID 必须是 org.qt-project.Qt.QtCreatorPlugin，以将其识别为 Qt Creator 插件，而且 FILE 必须指向插件元数据文件，文件描述请参考插件元数据。

    bool initialize(const QStringList &arguments, QString *errorString);
    void extensionsInitialized();
    ShutdownFlag aboutToShutdown();

基类定义了在插件生命周期期间调用的基本函数，这在此为新插件实现了。这些函数和它们的作用在插件生命周期中有详细描述。

private:
    void triggerAction();

该插件还有一个额外的自定义槽，用于在用户选择该插件添加的菜单项时弹出对话框。

源文件

源文件包含插件的实际实现，它注册了一个新的菜单和菜单项，并在该项目被触发时打开一个消息框。

所有必要的头文件，包括插件代码本身、来自 Core 插件和 Qt 的头文件，都在文件开始处包含。菜单和菜单项的设置在插件的 initialize 函数中完成，该函数在插件构造函数之后调用。在此函数中，插件可以确保它所依赖的插件的基本设置已完成，例如，Core 插件的 ActionManager 实例已创建。

有关实现插件接口的更多信息，请参阅 ExtensionSystem::IPlugin API 文档和插件生命周期。

    auto action = new QAction(tr("Example Action"), this);
    Core::Command *cmd = Core::ActionManager::registerAction(action, Constants::ACTION_ID,
                                                             Core::Context(Core::Constants::C_GLOBAL));
    cmd->setDefaultKeySequence(QKeySequence(tr("Ctrl+Alt+Meta+A")));
    connect(action, &QAction::triggered, this, &ExamplePlugin::triggerAction);

此部分代码创建了一个新的 QAction，将其注册为新的 Command 并将其连接到插件的槽。动作管理器提供了一个中心位置，用户可以分配和更改快捷键，并管理例如在不同情况下将菜单项指向不同插件等情况，以及其他一些事情。

    Core::ActionContainer *menu = Core::ActionManager::createMenu(Constants::MENU_ID);
    menu->menu()->setTitle(tr("Example"));
    menu->addAction(cmd);
    Core::ActionManager::actionContainer(Core::Constants::M_TOOLS)->addMenu(menu);

在此创建了一个新的菜单项，将创建的命令添加到其中，并将菜单添加到菜单栏的工具菜单中。

void ExamplePlugin::triggerAction()
{
    QMessageBox::information(Core::ICore::mainWindow(),
                             tr("Action Triggered"),
                             tr("This is an action from Example."));
}

此部分定义了菜单项被触发时调用的代码。它使用 Qt API 打开一个消息框，显示信息性文本和一个确定按钮。