事件脚本¶
事件脚本把简单的界面交互留在 .sil 里,不必为一个计数器再写 C++ 回调。它挂在事件属性上,用 { ... } 书写,可以读写 DataStore、做算术、按条件分支。
基本写法¶
Button {
text: "加血 +10";
width: 96;
height: 24;
onClick: { @health += 10; };
// 多语句用分号分隔
// onClick: { $gain = 10; @health += $gain; if (@health > 100) { @health = 100; } };
}
脚本只在对应事件触发时执行:
| 控件 | 事件 | 触发时机 |
|---|---|---|
Button |
click |
在按钮内按下并释放,或焦点激活 |
Checkbox |
change |
用户切换勾选 |
Slider |
change |
用户拖动或按键改变数值 |
TextBox |
change |
文本发生变化 |
TextBox |
submit |
回车提交 |
Dropdown |
change |
用户选择新项 |
事件属性名不区分大小写,onClick / on-click / ONCLICK 是同一个事件;action 是 click 的别名。
语句¶
脚本支持三类语句:
- 赋值:
@key = 表达式; - 复合赋值:
@key += 表达式;,同样支持-=、*=、/=。 - 条件:
if (表达式) { ... } else { ... },else后可再接if。
Checkbox {
text: "启用主题";
checked: @theme_on;
onChange: {
@theme_on = event.checked;
if (event.checked) {
@accent = "#5CD65C";
} else {
@accent = "#87919A";
}
};
}
语句之间用 ; 分隔,最后一条可以省略分号。脚本内支持 // 与 /* */ 注释。
赋值目标¶
| 写法 | 目标 | 生命周期 |
|---|---|---|
@health = 100; |
DataStore 键 health |
全局,跨脚本、跨控件 |
health = 100; |
同上(@ 可省略) |
全局 |
$gain = 10; |
本次执行的局部变量 | 只在本脚本这一次运行内有效 |
$ 变量适合拆解计算步骤:
onClick: {
$step = @shift_held ? 10 : 1;
@health += $step;
if (@health > 100) { @health = 100; }
};
$ 变量不会写入 DataStore,也不会在两次事件之间保留。
$变量与文档级 Var 不是一回事
$accent 在属性值里是编译期的 Var 替换;在脚本里是运行期的局部变量。两者可以同名,但互不影响。
读取值¶
脚本中的表达式与绑定使用同一套语法:
onClick: {
$next = @mode + 1;
if ($next > 2) { $next = 0; }
@mode = $next;
};
可以读取当前控件状态(checked、disabled 等)、其他数据键,以及事件载荷。
事件载荷¶
事件发生时,脚本可以读取 event:
| 字段 | 类型 | 适用事件 | 含义 |
|---|---|---|---|
event.name |
字符串 | 所有 | 事件名,如 "click"、"change" |
event.value |
依控件 | 值事件 | 新值:布尔、数字或文本 |
event.text |
字符串 | 文本类事件 | 相关文本(输入内容、选项文字) |
event.checked |
布尔 | change |
勾选状态 |
event.index |
数字 | change(Dropdown) |
选中索引 |
Checkbox {
checked: @theme_on;
onChange: { @theme_color = event.checked ? "#5CD65C" : "#E05252"; };
};
ForEach (data: @items, item: @item) {
Button {
text: "{{@item.name}}";
onClick: { @selected = @item.id; };
};
}
event.* 只在脚本执行期间有效;离开事件后再次求值会得到 null。
脚本与 C++ 回调的优先级¶
事件属性可以写脚本,也可以写回调名:
Button { onClick: "open_settings"; } // 交给 C++
Button { onClick: { @page = "settings"; }; } // 脚本处理
当同一个事件既有脚本又有 C++ 回调时,脚本优先,且不会再调用回调。这让你可以先用脚本快速实现,之后再迁移到 C++。
值事件(change / submit)的顺序相同:脚本存在时,注册的同名 C++ 回调不会被调用。
脚本能做什么,不能做什么¶
可以:
- 读写
DataStore的任意键; - 使用算术、比较、三元表达式与
if/else; - 读取局部作用域(
@item.name、组件参数)与控件状态; - 在一次执行中连续修改多个键;每个
Set都会立即通知绑定刷新。
不可以:
- 调用 C++ 函数或执行任意系统操作;
- 定义函数、循环或递归;
- 修改控件属性(例如“把按钮变红”)。需要视觉变化时,把状态写进数据键,再用绑定/条件值驱动属性;
- 在脚本里使用
$变量引用文档级Var。
把视觉变化交给绑定
脚本只改数据;界面如何响应由绑定决定。例如“点击后按钮变绿”应写成:
Button {
background: @active ? "#2F6B37" : "#1B2025";
onClick: { @active = !@active; };
}
写入与刷新¶
脚本中的 @key = ... 最终调用 DataStore::Set:
- 值真正改变时,读取该键的绑定立即重新求值。
- 同一事件内后续语句读取该键时,看到的是新值。
- 控件绘制在下一帧反映新状态。
多个控件读取同一个键时都会收到通知,因此一个按钮的脚本可以同时更新多个显示位置。
复杂逻辑放哪里¶
| 场景 | 建议 |
|---|---|
| 计数、取反、简单状态切换 | 写在 .sil 脚本 |
| 需要访问游戏对象、文件、网络 | 注册 C++ 回调 |
| 多个界面共享的业务状态 | C++ 写入 DataStore,界面只绑定 |
| 需要循环、复杂校验 | C++ 处理,结果写回数据键 |
排错¶
| 报错 / 现象 | 原因 |
|---|---|
scripts attach to an event property (onClick, onChange, onSubmit, ...) |
把 { ... } 写在了非事件属性上 |
expected '(' after 'if' |
if 后缺少括号 |
expected '=' ... after '...' |
赋值缺少运算符,或用了 == 当赋值 |
in 'xxx ...': use '==' to compare; '=' only assigns inside a script |
表达式里写了单个 = |
| 脚本不执行 | 事件没有触发,或控件被 disabled |
| 改了数据但界面没变 | 界面读取的是另一个键,或该属性没有绑定 |