猹件开发组ChaUI Script 简介
ChaUI Script 用来为页面组件添加交互。无需编写客户端 Mod，你就可以修改页面变量、切换组件状态、播放音效、打开其他页面，或把自定义数据交给服务端插件处理。文字和布局引用变量后还会实时响应变化，不需要为每个数值单独编写更新文字的脚本。
脚本运行在当前打开的页面会话中。页面重新打开时，未保存的临时变量和脚本创建的临时组件会恢复为页面文件中的初始状态。
脚本中的 component("id") 会取得当前会话里的安全组件对象。你可以读取它的当前属性、父组件和布局公式，也可以在允许的范围内修改临时状态。普通 = 会保存这一次计算出的结果；需要让脚本写入的布局以后继续跟随窗口或其他组件时，使用 formula(...)。
在哪里填写脚本
选中编辑器中的任意组件或布局，在右侧属性面板找到事件脚本区域，然后把脚本填写到对应事件中。
| 事件字段 | 触发时机 | 常见用途 |
|---|---|---|
leftClick | 鼠标左键点击组件 | 确认、切换状态、打开页面 |
rightClick | 鼠标右键点击组件 | 次要操作、返回、取消 |
middleClick | 鼠标中键点击组件 | 管理员快捷操作 |
hoverEnter | 鼠标进入组件范围 | 显示说明、播放悬浮效果 |
hoverLeave | 鼠标离开组件范围 | 恢复默认状态 |
create | 组件实例创建完成 | 设置初始状态、登记动态组件 |
页面自身还提供 open 与 close。它们适合调用页面自定义方法，完成一次性初始化和资源收尾。完整顺序、reload 行为与方法写法见页面生命周期与自定义方法。
同一个组件可以同时配置多个事件，每个事件只在自己的触发时机运行。
第一个脚本
下面的页面片段包含一个文本组件和一个按钮。点击按钮后，页面变量 count 增加，文本会自动显示最新次数。
vars:
count: 0 # 页面打开时的默认次数
elements:
- id: status_text
type: text
layout:
x: 20
y: 20
width: 160
height: 20
text:
value: "已经点击 {vars.count} 次"
textSize: 1
- id: confirm_button
type: button
layout:
x: 20
y: 50
width: 80
height: 20
button:
label: "确认"
events:
leftClick: |
vars.count = vars.count + 1
sound("sounds/click.ogg")上例只修改 count。text.value 中的 {vars.count} 会在每次显示时读取当前值，所以文字会自动更新。这个能力称为响应式变量。
脚本通常一行完成一个动作。如果编辑器中的脚本输入框只显示一行，也可以使用分号分隔多条语句：
vars.count = vars.count + 1; sound("sounds/click.ogg")中文写法
ChaUI Script 同时支持常用中文别名。上面的事件也可以写成：
变量.count = 变量.count + 1
音效("sounds/click.ogg")英文与中文写法可以混用，但同一个项目中建议保持统一，方便其他页面作者阅读。
保存与测试
修改脚本后，先保存页面，再打开运行时页面测试。修改文字、变量、显隐和播放本地音效等客户端行为可以立即看到；打开页面、执行服务端动作等能力，会由服务端从已经保存的页面中重新读取并确认。
推荐按下面的顺序测试：
- 在编辑器中填写事件脚本。
- 保存页面，确认编辑器没有报告格式错误。
- 关闭编辑器，以正常页面方式重新打开。
- 触发组件事件，观察页面变化和服务端反馈。
脚本能力分区
| 类型 | 示例 | 影响范围 |
|---|---|---|
| 页面变量 | vars.ready = true | 当前客户端页面会话 |
| 页面方法 | methods.refresh() | 复用当前页面中的命名脚本 |
| 生命周期 | open → create → close | 页面建立、组件创建和页面关闭 |
| 响应式文字 | 生命：{vals.player.health} | 自动显示变量或常量的最新值 |
| 循环与计时器 | timer("countdown", 20) { ... } | 有界重复或按 tick 更新当前页面变量 |
| 数学函数 | clamp、round、fixed、randomInt | 取整、格式化、区间计算、插值和随机数 |
| 组件状态 | component("title").visible = false | 当前客户端页面会话 |
| 组件对象读取 | vars.x = component("panel").layout.x | 取得当前计算值或组件配置 |
| 响应式布局绑定 | component("tip").layout.x = formula(component("panel").layout.x + 1) | 随依赖变化重新计算 |
| 临时组件 | copyComponent("card", "card_2") | 当前客户端页面会话，不自动保存 |
| 本地音效 | sound("sounds/click.ogg") | 当前客户端本地播放 |
| 服务端动作 | open("detail_page") | 服务端读取已保存脚本后执行 |
| 自定义发包 | packet("shop:select", "1") | 真实运行时执行到即可发送，交给服务端插件监听处理 |
建议先阅读响应式变量与实时文字，再继续学习数学函数、页面生命周期与自定义方法和语法与事件。需要制作倒计时、轮询显示或批量页面状态时，阅读循环与计时器。