diff --git a/custom-nodes/js/connection-callbacks-migration.mdx b/custom-nodes/js/connection-callbacks-migration.mdx index 97d87f79cc..a29db2000c 100644 --- a/custom-nodes/js/connection-callbacks-migration.mdx +++ b/custom-nodes/js/connection-callbacks-migration.mdx @@ -81,9 +81,37 @@ at step 2 via `graph.getNodeById()`. By `node:removed`, the node is gone. `graph.configure()` creates every node in the workflow before any node's own `configure()` runs and fires `onConnectionsChange` for its restored links. -So when your `onConnectionsChange` callback fires during load, every peer -node already exists and its link is already registered, so `graph.getNodeById()` -and link lookups from inside that callback resolve correctly. +So when your `onConnectionsChange` callback fires during load for a restored +link, every peer node already exists and its link is already registered, so `graph.getNodeById()` +and link lookups from inside that callback resolve correctly. Links pruned +from a subgraph definition are the exception, as the next section describes. + +## Unresolvable subgraph links are pruned on load + +When a subgraph definition loads, links inside it that can never resolve are +deleted. A link can never resolve when its origin or target node is missing, +when a subgraph boundary slot is out of range, or when a node dropped the +serialized input the link targeted. Each deleted link fires +`onConnectionsChange(type, index, false, link, slotOrIO)` on every endpoint node that +still exists. A new `false` notification during load means the link was pruned, +not that a user disconnected it. + +- **Timing.** Pruning runs when the subgraph definition is configured, after its + nodes and their `configure()` calls, and before any `onGraphConfigured` or + `onAfterGraphConfigured` hook runs. Nodes that define either hook are not + judged as having dropped an input, because they may add inputs from those + hooks. Nested subgraph nodes are the exception. +- **State inside the callback.** Every pruned link is already removed from the + subgraph, and stale IDs are cleared from the subgraph's boundary input and + output slots, before the first callback fires. Links that still resolve are + untouched. +- **Failure isolation.** Each endpoint callback runs in its own `try`. A throw is + reported as a warning and does not skip the other endpoint, the remaining + pruned links, or the rest of the load. + +Handlers that treat a load-time disconnect as a user action, such as removing a +dynamic input, should check `app.configuringGraph`, which is `true` while a +workflow loads. ## API prompt import does not reconnect resolved inputs diff --git a/es/custom-nodes/js/connection-callbacks-migration.mdx b/es/custom-nodes/js/connection-callbacks-migration.mdx index 76cb455eee..38124eac66 100644 --- a/es/custom-nodes/js/connection-callbacks-migration.mdx +++ b/es/custom-nodes/js/connection-callbacks-migration.mdx @@ -2,14 +2,15 @@ title: "Migración de callbacks de conexión para extensiones del frontend" sidebarTitle: "Migración de callbacks de conexión" description: "Orden de los callbacks onConnectionsChange y de eliminación de nodos, SubgraphIO en los límites de subgrafos y graph.events en extensiones de ComfyUI." -translationSourceHash: 06a9ae24 +translationSourceHash: 9a2f855a translationFrom: custom-nodes/js/connection-callbacks-migration.mdx translationBlockHashes: "_intro": cd84d91b "Check for SubgraphIO at subgraph boundaries": c049a9fe "Subscribe to node lifecycle events with graph.events": 1100692e "Node removal fires callbacks in this order (partially tested)": 720324f8 - "Workflow load resolves peer nodes before onConnectionsChange runs": 2b775215 + "Workflow load resolves peer nodes before onConnectionsChange runs": 87ff3f70 + "Unresolvable subgraph links are pruned on load": 09efbd4a "API prompt import does not reconnect resolved inputs": 619d6b69 "Reject connections before they are made": b9b94a8e "Removing a link inside the output callback skips the input callback": 3317def4 @@ -67,7 +68,17 @@ Para obtener el nodo eliminado desde el controlador `onConnectionsChange` de un ## La carga del flujo de trabajo resuelve los nodos pares antes de que se ejecute onConnectionsChange -`graph.configure()` crea todos los nodos del flujo de trabajo antes de que se ejecute el `configure()` propio de cualquier nodo y de que se dispare `onConnectionsChange` para sus enlaces restaurados. Por eso, cuando tu callback `onConnectionsChange` se dispara durante la carga, todos los nodos pares ya existen y su enlace ya está registrado, así que `graph.getNodeById()` y las búsquedas de enlaces desde dentro de ese callback se resuelven correctamente. +`graph.configure()` crea todos los nodos del flujo de trabajo antes de que se ejecute el `configure()` propio de cualquier nodo y de que se dispare `onConnectionsChange` para sus enlaces restaurados. Por eso, cuando tu callback `onConnectionsChange` se dispara durante la carga para un enlace restaurado, todos los nodos pares ya existen y su enlace ya está registrado, así que `graph.getNodeById()` y las búsquedas de enlaces desde dentro de ese callback se resuelven correctamente. Los enlaces eliminados de una definición de subgrafo son la excepción, como se describe en la siguiente sección. + +## Los enlaces de subgrafo que no se pueden resolver se eliminan al cargar + +Cuando se carga una definición de subgrafo, se eliminan los enlaces dentro de ella que nunca podrán resolverse. Un enlace no puede resolverse cuando falta su nodo de origen o de destino, cuando un slot del límite del subgrafo está fuera de rango, o cuando un nodo eliminó la entrada serializada a la que apuntaba el enlace. Cada enlace eliminado dispara `onConnectionsChange(type, index, false, link, slotOrIO)` en cada nodo extremo que todavía existe. Una nueva notificación `false` durante la carga significa que el enlace se eliminó, no que un usuario lo desconectó. + +- **Momento.** La eliminación se ejecuta cuando se configura la definición del subgrafo, después de sus nodos y de sus llamadas a `configure()`, y antes de que se ejecute cualquier hook `onGraphConfigured` u `onAfterGraphConfigured`. Los nodos que definen cualquiera de esos hooks no se consideran como si hubieran eliminado una entrada, porque pueden añadir entradas desde esos hooks. Los nodos de subgrafo anidados son la excepción. +- **Estado dentro del callback.** Antes de que se dispare el primer callback, todos los enlaces eliminados ya se han quitado del subgrafo, y los ID obsoletos se han borrado de los slots de entrada y salida del límite del subgrafo. Los enlaces que todavía se resuelven no se modifican. +- **Aislamiento de fallos.** El callback de cada extremo se ejecuta en su propio `try`. Una excepción se informa como advertencia y no omite el otro extremo, los demás enlaces eliminados ni el resto de la carga. + +Los manejadores que tratan una desconexión durante la carga como una acción del usuario, por ejemplo al quitar una entrada dinámica, deben comprobar `app.configuringGraph`, que es `true` mientras se carga un flujo de trabajo. ## La importación de prompts de API no reconecta las entradas resueltas diff --git a/ja/custom-nodes/js/connection-callbacks-migration.mdx b/ja/custom-nodes/js/connection-callbacks-migration.mdx index b6f64317ed..9ecadfde3d 100644 --- a/ja/custom-nodes/js/connection-callbacks-migration.mdx +++ b/ja/custom-nodes/js/connection-callbacks-migration.mdx @@ -2,14 +2,15 @@ title: "フロントエンド拡張機能向けの接続コールバック移行" sidebarTitle: "接続コールバックの移行" description: "ComfyUI拡張機能における onConnectionsChange とノード削除コールバックの順序、サブグラフ境界での SubgraphIO、graph.events についての説明。" -translationSourceHash: 06a9ae24 +translationSourceHash: 9a2f855a translationFrom: custom-nodes/js/connection-callbacks-migration.mdx translationBlockHashes: "_intro": cd84d91b "Check for SubgraphIO at subgraph boundaries": c049a9fe "Subscribe to node lifecycle events with graph.events": 1100692e "Node removal fires callbacks in this order (partially tested)": 720324f8 - "Workflow load resolves peer nodes before onConnectionsChange runs": 2b775215 + "Workflow load resolves peer nodes before onConnectionsChange runs": 87ff3f70 + "Unresolvable subgraph links are pruned on load": 09efbd4a "API prompt import does not reconnect resolved inputs": 619d6b69 "Reject connections before they are made": b9b94a8e "Removing a link inside the output callback skips the input callback": 3317def4 @@ -79,7 +80,17 @@ graph.events.addEventListener('node:added', (e) => { ## ワークフローの読み込みでは、onConnectionsChange が実行される前にピアノードが解決される -`graph.configure()` は、どのノードの `configure()` も実行される前にワークフロー内のすべてのノードを作成し、復元されたリンクに対して `onConnectionsChange` を発火します。そのため、読み込み中に `onConnectionsChange` コールバックが発火した時点では、すべてのピアノードがすでに存在し、そのリンクもすでに登録されているので、そのコールバック内からの `graph.getNodeById()` やリンクの検索は正しく解決されます。 +`graph.configure()` は、どのノードの `configure()` も実行される前にワークフロー内のすべてのノードを作成し、復元されたリンクに対して `onConnectionsChange` を発火します。そのため、読み込み中に復元されたリンクに対して `onConnectionsChange` コールバックが発火した時点では、すべてのピアノードがすでに存在し、そのリンクもすでに登録されているので、そのコールバック内からの `graph.getNodeById()` やリンクの検索は正しく解決されます。次のセクションで説明するように、サブグラフ定義から削除されたリンクは例外です。 + +## 解決できないサブグラフのリンクは読み込み時に削除される + +サブグラフ定義の読み込み時に、決して解決できないサブグラフ内のリンクは削除されます。リンクが解決できないのは、起点または終点のノードが存在しない場合、サブグラフ境界のスロットが範囲外の場合、またはノードがリンクの接続先だったシリアライズ済みの入力を削除した場合です。削除されたリンクごとに、まだ存在するすべての端点ノードで `onConnectionsChange(type, index, false, link, slotOrIO)` が発火します。読み込み中に新しく届く `false` 通知は、ユーザーが切断したのではなく、リンクが削除されたことを意味します。 + +- **タイミング。** 削除はサブグラフ定義の構成時に、そのノードと各ノードの `configure()` 呼び出しの後、かつ `onGraphConfigured` や `onAfterGraphConfigured` フックが実行される前に行われます。これらのフックのいずれかを定義しているノードは、フックから入力を追加する可能性があるため、入力を削除したとは判定されません。ただし、ネストされたサブグラフノードは例外です。 +- **コールバック内の状態。** 最初のコールバックが発火する前に、削除対象のリンクはすべてサブグラフから取り除かれ、サブグラフの境界入力・出力スロットから古い ID が消去されています。まだ解決できるリンクには手を加えません。 +- **障害の分離。** 各端点のコールバックはそれぞれ独立した `try` で実行されます。例外は警告として報告され、もう一方の端点、残りの削除対象リンク、または読み込みの残りの処理がスキップされることはありません。 + +読み込み中の切断をユーザー操作として扱うハンドラー(動的な入力を削除するものなど)は、ワークフローの読み込み中に `true` になる `app.configuringGraph` を確認してください。 ## API prompt インポートでは解決済みの入力が再接続されない diff --git a/ko/custom-nodes/js/connection-callbacks-migration.mdx b/ko/custom-nodes/js/connection-callbacks-migration.mdx index 2c379c868b..7d04fb9bb0 100644 --- a/ko/custom-nodes/js/connection-callbacks-migration.mdx +++ b/ko/custom-nodes/js/connection-callbacks-migration.mdx @@ -2,14 +2,15 @@ title: "프론트엔드 확장 프로그램을 위한 연결 콜백 마이그레이션" sidebarTitle: "연결 콜백 마이그레이션" description: "onConnectionsChange 및 노드 제거 콜백의 순서, 서브그래프 경계에서의 SubgraphIO, 그리고 ComfyUI 확장 프로그램에서의 graph.events." -translationSourceHash: 06a9ae24 +translationSourceHash: 9a2f855a translationFrom: custom-nodes/js/connection-callbacks-migration.mdx translationBlockHashes: "_intro": cd84d91b "Check for SubgraphIO at subgraph boundaries": c049a9fe "Subscribe to node lifecycle events with graph.events": 1100692e "Node removal fires callbacks in this order (partially tested)": 720324f8 - "Workflow load resolves peer nodes before onConnectionsChange runs": 2b775215 + "Workflow load resolves peer nodes before onConnectionsChange runs": 87ff3f70 + "Unresolvable subgraph links are pruned on load": 09efbd4a "API prompt import does not reconnect resolved inputs": 619d6b69 "Reject connections before they are made": b9b94a8e "Removing a link inside the output callback skips the input callback": 3317def4 @@ -81,9 +82,20 @@ graph.events.addEventListener('node:added', (e) => { `graph.configure()`는 워크플로의 모든 노드를 생성한 다음 각 노드의 `configure()`가 실행되면서 복원된 링크에 대해 `onConnectionsChange`를 발생시킵니다. 따라서 로드 중에 -`onConnectionsChange` 콜백이 실행될 때는 모든 피어 노드가 이미 존재하고 해당 링크도 +복원된 링크에 대해 `onConnectionsChange` 콜백이 실행될 때는 모든 피어 노드가 이미 존재하고 해당 링크도 이미 등록되어 있으므로, 그 콜백 내부에서의 `graph.getNodeById()`와 링크 조회가 -올바르게 해석됩니다. +올바르게 해석됩니다. 다음 섹션에서 설명하듯이 서브그래프 정의에서 제거된 링크는 +예외입니다. + +## 해석할 수 없는 서브그래프 링크는 로드 시 제거됩니다 + +서브그래프 정의가 로드될 때, 서브그래프 안에서 절대 해석될 수 없는 링크는 삭제됩니다. 링크를 해석할 수 없는 경우는 시작 또는 끝 노드가 없을 때, 서브그래프 경계 슬롯이 범위를 벗어났을 때, 또는 노드가 링크의 대상이던 직렬화된 입력을 삭제했을 때입니다. 삭제된 링크마다 아직 존재하는 모든 끝점 노드에서 `onConnectionsChange(type, index, false, link, slotOrIO)`가 발생합니다. 로드 중에 새로 오는 `false` 알림은 사용자가 연결을 끊은 것이 아니라 링크가 제거되었다는 뜻입니다. + +- **시점.** 제거는 서브그래프 정의가 구성될 때, 해당 노드와 각 노드의 `configure()` 호출 이후, 그리고 `onGraphConfigured` 또는 `onAfterGraphConfigured` 훅이 실행되기 전에 이루어집니다. 두 훅 중 하나를 정의한 노드는 그 훅에서 입력을 추가할 수 있으므로 입력을 삭제한 것으로 판단하지 않습니다. 단, 중첩된 서브그래프 노드는 예외입니다. +- **콜백 내부의 상태.** 첫 번째 콜백이 발생하기 전에 제거 대상 링크는 모두 서브그래프에서 이미 제거되어 있고, 서브그래프의 경계 입력 및 출력 슬롯에서 오래된 ID도 지워져 있습니다. 아직 해석할 수 있는 링크는 그대로 유지됩니다. +- **오류 격리.** 각 끝점 콜백은 별도의 `try`에서 실행됩니다. 예외는 경고로 보고되며, 다른 끝점, 나머지 제거 대상 링크 또는 로드의 나머지 과정을 건너뛰지 않습니다. + +로드 중의 연결 해제를 사용자 동작으로 처리하는 핸들러(예: 동적 입력 제거)는 워크플로가 로드되는 동안 `true`인 `app.configuringGraph`를 확인해야 합니다. ## API 프롬프트 가져오기는 확인된 입력을 다시 연결하지 않습니다 diff --git a/zh/custom-nodes/js/connection-callbacks-migration.mdx b/zh/custom-nodes/js/connection-callbacks-migration.mdx index 182a937790..7ba2575787 100644 --- a/zh/custom-nodes/js/connection-callbacks-migration.mdx +++ b/zh/custom-nodes/js/connection-callbacks-migration.mdx @@ -2,14 +2,15 @@ title: "前端扩展的连接回调迁移" sidebarTitle: "连接回调迁移" description: "onConnectionsChange 与节点移除回调的顺序、子图边界处的 SubgraphIO,以及 ComfyUI 扩展中的 graph.events。" -translationSourceHash: 06a9ae24 +translationSourceHash: 9a2f855a translationFrom: custom-nodes/js/connection-callbacks-migration.mdx translationBlockHashes: "_intro": cd84d91b "Check for SubgraphIO at subgraph boundaries": c049a9fe "Subscribe to node lifecycle events with graph.events": 1100692e "Node removal fires callbacks in this order (partially tested)": 720324f8 - "Workflow load resolves peer nodes before onConnectionsChange runs": 2b775215 + "Workflow load resolves peer nodes before onConnectionsChange runs": 87ff3f70 + "Unresolvable subgraph links are pruned on load": 09efbd4a "API prompt import does not reconnect resolved inputs": 619d6b69 "Reject connections before they are made": b9b94a8e "Removing a link inside the output callback skips the input callback": 3317def4 @@ -68,7 +69,17 @@ graph.events.addEventListener('node:added', (e) => { ## 工作流加载时会在 onConnectionsChange 运行之前解析对等节点 -`graph.configure()` 会在任何节点自身的 `configure()` 运行之前创建工作流中的每个节点,并为其恢复的连线触发 `onConnectionsChange`。因此,当你的 `onConnectionsChange` 回调在加载期间触发时,每个对等节点都已存在,其连线也已完成注册,所以在该回调内部通过 `graph.getNodeById()` 以及连线查找都能正确解析到目标。 +`graph.configure()` 会在任何节点自身的 `configure()` 运行之前创建工作流中的每个节点,并为其恢复的连线触发 `onConnectionsChange`。因此,当你的 `onConnectionsChange` 回调在加载期间为恢复的连线触发时,每个对等节点都已存在,其连线也已完成注册,所以在该回调内部通过 `graph.getNodeById()` 以及连线查找都能正确解析到目标。从子图定义中清除的连线是例外,详见下一节。 + +## 加载时会清除无法解析的子图连线 + +加载子图定义时,子图内永远无法解析的连线会被删除。连线无法解析的情况包括:起点或终点节点缺失、子图边界槽位超出范围,或节点删除了该连线所指向的已序列化输入。每条被删除的连线都会在每个仍然存在的端点节点上触发 `onConnectionsChange(type, index, false, link, slotOrIO)`。加载期间新出现的 `false` 通知表示该连线被清除,而不是用户断开了连接。 + +- **时机。** 清除在配置子图定义时进行,发生在其节点及各节点的 `configure()` 调用之后,并在任何 `onGraphConfigured` 或 `onAfterGraphConfigured` 钩子运行之前。定义了这两个钩子之一的节点不会被判定为删除了输入,因为它们可能会在这些钩子中添加输入;嵌套的子图节点除外。 +- **回调中的状态。** 在第一个回调触发之前,所有被清除的连线都已从子图中移除,子图边界输入和输出槽位中的过期 ID 也已清除。仍可解析的连线保持不变。 +- **故障隔离。** 每个端点的回调都在各自的 `try` 中运行。抛出的异常会作为警告报告,不会跳过另一个端点、其余被清除的连线或加载的其余部分。 + +将加载期间的断开视为用户操作的处理程序(例如移除动态输入)应检查 `app.configuringGraph`,它在工作流加载期间为 `true`。 ## 导入 API prompt 时不会重新连接已解析的输入