Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 0 additions & 49 deletions custom-nodes/v3_migration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@

## Migration Steps

Going from V1 to V3 should be simple in most cases and is simply a syntax change.

Check warning on line 76 in custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/v3_migration.mdx#L76

Did you really mean 'define_schema'?

### Step 1: Change Base Class

Expand Down Expand Up @@ -207,7 +207,7 @@

### Step 5: Handle Special Methods

The same special methods are supported as in v1, but either lowercased or renamed entirely to be more clear. Their usage remains the same.

Check warning on line 210 in custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/v3_migration.mdx#L210

Did you really mean 'lowercased'?

#### Validation (V1 → V3)

Expand Down Expand Up @@ -278,7 +278,7 @@

### Step 6: Create Extension and Entry Point

Instead of defining dictionaries to link node id to node class/display name, there is now a ```ComfyExtension``` class and an expected ```comfy_entrypoint``` function to be defined.

Check warning on line 281 in custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/v3_migration.mdx#L281

Did you really mean 'control_after_generate'?

In the future, more functions may be added to ComfyExtension to register more than just nodes via ```get_node_list```.

Expand Down Expand Up @@ -347,7 +347,7 @@

### ComfyUI Types

| V1 Type | V3 Type | Example |

Check warning on line 350 in custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/v3_migration.mdx#L350

Did you really mean 'Tooltip'?
|---------|---------|---------|
| `"IMAGE"` | `io.Image.Input()` | `io.Image.Input("image", tooltip="Input image")` |
| `"MASK"` | `io.Mask.Input()` | `io.Mask.Input("mask", optional=True)` |
Expand Down Expand Up @@ -381,12 +381,12 @@
| `display_name` | `str` | `None` | Display name shown in the UI. Falls back to `node_id` if not set. |
| `category` | `str` | `"sd"` | Category in the "Add Node" menu (e.g. `"image/transform"`). |
| `description` | `str` | `""` | Tooltip shown when hovering over the node. |
| `inputs` | `list[Input]` | `[]` | List of input definitions. |

Check warning on line 384 in custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/v3_migration.mdx#L384

Did you really mean 'kwargs'?
| `outputs` | `list[Output]` | `[]` | List of output definitions. |
| `hidden` | `list[Hidden]` | `[]` | List of hidden inputs to request (see [Hidden Inputs](#hidden-inputs)). |
| `search_aliases` | `list[str]` | `[]` | Alternative names for search. Useful for synonyms or old names after renaming. |

Check warning on line 387 in custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/v3_migration.mdx#L387

Did you really mean 'kwarg'?
| `is_output_node` | `bool` | `False` | Marks the node as an output node, causing it and its dependencies to be executed. |
| `is_input_list` | `bool` | `False` | When True, all inputs become `list[type]` regardless of how many items are passed in. |

Check warning on line 389 in custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/v3_migration.mdx#L389

Did you really mean 'tooltip'?
| `is_deprecated` | `bool` | `False` | Flags the node as deprecated, signaling users to find alternatives. |
| `is_experimental` | `bool` | `False` | Flags the node as experimental, warning users it may change. |
| `is_dev_only` | `bool` | `False` | Hides the node from search/menus unless dev mode is enabled. |
Expand Down Expand Up @@ -505,7 +505,7 @@

#### Save Helpers

Save helpers provide methods for saving files to the output directory with proper metadata embedding. They are typically used in output nodes.

Check warning on line 508 in custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/v3_migration.mdx#L508

Did you really mean 'Dicts'?

```python
from comfy_api.latest import ui, io
Expand Down Expand Up @@ -555,7 +555,7 @@
```

<Tip>
Passing `cls=cls` to save/preview helpers allows them to automatically embed workflow metadata (prompt, extra_pnginfo) in the saved files. Make sure to include `io.Hidden.prompt` and `io.Hidden.extra_pnginfo` in your schema's hidden list, or set `is_output_node=True` which adds them automatically.

Check warning on line 558 in custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/v3_migration.mdx#L558

Did you really mean 'extra_pnginfo'?

Check warning on line 558 in custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/v3_migration.mdx#L558

Did you really mean 'schema's'?
</Tip>

#### Returning Raw UI Dicts
Expand Down Expand Up @@ -699,7 +699,7 @@
)
```

Autogrow can be combined with MatchType to create lists of type-matched inputs:

Check warning on line 702 in custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/v3_migration.mdx#L702

Did you really mean 'Autogrow'?

```python
@classmethod
Expand Down Expand Up @@ -781,58 +781,9 @@
])
```

#### DynamicGroup

`DynamicGroup` repeats a widget template as a list of rows that the user adds and removes in the node. Each row shows the template's fields, and `execute` receives the rows as a list of dicts. Use it for nodes that take a variable number of structured items, for example a list of named weights or a set of per-item settings.

```python
@classmethod
def define_schema(cls):
return io.Schema(
node_id="WeightedMergeNode",
display_name="Weighted Merge",
category="transform",
inputs=[
io.DynamicGroup.Input(
"rows",
template=[
io.String.Input("name"),
io.Float.Input("weight", default=1.0, optional=True),
],
min=0, # minimum number of rows (default 0)
max=5, # maximum number of rows (default 20, hard cap 20)
group_name="Item", # label used by the add and remove controls
),
],
outputs=[io.Image.Output()],
)

@classmethod
def execute(cls, rows: io.DynamicGroup.Type) -> io.NodeOutput:
# rows is a list of dicts, one per submitted row
for row in rows:
name = row["name"]
weight = row["weight"]
...
```

Rules:

- The `template` is a non-empty list of widget inputs. Socket inputs, nested dynamic inputs, and fields with `force_input` are rejected.
- Field ids must be unique within a row. The group id and field ids cannot contain a `.`.
- `min` and `max` are integers that count submitted rows (defaults `0` and `20`). `max` must be between `1` and `20`, and `min` must be between `0` and `max`.
- Rows are submitted as `<group>.<index>.<field>` prompt keys, where the index runs from `0` to `max - 1` and has no leading zeros, even when fewer than `max` rows are submitted. The `<group>.` prefix is reserved for the group, so a sibling input cannot reuse it.

Values in `execute`:

- The group arrives as a `list[dict[str, Any]]`, one dict per submitted row. A gap in the middle keeps its slot as a dict with `None` fields, so `rows[i]` always matches row `i`. A field that is omitted is `None`, and widget defaults are not filled in; a submitted empty value such as an empty string is preserved.
- An empty group is `[]`.
- With `is_input_list=True`, each field arrives as a list and a missing field is `[None]`.
- With `lazy=True`, each field holds a `(value, original_key)` tuple.

### Async Execute

V3 supports async `execute` methods. This is useful for nodes that perform I/O operations, API calls, or other async work. Simply declare `execute` as `async`:

Check warning on line 786 in custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/v3_migration.mdx#L786

Did you really mean 'io'?

```python
@classmethod
Expand Down Expand Up @@ -907,7 +858,7 @@

The `old_widget_ids` parameter is important: workflow JSON stores widget values by position index, not by name. This list maps those positional indexes to input IDs so the replacement system can correctly identify widget values during migration.

For nodes using dynamic inputs (like Autogrow), use dotted paths in the mapping:

Check warning on line 861 in custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

custom-nodes/v3_migration.mdx#L861

Did you really mean 'Autogrow'?

```python
input_mapping=[
Expand Down
53 changes: 2 additions & 51 deletions ja/custom-nodes/v3_migration.mdx
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
title: "V3 移行"
description: "既存の V1 ノードを新しい V3 スキーマに移行する方法。"
translationSourceHash: 6173fdf9
translationSourceHash: ef191ae4
translationFrom: custom-nodes/v3_migration.mdx
translationBlockHashes:
"Overview": 109e87b3
"Core Concepts": 85282582
"Migration Steps": 8fcafaf6
"Migration Steps": 7840c755
---

## 概要
Expand Down Expand Up @@ -41,7 +41,7 @@
return {"required": {...}}

RETURN_TYPES = ("IMAGE",)
FUNCTION = "execute"

Check warning on line 44 in ja/custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

ja/custom-nodes/v3_migration.mdx#L44

Did you really mean 'io'?
CATEGORY = "my_category"

def execute(self, ...):
Expand Down Expand Up @@ -79,7 +79,7 @@

## 移行ステップ

V1 から V3 への移行は、ほとんどの場合単純で、構文の変更のみです。

Check warning on line 82 in ja/custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

ja/custom-nodes/v3_migration.mdx#L82

Did you really mean 'io'?

### ステップ 1: ベースクラスの変更

Expand Down Expand Up @@ -121,7 +121,7 @@
def INPUT_TYPES(s):
return {
"required": {
"image": ("IMAGE",),

Check warning on line 124 in ja/custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

ja/custom-nodes/v3_migration.mdx#L124

Did you really mean 'define_schema'?
"int_field": ("INT", {
"default": 0,
"min": 0,
Expand Down Expand Up @@ -303,7 +303,7 @@

**V3:**
```python
from comfy_api.latest import ComfyExtension

Check warning on line 306 in ja/custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

ja/custom-nodes/v3_migration.mdx#L306

Did you really mean 'control_after_generate'?

class MyExtension(ComfyExtension):
# 非同期として宣言する必要あり
Expand Down Expand Up @@ -389,10 +389,10 @@
| `description` | `str` | `""` | ノードにホバーしたときに表示されるツールチップ。 |
| `inputs` | `list[Input]` | `[]` | 入力定義のリスト。 |
| `outputs` | `list[Output]` | `[]` | 出力定義のリスト。 |
| `hidden` | `list[Hidden]` | `[]` | 要求する隠し入力のリスト([非表示入力](#非表示入力) を参照)。 |

Check warning on line 392 in ja/custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

ja/custom-nodes/v3_migration.mdx#L392

Did you really mean 'kwargs'?
| `search_aliases` | `list[str]` | `[]` | 検索の代替名。同義語や改名後の旧名に有用。 |
| `is_output_node` | `bool` | `False` | ノードを出力ノードとしてマークし、それとその依存関係を実行させる。 |
| `is_input_list` | `bool` | `False` | True の場合、いくつのアイテムが渡されても、すべての入力が `list[type]` になる。 |

Check warning on line 395 in ja/custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

ja/custom-nodes/v3_migration.mdx#L395

Did you really mean 'kwarg'?
| `is_deprecated` | `bool` | `False` | ノードを非推奨としてフラグ付けし、ユーザーに代替手段を探すよう通知。 |
| `is_experimental` | `bool` | `False` | ノードを実験的としてフラグ付けし、変更される可能性があることをユーザーに警告。 |
| `is_dev_only` | `bool` | `False` | 開発モードが有効でない限り、検索/メニューからノードを隠す。 |
Expand Down Expand Up @@ -705,7 +705,7 @@
)
```

Autogrow は MatchType と組み合わせて、型が一致した入力のリストを作成できます:

Check warning on line 708 in ja/custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

ja/custom-nodes/v3_migration.mdx#L708

Did you really mean 'Autogrow'?

```python
@classmethod
Expand Down Expand Up @@ -787,55 +787,6 @@
])
```

#### DynamicGroup

`DynamicGroup` は、ウィジェットのテンプレートを複数の行として繰り返し、ユーザーがノード上で行を追加・削除できるようにします。各行はテンプレートのフィールドを表示し、`execute` は行を辞書のリストとして受け取ります。名前付きの重みのリストや項目ごとの設定など、構造化された項目を可変個数受け取るノードに適しています。

```python
@classmethod
def define_schema(cls):
return io.Schema(
node_id="WeightedMergeNode",
display_name="Weighted Merge",
category="transform",
inputs=[
io.DynamicGroup.Input(
"rows",
template=[
io.String.Input("name"),
io.Float.Input("weight", default=1.0, optional=True),
],
min=0, # 最小行数(デフォルト 0)
max=5, # 最大行数(デフォルト 20、上限 20)
group_name="Item", # 追加・削除コントロールで使うラベル
),
],
outputs=[io.Image.Output()],
)

@classmethod
def execute(cls, rows: io.DynamicGroup.Type) -> io.NodeOutput:
# rows は辞書のリストで、送信された行ごとに 1 つ
for row in rows:
name = row["name"]
weight = row["weight"]
...
```

ルール:

- `template` は空でないウィジェット入力のリストです。ソケット入力、ネストされた動的入力、`force_input` を設定したフィールドは拒否されます。
- フィールド id は 1 行内で一意でなければなりません。グループ id とフィールド id に `.` を含めることはできません。
- `min` と `max` は送信された行数を数える整数です(デフォルトは `0` と `20`)。`max` は `1` 以上 `20` 以下でなければならず、`min` は `0` 以上 `max` 以下でなければなりません。
- 行は `<グループ>.<インデックス>.<フィールド>` 形式の prompt キーで送信され、インデックスは `0` から `max - 1` の範囲で先頭のゼロを付けません(送信する行が `max` 未満でも同じです)。`<グループ>.` プレフィックスはグループ用に予約されるため、兄弟入力で再利用することはできません。

`execute` で受け取る値:

- グループは `list[dict[str, Any]]` として渡され、送信された行ごとに 1 つの辞書になります。途中の欠落は `None` フィールドの辞書としてそのスロットを保持するため、`rows[i]` は常に `i` 行目に対応します。省略されたフィールドは `None` になり、ウィジェットのデフォルト値は埋め込まれません。送信された空の値(空文字列など)はそのまま保持されます。
- 空のグループは `[]` です。
- `is_input_list=True` の場合、各フィールドはリストとして渡され、欠落したフィールドは `[None]` になります。
- `lazy=True` の場合、各フィールドは `(値, 元のキー)` タプルを保持します。

### 非同期 Execute

V3 は非同期の `execute` メソッドをサポートしています。これは、I/O 操作、API 呼び出し、その他の非同期処理を行うノードに便利です。`execute` を `async` として宣言するだけです:
Expand Down
53 changes: 2 additions & 51 deletions ko/custom-nodes/v3_migration.mdx
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
title: "V3 마이그레이션"
description: "기존 V1 노드를 새 V3 스키마로 마이그레이션하는 방법."
translationSourceHash: 6173fdf9
translationSourceHash: ef191ae4
translationFrom: custom-nodes/v3_migration.mdx
translationBlockHashes:
"Overview": 109e87b3
"Core Concepts": 85282582
"Migration Steps": 8fcafaf6
"Migration Steps": 7840c755
---

## 개요
Expand Down Expand Up @@ -40,7 +40,7 @@
return {"required": {...}}

RETURN_TYPES = ("IMAGE",)
FUNCTION = "execute"

Check warning on line 43 in ko/custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

ko/custom-nodes/v3_migration.mdx#L43

Did you really mean 'io'?
CATEGORY = "my_category"

def execute(self, ...):
Expand Down Expand Up @@ -78,7 +78,7 @@

## 마이그레이션 단계

대부분의 경우 V1에서 V3으로의 이동은 간단하며, 단순한 문법 변경에 불과합니다.

Check warning on line 81 in ko/custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

ko/custom-nodes/v3_migration.mdx#L81

Did you really mean 'io'?

### 단계 1: 기본 클래스 변경

Expand Down Expand Up @@ -304,7 +304,7 @@
```python
from comfy_api.latest import ComfyExtension

class MyExtension(ComfyExtension):

Check warning on line 307 in ko/custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

ko/custom-nodes/v3_migration.mdx#L307

Did you really mean 'control_after_generate'?
# 반드시 비동기로 선언해야 함
async def get_node_list(self) -> list[type[io.ComfyNode]]:
return [
Expand Down Expand Up @@ -391,7 +391,7 @@
| `hidden` | `list[Hidden]` | `[]` | 요청할 히든 입력 목록 (참조: [히든 입력](#hidden-inputs)). |
| `search_aliases` | `list[str]` | `[]` | 검색을 위한 대체 이름. 동의어나 이름 변경 후의 이전 이름에 유용합니다. |
| `is_output_node` | `bool` | `False` | 노드를 출력 노드로 표시하여, 해당 노드와 그 의존성이 실행되도록 합니다. |
| `is_input_list` | `bool` | `False` | True이면 모든 입력이 전달된 항목 수에 관계없이 `list[type]`이 됩니다. |

Check warning on line 394 in ko/custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

ko/custom-nodes/v3_migration.mdx#L394

Did you really mean 'kwarg'?
| `is_deprecated` | `bool` | `False` | 노드를 지원 중단됨으로 표시하여, 사용자에게 대안을 찾도록 알립니다. |
| `is_experimental` | `bool` | `False` | 노드를 실험적으로 표시하여, 사용자에게 변경될 수 있음을 경고합니다. |
| `is_dev_only` | `bool` | `False` | 개발자 모드가 활성화되지 않은 경우 검색/메뉴에서 노드를 숨깁니다. |
Expand Down Expand Up @@ -704,7 +704,7 @@
)
```

Autogrow can be combined with MatchType to create lists of type-matched inputs:

Check warning on line 707 in ko/custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

ko/custom-nodes/v3_migration.mdx#L707

Did you really mean 'Autogrow'?

```python
@classmethod
Expand Down Expand Up @@ -786,55 +786,6 @@
])
```

#### DynamicGroup

`DynamicGroup`는 위젯 템플릿을 여러 행으로 반복하며, 사용자가 노드에서 행을 추가하거나 제거할 수 있습니다. 각 행은 템플릿의 필드를 표시하고, `execute`는 행을 딕셔너리 목록으로 받습니다. 이름이 있는 가중치 목록이나 항목별 설정처럼 구조화된 항목을 가변 개수로 받는 노드에 적합합니다.

```python
@classmethod
def define_schema(cls):
return io.Schema(
node_id="WeightedMergeNode",
display_name="Weighted Merge",
category="transform",
inputs=[
io.DynamicGroup.Input(
"rows",
template=[
io.String.Input("name"),
io.Float.Input("weight", default=1.0, optional=True),
],
min=0, # 최소 행 수 (기본값 0)
max=5, # 최대 행 수 (기본값 20, 상한 20)
group_name="Item", # 추가 및 제거 컨트롤에 사용하는 레이블
),
],
outputs=[io.Image.Output()],
)

@classmethod
def execute(cls, rows: io.DynamicGroup.Type) -> io.NodeOutput:
# rows는 제출된 행마다 하나씩 대응하는 딕셔너리 목록입니다
for row in rows:
name = row["name"]
weight = row["weight"]
...
```

규칙:

- `template`은 비어 있지 않은 위젯 입력 목록입니다. 소켓 입력, 중첩된 동적 입력, `force_input`을 설정한 필드는 거부됩니다.
- 필드 id는 한 행 안에서 고유해야 합니다. 그룹 id와 필드 id에는 `.`을 포함할 수 없습니다.
- `min`과 `max`는 제출된 행 수를 세는 정수입니다(기본값 `0`과 `20`). `max`는 `1` 이상 `20` 이하여야 하고, `min`은 `0` 이상 `max` 이하여야 합니다.
- 행은 `<그룹>.<인덱스>.<필드>` 형식의 prompt 키로 제출하며, 인덱스는 `0`부터 `max - 1`까지이고 앞에 오는 0을 붙이지 않습니다(제출하는 행이 `max`보다 적어도 마찬가지입니다). `<그룹>.` 접두사는 그룹 전용으로 예약되므로 형제 입력에서 재사용할 수 없습니다.

`execute`에서 받는 값:

- 그룹은 `list[dict[str, Any]]`로 전달되며, 제출된 행마다 딕셔너리 하나가 대응합니다. 중간의 비어 있는 위치는 `None` 필드를 가진 딕셔너리로 슬롯을 유지하므로 `rows[i]`는 항상 `i`번째 행과 일치합니다. 생략된 필드는 `None`이 되고 위젯 기본값은 채워지지 않습니다. 제출된 빈 값(빈 문자열 등)은 그대로 유지됩니다.
- 빈 그룹은 `[]`입니다.
- `is_input_list=True`이면 각 필드가 목록으로 전달되고, 누락된 필드는 `[None]`입니다.
- `lazy=True`이면 각 필드가 `(값, 원래 키)` 튜플을 담습니다.

### 비동기 Execute

V3는 비동기 `execute` 메서드를 지원합니다. I/O 작업, API 호출 또는 기타 비동기 작업을 수행하는 노드에 유용합니다. `execute`를 `async`로 선언하기만 하면 됩니다.
Expand Down Expand Up @@ -912,7 +863,7 @@

The `old_widget_ids` parameter is important: workflow JSON stores widget values by position index, not by name. This list maps those positional indexes to input IDs so the replacement system can correctly identify widget values during migration.

For nodes using dynamic inputs (like Autogrow), use dotted paths in the mapping:

Check warning on line 866 in ko/custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

ko/custom-nodes/v3_migration.mdx#L866

Did you really mean 'Autogrow'?

```python
input_mapping=[
Expand Down
53 changes: 2 additions & 51 deletions zh/custom-nodes/v3_migration.mdx
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
title: "V3 迁移指南"
description: "如何将现有的 V1 节点迁移到新的 V3 架构。"
translationSourceHash: 6173fdf9
translationSourceHash: ef191ae4
translationFrom: custom-nodes/v3_migration.mdx
translationBlockHashes:
"Overview": 109e87b3
"Core Concepts": 85282582
"Migration Steps": 8fcafaf6
"Migration Steps": 7840c755
---

## 概述
Expand Down Expand Up @@ -123,7 +123,7 @@
"required": {
"image": ("IMAGE",),
"int_field": ("INT", {
"default": 0,

Check warning on line 126 in zh/custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

zh/custom-nodes/v3_migration.mdx#L126

Did you really mean 'define_schema'?
"min": 0,
"max": 4096,
"step": 64,
Expand Down Expand Up @@ -307,7 +307,7 @@

class MyExtension(ComfyExtension):
# 必须声明为异步
async def get_node_list(self) -> list[type[io.ComfyNode]]:

Check warning on line 310 in zh/custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

zh/custom-nodes/v3_migration.mdx#L310

Did you really mean 'control_after_generate'?
return [
Example,
# 在这里添加更多节点
Expand Down Expand Up @@ -389,10 +389,10 @@
| `description` | `str` | `""` | 悬停在节点上时显示的工具提示。 |
| `inputs` | `list[Input]` | `[]` | 输入定义列表。 |
| `outputs` | `list[Output]` | `[]` | 输出定义列表。 |
| `hidden` | `list[Hidden]` | `[]` | 要请求的隐藏输入列表(参见[隐藏输入](#隐藏输入))。 |

Check warning on line 392 in zh/custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

zh/custom-nodes/v3_migration.mdx#L392

Did you really mean 'kwargs'?
| `search_aliases` | `list[str]` | `[]` | 搜索的备用名称。适用于同义词或重命名后的旧名称。 |
| `is_output_node` | `bool` | `False` | 将节点标记为输出节点,使其及其依赖项被执行。 |
| `is_input_list` | `bool` | `False` | 当为 True 时,无论传入多少项,所有输入都变为 `list[type]`。 |

Check warning on line 395 in zh/custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

zh/custom-nodes/v3_migration.mdx#L395

Did you really mean 'kwarg'?
| `is_deprecated` | `bool` | `False` | 将节点标记为已弃用,提示用户寻找替代方案。 |
| `is_experimental` | `bool` | `False` | 将节点标记为实验性,警告用户它可能会更改。 |
| `is_dev_only` | `bool` | `False` | 除非启用开发模式,否则从搜索/菜单中隐藏节点。 |
Expand Down Expand Up @@ -484,7 +484,7 @@

### UI 辅助工具

V3 在 `ui` 模块中提供了内置的 UI 辅助工具,用于处理预览和保存文件等常见模式。通过 `ui` 参数将它们传递给 `io.NodeOutput`。

Check warning on line 487 in zh/custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

zh/custom-nodes/v3_migration.mdx#L487

Did you really mean 'io'?

#### 预览辅助工具

Expand Down Expand Up @@ -705,7 +705,7 @@
)
```

Autogrow 可以与 MatchType 结合使用,创建类型匹配的输入列表:

Check warning on line 708 in zh/custom-nodes/v3_migration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (dripart) - vale-spellcheck

zh/custom-nodes/v3_migration.mdx#L708

Did you really mean 'Autogrow'?

```python
@classmethod
Expand Down Expand Up @@ -787,55 +787,6 @@
])
```

#### DynamicGroup

`DynamicGroup` 会把一个 widget 模板重复为若干行,用户可以在节点中增删这些行。每一行都会显示模板中的字段,`execute` 会以字典列表的形式接收这些行。它适用于需要可变数量结构化条目的节点,例如一组带名称的权重,或一组逐项设置。

```python
@classmethod
def define_schema(cls):
return io.Schema(
node_id="WeightedMergeNode",
display_name="Weighted Merge",
category="transform",
inputs=[
io.DynamicGroup.Input(
"rows",
template=[
io.String.Input("name"),
io.Float.Input("weight", default=1.0, optional=True),
],
min=0, # 最少行数(默认 0)
max=5, # 最多行数(默认 20,上限 20)
group_name="Item", # 添加和删除控件使用的标签
),
],
outputs=[io.Image.Output()],
)

@classmethod
def execute(cls, rows: io.DynamicGroup.Type) -> io.NodeOutput:
# rows 是字典列表,每个提交的行对应一个字典
for row in rows:
name = row["name"]
weight = row["weight"]
...
```

规则:

- `template` 是非空的 widget 输入列表。套接字输入、嵌套的动态输入,以及设置了 `force_input` 的字段都会被拒绝。
- 同一行内的字段 id 必须唯一。组 id 和字段 id 都不能包含 `.`。
- `min` 和 `max` 是表示已提交行数的整数(默认 `0` 和 `20`)。`max` 必须介于 `1` 和 `20` 之间,且 `min` 必须介于 `0` 和 `max` 之间。
- 行以 `<组>.<索引>.<字段>` 形式的 prompt 键提交,索引范围是 `0` 到 `max - 1`,且不带前导零,即使提交的行数少于 `max` 也是如此。`<组>.` 前缀为该组保留,因此同级输入不能复用。

`execute` 中的取值:

- 该组以 `list[dict[str, Any]]` 形式传入,每个提交的行对应一个字典。中间的空缺会保留为字段为 `None` 的字典,因此 `rows[i]` 始终对应第 `i` 行。被省略的字段为 `None`,不会填入 widget 的默认值;而提交的空值(例如空字符串)会被保留。
- 空组为 `[]`。
- 当 `is_input_list=True` 时,每个字段以列表形式传入,缺失字段为 `[None]`。
- 当 `lazy=True` 时,每个字段保存一个 `(值, 原始键)` 元组。

### 异步 Execute

V3 支持异步的 `execute` 方法。这对执行 I/O 操作、API 调用或其他异步工作的节点很有用。只需将 `execute` 声明为 `async`:
Expand Down
Loading