猹件开发组绝对布局
绝对布局用于组织组件树、提供父级公式变量和统一删除范围。它不会把自己的 X、Y 自动叠加到子组件坐标上，子组件仍按页面全局坐标计算。
布局的 visible 或 visibleWhen 变为不可见时，全部后代会一起退出布局计算、渲染、Tooltip 与交互；更深层后代也不会越过隐藏祖先单独显示。重新显示布局后，后代会按各自条件恢复。
适用场景
- 需要把一组全局定位组件归类
- 子组件通过
parent.x、parent.width等公式自行计算位置 - 希望删除布局时一并删除所有子孙组件
- 从简单页面逐步整理组件层级
通用配置
| 配置项 | 编辑器名称 | 类型 | 默认值 | 可选值或格式 | 说明 |
|---|---|---|---|---|---|
id | ID | 字符串 | 自动生成 layout_absolute_N | 页面内唯一 ID | 子组件通过 parent 引用它。 |
type | 类型 | 只读字符串 | layout_absolute | 固定值 | 创建后不能修改。 |
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，也作为 parent.x 提供给子组件。 |
layout.y | Y | 数字或公式 | 创建时画布位置 | 合法布局公式 | 布局矩形 Y，也作为 parent.y 提供给子组件。 |
layout.width | 宽 | 数字或公式 | 160 | 合法布局公式 | 布局宽度和 parent.width。 |
layout.height | 高 | 数字或公式 | 90 | 合法布局公式 | 布局高度和 parent.height。 |
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 | 空 | 多行脚本 | 鼠标离开时触发。 |
专属配置
| 配置项 | 编辑器名称 | 类型 | 默认值 | 可选值或格式 | 说明 |
|---|---|---|---|---|---|
| 无额外字段 | — | — | — | — | 绝对布局的行为由通用布局矩形和子组件 parent 决定。 |
布局组件只组织坐标、裁剪和组件树，不使用根级 scale 或 opacity。
布局组件可以通过 dragMode 让玩家整体移动这一组内容。拖动布局时，它的全部后代会一起显示在新位置，但原始布局公式和 parent 关系不会改变。temporary 只保留当前页面会话中的偏移；remember 会在松开后记住位置，下次打开同一页面继续使用。已有记忆即使后来改为 off 也会继续生效，直到脚本或管理员执行重置。
坐标行为
绝对布局的直接子组件会在父级上下文中计算公式，但最终 X、Y 不会自动加上父布局位置。
例如父布局位于 (100, 50)：
- 子组件
x: 10的最终 X 仍是10。 - 子组件
x: parent.x + 10的最终 X 是110。 - 子组件可以使用
parent.width、parent.height和自身尺寸计算居中位置。
配置示例
yaml
- id: root_group
type: layout_absolute
parent: ""
visible: true
enabled: false
z: 0
layout:
x: window.width * 0.5 - 160
y: window.height * 0.5 - 90
width: 320
height: 180
tooltip: []
events: {}
- id: group_title
type: text
parent: root_group
visible: true
enabled: false
z: 1
layout:
x: parent.x + 10 # 绝对布局不会自动叠加，需显式引用 parent.x
y: parent.y + 8
width: parent.width - 20
height: 14
text:
value: 绝对布局标题
textSize: 1
align: center常见问题
子组件为什么跑到屏幕左上角
绝对布局不自动叠加父级位置。需要使用 parent.x + ...、parent.y + ...，或直接填写页面全局坐标。
绝对布局为什么看不到背景
布局组件本身不绘制背景。需要添加矩形或图片子组件，并用 parent.width、parent.height 填满布局区域。