构建面板插件

简介

面板允许您以不同的方式可视化数据，是 Grafana 的基本构建块之一。Grafana 已经包含了几种类型的面板，并且在 Grafana 插件目录中提供了更多面板。

要添加对其他可视化的支持，您可以创建自己的面板插件。面板是 ReactJS 组件，可以使用 create-plugin 工具进行脚手架。

有关面板的更多信息，请参阅有关面板的文档。

先决条件

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

创建新插件

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

在新的目录中，使用 create-plugin 工具从模板创建插件。当提示您输入插件类型时，选择面板:
```
npx @grafana/create-plugin@latest
```
转到新创建的插件的目录
```
cd <your-plugin>
```
安装依赖项
```
npm install
```
构建插件
```
npm run dev
```
启动 Grafana
```
docker compose up
```
打开 Grafana，默认情况下为 https://127.0.0.1:3000/，然后转到**管理** > **插件**。确保您的面板插件在那里。

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

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

插件结构

您创建的每个插件至少需要两个文件：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 的类，并且可以是以下任何一项

面板插件

面板属性

PanelProps 接口公开了有关面板的运行时信息，例如面板尺寸和当前时间范围。

您可以通过 props 参数访问面板属性，如您的插件中所示。

src/components/SimplePanel.tsx
export const SimplePanel: React.FC<Props> = ({ options, data, width, height }) => {

开发工作流程

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

首先，您需要将面板添加到仪表板

在浏览器中打开 Grafana。
创建一个新的仪表板，并添加一个新的面板。
从可视化类型列表中选择您的面板。
保存仪表板。

现在您可以查看您的面板，尝试对面板插件进行更改

在 SimplePanel.tsx 中，更改圆圈的填充颜色。例如，要将其更改为绿色
src/components/SimplePanel.tsx
```
<circle style={{ fill: theme.visualization.getColorByName('green') }} r={100} />
```
保存文件。
在浏览器中，重新加载 Grafana 以查看新的更改。

添加面板选项

有时您希望为面板用户提供一个选项来配置插件的行为。通过为插件配置面板选项，您的面板将能够接受用户输入。

在前面的步骤中，您更改了代码中圆圈的填充颜色。让我们更改代码，以便插件用户可以从面板编辑器中配置颜色。

添加选项

面板选项在面板选项对象中定义。SimpleOptions 是一个描述选项对象的接口。

在 types.ts 中，添加一个 CircleColor 类型来保存用户可以选择的颜色
```
type CircleColor = 'red' | 'green' | 'blue';
```
在 SimpleOptions 接口中，添加一个名为 color 的新选项
```
color: CircleColor;
```

这是更新后的选项定义

src/types.ts
type SeriesSize = 'sm' | 'md' | 'lg';
type CircleColor = 'red' | 'green' | 'blue';

// interface defining panel options type
export interface SimpleOptions {
  text: string;
  showSeriesCount: boolean;
  seriesCountSize: SeriesSize;
  color: CircleColor;
}

添加选项控件

要从面板编辑器中更改选项，您需要将 color 选项绑定到选项控件。

Grafana 支持一系列选项控件，例如文本输入、开关和单选组。

让我们创建一个单选控件并将其绑定到 color 选项。

在构建器的末尾添加控件

src/module.ts
.addRadio({
  path: 'color',
  name: 'Circle color',
  defaultValue: 'red',
  settings: {
    options: [
      {
        value: 'red',
        label: 'Red',
      },
      {
        value: 'green',
        label: 'Green',
      },
      {
        value: 'blue',
        label: 'Blue',
      },
    ],
  }
});

path 用于将控件绑定到选项。您可以通过在选项对象中指定完整路径来将控件绑定到嵌套选项，例如 colors.background。

Grafana 为您构建了一个选项编辑器，并在面板编辑器侧边栏的**显示**部分中显示它。

使用新选项

您快完成了。您添加了一个新选项和一个相应的控件来更改值。但是插件尚未使用该选项。让我们改变这一点。

要将选项值转换为当前主题使用的颜色，请在 SimplePanel.tsx 中的 return 语句之前添加以下语句。
src/components/SimplePanel.tsx
```
let color = theme.visualization.getColorByName(options.color);
```
配置圆圈以使用颜色。
src/components/SimplePanel.tsx
```
<g>
  <circle style={{ fill: color }} r={100} />
</g>
```

现在，当您在面板编辑器中更改颜色时，圆圈的填充颜色也会随之更改。

使用数据帧创建动态面板

大多数面板可视化来自 Grafana 数据源的动态数据。在此步骤中，您将为每个序列创建一个圆圈，每个圆圈的半径等于该序列中的最后一个值。

信息

要在面板中使用查询中的数据，您需要设置数据源。如果您没有可用的数据源，则可以在开发时使用 TestData 数据源。

面板内数据源查询的结果在面板组件内的 data 属性中可用。

const { data } = props;

data.series 包含从数据源查询返回的序列。每个序列都表示为称为数据帧的数据结构。数据帧类似于表格，其中数据按列或字段存储，而不是按行存储。字段中的每个值都共享相同的数据类型，例如字符串、数字或时间。

以下是包含时间字段 Time 和数字字段 Value 的数据帧示例

时间	值
1589189388597	32.4
1589189406480	27.2
1589189513721	15.0

让我们看看如何从数据帧中检索数据并在可视化中使用它。

获取类型为 number 的每个字段的最后一个值，方法是在 SimplePanel.tsx 中的 return 语句之前添加以下内容
src/components/SimplePanel.tsx
```
const radii = data.series
  .map((series) => series.fields.find((field) => field.type === 'number'))
  .map((field) => field?.values.get(field.values.length - 1));
```
radii 将包含从数据源查询返回的每个序列中的最后一个值。您将使用这些值来设置每个圆圈的半径。

将 svg 元素更改为以下内容

src/components/SimplePanel.tsx
<svg
  className={styles.svg}
  width={width}
  height={height}
  xmlns="http://www.w3.org/2000/svg"
  xmlnsXlink="http://www.w3.org/1999/xlink"
  viewBox={`0 -${height / 2} ${width} ${height}`}
>
  <g fill={color}>
    {radii.map((radius, index) => {
      const step = width / radii.length;
      return <circle r={radius} transform={`translate(${index * step + step / 2}, 0)`} />;
    })}
  </g>
</svg>

请注意我们是如何为radii中的每个值创建一个<circle>元素的。

src/components/SimplePanel.tsx
{
  radii.map((radius, index) => {
    const step = width / radii.length;
    return <circle r={radius} transform={`translate(${index * step + step / 2}, 0)`} />;
  });
}

我们在这里使用transform将圆圈水平分布在面板中。

重新构建你的插件，并通过在面板中添加多个查询来试用它。刷新仪表盘。

如果你想了解更多关于数据帧的信息，请查看我们关于数据帧的介绍。

总结

在本教程中，你学习了如何为你的仪表盘创建自定义可视化。

简介​

先决条件​

创建新插件​

插件结构​

plugin.json​

module.ts​

面板插件​

面板属性​

开发工作流程​

添加面板选项​

添加选项​

添加选项控件​

使用新选项​

使用数据帧创建动态面板​

总结​

简介