跳转到主要内容

构建应用插件

简介​

在本教程中，您将学习如何创建一个 应用插件。应用插件是 Grafana 插件，允许您将数据源和面板插件打包在一个单独的包中。它还允许您在 Grafana 中创建自定义页面，提供一个专门的文档、注册表单和通过 HTTP 与其他服务集成的地方。您还可以使用应用插件创建 场景应用。

应用插件可以在 导航菜单 中显示，并提供定义 UI 扩展 的灵活性。

先决条件​

  • Grafana v10.0 或更高版本
  • LTS 版本的 Node.js

创建新的应用插件​

Grafana create-plugin 工具 是一个 CLI 应用程序，它简化了 Grafana 插件开发，让您可以专注于代码。该工具为您构建了一个入门级插件、所有必需的配置和一个使用 Docker Compose 的开发环境。

  1. 在新的目录中，使用 create-plugin 工具根据模板创建一个插件。当提示插件类型时，选择应用:

    npx @grafana/create-plugin@latest

  2. 转到您新创建的插件的目录

    cd <your-plugin>

  3. 安装依赖项

    npm install

  4. 构建插件

    npm run dev

  5. 启动 Grafana

    docker compose up
  6. 打开 Grafana，默认地址为 https://127.0.0.1:3000/，然后转到 管理 > 插件。确保您的插件已存在。应用。

您还可以通过检查日志来验证 Grafana 是否已发现您的插件。

INFO[01-01|12:00:00] Plugin registered       logger=plugin.loader pluginID=<your-plugin>
注意

如果您选择为您的应用程序插件设置后端，则在启动带有 Docker 的 Grafana 之前，必须通过运行 mage -v 来构建后端插件二进制文件。

插件的组成​

您创建的每个插件至少需要两个文件： plugin.json 和 src/module.ts。

plugin.json​

当 Grafana 启动时，它会扫描 插件目录 以查找包含 plugin.json 文件的任何子目录。该 plugin.json 文件包含有关您的插件的信息，并告诉 Grafana 您的插件需要哪些功能和依赖项。

虽然某些插件类型可以有特定的配置选项，但让我们看看必需的选项

  • type 告诉 Grafana 应期望哪种类型的插件。Grafana 支持三种类型的插件： panel、datasource 和 app。
  • name 是用户将在插件列表中看到的内容。如果您正在创建数据源，这通常是连接到的数据库的名称，例如 Prometheus、PostgreSQL 或 Stackdriver。
  • id 唯一标识您的插件，并应遵循以下命名约定： <$organization-name>-<$plugin-name>-<$plugin-type>。创建插件工具会根据您对其提示的响应正确配置此名称。

要查看 plugin.json 的所有可用配置设置，请参阅 plugin.json 架构。

module.ts​

在发现您的插件后，Grafana 加载 module.js 文件，这是您的插件的入口点。 module.js 公开了您插件的实现，这取决于您正在构建的插件类型。

具体来说， src/module.ts 需要导出一个扩展 GrafanaPlugin 的类，可以是以下之一

开发工作流程​

接下来，您将学习如何修改您的应用程序、构建它以及重新加载 Grafana 以反映您所做的更改的基本工作流程。

第一步是查看您已搭建的插件的实际效果。

  1. 使用 docker compose up 启动您的 Grafana 实例。
  2. 在浏览器中打开Grafana。访问 https://127.0.0.1:3000。
  3. 转到 应用 -> 您的应用名称。

现在您可以查看应用根页面（示例中的第一页），尝试修改应用插件

  1. 在 PageOne.tsx 中修改页面文本内容

    src/pages/PageOne.tsx
    <PluginPage>New page content</PluginPage>

  2. 保存文件。

  3. 在浏览器中重新加载Grafana。您的更改应该会出现。

在导航菜单中添加页面​

要向您的应用菜单项下的导航菜单添加页面，修改 plugin.json 文件的 includes 部分。

当您构建插件时，create-plugin 工具会向导航菜单添加一些示例页面。每个示例页面遵循类似于 /a/%PLUGIN_ID%/PAGE_NAME 的路径。例如，发送到 /a/%PLUGIN_ID% 的任何请求，如 /a/myorgid-simple-app/，都会被路由到应用插件的根页面。根页面是一个React组件，它为给定的路由返回内容。

让我们向导航菜单添加一个新页面

  1. 修改 plugin.json 添加新页面。

    src/plugin.json
    // ...
    "includes": [
        // ...
        {
            "type": "page",
            "name": "New Page",
            "path": "/a/%PLUGIN_ID%/new-page",
            "addToNav": true,
            "defaultNav": false
        }
    ]

  2. 保存 src/plugin.json 文件。

  3. 重启您的Grafana实例。

注意

保存 plugin.json 文件后，您需要重启您的Grafana实例才能在导航菜单中看到新页面。

新页面出现在导航菜单中。您现在可以编辑 src/components/App/App.tsx 中的React路由，并将其指向自定义组件。

  1. 创建一个名为 src/pages/NewPage.tsx 的新文件，并添加以下代码

    src/pages/NewPage.tsx
    import React from 'react';
    import { PluginPage } from '@grafana/runtime';

    export function NewPage() {
      return <PluginPage>New Page</PluginPage>;
    }

  2. 修改 src/components/App/App.tsx 中的路由以识别新页面

    src/components/App/App.tsx
    {
      /* .... */
    }
    <Route path="new-page" element={<NewPage />} />;

  3. 保存文件。

  4. 重新加载Grafana以在位置上看到新页面。

您不需要在 plugin.json 中的 includes 内部注册所有页面。只需注册您想添加到导航菜单的页面。

提示

您可以使用 role 属性来限制哪些用户可以访问导航菜单中的页面。

注意

导航菜单中只能有一级页面。不支持子菜单项。

配置页面​

您可以在应用插件中添加一个配置页面，用户可以在其中配置插件需要的任何设置。您的插件应该已经有一个示例配置页面，其源代码位于 src/components/AppConfig/AppConfig.tsx。

保存用户设置​

要存储用户设置，向 /api/plugins/%PLUGIN_ID%/settings 发送POST请求，并使用 jsonData 和 secureJsonData 作为数据。

export const updatePluginSettings = async (pluginId: string, data: Partial<PluginMeta>) => {
  const response = await getBackendSrv().fetch({
    url: `/api/plugins/${pluginId}/settings`,
    method: 'POST',
    data, // data: { jsonData: { ... }, secureJsonData: { ... } }
  });

  return lastValueFrom(response);
};

检索用户设置​

用户设置是插件 meta 的一部分。您可以通过使用 usePluginContext 钩子在React组件中检索它们。例如

import React from 'react';
import usePluginContext from '@grafana/data';

function MyComponent() {
  const context = usePluginContext();
  // user settings
  const jsonData = context.meta.jsonData;
}

使用数据代理从前端代码中获取数据​

如果您想从您的应用程序前端代码（例如，从第三方API）获取数据，而不出现CORS问题或使用认证请求，则可以使用数据代理。

在您的应用程序中添加嵌套插件​

您可以在应用程序插件中嵌套数据源和面板插件。请参阅使用嵌套插件。

包含外部插件​

如果您想让用户知道您的应用程序需要现有插件，您可以在plugin.json中将它添加为依赖项。注意，他们仍然需要自己安装它。

src/plugin.json
"dependencies": {
  "plugins": [
    {
      "type": "panel",
      "name": "Clock Panel",
      "id": "grafana-clock-panel",
      "version": "^2.1.0"
    }
  ]
}

下一步​