状态与数据

对象控件与当前实例

在对象列表中把点击、拖放和奖励准确作用到当前对象。

状态与数据 · 对象交互

控件是对象动作入口，不是对象状态

渲染布局可以为每个对象生成一行或卡片，但点击后必须把操作准确绑定到当前实例，并由 Worker 脚本完成校验和写入。

# 对象列表的运行链路

flowchart LR A[渲染布局遍历对象快照] --> B[为每行绑定稳定控件] B --> C[玩家点击当前行] C --> D[运行时注入 object 与 objID] D --> E[脚本校验并修改该实例] E --> F[新快照刷新列表]

不要把对象 ID硬编码到作者 HTML。重复控件运行时会为每个实例注入上下文。

# 读取当前对象

const current = tools.kwargs.object;
const currentId = current?.getID() ?? tools.kwargs.objID;

if (!current || currentId == null) {
  tools.showToast(tools.tr("未找到当前对象"), "error");
  return;
}

current.addPro("经验", 1);

tools.kwargs.object 是脚本代理，支持读取和修改当前实例；objID 适合传给删除、特效目标或后续查询。

# 明确动作作用范围

给 AI 描述对象动作时必须说清：

当前点击对象、当前选中对象，还是一组查询结果。
操作是否需要玩家属性或对象属性条件。
成功后修改、创建或删除哪些实例。
失败时是否保持列表和选择状态。
排序或筛选变化后，当前 ID 是否仍有效。

“升级装备”与“升级所有装备”是完全不同的事务，不能只靠控件名称推断。

# 渲染布局中的绑定

对象列表优先使用运行时支持的重复控件协议，让每一行保留真实对象上下文。页面只负责展示名称、属性和动作状态；修改仍交给绑定控件脚本。

对象卡片需要详情、装备、分解等多个动作时，为每种语义建立稳定控件 ID。不要让一个万能控件根据页面文本猜测当前行为。

# 指针和拖放

对象控件的 js_press、js_move、js_release 和 js_drop 会携带指针与来源上下文。拖动期间只维护候选位置或前端预览，松开时再验证并提交真实状态。

js_drop 可读取 tools.kwargs.source、dropTarget、来源控件与来源对象 ID。需要跟手 ghost 时使用稳定 label 的客户端特效，离开或释放后显式清理。

# 传统对象字段

传统模式可以在控件面板启用绑定类、对象名字/描述、对象需求、对象消耗、对象获得和创建对象。字段流程适合简单动作，但不要再在 js_g 中重复同一扣除或发放。

# 验收对象交互

点击第二行只修改第二个对象。
排序变化后仍按对象 ID 操作，不按旧数组序号。
删除当前行后选择状态和页面不会指向已删除对象。
快速点击不会重复创建、分解或领取。
空列表有明确界面，长列表不会阻塞渲染。
对象行特效只命中当前屏幕和当前实例。

继续阅读：对象脚本 API；传统模式可打开对象筛选器。