---
pkg: '@nocobase/plugin-workflow-loop'
---

# ループ

## はじめに

ループは、プログラミング言語における `for`、`while`、`forEach` といった構文構造に相当します。特定の回数、またはデータコレクション（配列）に対して操作を繰り返し実行したい場合に、ループノードを使用できます。

## インストール

このプラグインは組み込み済みのため、インストールは不要です。

## ノードの作成

ワークフローの設定画面で、フロー内のプラス（「+」）ボタンをクリックし、「ループ」ノードを追加します。

![Creating a Loop Node](https://static-docs.nocobase.com/b3c8061a66bfff037f4b9509ab0aad75.png)

ループノードを作成すると、ループ内部に分岐が生成されます。この分岐内には、任意の数のノードを追加できます。これらのノードは、ワークフローのコンテキスト変数だけでなく、ループコンテキストのローカル変数も使用できます。例えば、ループコレクション内で各イテレーションで処理されるデータオブジェクトや、ループ回数のインデックス（インデックスは `0` から始まります）などです。ローカル変数のスコープはループ内部に限定されます。複数のループがネストしている場合は、各階層の具体的なループのローカル変数を使用できます。

## ノードの設定

![20241016135326](https://static-docs.nocobase.com/20241016135326.png)

### ループオブジェクト

ループは、ループオブジェクトのデータ型に応じて異なる処理を行います。

1.  **配列**: 最も一般的なケースです。通常、クエリノードの複数のデータ結果や、事前ロードされた多対多のリレーションデータなど、ワークフローコンテキストの変数を選択できます。配列が選択された場合、ループノードは配列内の各要素を反復処理し、各ループで現在の要素をループコンテキストのローカル変数に割り当てます。

2.  **数値**: 選択された変数が数値の場合、その数値がループ回数として使用されます。値は正の整数のみをサポートしており、負の数はループに入らず、小数の小数点以下は無視されます。ローカル変数内のループ回数のインデックスは、ループオブジェクトの値でもあります。この値は **0** から始まり、例えばループオブジェクトの数値が 5 の場合、各ループでのオブジェクトとインデックスは順に 0、1、2、3、4 となります。

3.  **文字列**: 選択された変数が文字列の場合、その文字列の長さがループ回数として使用され、各ループでインデックスに従って文字列内の各文字が処理されます。

4.  **その他**: オブジェクト型を含むその他の型の値は、単一処理のループオブジェクトとして扱われ、一度だけループします。通常、このようなケースではループを使用する必要はありません。

変数を選択する以外に、数値型と文字列型では定数を直接入力することもできます。例えば、`5`（数値型）と入力するとループノードは5回ループし、`abc`（文字列型）と入力するとループノードは3回ループし、それぞれ `a`、`b`、`c` の3文字を処理します。定数を使用したい場合は、変数選択ツールで希望の型を選択してください。

### ループ条件

`v1.4.0-beta` 以降のバージョンでは、ループ条件に関するオプションが追加され、ノード設定でループ条件を有効にできるようになりました。

**条件**

条件ノードの条件設定と同様に、複数の条件を組み合わせて設定でき、現在のループ内の変数（ループオブジェクト、ループインデックスなど）も使用できます。

**チェックタイミング**

プログラミング言語の `while` や `do/while` と同様に、設定された条件を各ループの開始前、または各ループの終了後に評価するかを選択できます。後置条件評価では、条件判定を行う前に、ループボディ内の他のノードを一度実行させることができます。

**条件が満たされない場合**

プログラミング言語の `break` や `continue` ステートメントと同様に、ループを終了するか、次のイテレーションに進むかを選択できます。

### ループ内部ノードでエラーが発生した場合の処理

`v1.4.0-beta` 以降のバージョンでは、ループ内部のノードが実行に失敗した場合（条件が満たされない、エラーが発生するなど）に、その後のフローをどのように処理するかを設定できるようになりました。以下の3つの処理方法をサポートしています。

*   ワークフローを終了する（プログラミングの `throw` に相当）
*   ループを終了してワークフローを続行する（プログラミングの `break` に相当）
*   次のループオブジェクトに進む（プログラミングの `continue` に相当）

デフォルトは「ワークフローを終了する」ですが、必要に応じて選択を変更できます。

## 例

例えば、注文時に各商品の在庫チェックを行い、在庫が十分であれば在庫を減らし、そうでなければ注文明細内の商品を無効として更新する、といったケースです。

1.  以下の3つのコレクションを作成します。商品コレクション <-(1:m)-- 注文明細コレクション --(m:1)-> 注文コレクション。データモデルは以下の通りです。

    **注文コレクション**
    | フィールド名     | フィールドタイプ       |
    | ---------------- | ---------------------- |
    | 注文商品明細     | 一対多（注文明細）     |
    | 注文合計金額     | 数値                   |

    **注文明細コレクション**
    | フィールド名 | フィールドタイプ       |
    | ------------ | ---------------------- |
    | 商品         | 多対一（商品）         |
    | 数量         | 数値                   |

    **商品コレクション**
    | フィールド名 | フィールドタイプ |
    | ------------ | -------- |
    | 商品名       | 一行テキスト |
    | 価格         | 数値     |
    | 在庫         | 整数     |

2.  ワークフローを作成します。トリガーには「コレクションイベント」を選択し、「注文」コレクションの「レコード追加時」にトリガーされるように設定します。さらに、「注文明細」コレクションと、その明細下の「商品」コレクションのリレーションデータを事前ロードするように設定する必要があります。

    ![Loop Node_Example_Trigger Configuration](https://static-docs.nocobase.com/0086601c2fc0e17a64d046a4c86b49b7.png)

3.  ループノードを作成し、ループオブジェクトとして「トリガーデータ / 注文明細」を選択します。これは、注文明細コレクション内の各レコードを処理することを意味します。

    ![Loop Node_Example_Loop Node Configuration](https://static-docs.nocobase.com/2507becc32db5a9a0641c198605a20da.png)

4.  ループノード内部に「条件判断」ノードを作成し、商品の在庫が十分であるかを確認します。

    ![Loop Node_Example_Condition Node Configuration](https://static-docs.nocobase.com/a6d08d15786841e1a3512b38e4629852.png)

5.  在庫が十分な場合は、「はい」の分岐で「計算ノード」と「データ更新」ノードを作成し、計算された削減後の在庫を対応する商品のレコードに更新します。

    ![Loop Node_Example_Calculation Node Configuration](https://static-docs.nocobase.com/8df3604c71f8f8705b1552d3ebfe3b50.png)

    ![Loop Node_Example_Update Stock Node Configuration](https://static-docs.nocobase.com/2d84baa9b3b01bd85fccda9eec992378.png)

6.  そうでない場合は、「いいえ」の分岐で「データ更新」ノードを作成し、注文明細のステータスを「無効」に更新します。

    ![Loop Node_Example_Update Order Detail Node Configuration](https://static-docs.nocobase.com/4996613090c254c69a1d80f3b3a7fae2.png)

全体のワークフロー構造は以下の図の通りです。

![Loop Node_Example_Workflow Structure](https://static-docs.nocobase.com/6f59ef246c1f19976344a7624c4c4151.png)

このワークフローの設定と有効化が完了すると、新しい注文が作成された際に、注文明細内の商品在庫が自動的にチェックされます。在庫が十分であれば在庫が減らされ、そうでなければ注文明細内の商品は無効として更新されます（これにより、有効な注文合計金額を計算できるようになります）。