diff --git a/custom-nodes/v3_migration.mdx b/custom-nodes/v3_migration.mdx index 02a11f6535..49e6d6aa59 100644 --- a/custom-nodes/v3_migration.mdx +++ b/custom-nodes/v3_migration.mdx @@ -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 `..` 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 `.` 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`: diff --git a/ja/custom-nodes/v3_migration.mdx b/ja/custom-nodes/v3_migration.mdx index f10909f82c..341a9ef9c2 100644 --- a/ja/custom-nodes/v3_migration.mdx +++ b/ja/custom-nodes/v3_migration.mdx @@ -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 --- ## 概要 @@ -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` として宣言するだけです: diff --git a/ko/custom-nodes/v3_migration.mdx b/ko/custom-nodes/v3_migration.mdx index e72cf29dcb..2e31159281 100644 --- a/ko/custom-nodes/v3_migration.mdx +++ b/ko/custom-nodes/v3_migration.mdx @@ -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 --- ## 개요 @@ -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`로 선언하기만 하면 됩니다. diff --git a/zh/custom-nodes/v3_migration.mdx b/zh/custom-nodes/v3_migration.mdx index 6bfe545caf..f85cef6ebc 100644 --- a/zh/custom-nodes/v3_migration.mdx +++ b/zh/custom-nodes/v3_migration.mdx @@ -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 --- ## 概述 @@ -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`: