猹件开发组网格布局
网格布局把直接子组件按行列自动排布。它会根据容器尺寸、间距和四边内边距计算每个格子的最终矩形，适合规则列表、物品展示和菜单按钮组。
布局的 visible 或 visibleWhen 变为不可见时，全部后代会一起退出布局计算、渲染、Tooltip 与交互；更深层后代也不会越过隐藏祖先单独显示。重新显示布局后，后代会按各自条件恢复。
适用场景
- 物品、奖励和配方网格
- 多按钮菜单
- 规则排列的状态卡片
- 不希望手动计算每个子组件坐标的页面
通用配置
| 配置项 | 编辑器名称 | 类型 | 默认值 | 可选值或格式 | 说明 |
|---|---|---|---|---|---|
id | ID | 字符串 | 自动生成 layout_grid_N | 页面内唯一 ID | 子组件通过 parent 引用。 |
type | 类型 | 只读字符串 | layout_grid | 固定值 | 创建后不能修改。 |
parent | 父级 | 字符串 | 空 | 布局组件 ID | 可嵌套在其他布局中。 |
z | 层级 | 整数 | 0 | 任意整数 | 布局自身层级。 |
visible | 显示 | 布尔值 | true | true、false | 静态显隐开关。 |
enabled | 启用 | 布尔值 | true | true、false | 控制布局自身事件。 |
pointerEvents | 指针处理 | 枚举 | auto | auto、block、pass | 配置事件或提示后 auto 命中；block 强制遮挡，pass 永远穿透。 |
dragMode | 拖拽 | 枚举 | off | off、temporary、remember | 关闭拖动、仅本次页面保留位置，或在本地记住布局位置。 |
visibleWhen | 显示条件 | 条件表达式 | 空 | 只读条件 | 条件为假时不可见。 |
enabledWhen | 启用条件 | 条件表达式 | 空 | 只读条件 | 条件为假时禁用。 |
tooltip | 多行提示 | 字符串列表 | 空 | 最多 32 行，每行最多 256 字符 | 布局区域悬浮提示。 |
layout.x | X | 数字或公式 | 创建时画布位置 | 合法布局公式 | 网格容器左上角 X。 |
layout.y | Y | 数字或公式 | 创建时画布位置 | 合法布局公式 | 网格容器左上角 Y。 |
layout.width | 宽 | 数字或公式 | 160 | 合法布局公式 | 用于计算格子宽度。 |
layout.height | 高 | 数字或公式 | 90 | 合法布局公式 | 用于计算格子高度。 |
events.leftPress/rightPress/middlePress | 按下脚本 | ChaUI Script | 空 | 多行脚本 | 对应按键按下时触发。 |
events.leftRelease/rightRelease/middleRelease | 松开脚本 | ChaUI Script | 空 | 多行脚本 | 对应按键捕获仍有效并松开时触发。 |
events.leftClick | 左键脚本 | ChaUI Script | 空 | 多行脚本 | 左键事件。 |
events.rightClick | 右键脚本 | ChaUI Script | 空 | 多行脚本 | 右键事件。 |
events.middleClick | 中键脚本 | ChaUI Script | 空 | 多行脚本 | 中键事件。 |
events.hoverEnter | 悬浮进入脚本 | ChaUI Script | 空 | 多行脚本 | 鼠标进入时触发。 |
events.hoverLeave | 悬浮离开脚本 | ChaUI Script | 空 | 多行脚本 | 鼠标离开时触发。 |
专属配置
| 配置项 | 编辑器名称 | 类型 | 默认值 | 可选值或格式 | 说明 |
|---|---|---|---|---|---|
layoutGrid.rows | 行数 | 正整数 | 2 | 1 以上整数 | 网格行数。 |
layoutGrid.columns | 列数 | 正整数 | 2 | 1 以上整数 | 网格列数。 |
layoutGrid.gapX | 横向间距 | 非负整数 | 0 | 像素 | 相邻列之间的间距。 |
layoutGrid.gapY | 纵向间距 | 非负整数 | 0 | 像素 | 相邻行之间的间距。 |
layoutGrid.paddingLeft | 左内边距 | 非负整数 | 0 | 像素 | 容器左边缘到格子的距离。 |
layoutGrid.paddingTop | 上内边距 | 非负整数 | 0 | 像素 | 容器上边缘到格子的距离。 |
layoutGrid.paddingRight | 右内边距 | 非负整数 | 0 | 像素 | 容器右侧预留空间。 |
layoutGrid.paddingBottom | 下内边距 | 非负整数 | 0 | 像素 | 容器底部预留空间。 |
布局组件只组织坐标、裁剪和组件树，不使用根级 scale 或 opacity。
布局组件可以通过 dragMode 让玩家整体移动这一组内容。拖动布局时，它的全部后代会一起显示在新位置，但原始布局公式和 parent 关系不会改变。temporary 只保留当前页面会话中的偏移；remember 会在松开后记住位置，下次打开同一页面继续使用。已有记忆即使后来改为 off 也会继续生效，直到脚本或管理员执行重置。
子组件排布规则
网格只自动排布直接子组件，并按页面 elements 中的顺序从左到右、从上到下放置。
直接子组件自身的 layout.x、layout.y、layout.width、layout.height 不决定最终格子矩形，但这些字段仍需存在并通过公式校验。请确保 rows × columns 足以容纳所有直接子组件，避免多余组件落入重复位置。
格子尺寸计算会扣除四边内边距和所有间距，再平均分配剩余宽高。整数除法产生的少量余数不会继续分配。
配置示例
yaml
- 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: 4
gapY: 4
paddingLeft: 4
paddingTop: 4
paddingRight: 4
paddingBottom: 4
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，并增加行数或列数。