Flask 入门 - 模板

渲染模板

模板文件后缀名是 .html, 这些文件就是普通的 html 文件加上一些占位符变量, 它们都默认存放在 templates 文件夹中。

1
2
3
4
5
6
7
8
from flask import Flask, render_template
# ...
@app.route('/')
def index():
return render_template('index.html')
@app.route('/user/<name>')
def user(name):
return render_template('user.html', name=name)

render_template 函数的第一个参数是模板的文件名, 第二个参数是关键字参数, 在 name=name 中, 左侧的 name 代表模板文件(.html)中的占位符变量, 右侧的 name 表示 Python 函数中当前作用域中的名为 name 的变量。

模板文件中的变量

在模板文件中一般使用 结构表示一个变量, 它是一种特殊的占位符, 在渲染时会使用等号右侧的那个值替换掉该占位符(变量插值)。

Jinja2 能识别所有类型的变量, 如列表、字典、对象。例如:

1
2
3
4
<p>A value from a dictionary: {{ mydict['key'] }}.</p>
<p>A value from a list: {{ mylist[3] }}.</p>
<p>A value from a list, with a variable index: {{ mylist[myintvar] }}.</p>
<p>A value from an object's method: {{ myobj.somemethod() }}.</p>

使用过滤器可以改变占位符变量, 过滤器名添加在占位符变量名之后, 中间用 | 分割。例如, 首字母大写变量 name 的值:

1
Hello, {{ name|capitalize }}

下面是部分常用过滤器:

过滤器名 说  明
safe 渲染值时不转义
capitalize 把值的首字母转换成大写,其他字母转换成小写
lower 把值转换成小写形式
upper 把值转换成大写形式
title 把值中每个单词的首字母都转换成大写
trim 把值的首尾空格去掉
striptags 渲染之前把值中所有的 HTML 标签都删掉

safe 过滤器值得特别说明一下。默认情况下,出于安全考虑,Jinja2 会转义所有变量。例如,如果一个变量的值为 <h1>Hello</h1> ,Jinja2 会将其渲染成<h1>Hello</h1> ,浏览器能显示这个 h1 元素,但不会进行解释。

控制结构

Jinja2 提供了多种控制结构, 可以用来改变模板的渲染流程。例如 if 语句:

1
2
3
4
5
{% if user %}
Hello, {{ user }}!
{% else %}
Hello, 陌生人!
{% endif %}

使用 for 循环渲染一组元素:

1
2
3
4
5
<ul>
{% for comment in comments %}
<li>{{ comment }}</li>
{% endfor %}
</ul>

Jinja 还支持宏。 宏类似于 Python 代码中的函数:

1
2
3
4
5
6
7
8
9
{% macro render_comment(comment) %}
<li>{{ comment }}</li>
{% endmacro %}

<ul>
{% for comment in comments %}
{{ render_macro(comment) }}
{% endfor %}
</ul>

为了重复使用宏, 可以把宏放在单独的文件中, 然后在需要使用的模板中导入:

1
2
3
4
5
{% import 'macros.html' as macros %}
<ul>
{% for comment in comments %}
{{ macros.render_comment(comment) }}
</ul>

模板可以继承! 它类似于 Python 代码中的类继承。首先创建一个名为 base.html 的基模板:

1
2
3
4
5
6
7
8
9
10
11
<html>
<head>
{% block head %}
<title>{% block title %}{% endblock %} - My Application</title>
{% endblock %}
</head>
<body>
{% block body %}
{% endblock %}
</body>
</html>

block 标签定义的元素可以在衍生模板中修改。在本例中我们定义了名为 head/title/body的块。title 包含在 head 中。使用 extends 来扩展模板:

1
2
3
4
5
6
7
8
9
{% extends "base.html" %}
{% block title %}Index{% endblock %}
{% block head %}
{{ super() }}
<style></style>
{% endblock %}
{% block body %}
<h1>Hello, 世界!</h1>
{% endblock %}

extends 指令声明这个模板衍生自 base.html。在 extends 指令之后, 基模板中的 3 个块被重新定义, 模板引擎会将其插入到适当的位置。注意新定义的 head 块, 在基模板中其内容不是空的, 所以使用 super() 获取原来的内容。

使用 Flask-Boostrap

Bootstrap 是 Twitter 开发的一个开源框架,它提供的用户界面组件可用于创建整洁且具有吸引力的网页,而且这些网页还能兼容所有现代 Web 浏览器。

要想在程序中集成 Bootstrap,显然要对模板做所有必要的改动。使用一个名为 Flask-Bootstrap 的 Flask 扩展,简化集成的过程。Flask-Bootstrap 使用 pip 安装:

1
(venv) $ pip install flask-bootstrap

Flask 扩展一般都在创建程序实例时初始化:

1
2
3
from flask.ext.bootstrap import Bootstrap
# ...
bootstrap = Bootstrap(app)

初始化 Flask-Bootstrap 之后,就可以在程序中使用一个包含所有 Bootstrap 文件的基模板。这个模板利用 Jinja2 的模板继承机制,让程序扩展一个具有基本页面结构的基模板,其中就有用来引入 Bootstrap 的元素。示例 3-5 是把 user.html 改写为衍生模板后的新版本。

templates/user.html: 使用 Flask-Bootstrap 的模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{% extends "bootstrap/base.html" %}
{% block title %} Flasky {% endblock %}

{% block navbar %}
<div class="navbar navbar-inverse" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="/">Flasky</a>
</div>
<div class="nav-collapse collapse">
<ul class="nav navbar-nav">
<li><a href="/">Home</a></li>
</ul>
</div>
</div>
</div>
{% endblock %}

{% block content %}
<div class="container">
<div class="page-header">
<h1>Hello, {{ name }}!</h1>
</div>
{% endblock %}

Jinja2 中的 extends 指令从 Flask-Bootstrap 中导入 bootstrap/base.html,从而实现模板继承。Flask-Bootstrap 中的基模板提供了一个网页框架,引入了 Bootstrap 中的所有 CSS 和 JavaScript 文件。

基模板中定义了可在衍生模板中重定义的块。 block 和 endblock 指令定义的块中的内容可添加到基模板中。
上面这个 user.html 模板定义了 3 个块,分别名为 title 、 navbar 和 content 。这些块都是基模板提供的,可在衍生模板中重新定义。 title 块的作用很明显,其中的内容会出现在渲染后的 HTML 文档头部,放在 标签中。 navbar 和 content 这两个块分别表示页<br>面中的导航条和主体内容。

在这个模板中, navbar 块使用 Bootstrap 组件定义了一个简单的导航条。 content 块中有个 <div> 容器,其中包含一个页面头部。之前版本的模板中的欢迎信息,现在就放在这个页面头部。

在 Python 3 里面, flask.ext.bootstrap import Bootstrap 变为 from flask_bootstrap import Bootstrap

hello.py 变为:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
from flask import Flask, render_template
from flask_bootstrap import Bootstrap
from flask_script import Manager

app = Flask(__name__)
manager = Manager(app)
bootstrap = Bootstrap(app)

@app.route('/')
def index():
return '<h1>Hello,World</h1>'

@app.route('/user/<name>')
def user(name):
return render_template("user.html",name=name)

if __name__ == '__main__':
manager.run()

Flask-Bootstrap 的 base.html 模板还定义了很多其它, 都可以在衍生模板中使用。下表列出了所有可用的:

块名 说明
doc 整个HTML文档
html_attribs 标签的属性
html 标签中的内容
head 标签中的内容
title 标签中的内容
metas 一组 标签
styles 层叠样式表定义
body_attribs 标签的属性
body 标签中的内容
navbar 用户定义的导航条
content 用户定义的页面内容
scripts 文档底部的 javascript 声明

表 3-2 中的很多块都是 Flask-Bootstrap 自用的,如果直接重定义可能会导致一些问题。例如,Bootstrap 所需的文件在 styles 和 scripts 块中声明。如果程序需要向已经有内容的块中添加新内容,必须使用 Jinja2 提供的 super() 函数。例如,如果要在衍生模板中添加新的 JavaScript 文件,需要这么定义 scripts 块:

1
2
3
4
{% block scripts %}
{{ super() }}
<script type="text/javascript" src="my-script.js"></script>
{% endblock %}

自定义错误页面

不使用 Bootstrap 模板时:

1
2
3
4
5
6
7
@app.errorhandler(404)
def page_not_found(e):
return render_template('404.html'), 404

@app.errorhandler(500)
def internal_server_errpr(e):
return render_template('505.html'), 500

和视图函数一样, 错误处理程序也会返回响应。它们还返回与该错误对应的数字状态码。

这样做与 user.html 中的页面的布局就不一致了, 我们可以使用 Bootstrap 来重写。但是我们要继承 template/base.html 重新写一遍导航条代码吗? 不, 我们可以定义一个 base.html, 在里面定义好导航条, 其它模板如 user.html/404.html/500.html 都继承自该 base 模板。

templates/base.html: 包含导航条的程序基模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{% extends "bootstrap/base.html" %}

{% block title %} Flasky{% endblock %}

{% block navbar %}
<div class="navbar navbar-inverse" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="/">Flasky</a>
</div>
<div class="nav-collapse collapse">
<ul class="nav navbar-nav">
<li><a href="/">Home</a></li>
</ul>
</div>
</div>
</div>
{% endblock %}
{% block content %}
<div class="container">
{% block page_content %}{% endblock %}
</div>
{% endcontent %}

这个模板的 content 块中只有一个 <div> 容器,其中包含了一个名为 page_content 的新的空块,块中的内容由衍生模板定义。

现在,程序使用的模板继承自这个模板,而不直接继承自 Flask-Bootstrap 的基模板。通过继承templates/base.html 模板编写自定义的 404 错误页面很简单:

1
2
3
4
5
6
7
8
9
{% extends "base.html" %}

{% block title %}Flask - Page Not Found!{% endblock %}

{%block page_content %}
<div class="page-header">
<h1>Not Found</h1>
</div>
{% endblock %}

500.html 与 400.html 类似。hello.py 需要修改为:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
from flask import Flask, render_template
from flask_bootstrap import Bootstrap
from flask_script import Manager

app = Flask(__name__)
manager = Manager(app)
bootstrap = Bootstrap(app)

@app.route('/')
def index():
return '<h1>Hello,World</h1>'

@app.route('/user/<name>')
def user(name):
return render_template("user.html",name=name)

@app.errorhandler(404)
def page_not_found(e):
return render_template('404.html'), 404

@app.errorhandler(500)
def internal_server_errpr(e):
return render_template('505.html'), 500

if __name__ == '__main__':
manager.run()

再运行:

1
$ python hello.py runserver --host 127.0.0.1

在浏览器中输入想要的 url 进行测试。

链接

url_for 函数可以使用 app URL 映射中保存的信息生成合法的 URL。

url_for() 函数最简单的用法是以视图函数名(或者 app.add_url_route() 定义路由时使用的端点名)作为参数,返回对应的 URL。例如,在当前版本的 hello.py 程序中调用 url_for(‘index’) 得到的结果是 / 。调用 url_for('index', _external=True) 返回的则是绝对地址,在这个示例中是 http://localhost:5000/

生成连接程序内不同路由的链接时,使用相对地址就足够了。如果要生成在浏览器之外使用的链接,则必须使用绝对地址,例如在电子邮件中发送的链接。

使用 url_for() 生成动态地址时,将动态部分作为关键字参数传入。例如, url_for('user', name='john', _external=True) 的返回结果是 http://localhost:5000/user/john

静态文件

Web 程序不是仅由 Python 代码和模板组成。大多数程序还会使用静态文件,例如 HTML代码中引用的图片、JavaScript 源码文件和 CSS

你可能还记得在第 2 章中检查 hello.py 程序的 URL 映射时,其中有一个 static 路由。这是因为对静态文件的引用被当成一个特殊的路由,即 /static/<filename>。例如,调用 url_for('static', filename='css/styles.css', _external=True) 得 到 的 结 果 是 http://localhost:5000/static/css/styles.css

默认设置下,Flask 在程序根目录中名为 static 的子目录中寻找静态文件。如果需要,可在static 文件夹中使用子文件夹存放文件。服务器收到前面那个 URL 后,会生成一个响应,包含文件系统中 static/css/styles.css 文件的内容。

示例 3-10 展示了如何在程序的基模板中放置 favicon.ico 图标。这个图标会显示在浏览器的地址栏中。

示例 3-10 templates/base.html:定义收藏夹图标

1
2
3
4
5
{% block head %}
{{ super() }}
<link rel="shortcut icon" href="{{ url_for('static', filename = 'favicon.ico') }}" type="image/x-icon">
<link rel="icon" href="{{ url_for('static', filename = 'favicon.ico') }}" type="image/x-icon">
{% endblock %}

图标的声明会插入 head 块的末尾。注意如何使用 super() 保留基模板中定义的块的原始内容。

使用 Flask-Moment本地化日期和时间

1
pip install flask-moment

hello.py 修改为:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# -*- coding:utf8 -*-
from flask import Flask, render_template
from flask_bootstrap import Bootstrap
from flask_script import Manager
from flask_moment import Moment
from datetime import date

app = Flask(__name__)
manager = Manager(app)
bootstrap = Bootstrap(app)
moment = Moment(app)

@app.route('/')
def index():
return '<h1>Hello,World</h1>'

@app.route('/user/<name>')
def user(name):
return render_template("user.html",name=name)


@app.errorhandler(404)
def page_not_found(e):
return render_template('404.html'), 404

@app.errorhandler(500)
def internal_server_errpr(e):
return render_template('505.html'), 500

@app.route('/date')
def datetime():
return render_template('index.html', time=date(2016,9,30))

if __name__ == '__main__':
manager.run()

index.html 内容为:

1
2
3
4
5
6
7
8
9
10
11
{% extends "base.html" %}

{% block title %}Flask - time{% endblock %}

{%block page_content %}
<div class="page-header">
<h1>现在时间是 {{ moment().format('YYYY年M月D日, h:mm:ss a') }}</h1>
<h1>已经是 {{ moment().fromTime(time) }}</h1>
<h1>{{ moment().calendar() }}</h1>
</div>
{% endblock %}

最后效果为:

现在时间是 2016年9月30日, 12:44:14 凌晨


已经是 7 小时前


今天凌晨12点44分