猹件开发组相对布局
相对布局让直接子组件使用父布局内部坐标。子组件先在父级上下文中计算 X、Y，再自动叠加父布局的最终位置，适合整体移动的面板和复用组件组。
布局的 visible 或 visibleWhen 变为不可见时，全部后代会一起退出布局计算、渲染、Tooltip 与交互；更深层后代也不会越过隐藏祖先单独显示。重新显示布局后，后代会按各自条件恢复。
适用场景
- 面板整体移动时保持内部组件相对位置
- 弹窗、卡片、菜单项和组合控件
- 使用
parent.width、parent.height制作内部响应式布局 - 在其他布局中嵌套一组局部组件
通用配置
| 配置项 | 编辑器名称 | 类型 | 默认值 | 可选值或格式 | 说明 |
|---|---|---|---|---|---|
id | ID | 字符串 | 自动生成 layout_relative_N | 页面内唯一 ID | 子组件通过 parent 引用。 |
type | 类型 | 只读字符串 | layout_relative | 固定值 | 创建后不能修改。 |
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 | 空 | 多行脚本 | 鼠标离开时触发。 |
专属配置
| 配置项 | 编辑器名称 | 类型 | 默认值 | 可选值或格式 | 说明 |
|---|---|---|---|---|---|
| 无额外字段 | — | — | — | — | 相对布局的行为由通用布局矩形和子组件 parent 决定。 |
布局组件只组织坐标、裁剪和组件树，不使用根级 scale、rotation 或 opacity。
布局组件可以通过 dragMode 让玩家整体移动这一组内容。拖动布局时，它的全部后代会一起显示在新位置，但原始布局公式和 parent 关系不会改变。temporary 只保留当前页面会话中的偏移；remember 会在松开后记住位置，下次打开同一页面继续使用。已有记忆即使后来改为 off 也会继续生效，直到脚本或管理员执行重置。
坐标行为
父布局位于 (100, 50) 时，直接子组件 x: 10、y: 8 的最终位置是 (110, 58)。子组件宽高仍由自己的公式决定。
子组件公式中的 parent.x 和 parent.y 是父布局最终坐标。通常内部定位只需填写局部数字；如果再次把 parent.x 加入子组件 X，会造成重复偏移。
配置示例
yaml
- id: dialog
type: layout_relative
parent: ""
visible: true
enabled: false
z: 0
layout:
x: window.width * 0.5 - 100
y: window.height * 0.5 - 60
width: 200
height: 120
tooltip: []
events: {}
- id: dialog_title
type: text
parent: dialog
visible: true
enabled: false
z: 1
layout:
x: (parent.width - self.width) / 2 # 自动叠加 dialog.x，并按文字宽度居中
y: 8
text:
value: 相对布局标题
textSize: 1
align: center常见问题
子组件偏移了两次
相对布局已经自动叠加父布局位置。内部 X、Y 通常不要再写 parent.x + ... 或 parent.y + ...。
移动父布局后子组件是否需要逐个修改
不需要。直接子组件会跟随父布局整体移动，这正是相对布局的主要用途。