---
title: 循环
---

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

循环块是 Sim 中的一个容器块，它允许您通过重复执行一组块来创建迭代工作流。循环使您的工作流能够进行迭代处理。

循环块支持四种类型的迭代：

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

## 概述

循环块可以让您：

<Steps>
  <Step>
    <strong>遍历集合</strong>：逐一处理数组或对象中的项目
  </Step>
  <Step>
    <strong>重复操作</strong>：执行块固定次数
  </Step>
  <Step>
    <strong>基于条件循环</strong>：在满足或直到满足条件时继续执行
  </Step>
  <Step>
    <strong>汇总结果</strong>：收集所有循环迭代的输出
  </Step>
</Steps>

## 工作原理

循环块通过顺序迭代执行包含的块：

1. **初始化循环** - 设置迭代参数（计数或集合）
2. **执行迭代** - 为当前迭代运行包含的块
3. **收集结果** - 存储每次迭代的输出
4. **继续或完成** - 进入下一次迭代或结束循环

## 配置选项

### 循环类型

选择四种循环类型之一：

<Tabs items={['For Loop', 'ForEach Loop', 'While Loop', 'Do-While Loop']}>
  <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-3.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 结果

<div className="mb-4 rounded-md border p-4">
  <h4 className="font-medium">场景：处理多个客户记录</h4>
  <ol className="list-decimal pl-5 text-sm">
    <li>API 块获取客户列表</li>
    <li>ForEach 循环遍历每个客户</li>
    <li>循环内：代理分析客户数据</li>
    <li>循环内：函数存储分析结果</li>
  </ol>
</div>

### 迭代内容生成

<div className="mb-4 rounded-md border p-4">
  <h4 className="font-medium">场景：生成多个变体</h4>
  <ol className="list-decimal pl-5 text-sm">
    <li>将 For 循环设置为 5 次迭代</li>
    <li>循环内：代理生成内容变体</li>
    <li>循环内：评估器对内容进行评分</li>
    <li>循环后：函数选择最佳变体</li>
  </ol>
</div>

### 使用 While 循环的计数器

<div className="mb-4 rounded-md border p-4">
  <h4 className="font-medium">场景：使用基于计数器的循环处理项目</h4>
  <ol className="list-decimal pl-5 text-sm">
    <li>初始化工作流变量：`i = 0`</li>
    <li>While 循环条件：`<variable.i>` \< 10</li>
    <li>循环内：代理处理索引为 `<variable.i>` 的项目</li>
    <li>循环内：变量递增 `i = <variable.i> + 1`</li>
    <li>循环在 i 小于 10 时继续</li>
  </ol>
</div>

## 高级功能

### 限制

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

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

## 输入和输出

<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.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 循环
- **优雅地处理错误**：考虑在循环中添加错误处理，以实现更健壮的工作流
