comfyui-node-inputs

ComfyUI 节点输入

输入定义节点接受的数据。控件输入会创建 UI 控件；连接输入会创建插槽。

控件输入类型

INT

io.Int.Input("seed",
    default=0,
    min=0,
    max=0xffffffffffffffff,
    step=1,
    control_after_generate=True,  # adds increment/decrement/randomize control
    display_mode=io.NumberDisplay.number,  # "number", "slider", or "gradient_slider"
    tooltip="Random seed for generation",
)

NumberDisplay 选项：io.NumberDisplay.number、io.NumberDisplay.slider、io.NumberDisplay.gradient_slider

ControlAfterGenerate 选项：True（默认随机化），或 io.ControlAfterGenerate.fixed、.increment、.decrement、.randomize。从前端 v1.57.0 (#19867) 开始，模式值仅被视为控件的初始模式；旧版前端会将字符串用作控件小部件的名称。

FLOAT

io.Float.Input("strength",
    default=1.0,
    min=0.0,
    max=10.0,
    step=0.01,
    round=0.001,         # rounding precision
    display_mode=io.NumberDisplay.slider,
    gradient_stops=[{"offset": 0.0, "color": [0, 0, 0]}, {"offset": 1.0, "color": [255, 255, 255]}],  # for gradient_slider mode
    tooltip="Effect strength",
)

STRING

# Single-line string
io.String.Input("name",
    default="",
    placeholder="Enter name...",
)

# Multi-line text area
io.String.Input("prompt",
    multiline=True,
    default="",
    placeholder="Enter prompt...",
    dynamic_prompts=True,  # enable dynamic prompt syntax
)

BOOLEAN

io.Boolean.Input("enabled",
    default=True,
    label_on="Enabled",
    label_off="Disabled",
    tooltip="Toggle this feature",
)

COMBO（下拉菜单）

io.Combo.Input("mode",
    options=["option_a", "option_b", "option_c"],
    default="option_a",
    tooltip="Select processing mode",
    control_after_generate=True,  # adds increment/decrement/randomize control
)

带 Enum 的 Combo：

from enum import Enum

class BlendMode(Enum):
    NORMAL = "normal"
    MULTIPLY = "multiply"
    SCREEN = "screen"

io.Combo.Input("blend", options=BlendMode, default=BlendMode.NORMAL)
# Enum values auto-converted to string list

带文件上传的 Combo：

io.Combo.Input("image_file",
    options=[],
    upload=io.UploadType.image,          # .image, .audio, .video, .model (for generic file upload)
    image_folder=io.FolderType.input,    # .input, .output, .temp
)

带远程选项的动态 Combo：

io.Combo.Input("model_name",
    options=[],
    remote=io.RemoteOptions(
        route="/internal/models/checkpoints",
        refresh_button=True,
        control_after_refresh="first",  # "first" or "last"
        timeout=5000,        # ms
        max_retries=3,
        refresh=60000,       # TTL refresh interval in ms
    ),
)

安全性：当 combo / DynamicCombo 的值传入文件系统时，应将其视为不可信数据。在加载/保存边界处，重新验证任何用作文件/文件夹名、路径、格式或扩展名的值（使用 folder_paths.get_full_path_or_raise(...)、folder_paths.is_within_directory(base, path) 或固定的允许列表）——通过 API 提交的提示词可以使用 options 之外的值。

MULTICOMBO（多选下拉菜单）

io.MultiCombo.Input("tags",
    options=["tag1", "tag2", "tag3", "tag4"],
    default=["tag1"],
    placeholder="Select tags...",
    chip=True,  # display as chips
)
# Value type: list[str]

COLOR（颜色选择器）

io.Color.Input("color",
    default="#ffffff",
    socketless=True,  # widget only by default
)
# Value type: str (hex color)

COLORS（调色板）

io.Colors.Input("palette",
    default=["#ff0000", "#00ff00"],
    socketless=True,
)
# Value type: list[str] (hex colors)

BOUNDING_BOX（矩形选择器）

io.BoundingBox.Input("region",
    default={"x": 0, "y": 0, "width": 512, "height": 512},
    socketless=True,
    component="my_component",  # optional custom UI component name
    force_input=False,
)
# Value type: {"x": int, "y": int, "width": int, "height": int}

BOUNDING_BOXES（多个区域）

io.BoundingBoxes.Input("regions",
    default=[],
    socketless=True,
)
# Value type: list of {"x": int, "y": int, "width": int, "height": int, "metadata": dict}

CURVE（样条曲线编辑器）

io.Curve.Input("curve",
    default=[(0.0, 0.0), (1.0, 1.0)],  # linear ramp
    socketless=True,
)
# Value type: raw curve data; normalize with CurveInput.from_raw(value)
# (from comfy_api.input import CurveInput)

RANGE（色阶/范围编辑器）

io.Range.Input("levels",
    default={"min": 0.0, "max": 1.0},
    gradient_stops=None,     # gradient background for the slider
    show_midpoint=True,      # gamma midpoint handle
    value_min=0.0,
    value_max=1.0,
)
# Value type: raw dict; normalize with RangeInput.from_raw(value)
# (from comfy_api.input import RangeInput) -> .min_val, .max_val, .midpoint, .to_lut()

WEBCAM（摄像头采集）

io.Webcam.Input("capture")
# Value type: str

IMAGECOMPARE（比较控件）

io.ImageCompare.Input("comparison", socketless=True)
# Value type: dict

较新的编辑器控件（v0.31–v0.40，需要匹配的前端）

io.VideoEdit.Input("trim", features=["trim"])   # "trim" and/or "crop" (default both)
# Value: {"trim": {"start_time": float, "duration": float}, "crop": {"x","y","width","height"}}
#   apply with video.as_trimmed(...) / video.as_cropped(...); zero width/height = full frame
io.ResolutionPreview.Input("preview",            # live preview of a computed size; optional by default
    ratio_widget="aspect_ratio", megapixels_widget="megapixels", multiple_widget="multiple")
io.Compositor.Input("compositor")                # layer-editor state dict (pairs with io.Layers)
io.CameraInfoState.Input("camera_info_state", optional=True)  # camera editor state dict

输入选项（通用）

io.Image.Input("image",
    optional=True,        # not required; creates optional input socket
    tooltip="Description shown on hover",
    lazy=True,            # lazy evaluation - only computed when needed
    advanced=True,        # hidden by default in compact mode
    raw_link=True,        # receive raw link reference instead of value
)

force_input

强制将控件输入显示为连接插槽，而不是控件：

io.Float.Input("value",
    default=1.0,
    force_input=True,   # shows as socket, not slider
)

socketless

使控件输入仅显示为控件，不带输入插槽：

io.String.Input("note",
    default="",
    socketless=True,     # widget only, no connection socket
)

可选输入

class MyNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="MyNode",
            display_name="My Node",
            category="example",
            inputs=[
                io.Image.Input("image"),                        # required
                io.Mask.Input("mask", optional=True),           # optional
                io.Float.Input("blend", default=0.5),           # has default widget
            ],
            outputs=[io.Image.Output("IMAGE")],
        )

    @classmethod
    def execute(cls, image, mask=None, blend=0.5):
        # Optional inputs default to None when not connected
        if mask is not None:
            image = image * (1 - blend) + image * mask.unsqueeze(-1) * blend
        return io.NodeOutput(image)

隐藏输入

隐藏输入接收服务端提供的值，而非用户输入：

class MyNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="MyNode",
            display_name="My Node",
            category="example",
            inputs=[io.String.Input("text")],
            outputs=[io.String.Output()],
            hidden=[
                io.Hidden.unique_id,       # node's unique ID
                io.Hidden.prompt,           # full prompt data
                io.Hidden.extra_pnginfo,    # PNG metadata dict
                io.Hidden.dynprompt,        # dynamic prompt object
                io.Hidden.auth_token_comfy_org,  # auth token
                io.Hidden.api_key_comfy_org,     # API key
                io.Hidden.comfy_usage_source,    # prompt source, e.g. "comfyui-frontend"
                # io.Hidden.execution_list exists (v0.36+) but is core-internal and
                # slated for removal - DO NOT USE
            ],
        )

    @classmethod
    def execute(cls, text):
        # Access hidden values via cls.hidden
        node_id = cls.hidden.unique_id
        prompt = cls.hidden.prompt
        extra = cls.hidden.extra_pnginfo
        return io.NodeOutput(f"{text} (node: {node_id})")

惰性求值

惰性输入仅在实际需要时才求值，从而节省计算资源：

class ConditionalNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="ConditionalNode",
            display_name="Conditional",
            category="logic",
            inputs=[
                io.Boolean.Input("condition"),
                io.Image.Input("if_true", lazy=True),
                io.Image.Input("if_false", lazy=True),
            ],
            outputs=[io.Image.Output("IMAGE")],
        )

    @classmethod
    def check_lazy_status(cls, condition, if_true=None, if_false=None):
        """Return list of input names that need evaluation."""
        if condition and if_true is None:
            return ["if_true"]
        if not condition and if_false is None:
            return ["if_false"]
        return []

    @classmethod
    def execute(cls, condition, if_true, if_false):
        return io.NodeOutput(if_true if condition else if_false)

惰性求值规则：

• 将输入标记为 lazy=True
• 实现 check_lazy_status() 类方法
• 尚未求值的输入为 None；未连接的可选惰性输入不会出现在 kwargs 中——使用哨兵默认值（MISSING = object()）进行区分（参见 comfyui-node-advanced 中的 Switch 模式）
• 返回需要计算的输入名称列表，或返回空列表
• 该方法可能会被多次调用
• Autogrow/DynamicCombo 的惰性子输入在此处以 (value, key) 元组形式传入（参见 comfyui-node-advanced）

输入容差（核心策略）：不要仅仅因为值超出建议/UI 限制或可能导致结果不佳就拒绝它们；仅当操作否则会失败时才进行适配（截断/填充/调整大小）。安全检查（路径包含性）仍然适用。

V1 输入格式（旧版参考）

@classmethod
def INPUT_TYPES(s):
    return {
        "required": {
            "image": ("IMAGE",),
            "strength": ("FLOAT", {
                "default": 1.0, "min": 0.0, "max": 10.0, "step": 0.01
            }),
            "mode": (["option_a", "option_b"],),
            "text": ("STRING", {"multiline": True, "default": ""}),
        },
        "optional": {
            "mask": ("MASK",),
        },
        "hidden": {
            "unique_id": "UNIQUE_ID",
            "prompt": "PROMPT",
            "extra_pnginfo": "EXTRA_PNGINFO",
        },
    }

完整示例：多输入节点

class AdvancedImageNode(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="AdvancedImageNode",
            display_name="Advanced Image",
            category="image/advanced",
            description="Demonstrates various input types",
            inputs=[
                # Required connection input
                io.Image.Input("image", tooltip="Input image"),
                # Required widget inputs
                io.Float.Input("brightness", default=1.0, min=0.0, max=3.0,
                               step=0.1, display_mode=io.NumberDisplay.slider),
                io.Float.Input("contrast", default=1.0, min=0.0, max=3.0, step=0.1),
                io.Int.Input("seed", default=0, min=0, max=0xffffffffffffffff,
                             control_after_generate=True),
                io.Combo.Input("blend_mode", options=["normal", "multiply", "screen"]),
                io.Boolean.Input("flip_horizontal", default=False),
                io.String.Input("label", default="", socketless=True),
                # Optional inputs
                io.Mask.Input("mask", optional=True),
                io.Image.Input("overlay", optional=True),
                # Advanced inputs (collapsed by default)
                io.Float.Input("gamma", default=1.0, min=0.1, max=3.0, advanced=True),
            ],
            outputs=[
                io.Image.Output("IMAGE"),
                io.Mask.Output("MASK"),
            ],
        )

    @classmethod
    def execute(cls, image, brightness, contrast, seed, blend_mode,
                flip_horizontal, label, mask=None, overlay=None, gamma=1.0):
        result = image * brightness
        if flip_horizontal:
            result = torch.flip(result, dims=[2])
        if mask is not None:
            result = result * mask.unsqueeze(-1)
        return io.NodeOutput(result, mask if mask is not None else torch.ones(result.shape[:3]))

另请参阅

• comfyui-node-basics - 节点结构概述
• comfyui-node-datatypes - 数据类型详情
• comfyui-node-advanced - MatchType、Autogrow、DynamicCombo
• comfyui-node-lifecycle - 惰性求值详情