Grafana Scenes

作者 grafana1ccacf29049fApache-2.0279 个星标收录于 2026年10月8日更新于 2026年10月8日仓库今天更新

Build Grafana plugin pages using the @grafana/scenes framework. Use when creating new scene pages, adding panels/visualizations, setting up drilldown navigation, defining variables, configuring query runners, building table/timeseries/stat panels, or extending SceneObjectBase for custom scene objects. Triggers on any work involving SceneApp, SceneAppPage, EmbeddedScene, SceneQueryRunner, SceneDataTransformer, PanelBuilders, SceneFlexLayout, QueryVariable, or drilldown/tab configuration in Grafana plugins.

仅含说明Software Development

AI 生成的概览

使用 @grafana/scenes 框架构建 Grafana 插件页面，涵盖场景、面板、变量与下钻导航。

功能: 该技能提供使用 @grafana/scenes 框架构建 Grafana 插件页面的指导和代码模式。它说明如何组合 SceneApp、SceneAppPage、EmbeddedScene 等场景树，添加面板与可视化，定义查询运行器和数据转换器，设置变量，并配置下钻导航与标签页。它还介绍如何扩展 SceneObjectBase 以创建自定义场景对象，并列出常见陷阱。
适用场景: 适用于创建新的 Grafana 场景页面，或为 Grafana 插件添加面板、可视化、变量、查询运行器或下钻导航时。也适用于扩展 SceneObjectBase 以创建自定义场景对象，或使用 SceneApp、SceneAppPage、EmbeddedScene、PanelBuilders 等相关场景 API 的场景。
运行要求: 需要一个使用 @grafana/scenes 包并具备 TypeScript/React 工具链的 Grafana 插件项目。该技能不附带脚本，仅包含说明和代码示例。

@grafana/scenes Framework

Build reactive, data-driven Grafana plugin pages with declarative scene objects.

Core Concepts

Scenes composes a tree of objects: SceneApp → SceneAppPage → EmbeddedScene → layouts → panels. Each node can own data ($data), variables ($variables), time ranges ($timeRange), and behaviors ($behaviors) that propagate down the tree.

Quick Start: New Scene Page

1. Create the scene file

typescript

// src/components/scenes/MyFeature/scene.tsximport {  EmbeddedScene, SceneFlexLayout, SceneFlexItem,  SceneQueryRunner, SceneVariableSet, QueryVariable,  PanelBuilders, VariableValueSelectors, SceneControlsSpacer,} from '@grafana/scenes';
export function getMyFeatureScene(params: { datasource: DataSourceRef }) {  const queryRunner = new SceneQueryRunner({    datasource: params.datasource,    queries: [{ refId: 'A', expr: 'up{cluster=~"$cluster"}', instant: true, format: 'table' }],  });
  const panel = PanelBuilders.table()    .setData(queryRunner)    .setTitle('My Table')    .build();
  return new EmbeddedScene({    $variables: new SceneVariableSet({      variables: [        new QueryVariable({          name: 'cluster',          query: 'label_values(up, cluster)',          datasource: params.datasource,          isMulti: true, includeAll: true, defaultToAll: true,        }),      ],    }),    controls: [new VariableValueSelectors({}), new SceneControlsSpacer()],    body: new SceneFlexLayout({      direction: 'column',      children: [new SceneFlexItem({ body: panel })],    }),  });}

// src/components/scenes/MyFeature/scene.tsximport {  EmbeddedScene, SceneFlexLayout, SceneFlexItem,  SceneQueryRunner, SceneVariableSet, QueryVariable,  PanelBuilders, VariableValueSelectors, SceneControlsSpacer,} from '@grafana/scenes';
export function getMyFeatureScene(params: { datasource: DataSourceRef }) {  const queryRunner = new SceneQueryRunner({    datasource: params.datasource,    queries: [{ refId: 'A', expr: 'up{cluster=~"$cluster"}', instant: true, format: 'table' }],  });
  const panel = PanelBuilders.table()    .setData(queryRunner)    .setTitle('My Table')    .build();
  return new EmbeddedScene({    $variables: new SceneVariableSet({      variables: [        new QueryVariable({          name: 'cluster',          query: 'label_values(up, cluster)',          datasource: params.datasource,          isMulti: true, includeAll: true, defaultToAll: true,        }),      ],    }),    controls: [new VariableValueSelectors({}), new SceneControlsSpacer()],    body: new SceneFlexLayout({      direction: 'column',      children: [new SceneFlexItem({ body: panel })],    }),  });}

2. Create the page

typescript

// src/components/scenes/MyFeature/MyFeature.tsximport { SceneAppPage, SceneTimeRange } from '@grafana/scenes';
export function getMyFeaturePage(params) {  return new SceneAppPage({    title: 'My Feature',    url: '/a/my-plugin-id/my-feature',    routePath: 'my-feature/*',    $timeRange: new SceneTimeRange({ from: 'now-1h', to: 'now' }),    getScene: () => getMyFeatureScene(params),    drilldowns: [],  });}

// src/components/scenes/MyFeature/MyFeature.tsximport { SceneAppPage, SceneTimeRange } from '@grafana/scenes';
export function getMyFeaturePage(params) {  return new SceneAppPage({    title: 'My Feature',    url: '/a/my-plugin-id/my-feature',    routePath: 'my-feature/*',    $timeRange: new SceneTimeRange({ from: 'now-1h', to: 'now' }),    getScene: () => getMyFeatureScene(params),    drilldowns: [],  });}

3. Register in SceneApp

Add the page to the SceneApp pages array in the root scene file.

Key Patterns

Drilldowns (click-through navigation)

typescript

drilldowns: [{  routePath: ':cluster/*',  getPage: (match, parent) => new SceneAppPage({    title: decodeURIComponent(match.params.cluster),    url: `${parent.state.url}/${match.params.cluster}`,    routePath: `${match.params.cluster}/*`,    getScene: () => detailScene(decodeURIComponent(match.params.cluster)),  }),}]

drilldowns: [{  routePath: ':cluster/*',  getPage: (match, parent) => new SceneAppPage({    title: decodeURIComponent(match.params.cluster),    url: `${parent.state.url}/${match.params.cluster}`,    routePath: `${match.params.cluster}/*`,    getScene: () => detailScene(decodeURIComponent(match.params.cluster)),  }),}]

Tabs (sub-pages within a detail view)

Pass tabs: [SceneAppPage, ...] instead of getScene on a SceneAppPage. Each tab is itself a SceneAppPage with its own scene.

Query with transformations

Wrap a SceneQueryRunner in SceneDataTransformer to apply Grafana transforms or custom RxJS operators:

typescript

new SceneDataTransformer({  $data: queryRunner,  transformations: [    { id: 'organize', options: { renameByName: { 'Value #A': 'CPU' } } },    (ctx) => (source) => source.pipe(map((frames) => /* custom transform */)),  ],})

new SceneDataTransformer({  $data: queryRunner,  transformations: [    { id: 'organize', options: { renameByName: { 'Value #A': 'CPU' } } },    (ctx) => (source) => source.pipe(map((frames) => /* custom transform */)),  ],})

Custom scene object

Extend SceneObjectBase with a static Component for custom interactive UI:

typescript

class MyWidget extends SceneObjectBase<MyWidgetState> {  static Component = ({ model }: SceneComponentProps<MyWidget>) => {    const state = model.useState();    return <div>{state.value}</div>;  };}

class MyWidget extends SceneObjectBase<MyWidgetState> {  static Component = ({ model }: SceneComponentProps<MyWidget>) => {    const state = model.useState();    return <div>{state.value}</div>;  };}

Table column overrides

Build ConfigOverrideRule objects for drill-down links, filtering, units, widths, custom cells.

Panel types

PanelBuilders.table(), .timeseries(), .stat(), .gauge(), .barchart() — chain .setData(), .setTitle(), .setUnit(), .setOption(), .setOverrides(), then .build().

Common Pitfalls

Always use routePath: 'path/*' (with wildcard) on pages that have drilldowns or tabs
encodeURIComponent/decodeURIComponent URL params — K8s names can contain /
Variables referenced in queries as $varName must exist in an ancestor SceneVariableSet
getScene is called lazily; don't create side effects in the factory
For instant queries, set both instant: true and format: 'table'

Resources

来源与署名

来源：grafana/skills位于skills/grafana-plugins/grafana-scenes提交1ccacf2

许可证： Apache-2.0

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

Grafana Scenes

@grafana/scenes Framework

Core Concepts

Quick Start: New Scene Page

1. Create the scene file

2. Create the page

3. Register in SceneApp

Key Patterns

Drilldowns (click-through navigation)

Tabs (sub-pages within a detail view)

Query with transformations

Custom scene object

Table column overrides

Panel types

Common Pitfalls

Resources

来源与署名

更多来自 grafana/skills 的技能

React 19 Plugin Migration

Plugin Bundle Size

Check Npm

Mimir

K6 Trend Analysis

K6 Test Maintenance

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices