用 @grafana/scenes 构建 Grafana…

在 Grafana 插件中创建基于 @grafana/scenes 的响应式场景页面、面板、变量与下钻导航时使用。

适用场景

解决思路

1. 创建场景文件（如 src/components/scenes/MyFeature/scene.tsx）：从 @grafana/scenes 导入 EmbeddedScene、SceneFlexLayout、SceneFlexItem、SceneQueryRunner、SceneVariableSet、QueryVariable、PanelBuilders、VariableValueSelectors、SceneControlsSpacer。
2. 在场景工厂函数中创建 SceneQueryRunner，传入 datasource 和 queries（如 { refId: 'A', expr: 'up{cluster=~"$cluster"}', instant: true, format: 'table' }）。
3. 用 PanelBuilders.table()（或 .timeseries()/.stat()/.gauge()/.barchart()）链式调用 .setData(queryRunner)、.setTitle()、.setUnit()、.setOption()、.setOverrides()，最后 .build() 生成面板。
4. 在 EmbeddedScene 中通过 $variables: new SceneVariableSet({ variables: [...] }) 定义变量，例如 QueryVariable（name、query、datasource、isMulti、includeAll、defaultToAll）。
5. 在 EmbeddedScene 的 controls 中加入 VariableValueSelectors 和 SceneControlsSpacer，body 使用 SceneFlexLayout（direction: 'column'）并放入 SceneFlexItem 包裹面板。
6. 创建页面文件（如 src/components/scenes/MyFeature/MyFeature.tsx）：用 SceneAppPage 配置 title、url、routePath、$timeRange（如 SceneTimeRange({ from: 'now-1h', to: 'now' })）、getScene 和 drilldowns。
7. 在根场景文件的 SceneApp pages 数组中注册该页面。
8. 配置下钻：在 drilldowns 中提供 { routePath: ':cluster/*', getPage: (match, parent) => new SceneAppPage({...}) }，用 decodeURIComponent(match.params.cluster) 解析参数，url 拼接为 `${parent.state.url}/${match.params.cluster}`。
9. 配置标签页：在 SceneAppPage 上传入 tabs: [SceneAppPage, ...] 而不是 getScene，每个 tab 本身是一个带自己场景的 SceneAppPage。
10. 需要转换时用 SceneDataTransformer 包裹 SceneQueryRunner，在 transformations 中传入 Grafana 转换（如 { id: 'organize', options: { renameByName: { 'Value #A': 'CPU' } } }）或自定义 RxJS 操作符函数 (ctx) => (source) => source.pipe(map(...))。
11. 自定义场景对象：继承 SceneObjectBase<MyWidgetState>，并定义 static Component = ({ model }) => { const state = model.useState(); return ... }。
12. 表格列覆盖：构建 ConfigOverrideRule 对象来实现下钻链接、过滤、单位、宽度、自定义单元格。
13. 页面有下钻或标签页时，routePath 必须使用带通配符的形式（如 'path/*'）。
14. 对 URL 参数使用 encodeURIComponent/decodeURIComponent，因为 K8s 名称可能包含 '/'。
15. 查询中引用的变量（$varName）必须存在于祖先 SceneVariableSet 中。
16. getScene 是惰性调用的，不要在工厂函数中产生副作用。
17. 即时查询需同时设置 instant: true 和 format: 'table'。

适用边界 · 注意事项

• 不使用 @grafana/scenes 框架或非 Grafana 插件项目时不适用。
• 没有 Grafana 插件开发环境（@grafana/scenes 依赖、Plugin Tools）时不适用。