绝对布局

绝对布局用于组织组件树、提供父级公式变量和统一删除范围。它不会把自己的 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、rotation 或 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: true
  dragMode: remember
  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 + (parent.width - self.width) / 2 # 绝对布局需显式叠加父级位置
    y: parent.y + 8
  text:
    value: 绝对布局标题
    textSize: 1
    align: center

常见问题

怎样拖动整组组件

上面的 root_group 已启用位置记忆。拖动布局区域内的空白处，标题及其他通过 parent: root_group 归入布局的组件会一起移动，下次打开页面会继续使用记住的位置。嵌套布局的后代也会跟随，未归入该布局的组件不受影响。

若背景图片、文字或其他装饰挡住了指针，可给它们配置 pointerEvents: pass，让拖动落到父布局上。需要点击的按钮和输入框继续保留自己的交互；布局自身不能设置为穿透，也不能禁用。布局宽高应按面板的实际范围填写，填满整个页面的布局会受到页面边界限制，无法继续向外拖动。

子组件为什么跑到屏幕左上角

绝对布局不自动叠加父级位置。需要使用 parent.x + ...、parent.y + ...，或直接填写页面全局坐标。

绝对布局为什么看不到背景

布局组件本身不绘制背景。需要添加矩形或图片子组件，并用 parent.width、parent.height 填满布局区域。

绝对布局 ​

适用场景 ​

通用配置 ​

专属配置 ​

坐标行为 ​

配置示例 ​

常见问题 ​

怎样拖动整组组件 ​

子组件为什么跑到屏幕左上角 ​

绝对布局为什么看不到背景 ​