网格布局 ​

网格布局把直接子组件按行列自动排布。它会根据容器尺寸、间距和四边内边距计算每个格子的最终矩形，适合规则列表、物品展示和菜单按钮组。

布局的 visible 或 visibleWhen 变为不可见时，全部后代会一起退出布局计算、渲染、Tooltip 与交互；更深层后代也不会越过隐藏祖先单独显示。重新显示布局后，后代会按各自条件恢复。

适用场景 ​

• 物品、奖励和配方网格
• 多按钮菜单
• 规则排列的状态卡片
• 不希望手动计算每个子组件坐标的页面

通用配置 ​

专属配置 ​

布局组件只组织坐标、裁剪和组件树，不使用根级 scale、rotation 或 opacity。

布局组件可以通过 dragMode 让玩家整体移动这一组内容。拖动布局时，它的全部后代会一起显示在新位置，但原始布局公式和 parent 关系不会改变。temporary 只保留当前页面会话中的偏移；remember 会在松开后记住位置，下次打开同一页面继续使用。已有记忆即使后来改为 off 也会继续生效，直到脚本或管理员执行重置。

运行时修改行列 ​

脚本可动态写入 layoutGrid.rows 与 layoutGrid.columns：

component("reward_grid").layoutGrid.rows = 7
component("reward_grid").layoutGrid.columns = vars.columns
组件("reward_grid").网格布局.行数 = 7
组件("reward_grid").网格布局.列数 = 6

值必须是有限正整数；0、负数、小数、字符串和布尔值会让当前语句报脚本错误，后续独立语句继续执行。修改只作用于当前页面会话，不写回页面文件，下一帧布局快照会使用新行列并保持原有子组件顺序。

子组件排布规则 ​

网格只自动排布直接子组件，并按页面 elements 中的顺序从左到右、从上到下放置。

直接子组件自身的 layout.x、layout.y、layout.width、layout.height 不决定最终格子矩形，但这些字段仍需存在并通过公式校验。请确保 rows × columns 足以容纳所有直接子组件，避免多余组件落入重复位置。

格子尺寸计算会扣除四边内边距和所有间距，再平均分配剩余宽高。整数除法产生的少量余数不会继续分配。

使用公式和负内边距 ​

间距与四边内边距可以像 layout.x、layout.y、layout.width、layout.height 一样填写公式。公式会在页面显示时根据当前尺寸和数值重新计算，并四舍五入到 GUI 像素。

• self.width、self.height 表示网格容器自己的最终宽高。
• parent.width、parent.height 表示网格容器父级的最终宽高；网格没有父级时使用页面窗口大小。
• window.width、window.height 表示当前页面窗口大小。
• vars.xxx 读取页面变量，vals.xxx 读取当前可用的只读数值。

gapX 与 gapY 表示格子之间的距离，因此固定数字不能小于 0。四个内边距可以为负：负左内边距让第一列向左伸出，负右内边距会增加右侧可用空间，上下方向同理。

负内边距不会关闭父级或页面现有的裁剪。如果格子伸出可视区域后被截断，请检查滚动布局、子页面或页面边界的裁剪设置。

配置示例 ​

- id: reward_grid
  type: layout_grid
  parent: ""
  visible: true
  enabled: false
  z: 0
  layout:
    x: 20
    y: 20
    width: 140
    height: 62
  layoutGrid:
    rows: 2
    columns: 2
    gapX: "self.width / 35"
    gapY: "self.height / 16"
    paddingLeft: -4
    paddingTop: "-parent.height / 100"
    paddingRight: 4
    paddingBottom: "window.height / 100"
  tooltip: []
  events: {}

- id: reward_one
  type: item_display
  parent: reward_grid
  visible: true
  enabled: false
  z: 1
  layout:
    x: 0       # 网格直接子组件最终矩形由父布局计算
    y: 0
    width: 18
    height: 18
  itemDisplay:
    itemId: minecraft:diamond
    itemCount: 1

常见问题 ​

修改子组件宽高为什么没有效果 ​

网格直接子组件使用格子最终矩形。请修改网格容器尺寸、行列、间距或内边距。

子组件顺序不对 ​

网格按页面元素顺序排布。可以在编辑器中调整创建/复制与页面结构，确保直接子组件顺序符合预期。

最后一行组件重叠 ​

检查直接子组件数量是否超过 rows × columns，并增加行数或列数。

间距公式为什么变成了 0 ​

检查公式是否完整、引用的 vars 或 vals 是否存在，以及结果是否为有限数字。横向和纵向间距不能为负；需要让格子向容器外扩展时，请改用对应方向的负内边距。