数据帧是一种列式数据结构，能够高效地查询大量数据。由于数据帧是开发 Grafana 插件时的核心概念，本指南将介绍如何在面板插件中使用它们来可视化数据源查询返回的数据。

DataFrame 接口包含一个 name 和一个 fields 数组，其中每个字段都包含该字段的名称、类型和值。

从数据帧中读取值

构建面板插件时，数据源返回的数据帧可以通过面板组件中的 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);