可视化

您可以使用场景对象类 VizPanel 向场景添加可视化。

简单的 `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 或与其他同级和场景对象共享数据。

标题操作

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>
  ),
});

面板标题右上角的按钮可用于：

链接到其他场景
更改当前场景的按钮（例如，添加下钻页面）
一个更改可视化设置的 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)
);

单个覆盖配置以匹配器配置开始。多亏了匹配器，Grafana 知道应该将覆盖应用于结果的哪个部分。以下匹配器可用：

`matchFieldsWithName(name: string)`

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

`matchFieldsWithNameByRegex(regex: string)`

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

`matchFieldsByType(fieldType: FieldType)`

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

`matchFieldsByQuery(refId: string)`

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

`matchFieldsByValue(options: FieldValueMatcherConfig)`

选择所有与提供的值条件配置匹配的字段。此匹配器允许根据对序列的减少值执行的条件进行覆盖配置。例如，您可以为平均值高于提供值的序列配置覆盖。

`matchComparisonQuery(refId: string)`

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

步骤 8. 构建可视化

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

const myPanel = myTimeSeriesPanel.build();

步骤 9. 将可视化添加到场景

创建一个带布局的场景，并将可视化作为布局子项添加

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

这个构建的面板现在可以在场景中使用。

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

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，但您将无法获得带有加载状态和 VizPanel 提供的其他功能的 PanelChrome。如果您想要在面板框架内创建一个自定义可视化，使其看起来像场景中的其他面板，那么最好注册一个运行时面板插件。

步骤 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. 在场景中使用自定义面板

您现在可以在任何 VizPanel 中使用此 pluginId。请确保您指定的 pluginId 包含您的场景应用名称，并且不太可能与其他 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. 将可视化添加到场景​

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

自定义可视化​

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

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

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

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

源代码​