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: 49 additions & 0 deletions custom-nodes/v3_migration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -781,6 +781,55 @@ io.DynamicCombo.Input("combo", options=[
])
```

#### 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`:
Expand Down
53 changes: 51 additions & 2 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: ef191ae4
translationSourceHash: 6173fdf9
translationFrom: custom-nodes/v3_migration.mdx
translationBlockHashes:
"Overview": 109e87b3
"Core Concepts": 85282582
"Migration Steps": 7840c755
"Migration Steps": 8fcafaf6
---

## 概要
Expand Down Expand Up @@ -787,6 +787,55 @@ io.DynamicCombo.Input("combo", options=[
])
```

#### 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: 51 additions & 2 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: ef191ae4
translationSourceHash: 6173fdf9
translationFrom: custom-nodes/v3_migration.mdx
translationBlockHashes:
"Overview": 109e87b3
"Core Concepts": 85282582
"Migration Steps": 7840c755
"Migration Steps": 8fcafaf6
---

## 개요
Expand Down Expand Up @@ -786,6 +786,55 @@ io.DynamicCombo.Input("combo", options=[
])
```

#### 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
53 changes: 51 additions & 2 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: ef191ae4
translationSourceHash: 6173fdf9
translationFrom: custom-nodes/v3_migration.mdx
translationBlockHashes:
"Overview": 109e87b3
"Core Concepts": 85282582
"Migration Steps": 7840c755
"Migration Steps": 8fcafaf6
---

## 概述
Expand Down Expand Up @@ -787,6 +787,55 @@ io.DynamicCombo.Input("combo", options=[
])
```

#### 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