构建一个应用插件
介绍
在本教程中，您将学习如何创建应用插件。应用插件是 Grafana 插件，允许您将数据源和面板插件捆绑在一个包中。它们还使您能够在 Grafana 中创建自定义页面，提供专门的空间用于文档、注册表单以及通过 HTTP 与其他服务集成。您还可以使用应用插件创建场景应用。
应用插件可以显示在导航菜单中，并提供定义UI 扩展的灵活性。
先决条件
- Grafana v10.0 或更高版本
- Node.js 的 LTS 版本
创建一个新的应用插件
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://:3000，然后转到 Administration > Plugins。确保您的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唯一标识您的插件，应遵循此命名约定：<$组织名称>-<$插件名称>-<$插件类型>。create-plugin 工具会根据您的提示响应正确配置此项。
要查看 plugin.json 的所有可用配置设置，请参阅 plugin.json Schema。
module.ts
发现您的插件后，Grafana 会加载 module.js 文件，它是您的插件的入口点。module.js 公开了您插件的实现，这取决于您正在构建的插件类型。
具体来说，src/module.ts 需要导出一个继承自 GrafanaPlugin 的类，并且可以是以下任何一种
开发工作流程
接下来，您将学习更改应用、构建应用以及重新加载 Grafana 以反映所做更改的基本工作流程。
第一步是查看您搭建好的插件实际运行情况。
- 使用
docker compose up启动您的 Grafana 实例。 - 在浏览器中打开 Grafana。转到 https://:3000。
- 转到 Apps -> 您的应用名称。
现在您可以查看您的应用根页面（示例中的第一页），尝试对应用插件进行更改
-
在
PageOne.tsx中，更改页面的一些文本内容src/pages/PageOne.tsx<PluginPage>New page content</PluginPage> -
保存文件。
-
在浏览器中重新加载 Grafana。您的更改应该会显示出来。
在导航菜单中添加页面
要在应用菜单项下方的导航菜单中添加页面，请修改 plugin.json 文件的 includes 部分。
当您搭建插件时，create-plugin 工具会在导航菜单中添加一些示例页面。每个示例页面遵循 /a/%PLUGIN_ID%/页面名称 的路径。发送到 /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",
"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 中。只需注册您希望添加到导航菜单中的页面。
您可以使用 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 hook 在 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"
}
]
}