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