Jinja2：Python最主流的模板引擎-马育民老师

# 介绍

Jinja2 是 Python 生态中**最主流的模板引擎**，由 Armin Ronacher（Flask 作者）开发，广泛用于 Flask、FastAPI、Sphinx、Ansible、SaltStack 等项目，用来把模板文本 + 数据渲染成最终文本（HTML、配置文件、shell脚本等）。

### 核心思想

**模板 = 静态文本 + 占位/逻辑标记，填入变量输出最终内容**。

# 特点

1. **语法类似 Django Template，但功能更强**，支持完整表达式、函数调用、过滤器。
2. **沙箱模式**：可以限制模板可执行操作，适合外部用户上传模板的场景。
3. **自动转义**：默认开启 HTML 转义，防止 XSS；渲染配置文件时可关闭。
4. **模板继承、包含、宏**：实现页面复用，解决重复代码。
5. **支持过滤器、测试器、自定义扩展**，可接入Python函数。
6. **编译缓存**：模板会编译成 Python 字节码，重复渲染性能高。

# 安装

### pip 安装

```bash
pip install jinja2
```

### uv 安装

```
uv add jinja2
```

# 基础语法

### 1. 三种定界符
```jinja2
{{ 变量表达式 }}      {# 输出值 #}
{% 控制语句 %}        {# if、for、block、macro 逻辑 #}
{# 注释，不会输出 #}
```

### 2. 变量与过滤器 `|`
```jinja2
{# 变量输出 #}
{{ name }}
{{ user.age }}
{{ user['age'] }}

{# 过滤器：管道符 |，链式调用 #}
{{ name | upper }}          {# 转大写 #}
{{ num | default(0) }}      {# 默认值 #}
{{ content | escape }}      {# html转义，默认开启 #}
{{ list | join(',') }}
```

常用内置过滤器：`upper`、`lower`、`length`、`reverse`、`safe`（关闭转义）、`int`、`round`、`default`。

### 3. 条件判断
```jinja2
{% if score >= 60 %}
及格
{% elif score >= 80 %}
良好
{% else %}
不及格
{% endif %}
```

### 4. for循环
```jinja2
<ul>
{% for item in items %}
    <li>{{ loop.index }} - {{ item }}</li>
{% endfor %}
</ul>
```
循环内置变量 `loop`：
- `loop.index`：从1开始序号
- `loop.index0`：从0开始
- `loop.first` / `loop.last`：是否第一条/最后一条
- `loop.length`：列表长度

### 5. 模板继承（最常用）
父模板 base.html
```jinja2
<!DOCTYPE html>
<html>
<body>
{% block content %}{% endblock %}
</body>
</html>
```
子模板
```jinja2
{% extends "base.html" %}

{% block content %}
<h1>页面内容</h1>
{% endblock %}
```

### 6. 宏 macro（类似函数）
```jinja2
{% macro input(name, value='') %}
<input name="{{name}}" value="{{value}}">
{% endmacro %}

{{ input('username') }}
```

### 7. include 引入片段
```jinja2
{% include "header.html" %}
```

# Python 代码调用 Jinja2

### 方式1：字符串模板
```python
from jinja2 import Template

tpl = Template("Hello {{ name }}!")
result = tpl.render(name="Jinja2")
print(result) # Hello Jinja2!
```

### 方式2：从文件加载模板（项目常用）
```python
from jinja2 import Environment, FileSystemLoader

# 指定模板文件夹
env = Environment(loader=FileSystemLoader("./templates"))
tpl = env.get_template("demo.html")
out = tpl.render(title="标题", users=[1,2,3])
print(out)
```

# 使用场景

1. **Web后端渲染HTML**：Flask 默认模板引擎；FastAPI 可整合 Jinja2Templates。
2. **生成配置文件**：Ansible 大量使用 Jinja2 渲染 nginx、systemd 配置。
3. **代码生成**：自动生成 Python、C、SQL、Shell脚本。
4. **文档生成**：Sphinx文档工具。

原文出处：/show_1GW3riTvjdyN.html