猹件开发组滚动布局
滚动布局用于显示大于容器可视区域的内容。直接子组件按父级相对坐标计算，再减去横向和纵向滚动量；开启裁剪后，超出容器的显示和交互都会被限制。
布局的 visible 或 visibleWhen 变为不可见时，全部后代会一起退出布局计算、渲染、Tooltip 与交互；更深层后代也不会越过隐藏祖先单独显示。重新显示布局后，后代会按各自条件恢复。
适用场景
- 超出固定面板高度的内容
- 分段说明、任务列表和长菜单
- 需要预设查看位置的横向或纵向内容
- 需要裁剪子组件显示与点击范围的容器
通用配置
| 配置项 | 编辑器名称 | 类型 | 默认值 | 可选值或格式 | 说明 |
|---|---|---|---|---|---|
id | ID | 字符串 | 自动生成 layout_scroll_N | 页面内唯一 ID | 子组件通过 parent 引用。 |
type | 类型 | 只读字符串 | layout_scroll | 固定值 | 创建后不能修改。 |
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 | 空 | 多行脚本 | 鼠标离开时触发。 |
专属配置
| 配置项 | 编辑器名称 | 类型 | 默认值 | 可选值或格式 | 说明 |
|---|---|---|---|---|---|
layoutScroll.scrollX | 横向滚动 | 非负整数 | 0 | 像素 | 所有直接子组件最终 X 减去该值。 |
layoutScroll.scrollY | 纵向滚动 | 非负整数 | 0 | 像素 | 所有直接子组件最终 Y 减去该值。 |
layoutScroll.clip | 裁剪隐藏 | 布尔值 | true | true、false | 为真时裁剪超出容器的显示和交互；为假时允许溢出。 |
布局组件只组织坐标、裁剪和组件树，不使用根级 scale 或 opacity。
布局组件可以通过 dragMode 让玩家整体移动这一组内容。拖动布局时，它的全部后代会一起显示在新位置，但原始布局公式和 parent 关系不会改变。temporary 只保留当前页面会话中的偏移；remember 会在松开后记住位置，下次打开同一页面继续使用。已有记忆即使后来改为 off 也会继续生效，直到脚本或管理员执行重置。
坐标与裁剪行为
滚动布局先按相对布局方式处理直接子组件，再减去滚动量。例如容器位于 (100, 50)，子组件局部位置为 (10, 30)，scrollY=12，最终位置为 (110, 68)。
clip=true 时，子组件只有与容器可视矩形相交的部分能够绘制和交互。嵌套多个滚动布局时，有效裁剪区域会继续取交集。
当前字段表示滚动偏移值。是否由按钮、脚本或其他系统修改这些值，需要根据页面交互设计单独实现；不要把编辑器属性面板的滚轮滚动误认为运行页面内容滚动。
配置示例
yaml
- id: message_scroll
type: layout_scroll
parent: ""
visible: true
enabled: true
z: 0
layout:
x: 20
y: 20
width: 140
height: 38
layoutScroll:
scrollX: 0
scrollY: 12
clip: true
tooltip: []
events: {}
- id: message_line
type: text
parent: message_scroll
visible: true
enabled: false
z: 1
layout:
x: 8
y: 30
width: 120
height: 12
text:
value: 这行文字会向上滚动 12 像素
textSize: 0.8
textLineLength: 16常见问题
子组件全部看不到
检查 scrollX、scrollY 是否大于内容范围，并确认子组件与容器仍有交集。
组件画出去了但不能点击
clip=true 会同时裁剪显示和交互。只有容器内部可见部分能接收操作。
鼠标滚轮为什么没有自动改变 scrollY
scrollY 是布局配置值。当前页面需要自行通过交互或状态更新决定如何修改它。