```mdx
---
title: "模板"
description: "使用 Jinja2 模板转换和格式化数据"
icon: "note-sticky"
---

The Template node transforms and formats data from multiple sources into structured text using Jinja2 templating. Use it to combine variables, format outputs, and prepare data for downstream nodes or end users.

<Frame caption="模板节点配置界面">
  <img src="https://assets-docs.dify.ai/2025/04/0838bb5c7e1d1a58ed30fcd9fc48920f.png" alt="模板节点界面" />
</Frame>

## Jinja2 模板

模板节点使用 Jinja2 模板语法创建基于工作流数据动态适应的内容。这提供了类似编程的功能，包括循环、条件和过滤器，用于复杂的文本生成。

### 变量替换

使用双大括号引用工作流变量：`{{ variable_name }}`。可以使用点符号和括号语法访问嵌套对象属性和数组元素。

```jinja2
{{ user.name }}
{{ items[0].title }}
{{ data.metrics.score }}
```

### 条件逻辑

使用 if-else 语句根据数据值显示不同内容：

```jinja2
{% if user.subscription == 'premium' %}
Welcome back, Premium Member! You have access to all features.
{% else %}
Consider upgrading to Premium for additional capabilities.
{% endif %}
```

### 循环和迭代

使用 for 循环处理数组和对象以生成重复内容：

```jinja2
{% for item in search_results %}
### Result {{ loop.index }}
**Score**: {{ item.score | round(2) }}
{{ item.content }}
---
{% endfor %}
```

<Frame caption="模板处理知识检索结果">
  <img src="https://assets-docs.dify.ai/2025/04/0ae3f13cf725cb2c52c72cc354e592ee.png" alt="模板格式化示例" />
</Frame>

## 数据格式化

### 过滤器

Jinja2 过滤器在模板渲染期间转换数据：

```jinja2
{{ name | upper }}
{{ price | round(2) }}
{{ content | replace('\n', '<br>') }}
{{ timestamp | strftime('%B %d, %Y') }}
{{ score | default('No score available') }}
```

### 错误处理

使用默认值和条件检查优雅地处理缺失或无效数据：

```jinja2
{{ user.email | default('No email provided') }}
{{ metrics.accuracy | round(2) if metrics.accuracy else 'Not calculated' }}
```

## 交互式表单

模板可以生成交互式 HTML 表单，用于在聊天界面中收集结构化数据：

```html
<form data-format="json">
  <label for="username">Username:</label>
  <input type="text" name="username" required />
  
  <label for="priority">Priority:</label>
  <input type="select" name="priority" data-options='["low","medium","high"]'/>
  
  <label for="message">Message:</label>
  <textarea name="message" placeholder="Enter your message"></textarea>
  
  <input type="checkbox" name="urgent" data-tip="Mark as urgent"/>
  <button data-variant="primary">Submit</button>
</form>
```

<Frame caption="在聊天界面中渲染的交互式表单">
  <img src="https://assets-docs.dify.ai/2025/04/9d24e9cfa3cdde00e4eee15bd4bbea76.png" alt="交互式表单渲染" />
</Frame>

当用户提交表单时，响应变为可在下游工作流节点中立即处理的结构化 JSON 数据。

## 输出限制

模板输出限制为**80,000 个字符**（可通过 `TEMPLATE_TRANSFORM_MAX_LENGTH` 配置）。这可以防止内存问题并确保大型模板输出的合理处理时间。

## 常见用例

**报告生成** - 将来自多个来源的数据组合成具有一致结构和样式的格式化报告。

**API 响应格式化** - 将内部数据结构转换为供外部使用的用户友好格式。

**LLM 提示词准备** - 将复杂数据结构化为格式良好的提示词，提高 LLM 的处理准确性。

**电子邮件和通知模板** - 根据用户数据和工作流结果生成带有动态内容的个性化消息。

**数据转换** - 在不同的数据格式和结构之间进行转换，以便与外部系统集成。

## 最佳实践

**使用描述性变量名**以使模板可读和可维护，特别是在处理复杂数据结构时。

**处理缺失数据**，通过默认值和条件检查，防止模板渲染错误。

**格式化以提高可读性**，通过使用适当的间距、换行和格式创建干净、专业的输出。

**使用示例数据进行测试**，确保模板处理边缘情况并在不同输入场景中产生预期结果。
```