跳到主要内容

Grid 控件介绍

Grid 用于把一个页面划分为稳定、可复用的响应式区域。它适合仪表盘、详情页、主内容加侧栏、等宽卡片组等布局；每个区域中仍可以继续放 Form、Common Panel、ProTable、DataList 或其他内容控件。

阅读本手册后，你可以完成以下配置：

  • 理解 Grid、Grid Row 和 Grid Column 的三层结构
  • 使用 24 列栅格配置等分、主次和整行布局
  • 配置列间距、行间距、水平排列和垂直对齐
  • 设置列的最小高度，同时保留内容自适应
  • 组合 Grid 与 Form、Panel 和数据控件
  • 判断什么时候需要后端接口，什么时候只需要页面布局
  • 排查列换行、宽度不符合预期和设计态/运行态差异

1. 示例：活动运营看板​

Spark Sample 的 Grid 页面使用一个活动运营看板展示三种常用组合：

行列跨度用途
Equal Thirds8 + 8 + 8三个等宽指标卡
Main and Sidebar16 + 8活动详情与发布检查侧栏
Equal Halves12 + 12日程和受众两个等宽区域

页面结构如下：

Screen
└── Grid: Campaign Dashboard Grid
    ├── Row: Equal Thirds
    │   ├── Column 8/24 → Audience Reach
    │   ├── Column 8/24 → Conversion
    │   └── Column 8/24 → Budget
    ├── Row: Main and Sidebar
    │   ├── Column 16/24 → Campaign Details
    │   └── Column 8/24  → Release Checklist
    └── Row: Equal Halves
        ├── Column 12/24 → Schedule
        └── Column 12/24 → Audience

这个示例只演示页面布局，数据使用字段初始值，不依赖后端 Sample API。需要真实数据时，把对应 Form 换成 Data Form，或在列中放置 DataList、ProTable 等数据控件即可。

2. Grid 的三层结构​

Grid 不是一个直接摆放内容的单层容器，而是三层结构：

  1. Grid：控制所有行的水平排列和垂直对齐。
  2. Grid Row：代表一行，控制该行的列间距和换行后的行间距。
  3. Grid Column：占据 24 列中的若干格，并承载 Panel、Form、Tree 或其他内容。

配置时不要把 Form 直接添加到 Grid 或 Row。正确顺序是：

Grid → Grid Row → Grid Column → Common Panel / Form / data component

3. 添加 Grid​

  1. 打开目标页面并进入 Page Designer。
  2. 在页面结构中选择 Screen。
  3. 在 Screen 的 Grid 子元素区域添加 Grid。
  4. 选择 Grid，在 Rows 区域添加 Grid Row。
  5. 选择 Grid Row，在 Columns 区域添加一个或多个 Grid Column。
  6. 选择每个 Grid Column，设置 Span Columns。
  7. 在列的 Panels 区域添加 Common Panel、Form、ProTable 或其他内容。
  8. 保存页面，并分别检查设计画布和运行态。

新建 Grid Column 默认占 24/24，因此第一次添加时会显示为整行，不会成为几乎看不见的窄列。

4. 使用 24 列栅格​

每个 Grid Row 被划分为 24 个等宽逻辑格。Span Columns 决定一列占多少格，有效范围为 1～24。

常用组合：

目标布局Span Columns
单列整行24
两个等宽区域12 + 12
三个等宽区域8 + 8 + 8
四个等宽区域6 + 6 + 6 + 6
主内容加侧栏16 + 8 或 18 + 6
左侧栏加主内容6 + 18 或 8 + 16

同一行各列的跨度之和建议等于 24。小于 24 时会留下空白，空白位置由 Grid 的 Horizontal Alignment 决定；大于 24 时，超出的列会自动换到下一行。

Column Gap 是列之间的视觉间距，不需要从 24 中扣除。例如 8 + 8 + 8 配合 16px Column Gap 仍然是一整行。

5. 配置行间距​

选择 Grid Row，可以设置：

属性范围说明
Column Gap0～64同一行相邻列之间的水平间距，单位为像素
Row Gap0～64列发生换行时，上下两排之间的垂直间距，单位为像素

常规业务页面建议从 12～20 开始。多个 Row 之间还会保留页面设计系统的标准间距，因此不要为了“拉开整行”而把 Row Gap 设置得过大。

6. 配置对齐​

选择外层 Grid，可以设置：

6.1 Horizontal Alignment​

值效果
start从行首排列，最常用
end靠行尾排列
center整体居中
space-between首尾贴边，剩余空间分布在列之间
space-around每列两侧分配空间

当一行跨度刚好等于 24 时，通常没有额外水平空间，此时几个值看起来可能相同。要观察差异，可临时使用总跨度小于 24 的列组合，例如 8 + 8。

6.2 Vertical Alignment​

值效果
top列顶部对齐，最适合内容卡片
middle列在当前行中垂直居中
bottom列底部对齐

只有同一行各列高度不同时，垂直对齐差异才明显。

7. 设置列最小高度​

选择 Grid Column，使用 Minimum Column Height 设置该列的最低高度，范围为 0～1200 像素：

  • 0：高度跟随内容自动增长，默认且最安全。
  • 大于 0：内容较少时保留指定的最低高度；内容更多时仍会继续增长，不会被裁切。

同一行的卡片需要视觉上接近等高时，可以给这些列设置相同的最小高度。不要用过大的固定值制造空白；Grid 不会把 Minimum Column Height 当成最大高度。

8. 在列中组织内容​

Grid 负责页面区域，列内控件负责业务内容。推荐组合：

  • Common Panel + Form：有标题的详情卡片或指标卡。
  • Form：无额外卡片标题的输入区。
  • ProTable / DataList：列表与主区域、筛选区或侧栏组合。
  • Tree：Tree 通常应使用 Screen 的专用 Navigation Tree 区域；只有业务确实需要把树作为普通内容时才放入 Grid Column。

Grid 本身不保存业务数据，也不替代 Form 的 Controls Per Row 和 Form Grid Split。外层 Grid 决定页面区域宽度，Form 的列数和标签比例只在该区域内部计算。

9. 按示例复现​

按以下步骤可以复现 Spark Sample 的主要结构：

  1. 添加一个 Grid，Horizontal Alignment 设为 start，Vertical Alignment 设为 top。
  2. 添加第一行，Column Gap 和 Row Gap 都设为 16。
  3. 添加三个 Grid Column，Span Columns 都设为 8，Minimum Column Height 都设为 156。
  4. 每列添加一个 Common Panel，再添加一个只读单列表单，分别展示 Reach、Conversion 和 Budget。
  5. 添加第二行，间距同样设为 16；添加 16 和 8 两列，最小高度都设为 228。
  6. 在 16 列中放置两列 Form，在 8 列中放置单列检查清单 Form。
  7. 添加第三行，使用 12 + 12，最小高度设为 176。
  8. 保存后缩窄浏览器窗口，确认窄屏下各列按顺序堆叠为单列。

10. 响应式行为​

PC 宽度下，Grid 按 24 列跨度显示。手机或窄屏下，列会按配置顺序改为单列堆叠，避免把表单和卡片挤成无法阅读的窄条。

响应式堆叠不改变 Page JSON，也不会删除 Span Columns；恢复到较宽窗口后会重新按照原跨度排列。请按照阅读优先级安排列顺序，重要内容放在前面。

11. 后端与交互​

Grid 是纯布局控件，本身不发起请求，因此普通 Grid 示例不需要 Java 后端代码。只有列内的数据控件或 Interaction 需要访问业务数据时，才需要后端：

  • Data Form、DataList、ProTable 按各自 Data Source 请求数据。
  • 按钮、字段或子控件按各自 Interaction 执行动作。
  • 页面请求会统一携带环境和渲染模式；后端集成方式见页面请求上下文与后端调试。

不要把点击或请求动作配置在 Grid Row/Column 上来代替业务控件。交互应配置在真正承担动作的按钮、字段、卡片或数据控件上。

12. 常见问题​

12.1 一行中的列换行了​

检查各列 Span Columns 之和。总和超过 24 时，后面的列会换行；如果只想做两列，可使用 12 + 12、16 + 8 等组合。

12.2 Horizontal Alignment 看不出变化​

当总跨度等于 24 时没有剩余空间。临时改成 8 + 8，再比较 start、center、end 或 space-between。

12.3 Vertical Alignment 看不出变化​

确保同一行至少两列高度不同，或者给其中一列设置更大的 Minimum Column Height。

12.4 列内 Form 的标签比例不正确​

先确认 Grid Column 的宽度，再配置 Form。Form 的 Controls Per Row 会把当前列内部再次分栏，Form Grid Split 按每个控件所占的内部网格计算，不是按整个页面的 24 列计算。

12.5 设计画布和运行态不一致​

先保存页面，并确认运行态使用当前 versionId。如果只有数据不同，检查数据源和 Page Context；如果列宽、间距或对齐不同，检查当前页面是否已保存最新 Grid 属性。

最后于 更新