构建面板插件

简介

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

要支持其他可视化，您可以创建自己的面板插件。面板是ReactJS 组件，可以使用 create-plugin 工具来构建。

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

先决条件

Grafana v10.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支持三种类型的插件：面板、数据源 和 应用程序。
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 的类，可以是以下之一

面板插件

面板属性

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

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

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

开发工作流程

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

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

将面板添加到仪表板

在浏览器中打开Grafana。默认情况下，Grafana在 https://127.0.0.1:3000 可用。
创建一个新的仪表板。
- 从菜单中，选择 仪表板。
- 在右上角，选择新建 -> 仪表板。
- 选择 添加可视化 以开始配置您的新面板。
配置 TestData 数据源。在数据源配置窗口中，选择此仪表板的 TestData DB 数据源。
搜索并选择您的面板插件。在面板配置视图中，转到右侧的 可视化 列表，搜索您的面板插件，并选择它。
保存仪表板。

备选方案：使用已配置的示例面板仪表板

您还可以通过预配置的仪表板查看您的面板在操作中的效果

转到 仪表板 并选择 已配置的示例面板仪表板。
- TestData DB 数据源已为此仪表板配置了示例数据。
要编辑，在此仪表板中找到您的面板，并点击右上角的面板菜单（即三个垂直点）。
从下拉菜单中选择编辑以自定义或检查面板的设置。

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

在 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数据源。

当将面板添加到仪表板时，请配置数据源以动态填充数据。或者，您可以使用已配置了示例数据源的预配置样本面板仪表板。

使用预配置样本面板仪表板

预配置样本面板仪表板已预配置了TestData数据源。此设置包括用于测试和开发示例数据。示例数据位于raw_frame场景中，该场景在TestData数据源中，包含两个时间序列，具有相同的时间戳，如下表所示。该表显示这两个时间序列通过时间戳连接

时间戳	标签1	值1	标签2	值2
2020-12-31 19:00:00	A	10	A	40
2020-12-31 20:00:00	B	20	B	50
2020-12-31 21:00:00	C	15	C	45
2020-12-31 22:00:00	D	25	D	55
2020-12-31 23:00:00	E	30	E	60

此设置允许您使用真实示例数据测试面板的动态元素，结构化多个序列以实现更复杂的可视化。

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

const { data } = props;

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

以下是一个具有时间字段Time和数字字段Value的数据帧示例

时间	值
1589189388597	32.4
1589189406480	27.2
1589189513721	15.0

预配置样本面板仪表板**样本数据

时间戳	标签1	值1	标签2	值2
2020-12-31 19:00:00	A	10	A	40
2020-12-31 20:00:00	B	20	B	50
2020-12-31 21:00:00	C	15	C	45
2020-12-31 22:00:00	D	25	D	55
2020-12-31 23:00:00	E	30	E	60

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

通过在SimplePanel.tsx中添加以下内容，在return语句之前获取每个字段类型为number的最后一个值
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

面板插件

面板属性

开发工作流程

将面板添加到仪表板

备选方案：使用已配置的示例面板仪表板​

添加面板选项​

添加一个选项​

添加一个选项控件​

使用新的选项​

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

使用预配置样本面板仪表板​

总结​

简介