tomevault-io War3 UI 异步分层规范
强制规则
- 保持
UI 展示层与数据/游戏状态层分离。 - 把
GetLocalPlayer()分支内的逻辑视为异步本地逻辑；禁止在其中修改同步状态（单位、计时器、全局对局数据等）。 show/hide/refresh等 UI 生命周期方法禁止做业务数据写入；尤其禁止在 UI 操作链路内执行DzAPI_Map_Store*和其他会导致数据变动的操作。- 在 UI 回调里只做三类事情：
- 本地 UI 更新（show/hide/text/texture/位置）
- 事件参数写入（
currentPosAsync/args*/eventdata.bind*） - 触发异步到同步桥接（如
syncBus.DzSyncDataEx）
事件绑定选择
- 无数据绑定的事件用
onClick/onEnter/onLeave。 - 需要携带绑定数据（frame -> eventdata -> 业务参数）时用
spClick/spEnter/spLeave。 - 使用
sp*时，先绑定uiHashTable(frame).eventdata，再在回调中解包；禁止直接依赖外层局部变量闭包。
异步转同步（本地事件出网）
- 本地点击/交互不直接执行业务数据修改；先编码 payload 并发送（示例：
syncBus.DzSyncDataEx(channel, payload)）。 - 在
onDataSync(channel, ...)中解码并做权限校验（owner/player/对象存在性），通过后才触发trClick/trClose/trBtn1等同步逻辑。 - payload 至少包含三段信息：
- 事件类型（如
D/C/F/L/R） - 对象标识（如
sd、英雄索引） - 位置信息（如
pos）
回调参数传递
- 为匿名回调准备静态参数槽（如
currentSDAsync/currentPosAsync/argsHeroIndex）。 - 触发器前写入参数，触发后按需清理或覆盖，避免跨回调污染。
- 提供统一读取函数（
Get*Async/Get*Pos）给外部逻辑层。
生命周期与清理
- 销毁 UI 时，补发必要的离开事件（若存在“进入未离开”状态）。
- 销毁顺序保持“子组件 -> 主组件”，并把句柄置零。
- 本地 UI 关闭仅处理本地资源；同步状态变更交给同步事件处理器。
硬性检查清单（CR Gate）
在提交 UI 代码前，逐条检查。任意 FAIL 均禁止合并。
GetLocalPlayer()分支内不修改同步状态 PASS: 仅做 UI 显示、本地参数写入、发送同步消息。 FAIL: 创建/销毁单位、改全局业务数据、改计时器/组等对局同步状态。本地 UI 回调不直改业务数据 PASS:
onClick/spClick只编码 payload 或写current*Async/args*。 FAIL: 在 UI 点击回调里直接执行奖励发放、状态切换、背包改动等。正确选择
on*vssp*PASS: 无绑定数据用onClick/onEnter/onLeave；有 frame 数据解包需求用spClick/spEnter/spLeave。 FAIL: 需要eventdata却使用on*，或无数据需求滥用sp*。sp*回调前完成 eventdata 绑定 PASS: 对应按钮存在uiHashTable(btn.ui).eventdata.bind*。 FAIL: 回调中读取eventdata但未绑定或绑定不完整（缺少 bind2/bind3）。本地事件统一走“发送 -> 接收 -> 处理”链路 PASS:
DzSyncDataEx(channel, payload)发出后，在onDataSync(channel, ...)解码并处理。 FAIL: 本地事件绕过总线直接触发同步业务逻辑。onDataSync完成安全校验 PASS: 校验对象存在性、owner/player一致性、索引范围合法性后再触发业务触发器。 FAIL: 未校验即执行trClick/trClose/...。payload 结构可逆且稳定 PASS: payload 至少含
事件类型 + 对象标识 + 位置信息，解码规则与编码规则一一对应。 FAIL: 拼接格式歧义、长度位错误、解码位置错位。异步参数槽完整可读 PASS: 提供
Get*Async/Get*Pos读取接口，并在触发前写入对应参数。 FAIL: 回调依赖外层局部变量或隐式状态，导致异步读取不稳定。UI 销毁流程完整 PASS: 销毁前补发必要 leave，按子到父销毁并置零，避免悬空句柄。 FAIL: 直接销毁主框导致子组件泄漏，或 leave 状态丢失。
外部回调职责清晰 PASS: UI 层只发事件与展示；数据层在外部触发器/总线接收端处理。 FAIL: UI 文件内混入业务数据写入分支。
快速判定
- 全部 10 项
PASS：允许合并。 - 任意 1 项
FAIL：先修复再提审。 - 若无法判定：默认按
FAIL处理并补充注释说明边界。
参考实现（按需阅读）
references/war3lib-ui-examples.md
Converted and distributed by TomeVault — claim your Tome and manage your conversions.