用途
该技能用于构建或调试 Makepad UI 事件路由、控件动作、定时器驱动的更新以及 Rust/Splash 通信。使用前需先确认目标代码使用 script_mod/Splash 还是较早的 live_design API,并选用匹配的示例。
主要能力
Makepad 2.0 采用两层事件系统。
Splash 层:在 script_mod! 中直接编写内联事件处理器,包括 on_click(按钮点击,CheckBox 可传入勾选状态)、on_render(调用 .render() 时触发,用于动态内容,需配 new_batch: true 清除旧绘制内容)、on_return(TextInput 回车)和 on_startup(应用启动时在 Root 层触发一次)。处理器内可调用 Splash 函数、读写控件值、触发重渲染、触发其他控件点击、修改状态变量、使用数组方法和控制流。
Rust 层:MatchEvent trait 提供事件分派方法,涵盖生命周期(startup、shutdown、foreground、background、pause、resume)、窗口焦点、帧事件、控件动作(handle_action / handle_actions)、键盘输入、定时器、绘制、HTTP 请求与响应以及媒体设备事件。
桥接宏:script_eval!(cx, { ... }) 从 Rust 执行 Splash 代码以更新状态并触发渲染,支持用 #(expr) 注入 Rust 值;script_apply_eval!(cx, widget_ref, { ... }) 在运行时对指定控件打属性补丁。
控件动作 API:资料给出 Button(clicked、pressed、long_pressed、released 及带修饰键版本)、TextInput(changed、returned、escaped、key_down_unhandled)、CheckBox(changed)、DropDown(selected、changed、changed_label)、Slider(slided、end_slide、value)、RadioButton/RadioButtonGroup、LinkLabel 等控件的查询方法。
标准应用样板:资料提供 script 时代的应用结构示意,并强调 handle_event 必须同时调用 self.match_event(cx, event) 与 self.ui.handle_event(cx, event, &mut Scope::empty())。
使用方式
从 Rust 通过 self.ui.widget_type(cx, ids!(name)) 获取带类型的控件引用,再将 &Actions 传入相应动作查询方法;在事件处理器中用 script_eval! 回写 Splash 状态或触发渲染,用 script_apply_eval! 修改控件属性。嵌套控件访问模式参见 references/extended-guide.md。
适用场景
适用于 Makepad UI 事件路由、控件动作处理、定时器更新、Rust 与 Splash 双向通信等开发与调试工作,也包含针对“搜索框防抖”等具体需求的实践提示(保留待处理输入、取消被取代的定时器、标记响应防止过期更新、测试输入/空输入/取消/焦点变化/销毁等情形,并避免重复 Enter 或点击导致重复变更、避免记录敏感输入)。
限制
资料明确说明:需从 Cargo.lock 锁定 Makepad 的 Git 修订版本,并以该版本的源码和示例为准;“2.0”本身不保证 API 兼容性,所引用的片段跨越一个仍在变化的开发分支。未经用户明确批准,不得运行捆绑脚本。UI 层校验与服务器授权相互独立。