ComfyUI_VNCCS_Utils 的“实时交互”设计契约:为什么每个滑块都必须即拖即现
ComfyUI_VNCCS_Utils 的“实时交互”设计契约:为什么每个滑块都必须即拖即现
ComfyUI_VNCCS_Utils 是 ComfyUI 的实用自定义节点合集,包含 3D Factory、UniCanvas、Pose Studio、Prompt Designer 四大交互工作区。它有一条贯穿所有控件的强制“实时交互”设计契约:任何滑块、拖拽、画笔,在你按住的过程中必须即拖即现——松手之前,最新结果必须已经出现在屏幕上。这条契约怎么写、为什么这么苛刻、代码里如何落地,本文用通俗的方式讲清楚。
一、契约管什么:所有控件的“实时交互”范围
契约原文写在 docs/WIDGET_DESIGN.md,它不是某个节点的局部规范,而是覆盖现存和未来每一个交互控件的仓库级规则(AGENTS.md 中同样被声明为强制项)。
被点名的对象包括:
| 控件类型 | 出现的位置 |
|---|---|
| 滑块、数值拖擦(scrub) | Pose Studio 身体参数、3D Factory 精确数值面板 |
| 3D 对象拖拽 / gizmo | 3D Factory 高斯场景 |
| 关节、骨骼、时间轴 | Pose Studio 摆姿与动画 |
| 相机、视角、雷达盘 | 相机控制、UniCanvas 全景 |
| 画笔、遮罩、图层变换 | UniCanvas 无限画布 |
契约的核心就一句话(docs/WIDGET_DESIGN.md#L15 原文):
手势过程中冻结画面、松手才跳到最终值,是严格禁止的;未经用户要求的位移跳跃也是禁止的。
换句话说:“松手才刷新”在 ComfyUI_VNCCS_Utils 里不算特性,算 bug,并且不允许发布(docs/WIDGET_DESIGN.md#L43)。
二、6 条核心细则:让滑块即拖即现的完整规范
把 docs/WIDGET_DESIGN.md 浓缩成新手也能懂的 6 条:
- 用“过程事件”驱动显示。滑块、拖拽、画笔必须监听
input、pointermove这类持续触发的事件,让画面在按住期间每一刻都跟随最新输入,而不是等change事件。 - 每帧只画最新值,不排队旧值。昂贵渲染用
requestAnimationFrame合帧节流;如果两帧之间产生了多个值,只取最新值,永远不把过期的中间值塞进渲染队列。 - 太贵的操作先给轻量预览。全质量算不动时,立即显示一个轻量预览,保持上一帧有效画面不黑屏;后到的过期异步结果会被直接拒绝(最新值获胜),最终质量结果必须与预览的位置、几何完全一致。
- 松手只做“收尾”,不做“首发”。
change、pointerup、失焦这些“结束事件”只负责提交像素、持久化、同步和一条撤销记录——绝不允许由它们提供第一次可见更新。 - 成对控件实时同步。滑块与旁边的精确数值框是“绑定关系”,拖动一方时另一方立刻跟随;直接更新受影响的对象,而不是每次输入都重载整个控件。
- 一次手势 = 一条撤销记录。按住拖动全程画面连续变化,松手后 Undo 一步就能完整撤销整个手势,而不是撤销其中某一个中间帧。
三、落地拆解:3 个模块如何实现“即拖即现”
1. 3D Factory:把“一次手势”封装成对象
web/factory3d/core/property_gesture.mjs 中的 FactoryPropertyGesture 是契约的最小实现单元,逻辑非常直白:
// 拖动过程中的每一次输入(节选自 property_gesture.mjs)
this.write(ref, descriptor.id, accepted.value); // 立刻写入最新值
this.preview(ref, descriptor.id, accepted.value); // 立刻刷新预览
// …松手时 commit():只在这里生成 1 条 Undo 记录
input()每帧校验并写入最新值,同时刷新 3D 视口预览;commit()松手时才把整个手势记成一条Edit历史命令;cancel()(按 Escape、指针丢失等)则回滚到手势开始前的值。
配套的 web/factory3d/ui/numeric_property_binding.mjs 还实现了数值拖擦:直接按住数字左右拖即可改值,按住 Shift 变为 0.1 倍微调、Alt 变为 10 倍大步进,滑块与数字框通过 sync() 始终保持一致——正是细则 5 的落地。
2. UniCanvas:rAF 合帧 + 过期结果拒绝
以“颜色匹配”实时预览为例(web/unicanvas/layer_tools.mjs):预览合成被安排进 requestAnimationFrame,每次新值到达时若上一帧还没跑完就直接复用同一帧回调,天然实现“最新值获胜”;提交前还会检查编辑状态是否仍然有效(colorMatchIsCurrent),过期结果一律丢弃,只在松手时生成一对前后快照、记一条可撤销命令。画笔硬度、径向 HUD(右键拖出 size / opacity / hardness 实时调参)同理。
3. Pose Studio:关节与时间轴的连续驱动
Pose Studio 的前端 web/vnccs_pose_studio.js 与 web/pose_studio/core.js 中大量使用 pointerdown / pointermove / pointerup 序列 + requestAnimationFrame:拖关节、调 Age/Weight/Muscle 滑块、在 dope-sheet 时间轴上拖动关键帧,全部在按住期间逐帧渲染,Undo/Redo 按“完成的手势”为单位记录。
四、验收关卡:松手才刷新 = 禁止发布
契约不是口号,它带验收清单(docs/WIDGET_DESIGN.md#L35-L41):
- ✅ 按住手势跨越至少两个不同数值,释放前每一帧都必须渲染;
- ✅ 每一帧显示的都是最新值,包括内容从视口外滑入可见区域的情况;
- ✅ 松手后可见位置不变(不跳变),且整个手势恰好产生一条撤销命令;
- ✅ 无关内容保持原位,生成任务进行中仍正确阻塞文档编辑。
仓库里还有持续测试把这条契约“钉死”:tests/test_widget_hardening.mjs 会静态检查控件在移除时释放全局监听、同步锁必须放进 finally 等加固项,配合 tests/e2e/ 下的 Playwright 端到端用例,保证“即拖即现”不随版本退化。
五、新手上手:哪里能亲手体验“即拖即现”
🖱️ 装好节点后(ComfyUI Manager 中搜索 VNCCS Utils 安装,或手动 clone 到 ComfyUI/custom_nodes 并安装 requirements.txt),推荐从这几处感受契约:
- 3D Factory:点选场景对象直接拖拽 move/rotate/scale;展开精确数值面板按住数字左右“拖擦”微调。完整指南见 docs/VNCCS_3D_FACTORY.md
- Pose Studio:在节点内直接拖关节摆姿,或用 Age、Gender、Weight、Muscle、Height 滑块实时微调体型;松手后 Ctrl+Z 一步撤销整个手势。用法见 docs/VNCCS_POSE_STUDIO_USAGE.md
- UniCanvas:右键按住拖出径向 HUD,朝 size / opacity / hardness 方向拖动即可实时改参数;全景模式下环视、涂画、变换同样逐帧跟随。
- Visual Camera Control:用鼠标选择方位角与距离、拖动仰角滑块,预览与 prompt 即时更新。
六、延伸阅读:关键文件清单
| 文件 | 说明 |
|---|---|
| docs/WIDGET_DESIGN.md | 交互设计契约全文(含验收清单) |
| AGENTS.md | 仓库级强制规则:Realtime interaction is mandatory |
| web/factory3d/core/property_gesture.mjs | 数值手势:input → preview → commit/cancel |
| web/factory3d/ui/numeric_property_binding.mjs | 滑块/数字框绑定与实时拖擦 |
| web/unicanvas/layer_tools.mjs | UniCanvas 实时预览的 rAF 合帧实现 |
| tests/test_widget_hardening.mjs | 控件加固的回归测试 |
一句话总结:在 ComfyUI_VNCCS_Utils 里,“即拖即现”不是体验目标,而是发布门槛——任何控件只要松手才显示结果,就视为缺陷,不许出厂。这份写在 docs/WIDGET_DESIGN.md 里的契约,正是每个滑块都“听话”的原因。



