The data frame is a columnar data structure that allows for efficient querying of large amounts of data. Since data frames are a central concept when developing plugins for Grafana, in this guide we'll look at some ways you can use them in your panel plugin to visualize data returned by a data source query.

The DataFrame interface contains a name and an array of fields where each field contains the name, type, and the values for the field.

从数据帧中读取值

当您构建面板插件时，数据源返回的数据帧可从面板组件中的 data 属性获得。

function SimplePanel({ data: Props }) {
  const frame = data.series[0];

  // ...
}

在您开始读取数据之前，请考虑您期望得到的数据。例如，要可视化时间序列，您至少需要一个时间字段和一个数字字段。

const timeField = frame.fields.find((field) => field.type === FieldType.time);
const valueField = frame.fields.find((field) => field.type === FieldType.number);

其他类型的可视化可能需要多个维度。例如，一个使用三个数字字段的气泡图：X 轴、Y 轴和一个用于每个气泡半径的字段。在这种情况下，我们建议您不要硬编码字段名称，而是让用户选择用于每个维度的字段。

const x = frame.fields.find((field) => field.name === xField);
const y = frame.fields.find((field) => field.name === yField);
const size = frame.fields.find((field) => field.name === sizeField);

for (let i = 0; i < frame.length; i++) {
  const row = [x?.values[i], y?.values[i], size?.values[i]];

  // ...
}

或者，您可以使用 DataFrameView，它为您提供一个包含框架中每个字段的属性的对象数组。

const view = new DataFrameView(frame);

view.forEach((row) => {
  console.log(row[options.xField], row[options.yField], row[options.sizeField]);
});

从数据帧中显示值

字段选项让用户可以控制 Grafana 如何在数据帧中显示数据。

要将字段选项应用于值，请对相应的字段使用 display 方法。结果包含诸如颜色和后缀之类的信息，这些信息在显示值时使用。

const valueField = frame.fields.find((field) => field.type === FieldType.number);

return (
  <div>
    {valueField
      ? valueField.values.map((value) => {
          const displayValue = valueField.display!(value);
          return (
            <p style={{ color: displayValue.color }}>
              {displayValue.text} {displayValue.suffix ? displayValue.suffix : ''}
            </p>
          );
        })
      : null}
  </div>
);

要将字段选项应用于字段的名称，请使用 getFieldDisplayName。

const valueField = frame.fields.find((field) => field.type === FieldType.number);
const valueFieldName = getFieldDisplayName(valueField, frame);