赵走x博客 - 开发者的网上家园

Flask 实战：19、模板进阶实践

资源编号:75866 Python Web Flask Web开发实战：入门、进阶与原理解析热度：92

这一节我们会介绍模板在Flask程序中的常见应用，其中主要包括加载静态文件和自定义错误页面。

# 1、空白控制

在实际输出的HTML文件中，模板中的Jinja2语句、表达式和注释会保留移除后的空行，前面为了节省篇幅手动删掉了这些空行。以示例程序中的这段代码为例：

```

{% if user.bio %}
    <i>{{ user.bio }}</i>
{% else %}
    <i>This user has not provided a bio.</i>
{% endif %}

```

Jinja2语句中的HTML代码缩进并不是必须的，只是为了增加可读性，在编写大量Jinja2代码时可读性尤其重要。

实际输出的HTML代码如下所示：

```
<i>{{ user.bio }}</i>

<i>This user has not provided a bio.</i>
```

如果你想在渲染时自动去掉这些空行，可以在定界符内侧添加减号。比如，{%-endfor%}会移除该语句前的空白，同理，在右边的定界符内侧添加减号将移除该语句后的空白：

```

{% if user.bio -%}
    <i>{{ user.bio }}</i>
{% else -%}
    <i>This user has not provided a bio.</i>
{%- endif %}

```

现在输出的HTML代码如下所示：

```

<i>{{ user.bio }}</i>
<i>This user has not provided a bio.</i>

```

你可以访问[http://jinja.pocoo.org/docs/latest/templates/#whitespace-control](http://jinja.pocoo.org/docs/latest/templates/#whitespace-control) 查看更多细节。

除了在模板中使用减号来控制空白外，我们也可以使用模板环境对象提供的trim_blocks和lstrip_blocks属性设置，前者用来删除Jinja2语句后的第一个空行，后者则用来删除Jinja2语句所在行之前的空格和制表符（tabs）：

```

app.jinja_env.trim_blocks = True
app.jinja_env.lstrip_blocks = True

```

trim_blocks中的block指的是使用{%...%}定界符的代码块，与我们前面介绍模板继承中的块无关。

需要注意的是，宏内的空白控制行为不受trim_blocks和lstrip_blocks属性控制，我们需要手动设置，比如：

```

{% macro qux(amount=1) %}
    {% if amount == 1 -%}
        I am qux.
    {% elif amount > 1 -%}
        We are quxs.
    {%- endif %}
{% endmacro %}

```

事实上，我们没有必要严格控制HTML输出，因为多余的空白并不影响浏览器的解析。在部署时，我们甚至可以使用工具来去除HTML响应中所有的空白、空行和换行，这样可以减小文件体积，提高数据传输速度。所以，编写模板时应以可读性为先，在后面的示例程序中，我们将不再添加空白控制的代码，并且对Jinja2语句中的HTML代码进行必要的缩进来增加可读性。

# 2、加载静态文件

一个Web项目不仅需要HTML模板，还需要许多静态文件，比如CSS、JavaScript文件、图片以及音频等。在Flask程序中，默认我们需要将静态文件存储在与主脚本（包含程序实例的脚本）同级目录的static文件夹中。

为了在HTML文件中引用静态文件，我们需要使用url_for（）函数获取静态文件的URL。Flask内置了用于获取静态文件的视图函数，端点值为static，它的默认URL规则为/static/<path：filename>，URL变量filename是相对于static文件夹根目录的文件路径。

如果你想使用其他文件夹来存储静态文件，可以在实例化Flask类时使用static_folder参数指定，静态文件的URL路径中的static也会自动跟随文件夹名称变化。在实例化Flask类时使用static_url_path参数则可以自定义静态文件的URL路径。

在示例程序的static目录下保存了一个头像图片avatar.jpg，我们可以通过url_for（'static'，filename='avatar.jpg'）获取这个文件的URL，这个函数调用生成的URL为/static/avatar.jpg，在浏览器中输入[http://localhost:5000/static/avatar.jpg](http://localhost:5000/static/avatar.jpg) 即可访问这个图片。在模板watchlist2.html里，我们在用户名的左侧添加了这个图片，使用url_for（）函数生成图片src属性所需的图片URL，如下所示：

```

```

另外，我们还创建了一个存储CSS规则的styles.css文件，我们使用下面的方式在模板中加载这个文件：

```

```

### 1.添加Favicon

在运行前两章的示例程序时，我们经常在命令行看到一条404状态的GET请求记录，请求的URL为/favicon.ico，如下所示：

```

127.0.0.1 - - [08/Feb/2018 18:31:12] "GET /favicon.ico HTTP/1.1" 404 -

```

这个favicon.ico文件指的是Favicon（favorite icon，收藏夹头像/网站头像），又称为shortcut icon、tab icon、website icon或是bookmark icon。顾名思义，这是一个在浏览器标签页、地址栏和书签收藏夹等处显示的小图标，作为网站的特殊标记。浏览器在发起请求时，会自动向根目录请求这个文件，在前面的示例程序中，我们没有提供这个文件，所以才会产生上面的404记录。

要想为Web项目添加Favicon，你要先有一个Favicon文件，并放置到static目录下。它通常是一个宽高相同的ICO格式文件，命名为favicon.ico。

除了ICO格式，PNG和（无动画的）GIF格式也被所有主流浏览器支持。

Flask中静态文件的默认路径为/static/filename，为了正确返回Favicon，我们可以显式地在HTML页面中声明Favicon的路径。首先可以在<head>部分添加一个<link>元素，然后将rel属性设置为icon，如下所示：

```

```

> 附注
大部分教程将rel属性设置为shortcut icon，事实上，shortcut是多余的，可以省略掉。

### 2.使用CSS框架

在编写Web程序时，手动编写CSS比较麻烦，更常见的做法是使用CSS框架来为程序添加样式。CSS框架内置了大量可以直接使用的CSS样式类和JavaScript函数，使用它们可以非常快速地让程序页面变得美观和易用，同时我们也可以定义自己的CSS文件来进行补充和调整。以Bootstrap（[http://getbootstrap.com/](http://getbootstrap.com/) ）为例，我们需要访问Bootstrap的下载页面（[http://getbootstrap.com/docs/4.0/getting-started/download/](http://getbootstrap.com/docs/4.0/getting-started/download/) ）下载相应的资源文件，然后分类别放到static目录下。

Bootstrap是最流行的开源前端框架之一，它有浏览器支持广泛、响应式设计等特点。使用它可以快速搭建美观、现代的网页。Bootstrap的官方文档（[http://getbootstrap.com/docs/](http://getbootstrap.com/docs/) ）提供了很多简单易懂的示例代码。

通常情况下，CSS和JavaScript的资源引用会在基模板中定义，具体方式和加载我们自定义的styles.css文件相同：

```

...
{% block styles %}
    <link rel="stylesheet" href="{{ url_for('static', filename='css/bootstrap.min.css') }}">
{% endblock %}
...
{% block scripts %}
    <script src="{{ url_for('static', filename='js/jquery.min.js') }}"></script>
    <script src="{{ url_for('static', filename='js/popper.min.js') }}"></script>
    <script src="{{ url_for('static', filename='js/bootstrap.min.js') }}"></script>
{% endblock %}
...

```

如果不使用Bootstrap提供的JavaScript功能，那么也可以不加载。另外，Bootstrap所依赖的jQuery（[https://jquery.com/](https://jquery.com/) ）和Popper.js（[https://popper.js.org/](https://popper.js.org/) ）需要单独下载，这三个JavaScript文件在引入时要按照jQuery→Popper.js→Boostrap的顺序引入。

虽然我建议在开发时统一管理静态资源，如果你想简化开发过程，那么从CDN加载是更方便的做法。从CND加载时，只需要将相应的URL替换为CDN提供的资源URL，比如：

```

...
{% block styles %}
    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css">
{% endblock %}
...
{% block scripts %}
    <script src="https://code.jquery.com/jquery-3.2.1.slim.min.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
    <script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>
{% endblock %}
...

```

### 3.使用宏加载静态资源

为了方便加载静态资源，我们可以创建一个专门用于加载静态资源的宏，如代码清单所示。

```

{% macro static_file(type, filename_or_url, local=True) %}
    {% if local %}
        {% set filename_or_url = url_for('static', filename=filename_or_url) %}
    {% endif %}
    {% if type == 'css' %}
        <link rel="stylesheet" href="{{ filename_or_url }}" type="text/css">
    {% elif type == 'js' %}
        <script type="text/javascript" src="{{ filename_or_url }}"></script>
    {% elif type == 'icon' %}
        <link rel="icon" href="{{ filename_or_url }}">
    {% endif %}
{% endmacro %}

```

在模板中导入宏后，只需在调用时传入静态资源的类别和文件路径就会获得完整的资源加载语句。使用它加载CSS文件的示例如下：

```

static_file('css', 'css/bootstrap.min.css')

```

使用它也可以从CDN加载资源，只需要将关键字参数local设为False，然后传入资源的URL即可：

```

static_file('css', 'https://maxcdn.../css/bootstrap.min.css', local=False)

```

# 3、消息闪现

Flask提供了一个非常有用的flash（）函数，它可以用来“闪现”需要显示给用户的消息，比如当用户登录成功后显示“欢迎回来！”。在视图函数调用flash（）函数，传入消息内容即可“闪现”一条消息。当然，它并不是我们想象的，能够立刻在用户的浏览器弹出一条消息。实际上，使用功能flash（）函数发送的消息会存储在session中，我们需要在模板中使用全局函数get_flashed_messages（）获取消息并将其显示出来。

通过flash（）函数发送的消息会存储在session对象中，所以我们需要为程序设置密钥。可以通过app.secret_key属性或配置变量SECRET_KEY设置，具体可参考之前的相关内容。

你可以在任意视图函数中调用flash（）函数发送消息。为了测试消息闪现，我们添加了一个just_flash视图，在函数中发送了一条消息，最后重定向到index视图，如代码清单所示：

```

from flask import Flask, render_template, flash

app = Flask(__name__)
app.secret_key = 'secret string'

@app.route('/flash')
def just_flash():
    flash('I am flash, who is looking for me?')
    return redirect(url_for('index'))

```

Flask提供了get_flashed_message（）函数用来在模板里获取消息，因为程序的每一个页面都有可能需要显示消息，我们把获取并显示消息的代码放在基模板中content块的上面，这样就可以在页面主体内容的上面显示消息:
```

<main>
    {% for message in get_flashed_messages() %}
        <div class="alert">{{ message }}</div>
    {% endfor %}
    {% block content %}{% endblock %}
</main>

```

因为同一个页面可能包含多条要显示的消息，所以这里使用for循环迭代get_flashed_message（）返回的消息列表。另外，我们还为消息定义了一些CSS规则，你可以在示例程序中的static/styles.css文件中查看。现在访问[http://localhost:5000](http://localhost:5000) 打开示例程序的主页，如果你单击页面上的Flash something链接（指向/flash），页面重载后就会显示一条消息，如图3-4所示。

![image.png](https://img.hacpai.com/file/2019/09/image-06227afa.png)
图3-4　消息闪现示例

当get_flashed_message（）函数被调用时，session中存储的所有消息都会被移除。如果你这时刷新页面，会发现重载后的页面不再出现这条消息。

# 4、自定义错误页面

当程序返回错误响应时，会渲染一个默认的错误页面，我们在第2章和它们打过招呼。默认的错误页面太简单了，而且和其他页面的风格不符，导致用户看到这样的页面时往往会不知所措。我们可以注册错误处理函数来自定义错误页面。

错误处理函数和视图函数很相似，返回值将会作为响应的主体，因此我们首先要创建错误页面的模板文件。为了和普通模板区分开来，我们在模板文件夹templates里为错误页面创建了一个errors子文件夹，并在其中为最常见的404和500错误创建了模板文件。
404页面模板：

```
{% extends 'base.html' %}

{% block title %}404 - Page Not Found{% endblock %}

{% block content %}
<h1>Page Not Found</h1>
<p>You are lost...</p>
{% endblock %}

```

错误处理函数需要附加app.errorhandler（）装饰器，并传入错误状态码作为参数。错误处理函数本身则需要接收异常类作为参数，并在返回值中注明对应的HTTP状态码。当发生错误时，对应的错误处理函数会被调用，它的返回值会作为错误响应的主体。下面代码是用来捕捉404错误的错误处理器：
```
from flask import Flask, render_template
...
@app.errorhandler(404)
def page_not_found(e):
    return render_template('errors/404.html'), 404
```

错误处理函数接收异常对象作为参数，内置的异常对象提供了下列常用属性，如表3-7所示。

![image.png](https://img.hacpai.com/file/2019/09/image-960988b6.png)

表3-7　Werkzeug内置的HTTP异常类的常用属性

如果你不想手动编写错误页面的内容，可以将这些信息传入错误页面模板，在模板中用它们来构建错误页面。不过需要注意的是，传入500错误处理器的是真正的异常对象，通常不会提供这几个属性，你需要手动编写这些值。

我们在第2章介绍过，Flask通过抛出Werkzeug中定义的HTTP异常类来表示HTTP错误，错误处理函数接收的参数就是对应的异常类。基于这个原理，你也可以使用app.errorhandler（）装饰器为其他异常注册处理函数，并返回自定义响应，只需要在app.errorhandler（）装饰器中传入对应的异常类即可。比如，使用app.errorhandler（NameError）可以注册处理NameError异常的函数。

这时如果访问一个错误的URL（即未在程序中定义的URL），比如[http://localhost:5000/nothing](http://localhost:5000/nothing) ，将会看到如图3-5所示的错误页面。

![image.png](https://img.hacpai.com/file/2019/09/image-bd2994e8.png)
图3-5　自定义404错误页面

除了404错误，我们还需要为另一个最常见的500错误编写错误处理器和模块，这些代码基本相同。

# 5、　JavaScript和CSS中的Jinja2

当程序逐渐变大时，很多时候我们会需要在JavaScript和CSS代码中使用Jinja2提供的变量值，甚至是控制语句。比如，通过传入模板的theme_color变量来为页面设置主题色彩，或是根据用户是否登录来决定是否执行某个JavaScript函数。

首先要明白的是，只有使用render_template（）传入的模板文件才会被渲染，如果你把Jinja2代码写在单独的JavaScript或是CSS文件中，尽管你在HTML中引入了它们，但它们包含的Jinja2代码永远也不会被执行。对于这类情况，下面有一些Tips：

### 1.行内/嵌入式JavaScript/CSS

如果要在JavaScript和CSS文件中使用Jinja2代码，那么就在HTML中使用`<style>`和`<script>`标签定义这部分CSS和JavaScript代码。

在这部分CSS和JavaScript代码中加入Jinja2时，不用考虑编写时的语法错误，比如引号错误，因为Jinja2会在渲染后被替换掉，所以只需要确保渲染后的代码正确即可。

不过我并不推荐使用这种方式，尤其是行内JavaScript/CSS会让维护变得困难。避免把大量JavaScript代码留在HTML中的办法就是尽量将要使用的Jinja2变量值在HTML模板中定义为JavaScript变量。

### 2.定义为JavaScript/CSS变量

对于想要在JavaScript中获取的数据，如果是元素特定的数据，比如某个文章条目对应的id值，可以通过HTML元素的data-*属性存储。你可以自定义横线后的名称，作为元素上的自定义数据变量，比如data-id，data-username等，比如：

```
<span data-id="{{ user.id }}" data-username="{{ user.username }}">{{ user.username }}</span>
```

在JavaScript中，我们可以使用DOM元素的dataset属性获取data-*属性值，比如element.dataset.username，或是使用getAttribute（）方法，比如element.getAttribute（'data-username'）；使用jQuery时，可以直接对jQuery对象调用data方法获取，比如$element.data（'username'）。

在HTML中，“data-*”被称为自定义数据属性（custom data attribute），我们可以用它来存储自定义的数据供JavaScript获取。在后面的其他程序中，我们也会频繁使用这种方式来传递数据。

对于需要全局使用的数据，则可以在页面中使用嵌入式JavaScript定义变量，如果没法定义为JavaScript变量，那就考虑定义为函数，比如：

```

```

当你在JavaScript中插入了太多Jinja2语法时，或许这时你该考虑将程序转变为Web API，然后专心使用JavaScript来编写客户端，在本书的第二部分我们会介绍如何编写Web API。

CSS同理，有些时候你会需要将Jinja2变量值传入CSS文件，比如我们希望将用户设置的主题颜色设置到对应的CSS规则中，或是需要将static目录下某个图片的URL传入CSS来设置为背景图片，除了将这部分CSS定义直接写到HTML中外，我们可以将这些值定义为CSS变量，如下所示：

```

```

在CSS文件中，使用var（）函数并传入变量名即可获取对应的变量值：

```

#foo {
    color: var(--theme-color); 
}
#bar {
    background: var(--background-url); 
}
```