ComfyUI Custom DOMWidget 开发说明文档 (Vanilla JavaScript)

本文档旨在说明如何使用 Vanilla JavaScript (纯 JS) 在 ComfyUI 前端中实现自定义 DOMWidget。DOMWidget 允许你将标准的 HTML 元素（如 div, video, canvas, input 等）嵌入到 ComfyUI 的节点中，并享受前端自动布局和缩放管理。

1. 核心概念

在 ComfyUI 中，DOMWidget 是对 LiteGraph 默认 Canvas 渲染逻辑的扩展。它在 Canvas 之上维护一个 HTML 层，使得复杂的交互和媒体显示变得非常容易。

核心 API

app.registerExtension: 注册扩展的入口。
getCustomWidgets: 定义新部件类型的钩子。
node.addDOMWidget(name, type, element, options): 将 HTML 元素添加到节点的关键方法。

2. 基础结构

一个标准的自定义 DOMWidget 扩展通常遵循以下结构：

import { app } from "../../scripts/app.js";

app.registerExtension({
    name: "My.Custom.Extension",
    async getCustomWidgets() {
        return {
            // 定义一个名为 "MY_WIDGET_TYPE" 的新部件类型
            MY_WIDGET_TYPE(node, inputName, inputData, app) {
                // 1. 创建 HTML 元素
                const container = document.createElement("div");
                container.innerHTML = "Hello <b>DOMWidget</b>!";
                
                // 2. 样式设置 (可选)
                container.style.color = "white";
                container.style.padding = "5px";

                // 3. 调用 addDOMWidget 并返回结果
                const widget = node.addDOMWidget(inputName, "MY_WIDGET_TYPE", container, {
                    // 配置选项
                    getValue() {
                        return container.innerText;
                    },
                    setValue(v) {
                        container.innerText = v;
                    }
                });

                // 4. 固定返回格式
                return { widget };
            }
        };
    }
});

3. `addDOMWidget` 详细参数

node.addDOMWidget(name, type, element, options)

参数说明:

name: 部件的内部名称（通常匹配输入名称）。
type: 部件的类型标识符。
element: 实际的 HTML 元素。
options: (Object) 包含生命周期和行为的配置项。

`options` 常用字段:

字段	类型	说明
`getValue`	`Function`	定义部件序列化时的值来源。
`setValue`	`Function`	定义如何从工作流数据中恢复部件状态。
`getMinHeight`	`Function`	返回部件的最小像素高度。
`getHeight`	`Function`	返回部件的期望高度（可返回百分比字符串，如 `"50%"`）。
`hideOnZoom`	`Boolean`	当 Canvas 缩小到一定程度时是否隐藏 DOM 元素（提高性能，默认 `true`）。
`onDraw`	`Function`	每一帧绘制时触发，可用于在 Canvas 上做额外标注。
`afterResize`	`Function`	节点缩放后的回调。

4. 样式与布局管理

ComfyUI 前端使用 CSS 变量来协调 Canvas 节点与 DOM 部件的尺寸。你可以在元素的 style 或 CSS 中设置这些变量：

container.style.setProperty('--comfy-widget-min-height', '100px');
container.style.setProperty('--comfy-widget-max-height', '500px');

由于 DOMWidget 被放置在绝对定位的容器中，建议容器元素的样式设为：

container.style.width = "100%";
container.style.boxSizing = "border-box";

5. 生命周期与交互

如果你需要访问其他部件或在特定时刻触发逻辑，可以结合 nodeCreated 钩子：

app.registerExtension({
    name: "My.Lifecycle.Extension",
    nodeCreated(node) {
        if (node.comfyClass === "MyCustomNode") {
            // 查找刚才创建好的 DOMWidget
            const myWidget = node.widgets.find(w => w.name === "my_input");
            
            // 可以在这里绑定事件
            myWidget.element.addEventListener("click", () => {
                console.log("Widget clicked!", myWidget.value);
            });
        }
    }
});

6. 完整实战示例: 简易文本预览器

这个示例实现了一个动态显示文本字数统计的预览器部件。

import { app } from "../../scripts/app.js";

app.registerExtension({
    name: "Comfy.TextCounter",
    getCustomWidgets() {
        return {
            TEXT_COUNTER(node, inputName) {
                const el = document.createElement("div");
                el.style.background = "#222";
                el.style.border = "1px solid #444";
                el.style.padding = "8px";
                el.style.borderRadius = "4px";
                el.style.fontSize = "12px";
                
                const label = document.createElement("span");
                label.innerText = "Characters: 0";
                el.appendChild(label);

                const widget = node.addDOMWidget(inputName, "TEXT_COUNTER", el, {
                    getValue() { return node.widgets[0]?.value || ""; },
                    setValue(v) { /* 逻辑通常由上游触发 */ },
                    getMinHeight() { return 40; }
                });

                // 设置一个自定义更新逻辑
                widget.updateCount = (text) => {
                    label.innerText = `Characters: ${text.length}`;
                };

                return { widget };
            }
        };
    },
    nodeCreated(node) {
        if (node.comfyClass === "MyTextNode") {
            const counterWidget = node.widgets.find(w => w.type === "TEXT_COUNTER");
            const textWidget = node.widgets.find(w => w.name === "text");
            
            if (counterWidget && textWidget) {
                // 监听文本部件的回调
                const oldCallback = textWidget.callback;
                textWidget.callback = function(v) {
                    if (oldCallback) oldCallback.apply(this, arguments);
                    counterWidget.updateCount(v);
                };
            }
        }
    }
});

7. 注意事项

路径引用: 引用 app 时请根据你的插件目录深度调整路径，通常是 ../../scripts/app.js。
清理: 如果你创建了外部引用（如 setInterval 或全局监听），请确在 node.onRemoved 中进行清理。
安全性: 如果动态设置 innerHTML，请确保内容来源可靠，防止 XSS 攻击。
性能: 对于高频更新的 DOM 元素，注意不要触发过多的重排（Reflow）。

6.6 KiB Raw Blame History Unescape Escape