构建场景布局

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

弹性盒布局

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

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。
SceneFlexLayoutmaxWidth、maxHeight、height或width约束被移除。
SceneFlexLayout和SceneFlexItem使用父布局上设置的minHeight或height（除非在其中直接指定）。这是为了强制在方向为row的SceneFlexLayout上设置的height或minHeight限制也应用于其子元素，以便在触发更改方向为column的响应式媒体查询时，这些限制将继续对子元素起作用。

这些行为会在与 Grafana 的 theme.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(),
  }),
});

源代码

查看示例源代码

弹性盒布局​

步骤 1. 创建一个场景​

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

步骤 3. 添加布局子元素​

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

响应式弹性布局​

CSS 网格布局​

网格布局​

步骤 1. 创建一个场景​

步骤 2. 配置网格布局​

步骤 3. 添加布局子元素​

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

步骤 5. 添加网格行​

分割布局​

步骤 1. 创建一个场景​

步骤 2. 配置分割布局​

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

源代码​

弹性盒布局

步骤 1. 创建一个场景

步骤 2. 配置弹性盒布局

步骤 3. 添加布局子元素

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

响应式弹性布局

CSS 网格布局

网格布局

步骤 1. 创建一个场景

步骤 2. 配置网格布局

步骤 3. 添加布局子元素

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

步骤 5. 添加网格行

分割布局

步骤 1. 创建一个场景

步骤 2. 配置分割布局

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

源代码