设置 API

使用 app.registerExtension 添加、读取、写入 ComfyUI 扩展设置并响应变更，涵盖 boolean、text、number、slider、combo、color 和 image 等设置类型。

你可以为 ComfyUI 提供一个设置对象，这些设置会显示在用户打开 ComfyUI 设置面板时。

基本操作

添加一个设置项

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

app.registerExtension({
    name: "My Extension",
    settings: [
        {
            id: "example.boolean",
            name: "示例布尔设置",
            type: "boolean",
            defaultValue: false,
        },
    ],
});

id 必须在所有扩展中唯一，并将用于获取设置值。

如果你没有指定分类，那么 id 会通过 . 分割来决定它在设置面板中的显示位置。

如果你的 id 不包含 .，它会显示在"其他"分类下，并以你的 id 作为分组标题。
如果你的 id 至少包含一个 .，最左边的部分会作为设置分类，第二部分作为分组标题，后续部分会被忽略。

读取设置项

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

if (app.extensionManager.setting.get('example.boolean')) {
    console.log("设置已启用。");
} else {
    console.log("设置已禁用。");
}

响应设置变化

当用户在设置面板中更改设置时，onChange() 事件处理器会被立即调用。

每次页面加载、扩展注册时也会调用。

{
    id: "example.boolean",
    name: "示例布尔设置",
    type: "boolean",
    defaultValue: false,
    onChange: (newVal, oldVal) => {
        console.log(`设置从 ${oldVal} 变为 ${newVal}`);
    },
}

写入设置项

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

try {
    await app.extensionManager.setting.set("example.boolean", true);
} catch (error) {
    console.error(`更改设置时出错: ${error}`);
}

额外配置

每种设置类型都会渲染一个 ComfyUI 前端表单组件。可以在 attrs 字段中为该组件传入额外属性。各类型支持的属性见类型一节。

例如，下面限制了数字输入框的范围和步长：

{
    id: "example.number",
    name: "示例数字设置",
    type: "number",
    defaultValue: 0,
    attrs: {
        min: 0,
        max: 100,
        step: 5,
    },
    onChange: (newVal, oldVal) => {
        console.log(`设置从 ${oldVal} 变为 ${newVal}`);
    },
}

如果你的扩展传入了 showButtons、maxFractionDigits、editable 或 filter 等 PrimeVue 属性，请参阅 PrimeVue 移除迁移指南。设置面板已不再使用 PrimeVue 组件，这些属性不会生效。

类型

布尔值（Boolean）

显示一个开关。

{
    id: "example.boolean",
    name: "示例布尔设置",
    type: "boolean",
    defaultValue: false,
    onChange: (newVal, oldVal) => {
        console.log(`设置从 ${oldVal} 变为 ${newVal}`);
    },
}

文本（Text）

自由文本输入。

{
    id: "example.text",
    name: "示例文本设置",
    type: "text",
    defaultValue: "Foo",
    onChange: (newVal, oldVal) => {
        console.log(`设置从 ${oldVal} 变为 ${newVal}`);
    },
}

数字（Number）

用于输入数字。

输入框始终显示增减按钮。支持的 attrs 有 min、max、step 和 formatOptions。formatOptions 接受 Intl.NumberFormatOptions，因此可以用 maximumFractionDigits 控制显示的小数位数。

{
    id: "example.number",
    name: "示例数字设置",
    type: "number",
    defaultValue: 42,
    attrs: {
        step: 0.1,
        formatOptions: { maximumFractionDigits: 1 },
    },
    onChange: (newVal, oldVal) => {
        console.log(`设置从 ${oldVal} 变为 ${newVal}`);
    },
}

滑块（Slider）

允许用户直接输入数字或通过滑块选择。

支持的 attrs 有 min、max 和 step。不支持区间。

{
    id: "example.slider",
    name: "示例滑块设置",
    type: "slider",
    attrs: {
        min: -10,
        max: 10,
        step: 0.5,
    },
    defaultValue: 0,
    onChange: (newVal, oldVal) => {
        console.log(`设置从 ${oldVal} 变为 ${newVal}`);
    },
}

下拉选择（Combo）

允许用户从下拉列表中选择。

你可以用纯字符串或带 text 和 value 字段的对象提供选项。如果只提供字符串，则会同时作为显示和实际值。

通过 searchable: true 属性允许用户搜索列表。不支持分组和自定义文本输入。

{
    id: "example.combo",
    name: "示例下拉设置",
    type: "combo",
    defaultValue: "first",
    options: [
        { text: "我的第一个选项", value: "first" },
        "我的第二个选项",
    ],
    attrs: {
        searchable: true,
    },
    onChange: (newVal, oldVal) => {
        console.log(`设置从 ${oldVal} 变为 ${newVal}`);
    },
}

颜色（Color）

允许用户通过颜色选择器选择颜色或输入十六进制颜色值。

注意格式必须为六位十六进制（带透明度时为八位），不支持三位简写。

{
    id: "example.color",
    name: "示例颜色设置",
    type: "color",
    defaultValue: "ff0000",
    onChange: (newVal, oldVal) => {
        console.log(`设置从 ${oldVal} 变为 ${newVal}`);
    },
}

图片（Image）

允许用户上传图片。

设置会以 data URL 格式保存。

{
    id: "example.image",
    name: "示例图片设置",
    type: "image",
    onChange: (newVal, oldVal) => {
        console.log(`设置从 ${oldVal} 变为 ${newVal}`);
    },
}

隐藏（Hidden）

隐藏设置不会显示在设置面板，但你可以在代码中读写它们。

{
    id: "example.hidden",
    name: "示例隐藏设置",
    type: "hidden",
}

其他

分类（Categories）

你可以通过 category 字段单独指定设置的分类，与 id 无关。这样可以在不更改 id 的情况下调整分类和命名，不会丢失用户已设置的值。

{
    id: "example.boolean",
    name: "示例布尔设置",
    type: "boolean",
    defaultValue: false,
    category: ["分类名称", "分组标题", "设置标签"],
}

工具提示（Tooltips）

你可以通过 tooltip 字段添加额外的上下文帮助。这会在字段名后显示一个小的 ℹ︎ 图标，用户悬停时会显示帮助文本。

{
    id: "example.boolean",
    name: "示例布尔设置",
    type: "boolean",
    defaultValue: false,
    tooltip: "这是一些有用的提示信息",
}