> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-docs-recommend-assets-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 设置

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

## 基本操作

### 添加一个设置项

```javascript theme={null}
import { app } from "../../scripts/app.js";

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

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

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

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

### 读取设置项

```javascript theme={null}
import { app } from "../../scripts/app.js";

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

### 响应设置变化

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

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

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

### 写入设置项

```javascript theme={null}
import { app } from "../../scripts/app.js";

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

### 额外配置

设置类型基于 [PrimeVue](https://primevue.org/) 组件。
在 `attrs` 字段中添加 PrimeVue 文档中描述的属性即可为 ComfyUI 设置项配置更多参数。

例如，下面为数字输入框添加了增减按钮：

```javascript theme={null}
{
    id: "example.number",
    name: "示例数字设置",
    type: "number",
    defaultValue: 0,
    attrs: {
        showButtons: true,
    },
    onChange: (newVal, oldVal) => {
        console.log(`设置从 ${oldVal} 变为 ${newVal}`);
    },
}
```

## 类型

### 布尔值（Boolean）

显示一个开关。

基于 [ToggleSwitch PrimeVue 组件](https://primevue.org/toggleswitch/)。

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

### 文本（Text）

自由文本输入。

基于 [InputText PrimeVue 组件](https://primevue.org/inputtext/)。

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

### 数字（Number）

用于输入数字。

如需允许小数位，请将 `maxFractionDigits` 属性设置为大于 0 的数字。

基于 [InputNumber PrimeVue 组件](https://primevue.org/inputnumber/)。

```javascript theme={null}
{
    id: "example.number",
    name: "示例数字设置",
    type: "number",
    defaultValue: 42,
    attrs: {
        showButtons: true,
        maxFractionDigits: 1,
    },
    onChange: (newVal, oldVal) => {
        console.log(`设置从 ${oldVal} 变为 ${newVal}`);
    },
}
```

### 滑块（Slider）

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

基于 [Slider PrimeVue 组件](https://primevue.org/slider/)。不支持区间。

```javascript theme={null}
{
    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` 字段的对象提供选项。如果只提供字符串，则会同时作为显示和实际值。

通过 `editable: true` 属性允许用户输入自定义内容，通过 `filter: true` 属性允许搜索。

基于 [Select PrimeVue 组件](https://primevue.org/select/)。不支持分组。

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

### 颜色（Color）

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

注意格式必须为六位十六进制，不支持三位简写。

基于 [ColorPicker PrimeVue 组件](https://primevue.org/colorpicker/)。

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

### 图片（Image）

允许用户上传图片。

设置会以 [data URL](https://developer.mozilla.org/en-US/docs/Web/URI/Schemes/data) 格式保存。

基于 [FileUpload PrimeVue 组件](https://primevue.org/fileupload/)。

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

### 隐藏（Hidden）

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

```javascript theme={null}
{
    id: "example.hidden",
    name: "示例隐藏设置",
    type: "hidden",
}
```

## 其他

### 分类（Categories）

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

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

### 工具提示（Tooltips）

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

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