---
title: 循环
---

import { Callout } from 'fumadocs-ui/components/callout'
import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
import { Image } from '@/components/ui/image'

循环块是一个容器，用于重复执行块。可以迭代集合、重复操作固定次数，或在满足条件时继续执行。

<Callout type="info">
  循环块是容器节点，内部包含其他块。根据您的配置，内部块会多次执行。
</Callout>

## 配置选项

### 循环类型

选择以下四种循环类型之一：

<Tabs items={['For 循环', 'ForEach 循环', 'While 循环', 'Do-While 循环']}>
  <Tab>
    **For 循环（迭代）** - 一个执行固定次数的数字循环：
    
    <div className="flex justify-center">
      <Image
        src="/static/blocks/loop-1.png"
        alt="带有迭代的 For 循环"
        width={500}
        height={400}
        className="my-6"
      />
    </div>
    
    当需要重复操作特定次数时使用此方法。
    

    ```
    Example: Run 5 times
    - Iteration 1
    - Iteration 2
    - Iteration 3
    - Iteration 4
    - Iteration 5
    ```

  </Tab>
  <Tab>
    **ForEach 循环（集合）** - 一个基于集合的循环，迭代数组或对象中的每一项：
    
    <div className="flex justify-center">
      <Image
        src="/static/blocks/loop-2.png"
        alt="带有集合的 ForEach 循环"
        width={500}
        height={400}
        className="my-6"
      />
    </div>
    
    当需要处理一组项目时使用此方法。
    

    ```
    Example: Process ["apple", "banana", "orange"]
    - Iteration 1: Process "apple"
    - Iteration 2: Process "banana"
    - Iteration 3: Process "orange"
    ```

  </Tab>
  <Tab>
    **While 循环（基于条件）** - 当条件为真时继续执行：
    
    <div className="flex justify-center">
      <Image
        src="/static/blocks/loop-3.png"
        alt="带有条件的 While 循环"
        width={500}
        height={400}
        className="my-6"
      />
    </div>
    
    当需要循环直到满足特定条件时使用此方法。条件在每次迭代的**之前**进行检查。

    ```
    Example: While {"<variable.i>"} < 10
    - Check condition → Execute if true
    - Inside loop: Increment {"<variable.i>"}
    - Inside loop: Variables assigns i = {"<variable.i>"} + 1
    - Check condition → Execute if true
    - Check condition → Exit if false
    ```

  </Tab>
  <Tab>
    **Do-While 循环（基于条件）** - 至少执行一次，然后在条件为真时继续执行：
    
    <div className="flex justify-center">
      <Image
        src="/static/blocks/loop-4.png"
        alt="带有条件的 Do-While 循环"
        width={500}
        height={400}
        className="my-6"
      />
    </div>
    
    当需要至少执行一次，然后循环直到满足条件时使用此方法。条件在每次迭代的**之后**进行检查。

    ```
    Example: Do-while {"<variable.i>"} < 10
    - Execute blocks
    - Inside loop: Increment {"<variable.i>"}
    - Inside loop: Variables assigns i = {"<variable.i>"} + 1
    - Check condition → Continue if true
    - Check condition → Exit if false
    ```

  </Tab>
</Tabs>

## 如何使用循环

### 创建循环

1. 从工具栏中拖动一个循环块到画布上
2. 配置循环类型和参数
3. 将其他块拖入循环容器内
4. 根据需要连接这些块

### 访问结果

循环完成后，您可以访问聚合结果：

- **`<loop.results>`**：所有循环迭代结果的数组

## 示例用例

**处理 API 结果** - ForEach 循环处理来自 API 的客户记录

```
API (Fetch) → Loop (ForEach) → Agent (Analyze) → Function (Store)
```

**迭代内容生成** - For 循环生成多个内容变体

```
Loop (5x) → Agent (Generate) → Evaluator (Score) → Function (Select Best)
```

**带计数器的 While 循环** - While 循环使用计数器处理项目

```
Variables (i=0) → Loop (While i<10) → Agent (Process) → Variables (i++)
```

## 高级功能

### 限制

<Callout type="warning">
  容器块（循环和并行）不能嵌套在彼此内部。这意味着：
  - 您不能将一个循环块放入另一个循环块中
  - 您不能将一个并行块放入循环块中
  - 您不能将任何容器块放入另一个容器块中
  
  如果您需要多维迭代，请考虑重构您的工作流以使用顺序循环或分阶段处理数据。
</Callout>

<Callout type="info">
  循环是按顺序执行的，而不是并行执行。如果您需要并发执行，请使用并行块。
</Callout>

## 输入和输出

<Tabs items={['配置', '变量', '结果']}>
  <Tab>
    <ul className="list-disc space-y-2 pl-6">
      <li>
        <strong>循环类型</strong>：选择 'for'、'forEach'、'while' 或 'doWhile'
      </li>
      <li>
        <strong>迭代次数</strong>：执行的次数（for 循环）
      </li>
      <li>
        <strong>集合</strong>：要迭代的数组或对象（forEach 循环）
      </li>
      <li>
        <strong>条件</strong>：布尔表达式（while/do-while 循环）
      </li>
    </ul>
  </Tab>
  <Tab>
    <ul className="list-disc space-y-2 pl-6">
      <li>
        <strong>loop.currentItem</strong>：当前正在处理的项目
      </li>
      <li>
        <strong>loop.index</strong>：当前迭代编号（从 0 开始）
      </li>
      <li>
        <strong>loop.items</strong>：完整集合（forEach 循环）
      </li>
    </ul>
  </Tab>
  <Tab>
    <ul className="list-disc space-y-2 pl-6">
      <li>
        <strong>loop.results</strong>：所有迭代结果的数组
      </li>
      <li>
        <strong>结构</strong>：结果保持迭代顺序
      </li>
      <li>
        <strong>访问</strong>：在循环后的块中可用
      </li>
    </ul>
  </Tab>
</Tabs>

## 最佳实践

- **设置合理的限制**：保持迭代次数在合理范围内，以避免长时间的执行
- **对集合使用 ForEach**：在处理数组或对象时，使用 ForEach 而不是 For 循环
- **优雅地处理错误**：考虑在循环中添加错误处理，以实现更健壮的工作流程

## 输入与输出

<Tabs items={['Configuration', 'Variables', 'Results']}>
  <Tab>
    <ul className="list-disc space-y-2 pl-6">
      <li>
        <strong>循环类型</strong>：可选择 'for'、'forEach'、'while' 或 'doWhile'
      </li>
      <li>
        <strong>迭代次数</strong>：执行的次数（适用于 for 循环）
      </li>
      <li>
        <strong>集合</strong>：要遍历的数组或对象（适用于 forEach 循环）
      </li>
      <li>
        <strong>条件</strong>：要判断的布尔表达式（适用于 while/do-while 循环）
      </li>
    </ul>
  </Tab>
  <Tab>
    仅在循环**内部**可用：
    <ul className="list-disc space-y-2 pl-6">
      <li>
        <strong>{"<loop.index>"}</strong>：当前迭代次数（从 0 开始）
      </li>
      <li>
        <strong>{"<loop.currentItem>"}</strong>：当前正在处理的项（仅适用于 forEach）
      </li>
      <li>
        <strong>{"<loop.items>"}</strong>：完整集合（仅适用于 forEach）
      </li>
    </ul>
  </Tab>
  <Tab>
    <ul className="list-disc space-y-2 pl-6">
      <li>
        <strong>{"<blockname.results>"}</strong>：所有迭代结果的数组（通过区块名访问）
      </li>
      <li>
        <strong>结构</strong>：结果保持迭代顺序
      </li>
      <li>
        <strong>访问</strong>：循环结束后可在后续区块中访问
      </li>
    </ul>
  </Tab>
</Tabs>

## 最佳实践

- **设置合理的限制**：保持迭代次数适中，避免执行时间过长
- **集合处理优先用 ForEach**：处理数组或对象时，优先使用 ForEach 而不是 For 循环
- **优雅处理错误**：建议在循环内部添加错误处理，使流程更健壮
