构建应用程序插件
介绍
在本教程中，您将学习如何创建一个应用程序插件。应用程序插件是 Grafana 插件，允许您将数据源和面板插件捆绑在一个包中。它们还使您能够在 Grafana 中创建自定义页面，为文档、注册表单、通过 HTTP 与其他服务的集成提供专用空间。您还可以使用应用程序插件来创建 场景应用程序.
应用程序插件可以在 导航菜单 中显示，并提供定义 UI 扩展 的灵活性。
先决条件
- Grafana v9.0 或更高版本
- LTS 版本的 Node.js
创建新的应用程序插件
Grafana create-plugin 工具 是一个 CLI 应用程序，简化了 Grafana 插件开发，使您可以专注于代码。该工具会为您构建一个入门插件，所有必需的配置以及使用 Docker Compose 的开发环境。
-
在新的目录中，使用 create-plugin 工具从模板创建插件。当提示您选择插件类型时，选择app:
npx @grafana/create-plugin@latest -
转到新创建的插件的目录
cd <your-plugin> -
安装依赖项
npm install -
构建插件
npm run dev -
启动 Grafana
docker compose up - 打开 Grafana，默认情况下为 https://127.0.0.1:3000/，然后转到管理>插件。确保您的app插件存在。
您还可以通过检查日志来验证 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>。create-plugin 工具会根据您对提示的响应正确配置此项。
要查看 plugin.json 的所有可用配置设置，请参阅 plugin.json 架构.
module.ts
在发现您的插件后，Grafana 会加载 module.js 文件，这是您的插件的入口点。module.js 公开您的插件的实现，这取决于您正在构建的插件类型。
具体来说，src/module.ts 需要导出一个扩展 GrafanaPlugin 的类，它可以是以下任何一种
开发工作流程
接下来，您将学习对应用程序进行更改、构建它以及重新加载 Grafana 以反映您所做更改的基本工作流程。
第一步是查看您构建好的插件的实际效果。
- 使用
docker compose up启动您的 Grafana 实例。 - 在浏览器中打开 Grafana。转到 https://127.0.0.1:3000.
- 转到 **应用程序** -> **您的应用程序名称**。
现在您可以查看应用程序根页面（示例中的第一个页面），尝试对应用程序插件进行更改
-
在
PageOne.tsx中，更改一些页面文本内容src/pages/PageOne.tsx<PluginPage>New page content</PluginPage> -
保存文件。
-
在浏览器中重新加载 Grafana。您的更改应该会显示。
在导航菜单中添加页面
要在应用程序菜单项下向导航菜单添加页面，请修改 plugin.json 文件的 includes 部分.
当您构建插件时，create-plugin 工具会向导航菜单添加一些示例页面。每个示例页面都遵循一个路径，例如 /a/%PLUGIN_ID%/PAGE_NAME。发送到 /a/%PLUGIN_ID% 的任何请求（例如，/a/myorgid-simple-app/）都将路由到应用程序插件的根页面。根页面是一个 React 组件，它返回给定路由的内容。
让我们向导航菜单添加一个新页面
-
修改
plugin.json以添加新页面。src/plugin.json// ...
"includes": [
// ...
{
"type": "page",
"name": "New Page",
"path": "/a/%PLUGIN_ID%/new-page",
"roles": "Admin",
"addToNav": true,
"defaultNav": false
}
] -
保存
src/plugin.json文件。 -
重新启动 Grafana 实例。
保存 plugin.json 文件后，您需要重新启动 Grafana 实例才能在导航菜单中看到新页面。
新页面将显示在导航菜单中。您现在可以编辑 src/components/App/App.tsx 中的 React 路由，并将自定义组件指向它。
-
创建一个名为
src/pages/NewPage.tsx的新文件，并添加以下代码src/pages/NewPage.tsximport React from 'react';
import { PluginPage } from '@grafana/runtime';
export function NewPage() {
return <PluginPage>New Page</PluginPage>;
} -
修改
src/components/App/App.tsx中的路由以识别新页面src/components/App/App.tsx{
/* .... */
}
<Route path="new-page" element={<NewPage />} />; -
保存文件。
-
重新加载 Grafana 以查看新页面。
您不需要在 plugin.json 中的 includes 中注册所有页面。只需注册要添加到导航菜单的页面。
您在导航菜单中只能有一级页面。不支持子菜单项。
配置页面
您可以在应用程序插件中添加一个配置页面，用户可以在其中配置插件所需的任何设置。您的插件应该已经有一个示例配置页面，其源代码位于 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 中将其添加为依赖项。请注意，他们仍然需要自己安装它。
"dependencies": {
"plugins": [
{
"type": "panel",
"name": "Clock Panel",
"id": "grafana-clock-panel",
"version": "^2.1.0"
}
]
}