可视化

您可以使用 scene 对象类 VizPanel 将可视化添加到您的 scene 中。

简单的 `VizPanel` 示例

new VizPanel({
    pluginId: 'timeseries',
    title: 'Time series',
    options: {
        legend: {
            showLegend: false,
        }
    },
    fieldConfig: {
        defaults: {
            unit: 'bytes',
            min: 0,
            custom: { lineWidth: 2 fillOpacity: 6 },
        },
        overrides: [],
    }
})

注意

前面示例中使用的 pluginId timeseries 指的是核心 Grafana 面板插件，它是时间索引数据的标准图形可视化。 options 和 fieldConfig 与您在查看面板检查抽屉中的 JSON 选项卡时在典型的仪表板面板中看到的选项相同。要访问此选项卡，请在面板编辑菜单中单击 Inspect > Panel JSON。

数据

VizPanel 使用 sceneGraph.getData(model) 调用来查找并订阅具有 SceneDataProvider 对象的最近父级。这意味着如果 $data 设置在任何父级别上，则 VizPanel 使用在其自身级别上设置的 $data，或者与其他同级和 scene 对象共享数据。

头部操作

VizPanel 具有一个名为 headerActions 的属性，它可以是 React.ReactNode 或自定义 SceneObject。如果您想在面板头部的右上角放置链接或按钮，此属性很有用。例如

类型为 VizPanelMenu 的 menu 属性是可选的，设置后，它会在面板的右上角定义一个菜单。菜单对象仅在下拉菜单本身呈现时激活。因此，添加动态菜单操作和链接的最佳方法是在附加到菜单的行为中添加它们。

new VizPanel({
  pluginId: 'timeseries',
  title: 'Time series',
  headerActions: (
    <LinkButton size="sm" variant="secondary" href="scenes/drilldown/url">
      Drilldown
    </LinkButton>
  ),
});

面板头部右上角的按钮可用于

链接到其他 scene
更改当前 scene 的按钮（例如，添加下钻页面）
更改可视化设置的 RadioButtonGroup

对于 LinkButton、Button 和 RadioButtonGroup，当您将它们放置在面板头部时，请使用 size="sm"。

标准 Grafana 可视化

Scenes 提供了一个辅助 API PanelBuilders，用于构建标准 Grafana 可视化。这些包括

条形图
条形仪表盘
数据网格
火焰图
仪表盘
地理地图
热图
直方图
日志
新闻
节点图
饼图
统计
状态时间线
状态历史
表格
文本
时间序列
趋势
追踪
XY 图表

PanelBuilders API 为构建上述可视化类型的 VizPanel 对象提供支持，并支持面板选项和字段配置。

步骤 1. 导入 `PanelBuilders` API

import { PanelBuilders } from '@grafana/scenes';

步骤 2. 配置标准可视化 `VizPanel` 对象

const myTimeSeriesPanel = PanelBuilders.timeseries().setTitle('My first panel');

步骤 3. 配置数据和时间范围

const data = new SceneQueryRunner({
  datasource: {
    type: 'prometheus',
    uid: '<PROVIDE_GRAFANA_DS_UID>',
  },
  queries: [
    {
      refId: 'A',
      expr: 'rate(prometheus_http_requests_total{}[5m])',
    },
  ],
  $timeRange: new SceneTimeRange({ from: 'now-5m', to: 'now' }),
});

myTimeSeriesPanel.setData(data);

步骤 4. 配置面板选项

myTimeSeriesPanel.setOption('legend', { asTable: true }).setOption('tooltip', { mode: TooltipDisplayMode.Single });

步骤 5. 配置标准选项

所有 Grafana 可视化都带有标准选项。 PanelBuilders 提供了单独设置每个标准选项的方法。在官方 Grafana 文档中阅读有关标准选项的更多信息。

myTimeSeriesPanel.setDecimals(2).setUnit('ms');

步骤 6. 配置自定义字段配置

Grafana 可视化提供自定义的、特定于可视化的配置选项，称为字段配置。在官方 Grafana 文档中阅读有关字段配置的更多信息。

使用 setCustomFieldConfig 方法设置所需字段配置属性的值。

myTimeSeriesPanel.setCustomFieldConfig('lineInterpolation', LineInterpolation.Smooth);

步骤 7. 配置覆盖

Grafana 可视化允许您为特定字段或系列自定义可视化设置。这是通过添加覆盖规则来实现的，该规则针对一组特定字段，并且每个字段都可以定义多个选项。在官方 Grafana 文档中阅读有关覆盖的更多信息。

使用 setOverrides 方法设置所需的字段配置覆盖。对于标准选项，请使用 override<OptionName> 方法。对于自定义字段配置，请使用 overrideCustomConfigProperty 方法。

myTimeSeriesPanel.setOverrides((b) =>
  b.matchFieldsWithNameByRegex('/metrics/').overrideDecimals(4).overrideCustomFieldConfig('lineWidth', 5)
);

单个覆盖配置以 matcher 配置开始。借助 matchers，Grafana 知道覆盖应应用于结果的哪个部分。以下 matchers 可用

`matchFieldsWithName(name: string)`

基于提供的字段名称选择字段。您使用此选择器添加到规则的属性仅应用于此单个字段。

`matchFieldsWithNameByRegex(regex: string)`

使用正则表达式指定要覆盖的字段。您使用此选择器添加到规则的属性将应用于字段名称与正则表达式匹配的所有字段。

`matchFieldsByType(fieldType: FieldType)`

按类型选择字段，例如字符串、数字等。您使用此选择器添加到规则的属性将应用于与所选类型匹配的所有字段。

`matchFieldsByQuery(refId: string)`

选择特定查询（例如 A、B 或 C）返回的所有字段。您使用此选择器添加到规则的属性将应用于所选查询返回的所有字段。

`matchFieldsByValue(options: FieldValueMatcherConfig)`

选择与提供的 value 条件配置匹配的所有字段。此 matcher 允许基于针对系列缩减值执行的条件配置覆盖。例如，您可以为平均值高于提供的值的系列配置覆盖。

`matchComparisonQuery(refId: string)`

选择比较查询返回的所有字段。您使用此选择器添加到规则的属性将应用于为所选查询执行的比较查询返回的所有字段。阅读有关时间范围比较的更多信息。

步骤 8. 构建可视化

使用 build 方法生成配置的 VizPanel 对象

const myPanel = myTimeSeriesPanel.build();

步骤 9. 将可视化添加到 scene

创建一个带有布局的 scene，并将可视化添加为布局子项

const scene = new EmbeddedScene({
  body: new SceneFlexLayout({
    children: [
      new SceneFlexItem({
        body: myPanel,
      }),
    ],
  }),
});

构建的面板现在可以在 scene 中使用了。

将通用可视化配置提取到 mixin 函数

function latencyGraphMixin(builder: ReturnType<typeof PanelBuilders["timeseries"]>) {
  builder.setMin(0);
  builder.setOption('legend', { showLegend: false: true })
}

const panel = PanelBuilders.timeseries().applyMixin(latencyGraphMixin).setData(...)

自定义可视化

如果您想确定数据如何在您的 Grafana 应用程序插件中可视化，您可以通过两种方式来实现。您始终可以选择创建自定义 SceneObject，但您将无法获得 PanelChrome，它具有加载状态和 VizPanel 提供的其他功能。如果您想要面板框架内的自定义可视化，并且该可视化应看起来像 scene 中的其他面板，那么最好注册一个运行时面板插件。

步骤 1. 定义自定义面板选项和字段配置

interface CustomVizOptions {
  mode: string;
}

interface CustomVizFieldOptions {
  numericOption: number;
}

interface Props extends PanelProps<CustomVizOptions> {}

步骤 2. 定义渲染自定义 `PanelPlugin` 的 react 组件

export function CustomVizPanel(props: Props) {
  const { options, data } = props;

  return (
    <div>
      <h4>
        CustomVizPanel options: <pre>{JSON.stringify(options)}</pre>
      </h4>
      <div>
        CustomVizPanel field config: <pre>{JSON.stringify(data.series[0]?.fields[0]?.config)}</pre>
      </div>
    </div>
  );
}

步骤 3. 创建 `PanelPlugin` 实例并将其注册到 Scenes 库

import { sceneUtils } from '@grafana/scenes';

const myCustomPanel = new PanelPlugin<CustomVizOptions, CustomVizFieldOptions>(CustomVizPanel).useFieldConfig({
  useCustomConfig: (builder) => {
    builder.addNumberInput({
      path: 'numericOption',
      name: 'Numeric option',
      description: 'A numeric option',
      defaultValue: 1,
    });
  },
});

sceneUtils.registerRuntimePanelPlugin({ pluginId: 'my-scene-app-my-custom-viz', plugin: myCustomPanel });

步骤 4. 在 scene 中使用自定义面板

您现在可以在任何 VizPanel 中使用此 pluginId。确保您指定的 pluginId 包含您的 scene 应用程序名称，并且不太可能与其他 Scenes 应用程序冲突。

const data = new SceneQueryRunner({
  datasource: {
    type: 'prometheus',
    uid: 'gdev-prometheus',
  },
  queries: [
    {
      refId: 'A',
      expr: 'rate(prometheus_http_requests_total{}[5m])',
    },
  ],
  $timeRange: new SceneTimeRange({ from: 'now-5m', to: 'now' }),
});

return new EmbeddedScene({
  $data: data,
  body: new SceneFlexLayout({
    children: [
      new SceneFlexItem({
        body: new VizPanel({
          pluginId: 'my-scene-app-my-custom-viz',
          options: { mode: 'my-custom-mode' },
          fieldConfig: {
            defaults: {
              unit: 'ms',
              custom: {
                numericOption: 100,
              },
            },
            overrides: [],
          },
        }),
      }),
    ],
  }),
});

有关更多信息，请参阅关于构建面板插件的官方教程。请记住，对于 Scenes 运行时面板插件，您不需要面板插件的 plugin.json 文件，因为它不会是一个可以在仪表板中使用的独立插件。您只能在您的 Scenes 应用程序中引用该插件。

源代码

查看示例源代码

简单的 VizPanel 示例​

数据​

头部操作​

菜单​

标准 Grafana 可视化​

步骤 1. 导入 PanelBuilders API​

步骤 2. 配置标准可视化 VizPanel 对象​

步骤 3. 配置数据和时间范围​

步骤 4. 配置面板选项​

步骤 5. 配置标准选项​

步骤 6. 配置自定义字段配置​

步骤 7. 配置覆盖​

matchFieldsWithName(name: string)​

matchFieldsWithNameByRegex(regex: string)​

matchFieldsByType(fieldType: FieldType)​

matchFieldsByQuery(refId: string)​

matchFieldsByValue(options: FieldValueMatcherConfig)​

matchComparisonQuery(refId: string)​

步骤 8. 构建可视化​

步骤 9. 将可视化添加到 scene​

将通用可视化配置提取到 mixin 函数​

自定义可视化​

步骤 1. 定义自定义面板选项和字段配置​

步骤 2. 定义渲染自定义 PanelPlugin 的 react 组件​

步骤 3. 创建 PanelPlugin 实例并将其注册到 Scenes 库​

步骤 4. 在 scene 中使用自定义面板​

源代码​