# 第3章 · Jinja2 模板引擎

对应教材第 3 章：三种语法、变量、控制结构、包含、继承、宏、全局对象、过滤器、Flask-Bootstrap。

第 2 章把 HTML 写死了，数据一变就得改页面。这一章解决的是：**页面只写一次，数据从 Python 传进来**。

> 教材这一章的 8 个知识点，本目录做成了 **8 个独立页面**，一页只讲一件事，方便课堂上逐个点开。

---

## 运行

```bat
cd ch03\ch3
..\..\..\venv\Scripts\python.exe app.py
```

首页 <http://127.0.0.1:5113/> 是一张“知识点地图”，点表格里的链接进各页。

| 地址 | 讲什么 | 模板文件 |
|---|---|---|
| `/` | 三种语法速查 + 知识点地图 | `index.html` |
| `/value`、`/value/谢福财` | 注入变量 + `or` 默认值 | `value.html` |
| `/control`、`/control/3` | `if` / `for`，空列表走哪个分支 | `control.html` |
| `/include` | `include` 包含页头页脚 | `include_demo.html` + `_header.html` + `_footer.html` |
| `/inherit` | `extends` 继承母版 | `inherit_child.html` |
| `/macro`、`/macro/3` | 宏 + 跨文件 `import` + 增减按钮 | `macro_page.html` + `macro_define.html` |
| `/global` | `add_template_global` 注册全局对象 | `global_demo.html` |
| `/filter` | 13 个内置过滤器 + 2 个自定义过滤器 | `filter_demo.html` |
| `/bootstrap` | Flask-Bootstrap / Bootstrap-Flask | `bootstrap_base.html` + `bootstrap_demo.html` |

---

## 文件

| 文件 | 作用 |
|---|---|
| `app.py` | 一份 `STUDENTS` 列表 + 8 组路由；`add_template_global` / `add_template_filter` 都在这 |
| `templates/base.html` | 母版：`<head>`、导航（9 个链接）、页脚、`{% block content %}` 挖坑 |
| `templates/_header.html` `_footer.html` | 被 `include` 的公共片段，自己不带 `<html>` |
| `templates/macro_define.html` | 宏仓库：只定义、不输出，供别的模板 `import` |
| `templates/bootstrap_base.html` | Bootstrap 母版，一句 `load_css()` 装好样式 |

---

## 知识点 → 代码对照

### 1. 三种标记

| 写法 | 名字 | 用途 |
|---|---|---|
| `{{ ... }}` | 表达式 | 输出变量的值 |
| `{% ... %}` | 语句 | for / if / block / extends / include / macro |
| `{# ... #}` | 注释 | 不会出现在最终 HTML 里，连源码里都不留 |

### 2. 变量与默认值

```jinja
{{ name }}                  {# 普通变量 #}
{{ username or '游客' }}     {# 没传值时给默认值，比 if 更短 #}
{{ students.0.name }}       {# 列表第 0 项的名字 #}
{{ students[1]['cls'] }}    {# 下标 + 键，和 Python 一样 #}
```

### 3. 控制结构

```jinja
{% if num <= 0 %}
  <h2>文章数量为 0，没有内容可展示。</h2>   {# 空列表也得有交代 #}
{% else %}
  {% for article in articles %}
    <h2>{{ loop.index }}. {{ article.title }}</h2>
    {% if loop.last %}<p>最后一篇</p>{% endif %}
  {% endfor %}
{% endif %}
```

`loop` 是 Jinja2 自动给的：`loop.index`（1 起）、`loop.index0`（0 起）、`loop.first`、`loop.last`、`loop.length`。

### 4. 包含 include 与继承 extends

| 写法 | 比喻 | 用在哪 |
|---|---|---|
| `{% include 'x.html' %}` | 把一页纸**贴**进来 | 页头、页脚、广告条 |
| `{% extends 'base.html' %}` | 照模板**填**内容 | 整页骨架 |

```jinja
{% include '_header.html' %}      {# 公共块直接搬进来 #}

{% extends 'base.html' %}         {# 子模板第一行 #}
{% block title %}标题{% endblock %}
{% block content %} ... {% endblock %}
```

### 5. 宏 macro（定义在单独文件）

`macro_define.html`：

```jinja
{% macro article_item(title, content) %}
  <h2>{{ title }}</h2><p>{{ content }}</p>
{% endmacro %}
```

用的时候先 import，再像函数一样调用：

```jinja
{% import 'macro_define.html' as macro %}
{{ macro.article_item('标题', '正文') }}
{{ macro.button('−1 篇', '/macro/' ~ num_prev) }}
```

### 6. 注册全局对象

```python
def range_list(x):
    return list(range(x))

app.add_template_global(range_list, 'global_test')   # 模板里 {{ global_test(10) }}
app.add_template_global(2026, 'YEAR')                # 常量也能注册
```

好处：`base.html` 这种被所有页面继承的模板里要用某个函数，不必每个视图都传一遍。

### 7. 变量过滤器

```python
def convert_time(t):
    return time.strftime('%Y-%m-%d %H:%M:%S', time.localtime(t))

app.add_template_filter(convert_time)      # 不写别名 = 用函数名
```

```jinja
{{ 1572497288.095447 | convert_time }}     {# 2019-10-31 12:48:08 #}
{{ 85 | score_level }}                      {# 自定义：良好 #}
{{ name | trim | upper }}                   {# 过滤器可串联 #}
```

内置常用：`length` `upper` `lower` `trim` `default` `round` `truncate` `join` `sort` `first` `last` `replace` `striptags` `safe` `tojson`。

### 8. Flask-Bootstrap

```python
from flask_bootstrap import Bootstrap5
Bootstrap5(app)
```

母版里两句话装好 CSS/JS：

```jinja
{{ bootstrap.load_css() }}
...
{{ bootstrap.load_js() }}
```

### 9. `{% raw %}`

要在页面上**原样显示** `{{ }}`（比如讲义里教语法），用：

```jinja
{% raw %}{{ 这是要显示的文字 }}{% endraw %}
```

---

## 常见坑

| 现象 | 原因 | 解决 |
|---|---|---|
| `TemplateNotFound: base.html` | `templates/` 目录名拼错，或没在项目目录下运行 | 目录必须叫 `templates`；`cd` 进项目再跑 |
| `TemplateNotFound: bootstrap/base.html` | Bootstrap-Flask 2.x **删掉了**自带的 base 模板 | 自己写母版（看 `bootstrap_base.html`），用 `load_css()` / `load_js()` |
| `UndefinedError: 'xxx' is undefined` | 视图函数没传这个变量 | 检查 `render_template()` 的关键字参数，或用 `or` 兜底 |
| `extends` 没生效 | 它不在第一行 | 前面不能有任何输出（`{# #}` 注释可以） |
| `{% block %}` 内容不显示 | 子模板 block 名和母版对不上 | 名字必须完全一致 |
| 自定义过滤器/全局对象报未定义 | 注册在了另一个 Flask 实例上 | 必须 `app.add_template_filter()` 注册到同一个 `app` |
| 宏里的参数没生效 | 用了 `{% include %}` 而不是 `{% import %}` | 宏要用 import，include 只是贴内容 |
| 中文乱码 | 模板不是 UTF-8 | PyCharm 右下角改成 **UTF-8** |

---

## 练习

1. 给 `control.html` 加一个“删除最后一篇”的链接，用 `num - 1` 当参数。
2. 在 `macro_define.html` 里加 `card(title, body)` 宏，并在 `/inherit` 页面调用它。
3. 注册第三个过滤器 `hide_phone`：把手机号中间四位变成 `****`，在 `/filter` 页展示。
4. 给 `base.html` 加一个 `{% block footer %}`，让 `/include` 页覆盖它。

---

《Web 程序开发（Python Web）》· 配套代码 · 谢福财
