构建场景布局

场景支持两种布局类型：弹性布局和网格布局。在本指南中，您将了解如何使用和配置 SceneFlexLayout 和 SceneGridLayout。

Flexbox 布局

SceneFlexLayout 允许您使用浏览器 CSS 弹性框布局构建灵活的场景。这使您能够定义非常动态的布局，其中面板的宽度和高度可以适应可用空间。

步骤 1. 创建场景

通过创建一个将 body 配置为 SceneFlexLayout 的场景来开始使用弹性盒布局。

const scene = new EmbeddedScene({
  body: new SceneFlexLayout({}),
});

步骤 2. 配置弹性盒布局

SceneFlexLayout 允许配置弹性盒行为。您可以配置以下属性：

direction - 配置弹性盒布局的主轴。放置在布局内的子项遵循其方向。
wrap - 配置布局子项的行为。默认情况下，子项尝试适应一行。

默认情况下，SceneFlexLayout 使用 row 方向。要创建列布局，请使用以下代码：

const scene = new EmbeddedScene({
  body: new SceneFlexLayout({
    direction: 'column',
  }),
});

步骤 3. 添加布局子项

SceneFlexLayout 有一个 children 属性。它接受一个由 SceneFlexItem 或 SceneFlexLayout 对象组成的数组。创建一个具有两个、大小相等的列布局项的场景。

const scene = new EmbeddedScene({
  body: new SceneFlexLayout({
    direction: 'column',
    children: [new SceneFlexItem({ minHeight: 200 }), new SceneFlexItem({ minHeight: 300 })],
  }),
});

Both SceneFlexLayout 和 SceneFlexItem 对象类型接受以下配置选项，允许大小约束和行为

  flexGrow?: CSSProperties['flexGrow'];
  alignSelf?: CSSProperties['alignSelf'];
  width?: CSSProperties['width'];
  height?: CSSProperties['height'];
  minWidth?: CSSProperties['minWidth'];
  minHeight?: CSSProperties['minHeight'];
  maxWidth?: CSSProperties['maxWidth'];
  maxHeight?: CSSProperties['maxHeight'];
  xSizing?: 'fill' | 'content';
  ySizing?: 'fill' | 'content';
  // For sizing constaints on smaller screens
  md?: SceneFlexItemPlacement;

我们强烈建议为使用 column 方向的布局的所有子项设置 minHeight。这确保它们在较小屏幕上不会被过度压缩。如果您在 SceneFlexLayout 对象上设置了 minHeight 或 height，则无需在每个子项上设置它，因为它们将继承这些约束。

步骤 4. 将面板添加到弹性布局项

上一个示例设置了场景的布局。要可视化数据，请配置 SceneQueryRunner 并将其添加到场景中。

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

const scene = new EmbeddedScene({
  $data: queryRunner,
  body: new SceneFlexLayout({
    direction: 'column',
    children: [new SceneFlexItem({}), new SceneFlexItem({})],
  }),
});

接下来，将 VizPanel 对象添加为布局项的 body。

const queryRunner = new SceneQueryRunner({
  datasource: {
    type: 'prometheus',
    uid: '<PROVIDE_GRAFANA_DS_UID>',
  },
  queries: [
    {
      refId: 'A',
      expr: 'rate(prometheus_http_requests_total{}[5m])',
    },
  ],
});

const scene = new EmbeddedScene({
  $data: queryRunner,
  body: new SceneFlexLayout({
    direction: 'column',
    children: [
      new SceneFlexItem({
        body: PanelBuilders.timeseries().setTitle('Time series').build(),
      }),
      new SceneFlexItem({
        body: PanelBuilders.table().setTitle('Table').build(),
      }),
    ],
  }),
});

这将渲染两个面板，一个是时间序列面板，另一个是表格面板。

注意

对于包含 VizPanel 对象的 SceneFlexItems，建议您设置 minHeight 或 minWidth 约束，以避免面板因屏幕空间有限而过度压缩。

响应式弹性布局

默认情况下，SceneFlexLayout 对小屏幕有一些响应式行为。

SceneFlexLayout 的方向从 row 更改为 column。
移除了 SceneFlexLayout 的 maxWidth、maxHeight、height 或 width 约束。
SceneFlexLayout 和 SceneFlexItem 使用父布局上设置的 minHeight 或 height（除非直接在它上指定）。这是为了确保在 SceneFlexLayout 上设置方向为 row 的 height 或 minHeight 约束也应用于其子项，以便当响应式媒体查询触发方向更改为 column 时，这些约束继续作用于子项。

这些行为适用于与 Grafana 的主题断点 breakpoints.down('md') 匹配的屏幕。

您可以使用存在于 SceneFlexLayout 和 SceneFlexItem 上的 md 属性来覆盖这些行为并设置自定义方向和大小约束。例如

new SceneFlexLayout({
  direction: 'row',
  minHeight: 200,
  md: {
    minHeight: 100,
    direction: 'row',
  },
  children: [getStatPanel({}), getStatPanel({})],
}),

在上面的示例中，我们使用 md 属性覆盖了默认的响应式行为，该行为将行布局更改为列布局。我们还应用了一个更紧的 minHeight 约束。

CSS 网格布局

作为 SceneFlexLayout 的替代方案，SceneCSSGridLayout 可用于将场景项包裹在 CSS 网格中。

const scene = new EmbeddedScene({
  body: new SceneCSSGridLayout({
    templateColumns: `repeat(auto-fit, minmax(400px, 1fr))`,
    children: [
      PanelBuilders.timeseries().setTitle('Graph 1').build(),
      PanelBuilders.timeseries().setTitle('Graph 2').build(),
    ],
  }),
});

SceneCSSGridLayout 接受与 SceneFlexLayout 相同的 children，并具有以下属性来应用 CSS 网格样式

autoRows?: CSSProperties['gridAutoRows'];
templateRows?: CSSProperties['gridTemplateRows'];
templateColumns: CSSProperties['gridTemplateColumns'];
/** In Grafana design system grid units (8px)  */
rowGap: number;
/** In Grafana design system grid units (8px)  */
columnGap: number;
justifyItems?: CSSProperties['justifyItems'];
alignItems?: CSSProperties['alignItems'];
justifyContent?: CSSProperties['justifyContent'];
// For sizing constaints on smaller screens
md?: SceneCSSGridLayoutState;

使用 CSS 网格可以轻松构建动态面板网格，其中面板大小约束可以针对网格本身而不是每个面板进行指定。这对于构建等尺寸面板的网格非常有用。

下面的网格布局配置为具有最小尺寸为 400px 的子元素，如果有更多空间可用，则将其平均分配。使用 autoRows 设置高度。此配置将启用非常响应式的等尺寸面板布局。

const scene = new EmbeddedScene({
  body: new SceneCSSGridLayout({
    templateColumns: `repeat(auto-fit, minmax(400px, 1fr))`,
    autoRows: '150px',
    rowGap: 2,
    columnGap: 2,
    children: [
      new SceneCSSGridItem({
        body: PanelBuilders.timeseries().setTitle('Time series').build(),
      }),
      new SceneCSSGridItem({
        body: PanelBuilders.table().setTitle('Table').build(),
      }),
      new SceneCSSGridItem({
        body: PanelBuilders.timeseries().setTitle('Time series').build(),
      }),
      new SceneCSSGridItem({
        body: PanelBuilders.table().setTitle('Table').build(),
      }),
    ],
  }),
});

围绕每个子元素的 SceneCSSGridItem 包装器是可选的。

网格布局

SceneGridLayout 允许您构建可以拖动和移动的元素网格场景。这是 Grafana 核心仪表板体验中使用的默认布局。除非您需要让用户能够移动面板，否则不建议用于场景应用插件。

步骤 1. 创建场景

通过创建一个将 body 配置为 SceneGridLayout 的场景来开始使用网格布局。

const scene = new EmbeddedScene({
  $data: queryRunner,
  body: new SceneGridLayout({}),
});

步骤 2. 配置网格布局

SceneGridLayout 允许配置网格行为。提供的网格有 24 列。

您可以配置以下属性

isDraggable - 配置网格项是否可移动。
isLazy - 配置网格项是否在它们位于视口外时初始化。

const scene = new EmbeddedScene({
  $data: queryRunner,
  body: new SceneGridLayout({
    isDraggable: false,
    isLazy: true,
  }),
});

步骤 3. 添加布局子项

SceneGridLayout 有一个 children 属性。它接受一个 SceneGridItem 或 SceneGridRow 对象的数组。创建一个场景，其中包含两行网格项

const scene = new EmbeddedScene({
  $data: queryRunner,
  body: new SceneGridLayout({
    children: [
      new SceneGridItem({
        x: 0,
        y: 0,
        width: 12,
        height: 10,
        isResizable: false,
        isDraggable: false,
      }),
      new SceneGridItem({
        x: 12,
        y: 0,
        width: 12,
        height: 10,
        isResizable: false,
        isDraggable: false,
      }),
    ],
  }),
});

SceneGridItem 接受以下配置选项，这些选项以 24 列网格单位表示

  x?: number;
  y?: number;
  width?: number;
  height?: number;

步骤 4. 向网格布局项添加面板

将 VizPanel 添加到 SceneGridItem 以显示可视化数据

const scene = new EmbeddedScene({
  $data: queryRunner,
  body: new SceneGridLayout({
    children: [
      new SceneGridItem({
        x: 0,
        y: 0,
        width: 12,
        height: 10,
        isResizable: false,
        isDraggable: false,
        body: PanelBuilders.timeseries().setTitle('Time series').build(),
      }),
      new SceneGridItem({
        x: 12,
        y: 0,
        width: 12,
        height: 10,
        isResizable: false,
        isDraggable: false,
        body: PanelBuilders.table().setTitle('Table').build(),
      }),
    ],
  }),
});

步骤 5. 添加网格行

网格行是一个将其他 SceneGridItems 组合到可折叠行的布局项。使用 SceneGridRow 将行添加到场景中

注意

在 SceneGridRow 中，x 和 y 坐标相对于行。

const row = new SceneGridRow({
  x: 0,
  y: 0,
  children: [
    new SceneGridItem({
      x: 0,
      y: 0,
      width: 12,
      height: 10,
      isResizable: false,
      isDraggable: false,
      body: PanelBuilders.timeseries().setTitle('Time series').build(),
    }),
    new SceneGridItem({
      x: 12,
      y: 0,
      width: 12,
      height: 10,
      isResizable: false,
      isDraggable: false,
      body: PanelBuilders.table().setTitle('Table').build(),
    }),
  ],
});

const scene = new EmbeddedScene({
  $data: queryRunner,
  body: new SceneGridLayout({
    children: [row],
  }),
});

分割布局

SplitLayout 允许您通过垂直或水平排列的可调整大小的面板组合来构建场景。

步骤 1. 创建场景

通过创建一个将 body 配置为 SplitLayout 的场景来开始使用分割布局

const scene = new EmbeddedScene({
  $data: queryRunner,
  body: new SplitLayout({}),
});

步骤 2. 配置分割布局

SplitLayout 允许配置多个选项

direction - 配置面板是否按行或列定位。
primary - 第一个面板。
secondary - 第二个面板

const scene = new EmbeddedScene({
  $data: queryRunner,
  body: new SplitLayout({
    direction: 'column',
  }),
});

步骤 3. 提供 `primary` 和 `secondary` 对象

primary 和 secondary 都接受一个 SceneFlexItemLike 对象。

const scene = new EmbeddedScene({
  $data: queryRunner,
  body: new SplitLayout({
    direction: 'column',
    primary: PanelBuilders.timeseries().setTitle('Primary panel').build(),
    secondary: PanelBuilders.table().setTitle('Secondary panel').build(),
  }),
});

源代码

查看示例源代码

Flexbox 布局​

步骤 1. 创建场景​

步骤 2. 配置弹性盒布局​

步骤 3. 添加布局子项​

步骤 4. 将面板添加到弹性布局项​

响应式弹性布局​

CSS 网格布局​

网格布局​

步骤 1. 创建场景​

步骤 2. 配置网格布局​

步骤 3. 添加布局子项​

步骤 4. 向网格布局项添加面板​

步骤 5. 添加网格行​

分割布局​

步骤 1. 创建场景​

步骤 2. 配置分割布局​

步骤 3. 提供 primary 和 secondary 对象​

源代码​

Flexbox 布局

步骤 1. 创建场景

步骤 2. 配置弹性盒布局

步骤 3. 添加布局子项

步骤 4. 将面板添加到弹性布局项

响应式弹性布局

CSS 网格布局

网格布局

步骤 1. 创建场景

步骤 2. 配置网格布局

步骤 3. 添加布局子项

步骤 4. 向网格布局项添加面板

步骤 5. 添加网格行

分割布局

步骤 1. 创建场景

步骤 2. 配置分割布局

步骤 3. 提供 `primary` 和 `secondary` 对象

源代码