4. 视图及其模型
到目前为止,动作都是自己生成响应:文本、JSON,以及写在字符串中的少量 HTML 标签。在 MVC 应用程序中,这是视图的职责:视图是一个描述页面 HTML 的文件,其中带有占位符,用于放置动作传给它的数据——即视图模型。
[Flask] 自带一个视图引擎 [Jinja2],由同一个团队(*Pallets* 项目)开发。也可以使用其他引擎([Mako]、[Chameleon]……),但 [Jinja2] 是 [Python] 中使用最广泛的:它出现在 [Django] (作为可选项)、[Ansible]、静态网站生成器等之中……本课程使用的就是它。
[Jinja2] 视图(文档中称之为 *template*,即页面模板)是一个文本文件——这里是 HTML 文件——其中有三种标签会在服务器端被解释:
- [{{ expression }}]:表达式的值,插入到页面中;
- [{% instruction %}]:指令:条件([if])、循环([for])、模板继承([extends]、[block])、包含([include])、宏……;
- [{# comment #}]:不会出现在生成页面中的注释。
其他所有内容都原样复制。表达式的语法与 [Python] 相似。这不同于 [Thymeleaf],即 [Spring MVC] 课程的视图引擎,其视图是添加了 [th:] 属性的有效 HTML 文件;相反,它使 [Jinja2] 更接近 [Razor] ([ASP.NET Core MVC]),后者把 HTML 和代码混合在一起。默认情况下,[Flask] 在应用程序的 [templates] 文件夹中查找视图。
4.1. 示例 13:第一个视图
| 13-first-view/
├── app.py
├── controllers/
│ └── views.py
├── models/
│ └── page.py
└── templates/
└── views/
├── index.html
└── unknown.html
|
4.1.1. 视图模型:models/page.py
| # models/page.py:视图的模型,即动作传递给视图的数据
from dataclasses import dataclass
@dataclass
class PageModel:
title: str
message: str
time: str
|
视图模型是一个简单的 [dataclass] (见示例 06):即视图将要显示的三项信息。并不要求把视图的模型定义为类:也可以把三个独立的变量传给视图。不过,类可以说明视图所期望的内容,并让编辑器能够检查动作的代码。案例研究将采用这种做法,每个视图都有自己的模型类。
4.1.2. 控制器:controllers/views.py
| # controllers/views.py:返回视图的动作
from datetime import datetime
from flask import Blueprint, render_template
from models.page import PageModel
views = Blueprint("views", __name__)
# render_template:Jinja2 引擎根据视图
# templates/views/index.html 以及作为关键字参数传入的变量构建页面
# (这里只有一个,[model]);生成的页面就是动作的响应
@views.get("/")
def index():
model = PageModel(
"My first view",
"This page was built by Jinja2, on the server.",
datetime.now().strftime("%H:%M:%S"))
return render_template("views/index.html", model=model)
# 同一个视图配上另一个模型;或者另一个视图,配 404 状态码
@views.get("/hello/<name>")
def hello(name):
if name == "unknown":
# 元组 (page, code):页面,以 404 状态码发送
return render_template("views/unknown.html", name=name), 404
model = PageModel(
f"Hello {name}",
"This time, the title of the page comes from the URL.",
datetime.now().strftime("%H:%M:%S"))
return render_template("views/index.html", model=model)
|
- 第 4 行:导入函数 [render_template];
- 第 16–19 行:动作构建视图模型。[datetime.now().strftime("%H:%M:%S")]:格式化后的当前时间(见示例 12);
- 第 20 行:[render_template] 指示 [Jinja2] 生成页面:第一个参数是视图路径,相对于 [templates] 文件夹;后面的命名参数是视图的变量;这里只有一个:[model]。[render_template] 返回所生成页面的文本,它成为动作的响应(类型为 [text/html]);
- 第 28 行:另一个视图,带有不同的变量([name])。元组 [(page, 404)] 发送状态码为 404 的页面(见示例 03):一个自定义错误页面;
- 第 29–33 行:与动作 [index] 相同的视图,但使用不同的模型。这正是把动作与视图分离的好处:同一个视图可以被多个动作使用。
4.1.3. 视图:templates/views/index.html
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
{# {{ ... }}:表达式的值,插入到页面中 #}
<title>{{ model.title }}</title>
</head>
<body>
<h1>{{ model.title }}</h1>
<p>{{ model.message }}</p>
<p>Page built at {{ model.time }}.</p>
</body>
</html>
|
- 第 5 行:一个 [Jinja2] 注释;
- 第 6 行:[{{ model.title }}] 插入变量 [title] 的 [model] 属性值。[Jinja2] 的点号表示法比 [Python] 的更灵活:[model.title] 首先查找属性 [title],如果没有找到,再查找键 ["title"] (如果 [model] 是字典)。因此,视图代码不需要知道它的模型是对象还是字典。
由 [{{ }}] 插入的所有内容都会被转义:字符 [<]、[>]、[&]、["]和 ['] 会被替换为它们的 HTML 实体代码。这就是函数 [escape] 在示例 09 中所起的作用,但这一次是自动完成的:[Flask] 对名称以 [.html]、[.htm]、[.xml]、[.xhtml]、或 [.svg] 结尾的视图启用自动转义(*autoescape*)。这可以防止视图不经意间把用户提供的 HTML 插入到页面中。
4.1.4. 视图:templates/views/unknown.html
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Unknown</title>
</head>
<body>
<h1>Nobody is called [{{ name }}] here.</h1>
</body>
</html>
|
视图并不要求必须接收一个对象:变量 [name] 是一个字符串。
4.1.5. 执行


原始响应展示了 [Jinja2] 所做的工作:[{{ }}] 标签已被替换为它们的值,注释已经消失(原处留下了一个空行;在下一个示例中我们将看到如何避免这一点)。
| curl -i http://localhost:5000/
|
| HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 242
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>My first view</title>
</head>
<body>
<h1>My first view</h1>
<p>This page was built by Jinja2, on the server.</p>
<p>Page built at 15:30:51.</p>
</body>
</html>
|
“自定义”错误页面,随后是一个包含 HTML 的名称([<b>martin],经过 URL 编码):
| curl -i http://localhost:5000/hello/unknown
curl http://localhost:5000/hello/%3Cb%3Emartin
|
| HTTP/1.1 404 NOT FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 164
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Unknown</title>
</head>
<body>
<h1>Nobody is called [unknown] here.</h1>
</body>
</html>
...
<title>Hello <b>martin</title>
...
<h1>Hello <b>martin</h1>
...
|
[<b>] 标签被转义了,整个过程中没有涉及任何动作或视图的处理。
4.2. 示例 14:Jinja2 语言
本示例把 [Jinja2] 的主要结构整合到了一个视图中。
4.2.1. 模型与动作
| # models/basics.py:示例 14 的视图模型
from dataclasses import dataclass
from decimal import Decimal
@dataclass
class Product:
name: str
price: Decimal
in_stock: bool
@dataclass
class Address:
street: str
city: str
@dataclass
class BasicsModel:
title: str
name: str
nickname: str | None
html: str
logged_in: bool
currency: str
products: list[Product]
cart: list[Product]
address: Address
|
该模型包含各种类型的值:字符串、[None]、布尔值、对象列表、空列表,以及包含其他对象的对象。标准模块 [Decimal] 中的 [decimal] 类型能精确表示十进制数(不同于 [float] 类型,对它而言 [0.1 + 0.2] 等于 [0.30000000000000004]);金额应当使用这种类型。
| # controllers/basics.py:使用 Jinja2 主要结构的视图
from decimal import Decimal
from flask import Blueprint, render_template
from models.basics import Address, BasicsModel, Product
basics = Blueprint("basics", __name__)
@basics.get("/")
def index():
model = BasicsModel(
title="Jinja2 basics",
name="Martin",
nickname=None,
html="<b>this is HTML</b>",
logged_in=True,
currency="€",
products=[
Product("Keyboard", Decimal("25"), True),
Product("Mouse", Decimal("12.5"), False),
Product("Screen", Decimal("149"), True),
],
cart=[],
address=Address("12 rue des Lilas", "Angers"))
return render_template("basics/index.html", model=model)
|
动作构建模型并将其传给视图。[Decimal("12.5")]:用字符串构造十进制数,以避免使用不精确的 [float]。
4.2.2. 配置:app.py
| # app.py:示例 14 的应用
from flask import Flask
from controllers.basics import basics
def create_app():
app = Flask(__name__)
# {% ... %} 标签不会在生成的页面中留下空行:
# trim_blocks 删除标签后面的换行符,lstrip_blocks 删除
# 标签所在行中它之前的空格
app.jinja_env.trim_blocks = True
app.jinja_env.lstrip_blocks = True
app.register_blueprint(basics)
return app
if __name__ == "__main__":
create_app().run(port=5000, debug=True)
|
- 第 12–13 行:[app.jinja_env] 是应用程序的 [Jinja2] 环境——即加载并执行视图的对象。默认情况下,单独占一行的 [{% %}] 标签会把它前面的空格和后面的换行符保留在生成的页面中:循环就会产生大量空行。[trim_blocks] 会移除标签后面的换行符,而 [lstrip_blocks] 会移除标签前面的空格。这两项设置不会影响页面的显示(浏览器会忽略这些空白字符),但它们使生成的 HTML 更易读。后面所有示例都启用了这两项设置。
4.2.3. 视图:templates/basics/index.html
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>{{ model.title }}</title>
</head>
<body>
{# {% set %}:视图的变量;过滤器(|)用于转换值 #}
{% set total = model.products | sum(attribute="price") %}
{% set count = model.products | length %}
<h1>{{ model.title }}</h1>
{# 1. 显示模型的一个值;None 会显示为 "None":过滤器
default(text, true) 会替换空值或 None 值。这条 Jinja2
注释不会出现在生成的页面中 #}
<p>1. Name: {{ model.name }} - nickname: [{{ model.nickname }}] [{{ model.nickname | default("", true) }}]</p>
{# 2. {{ }} 会转义 HTML;safe 过滤器则原样插入 #}
<p>2a. {{ model.html }}</p>
<p>2b. {{ model.html | safe }}</p>
{# 3. 一个条件 #}
{% if model.logged_in %}
<p>3. You are logged in.</p>
{% else %}
<p>3. You are not logged in.</p>
{% endif %}
{# 4. 一个循环:[loop] 描述循环的状态 #}
<p>4. Our products:</p>
<ul>
{% for product in model.products %}
<li>no. {{ loop.index0 }}: {{ product.name }}, {{ product.price }} {{ model.currency }}
{{ "(in stock)" if product.in_stock else "(sold out)" }}
{% if loop.first %}- the first one{% endif %}
{% if loop.last %}- the last one, seen by {{ model.name }}{% endif %}
</li>
{% endfor %}
</ul>
{# 5. 空列表:for 循环的 else 块 #}
<p>5. Your cart:
{% for p in model.cart %}<span>{{ p.name }}</span>{% else %}it is empty.{% endfor %}
</p>
{# 6. 计算表达式、set 变量,以及 format 过滤器 #}
<p>6. {{ count }} products, for a total of {{ total }} {{ model.currency }};
average price: {{ "%.2f" | format(total / count) }} {{ model.currency }}</p>
{# 7. 对象内部的对象,以及 Python 方法(upper) #}
<p>7. Address: {{ model.address.street }}, {{ model.address.city.upper() }}</p>
<p>8. An email address: contact@example.com</p>
</body>
</html>
|
- 第 9–10 行:[{% set %}] 创建一个视图变量。过滤器用于转换值:[value | filter] 或 [value | filter(parameters)]。过滤器 [sum(attribute="price")] 对列表中各元素的 [price] 属性求和;过滤器 [length] 返回列表的长度。[Jinja2] 提供了大约五十个过滤器:[upper]、[lower]、[title]、[trim]、[join]、[sort]、[round]、[default]、[replace]、[truncate]……;
- 第 15 行:值 [None] 被显示为……[None]。过滤器 [default(value, true)] 用指定的值替换“空”值([None]、空字符串、零);如果没有第二个参数 [true],它只会替换未定义的变量;
- 第 17–18 行:[{{ }}] 会转义 HTML(2a);而过滤器 [safe] 则声明该值是安全的 HTML,应当原样插入(2b)。[safe] 仅用于应用程序自己生成的 HTML,绝不能用于用户输入;
- 第 20–24 行:一个条件:[{% if %}]、[{% elif %}]、[{% else %}]、[{% endif %}]。与 [Python] 用缩进来界定代码块不同,[Jinja2] 用 [end...] 标签来关闭每个代码块;
- 第 28–34 行:一个循环 [{% for %}] …… [{% endfor %}]。在循环内部,特殊变量 [loop] 描述循环的状态:[loop.index] (迭代序号,从 1 开始)、[loop.index0] (从 0 开始)、[loop.first]、[loop.last] (分别在第一次和最后一次迭代时为真)、[loop.length] (元素个数)。循环之外的变量([model.name])仍然可以访问;
- 第 30 行:[Python] 的条件表达式 [a if condition else b] 在 [Jinja2] 中同样适用;
- 第 38 行:[for] 循环可以包含一个 [{% else %}] 块,当列表为空时执行。这比用 [if] 检查列表长度更简单;
- 第 41–42 行:计算表达式([total / count])。过滤器 [format] 应用的格式类似于 [%] 运算符(来自 [Python]):["%.2f"] 显示保留两位小数的数字。在示例 16 中,我们将看到一种格式化数字和金额的好得多的方法;
- 第 44 行:点号表示法可以遍历对象([model.address.city]),并允许调用它们的方法:[upper()] 是 [Python] 字符串的方法;
- 第 45 行:一个电子邮件地址,原样书写。字符 [@]在其他视图引擎([Razor])中有特殊含义,但在 [Jinja2] 中没有:只有标签 [{{ }}]、[{% %}]、和 [{# #}] 会被解释。
4.2.4. 执行

生成的页面:
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Jinja2 basics</title>
</head>
<body>
<h1>Jinja2 basics</h1>
<p>1. Name: Martin - nickname: [None] []</p>
<p>2a. <b>this is HTML</b></p>
<p>2b. <b>this is HTML</b></p>
<p>3. You are logged in.</p>
<p>4. Our products:</p>
<ul>
<li>no. 0: Keyboard, 25 €
(in stock)
- the first one </li>
<li>no. 1: Mouse, 12.5 €
(sold out)
</li>
<li>no. 2: Screen, 149 €
(in stock)
- the last one, seen by Martin </li>
</ul>
<p>5. Your cart:
it is empty. </p>
<p>6. 3 products, for a total of 186.5 €;
average price: 62.17 €</p>
<p>7. Address: 12 rue des Lilas, ANGERS</p>
<p>8. An email address: contact@example.com</p>
</body>
</html>
|
注释已经消失,[{% %}] 标签也没有留下任何空行。某些行的格式(“[- the first one </li>]”)表明 [trim_blocks] 和 [lstrip_blocks] 同样会影响位于行中间的标签;这对浏览器没有影响。
4.3. 示例 15:布局模板、片段、静态文件
网站的各个页面通常共享相同的结构:页眉、导航栏、页脚和相同的样式表。与其在每个视图中重复这一结构,不如在一个布局模板 (*layout*)中只写一次,由各页面来继承。本示例还使用 [Bootstrap],这是使用最广泛的 CSS 框架,用于设置样式。
| 15-layout/
├── app.py
├── controllers/
│ └── pages.py
├── static/
│ └── css/
│ └── styles.css
└── templates/
├── fragments/
│ ├── card.html
│ └── navbar.html
├── layout.html
└── pages/
├── home.html
├── raw.html
└── team.html
|
4.3.1. 静态文件
HTML 页面会引用其他文件:样式表、[JavaScript] 脚本和图像。这些由服务器原样发送的文件称为静态文件。[Flask] 会自动提供应用程序 [static] 目录的内容,其 URL 为 [/static/...]:文件 [static/css/styles.css] 可通过 URL [/static/css/styles.css] 访问。
| /* 除 Bootstrap 之外的一些设置 */
body {
background-color: #f5f7fa;
}
/* 布局的页脚 */
.footer {
margin-top: 2rem;
font-size: 0.85rem;
color: #6c757d;
}
/* 页面底部的错误消息,浅粉色背景 */
.error-area {
margin-top: 1.5rem;
padding: 0.75rem 1rem;
background-color: #fdecef;
border: 1px solid #f5c2c7;
border-radius: 0.375rem;
color: #842029;
}
|
在 [Bootstrap] 之外再添加几条 CSS 规则:浅灰色背景、页脚样式,以及后续示例中将使用的错误区域样式。
[Bootstrap]另一方面,示例 15 至 28 都会用到它。与其在每个示例的 [static] 文件夹中各放一份副本,不如让这些示例共享它:它位于 [examples/common/bootstrap] 文件夹中。因此,必须指示 [Flask] 也使用这个文件夹。这就是 [app.py] 中以下代码行的作用:
| # app.py:示例 15 的应用
from datetime import date
from pathlib import Path
from flask import Blueprint, Flask, request
from controllers.pages import pages
# Bootstrap,由各示例共享:examples/common/bootstrap 文件夹,
# 从本文件所在位置定位(而不是从当前文件夹)
BOOTSTRAP = Path(__file__).resolve().parent.parent / "common" / "bootstrap"
def create_app():
app = Flask(__name__)
app.jinja_env.trim_blocks = True
app.jinja_env.lstrip_blocks = True
# 一个没有路由、只提供静态文件的蓝图:
# BOOTSTRAP 文件夹,位于 /bootstrap/... URL 下
app.register_blueprint(Blueprint("bootstrap", __name__, static_folder=BOOTSTRAP,
static_url_path="/bootstrap"))
app.register_blueprint(pages)
# "上下文处理器":在构建每个视图之前执行,
# 它把自己的变量添加到所有视图的模型中
@app.context_processor
def common_model():
return {"path": request.path, "year": date.today().year}
return app
if __name__ == "__main__":
create_app().run(port=5000, debug=True)
|
- 第 11 行:[common/bootstrap] 文件夹的路径。来自标准模块 [Path] 的 [pathlib] 表示文件路径。[Path(__file__)] 是文件 [app.py] 本身的路径([__file__] 是 [Python] 在每个模块中定义的变量);[resolve()] 将其变为绝对路径;[parent] 指包含它的文件夹([15-layout]),[parent.parent] 指 上一级文件夹([examples]);运算符 [/] 用于向路径追加一个元素。依据文件的位置而不是当前文件夹来指定目录,可以让应用程序从任意文件夹启动;
- 第 20–21 行:蓝图可以拥有自己的静态文件文件夹([static_folder]),并通过指定的 URL([static_url_path])提供服务。这个蓝图只包含这些:它没有任何路由。因此,文件 [common/bootstrap/css/bootstrap.min.css] 可通过 URL [/bootstrap/css/bootstrap.min.css] 访问;
- 第 26–28 行:上下文处理器 是 [Flask] 在生成每一个视图之前执行的函数。它返回一个字典,字典中的键值对会被添加到视图的变量中。这样,[path] (所请求 URL 的路径)和 [year] (当前年份)就可以在所有视图中使用,而无需动作来提供它们。布局模板用它们来生成页脚。
4.3.2. 布局模板:templates/layout.html
| <!doctype html>
{# 页面的布局:各页面扩展(EXTEND)它,并填充其中的块 #}
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
{# 一个块:页面可以填充的插槽;这里带有默认内容 #}
<title>{% block title %}Home{% endblock %} - My site</title>
{# url_for 构建静态文件的 URL:/bootstrap/css/bootstrap.min.css #}
<link rel="stylesheet" href="{{ url_for('bootstrap.static', filename='css/bootstrap.min.css') }}">
<link rel="stylesheet" href="{{ url_for('static', filename='css/styles.css') }}">
</head>
<body>
<div class="container py-3">
{# 插入 fragments/navbar.html 文件 #}
{% include "fragments/navbar.html" %}
<main>
{# 操作所请求的页面内容插入到这里 #}
{% block content %}{% endblock %}
</main>
{# path、year:添加到所有视图的模型中(参见 app.py) #}
<footer class="footer">Page [{{ path }}] - © {{ year }}</footer>
</div>
</body>
</html>
|
- 第 6 行:[viewport] 标签指示移动浏览器按屏幕宽度显示页面,而 [Bootstrap] 正是需要这一点;
- 第 8 行:块是一个具名容器,继承该模板的页面可以填充它。写在 [{% block title %}] 和 [{% endblock %}] 之间的内容是该块的默认内容,未重写它的页面会使用这些内容;
- 第 10–11 行:[url_for](我们在动作中已经见过它,见示例 04)同样可以生成静态文件的 URL:[static] 指应用程序的静态文件夹,[bootstrap.static] 指蓝图 [bootstrap] 的静态文件夹;[filename] 是该文件夹内的文件路径。[url_for] 可在所有视图中使用。手动输入 URL([/static/css/styles.css])同样可行,但如果文件夹被移动,或者应用程序安装在某个 URL 前缀之下,[url_for] 能够自动适应;
- 第 16 行:[{% include %}] 插入另一个视图的内容,这里是导航栏。被包含的视图可以访问包含它的视图的变量;
- 第 19 行:每个页面用自己的内容填充的块,默认为空;
- 第 22 行:页脚使用了来自上下文处理器的两个变量。
[container] 是 [Bootstrap] 的类,它使内容居中并限制其宽度;[py-3] 添加垂直内边距:[Bootstrap] 提供了数以百计的这类类,它们组合在 [class] 属性中使用。
4.3.3. 导航栏:templates/fragments/navbar.html
| {# 一个片段:由 {% include %} 插入的一段页面 #}
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
<span class="navbar-brand">My site</span>
<div class="navbar-nav">
<a class="nav-link" href="/">Home</a>
<a class="nav-link" href="/team">Team</a>
<a class="nav-link" href="/raw">Page without layout</a>
</div>
</nav>
|
片段:页面中本身没有独立意义的一部分。类 [navbar]、[navbar-brand] 和 [nav-link] 是 [Bootstrap] 中导航栏所用的类。
4.3.4. 宏:templates/fragments/card.html
| {# 一个宏(MACRO):带参数的一段页面,类似函数 #}
{% macro card(name, role) %}
<div class="card">
<div class="card-body">
<h5 class="card-title">{{ name }}</h5>
<p class="card-text">{{ role }}</p>
</div>
</div>
{% endmacro %}
|
- 第 2–9 行:宏是带有参数的页面片段;这是 [Jinja2] 的功能。调用它——[{{ card("name", "role") }}]——会插入用这些值生成的页面片段。参数可以有默认值,就像 [Python] 中一样:[{% macro card(name, role="") %}]。卡片([card])是 [Bootstrap] 的一个组件。
4.3.5. 页面
| {# 此页面扩展(EXTEND)布局:它只提供各块的内容 #}
{% extends "layout.html" %}
{# fragments/card.html 文件中的 [card] 宏 #}
{% from "fragments/card.html" import card %}
{% block content %}
<h1>Welcome</h1>
<p>This page only contains its own content: the header, the navigation
bar and the footer come from the <code>layout.html</code> layout.</p>
{# 宏的调用,带有两个就地编写的参数 #}
{{ card("A macro", "called with parameters written on the spot") }}
{% endblock %}
|
- 第 2 行:该页面继承布局模板:[Jinja2] 生成布局页面,并用该页面重新定义的块替换布局中的块。[{% extends %}] 必须是视图中的第一个标签。在继承了布局模板的视图中,写在块之外的文本不会出现在生成的页面中(不过,[{% set %}] 指令在其中仍然有效;我们将在国际化一章中看到这一点);
- 第 4 行:导入在另一个文件中定义的宏 [card];
- 第 6 行:重新定义布局模板的 [content] 块。该页面没有重新定义 [title] 块:它保留默认内容“Home”;
- 第 11 行:宏调用。
| {% extends "layout.html" %}
{% from "fragments/card.html" import card %}
{% block title %}Our team{% endblock %}
{% block content %}
<h1>Our team</h1>
<div class="row g-3">
{% for member in members %}
<div class="col-md-4">
{# 宏接收当前成员的姓名和角色 #}
{{ card(member.name, member.role) }}
</div>
{% endfor %}
</div>
{% endblock %}
|
- 第 4 行:该页面同样重新定义了标题;
- 第 9–14 行:每位团队成员一张卡片,使用 [Bootstrap] 的网格排布([row]、[col-md-4]:在中等或大屏幕上为三列,在手机上为一列)。
控制器没有任何新内容:
| # controllers/pages.py:三个页面
from dataclasses import dataclass
from flask import Blueprint, render_template
pages = Blueprint("pages", __name__)
# 团队的一名成员
@dataclass
class Member:
name: str
role: str
@pages.get("/")
def home():
return render_template("pages/home.html")
@pages.get("/team")
def team():
members = [
Member("Marie Pélissier", "Director"),
Member("Jacques Bromard", "Developer"),
Member("Philippe Jandot", "Graphic designer"),
]
return render_template("pages/team.html", members=members)
@pages.get("/raw")
def raw():
return render_template("pages/raw.html")
|
最后,第三个页面不使用布局模板:
| <!doctype html>
{# 此视图不使用布局:它是一个完整的页面 #}
<html lang="en">
<head>
<meta charset="utf-8">
<title>Raw page</title>
</head>
<body>
<p>This page does not use the layout: no Bootstrap, no navigation bar.</p>
<p><a href="/">Back to home</a></p>
</body>
</html>
|
4.3.6. 执行



浏览器收到的团队页面:
| curl http://localhost:5000/team
|
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Our team - My site</title>
<link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
<link rel="stylesheet" href="/static/css/styles.css">
</head>
<body>
<div class="container py-3">
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
<span class="navbar-brand">My site</span>
<div class="navbar-nav">
<a class="nav-link" href="/">Home</a>
<a class="nav-link" href="/team">Team</a>
<a class="nav-link" href="/raw">Page without layout</a>
</div>
</nav> <main>
<h1>Our team</h1>
<div class="row g-3">
<div class="col-md-4">
<div class="card">
<div class="card-body">
<h5 class="card-title">Marie Pélissier</h5>
<p class="card-text">Director</p>
</div>
</div>
</div>
...
</div>
</main>
<footer class="footer">Page [/team] - © 2026</footer>
</div>
</body>
</html>
|
浏览器收到了一个完整的页面:布局模板、片段、页面和宏都是在服务器上组装的。样式表的 URL 由 [url_for] 计算得出。可以验证 [Bootstrap] 文件是否被正确提供([curl] 的 [-I] 选项只显示响应头):
| curl -I http://localhost:5000/bootstrap/css/bootstrap.min.css
|
| HTTP/1.1 200 OK
Content-Disposition: inline; filename=bootstrap.min.css
Content-Type: text/css; charset=utf-8
...
|
4.4. 示例 16:辅助函数
视图经常需要格式化各种值:带货币符号的金额、完整书写的日期,或大写文本。这类代码不属于动作(动作不负责呈现),而且直接写在视图中会很繁琐。因此,它们用 [Python] 编写,放在供视图调用的函数中:这些就是视图的辅助函数。[Jinja2] 识别三种类型:过滤器 ([{{ price | money }}])、全局函数 ([{{ uppercase(name) }}])以及 宏,后者我们已经接触过。
| # helpers/formats.py:由视图调用的函数
from datetime import date
from decimal import Decimal
from babel.dates import format_date
from babel.numbers import format_currency
from flask import g
# "keyboard" -> "KEYBOARD"
def uppercase(text: str | None) -> str:
return "" if text is None else text.upper()
# 以请求所用语言的格式表示的某种货币金额(g.locale,
# 见 app.py):1149.9 -> 英文为 "€1,149.90",法文为 "1 149,90 €"。
# Babel 库了解每个国家的惯例
def money(amount: Decimal, currency: str = "EUR") -> str:
return format_currency(amount, currency, locale=g.locale)
# 以完整文字表示的日期,使用请求的语言:"Saturday, September 26, 2026"
def long_date(day: date) -> str:
return format_date(day, format="full", locale=g.locale)
|
- 第 11–12 行:一个接受 [None] 的普通函数;
- 第 18–19 行:格式化金额。这取决于语言:法语中为 [1 149,90 €] (用空格分隔千位,小数点用逗号,符号放在金额之后);英语中为 [€1,149.90]。[Babel] 库支持所有国家的惯例(它使用 Unicode 项目 *CLDR* 的数据):[format_currency(amount, currency, locale=...)] 格式化金额,货币用其国际代码表示([EUR]、[USD])。区域设置 ([fr_FR]、[en_US])指定语言和国家。这里它读取自 [g.locale],我们接下来就会介绍它;
- 第 23–24 行:[format_date] 格式化日期;格式 [full] 会完整写出日期,包括星期几。
4.4.2. 配置:app.py
| # app.py:示例 16 的应用
from pathlib import Path
from flask import Blueprint, Flask, g, request
from helpers import formats
from controllers.pages import pages
BOOTSTRAP = Path(__file__).resolve().parent.parent / "common" / "bootstrap"
def create_app():
app = Flask(__name__)
app.jinja_env.trim_blocks = True
app.jinja_env.lstrip_blocks = True
app.register_blueprint(Blueprint("bootstrap", __name__, static_folder=BOOTSTRAP,
static_url_path="/bootstrap"))
app.register_blueprint(pages)
# 每个请求的格式化语言:URL 的 ?lang=fr 参数,
# 否则为英语。before_request:在每个动作之前
# 执行的函数;[g]:在一次请求期间存在的对象
@app.before_request
def set_language():
g.locale = "fr_FR" if request.args.get("lang") == "fr" else "en_US"
# "自制" 过滤器:{{ price | money }}、{{ day | long_date }}
app.add_template_filter(formats.money)
app.add_template_filter(formats.long_date)
# 一个全局函数,可在所有视图中调用:{{ uppercase(name) }}
app.add_template_global(formats.uppercase)
return app
if __name__ == "__main__":
create_app().run(port=5000, debug=True)
|
- 第 23–25 行:格式化所用的语言取决于请求:URL 的参数 [?lang=fr] 选择法语;英语是默认语言。[@app.before_request] 注册一个函数,[Flask] 会在每个动作之前执行它(请求生命周期一章将详细介绍这些“钩子”)。它把区域设置存放在 [g] 中,这是 [Flask] 的一个对象,与 [request] 一样,它专属于当前请求:你可以往里面存放任何东西([g.locale = ...]);请求结束时它会被丢弃。这是在处理同一个请求的不同函数之间共享信息的方式,无需把信息作为参数一个接一个地传递。数据作用域一章将再次讨论这一主题;
- 第 28–29 行:把两个函数以各自的名称注册为 过滤器——[Jinja2] 的过滤器。过滤器的第一个参数是放在 [|] 之前的值;后面的参数是过滤器自己的参数:[{{ price | money("USD") }}] 调用 [money(price, "USD")];
- 第 31 行:把一个函数注册为全局视图函数。
装饰器 [@app.template_filter()] (应用于函数本身)是注册过滤器的另一种方式。在 [add_template_filter] 中从 [app.py] 内部调用它,其好处是使模块 [helpers/formats.py] 独立于 [Flask]([g] 除外)。
4.4.3. 控制器:controllers/pages.py
| # controllers/pages.py:两个页面
from dataclasses import dataclass
from datetime import date
from decimal import Decimal
from flask import Blueprint, render_template
pages = Blueprint("pages", __name__)
@dataclass
class Product:
name: str
price: Decimal
stock: int
@pages.get("/")
def home():
return render_template("pages/home.html", today=date.today())
@pages.get("/products")
def products():
return render_template("pages/products.html", products=[
Product("keyboard", Decimal("25"), 12),
Product("mouse", Decimal("12.5"), 0),
Product("screen", Decimal("1149.9"), 3),
])
|
动作把原始值传给视图:一个 [date],一些 [Decimal]。格式化由视图负责。
4.4.4. 视图
| {# 一个宏:导航栏的链接,如果当前页面位于 [href] 路径之下,就会
获得 [active] 类。[request]:当前
请求,Flask 将其提供给所有视图 #}
{% macro link(href, text) %}
{% set active = request.path == "/" if href == "/" else request.path.startswith(href) %}
<a class="nav-link{{ ' active' if active }}" href="{{ href }}">{{ text }}</a>
{% endmacro %}
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
<span class="navbar-brand">Helpers</span>
<div class="navbar-nav">
{# 1. 在视图中编写的条件 #}
<a class="nav-link{% if request.path == '/' %} active{% endif %}" href="/">Home</a>
{# 2. [link] 宏 #}
{{ link("/products", "Products") }}
{# 3. url_for 构建操作的 URL;不属于路径变量的参数会
添加到 URL 末尾:/products?lang=fr #}
<a class="nav-link" href="{{ url_for('pages.products', lang='fr') }}">Produits (fr)</a>
</div>
</nav>
|
- 第 4–7 行:一个为导航栏创建链接的宏。当前页面的链接会被赋予 [active] 类,该类来自 [Bootstrap],用于将其高亮。变量 [request] (当前请求)在所有视图中都可用,[g]、[url_for] 和 [session] 也是如此(见作用域一章)。第 5 行的条件表达式单独处理主页,其路径 [/]是所有其他路径的起点;
- 第 6 行:不带 [else] 的条件表达式在条件为假时返回空字符串;
- 第 13 行:同样的功能,直接写在视图中,不使用宏。宏避免了对每个链接重复写条件;
- 第 18 行:[url_for] 的参数如果不是路由路径中的变量,就会作为参数添加到 URL 中:[/products?lang=fr]。
| {# 一个 Bootstrap 徽章:商品有库存时为绿色,否则为红色 #}
{% macro badge(stock) %}
<span class="badge {{ 'text-bg-success' if stock > 0 else 'text-bg-danger' }}">
{{- stock ~ " in stock" if stock > 0 else "sold out" -}}
</span>
{% endmacro %}
|
- 第 3 行:一个 [Bootstrap] 徽章,根据库存显示为绿色([text-bg-success])或红色([text-bg-danger]);
- 第 4 行:[Jinja2] 的运算符 [~] 会把两个值转换为字符串后再连接([+] 则拒绝把整数和字符串相加)。[{{-] 和 [-}}] 中的短横线会移除位于标签之前或之后的空白(空格和换行符):这样,徽章文本就与其标签紧贴在一起。
| {% extends "layout.html" %}
{% block title %}Home{% endblock %}
{% block content %}
<h1>Home</h1>
{# "自制的" long_date 过滤器 #}
<p>Today is {{ today | long_date }}.</p>
{# g:当前请求的对象,在视图中也可以访问 #}
<p>Formatting language: {{ g.locale }}
(<a href="/?lang=fr">in French</a>, <a href="/">in English</a>)</p>
{% endblock %}
|
- 第 7 行:调用“自定义”过滤器;
- 第 9 行:在视图中可以访问 [g] 对象。
| {% extends "layout.html" %}
{% from "fragments/badge.html" import badge %}
{% block title %}Products{% endblock %}
{% block content %}
<h1>Products</h1>
<table class="table table-sm w-auto">
<thead><tr><th>Product</th><th>Price</th><th>Price in dollars</th><th>Stock</th></tr></thead>
<tbody>
{% for product in products %}
<tr>
{# 一个全局函数,然后是一个过滤器,先不带参数,再带参数 #}
<td>{{ uppercase(product.name) }}</td>
<td>{{ product.price | money }}</td>
<td>{{ product.price | money("USD") }}</td>
{# [badge] 宏构建徽章的 HTML #}
<td>{{ badge(product.stock) }}</td>
</tr>
{% endfor %}
</tbody>
</table>
{% endblock %}
|
- 第 13 行:调用全局函数;
- 第 14–15 行:[money] 过滤器,先使用其默认货币,再带参数使用;
- 第 17 行:调用导入的宏。
[layout.html] 布局模板是示例 15 中那个模板的简化版本。
4.4.5. 执行


同一个页面,带参数 [?lang=fr]。只有数字的格式发生了变化:文本本身是硬编码在视图中的。国际化一章还将翻译这些文本。

生成的 HTML 节选:
| curl "http://localhost:5000/products?lang=en"
|
| ...
<tr>
<td>KEYBOARD</td>
<td>€25.00</td>
<td>$25.00</td>
<td><span class="badge text-bg-success">12 in stock</span>
</td>
</tr>
...
|
4.5. 示例 17:GET 表单
HTML 表单根据其 [method] 属性,以两种方式之一把字段发送到服务器:
- [method="get"]:字段作为参数添加到 URL 中([/search?keyword=le&genre=novel])。这是执行查询的表单所使用的方法:搜索或筛选。包含结果的 URL 可以被收藏、分享,或安全地重新加载;
- [method="post"]:字段包含在请求体中(见示例 11)。这是修改数据的表单所使用的方法:注册、添加或删除。
第一个表单是图书搜索。
4.5.1. 模型:models/books.py
| # models/books.py:一本书,以及视图的模型
from dataclasses import dataclass
@dataclass(frozen=True)
class Book:
title: str
author: str
genre: str
# 视图的模型:输入(用于再次显示)、体裁、结果
@dataclass
class SearchModel:
keyword: str
genre: str
genres: list[str]
results: list[Book]
|
- 第 5 行:[frozen=True] 使 [Book] 对象成为不可变的:对象一旦创建,其属性就不能再被修改。对于所有请求共享的数据(例如图书列表),这是一种良好的实践;
- 第 14–18 行:视图模型包含用户的输入(以便表单可以再次显示它)、建议的类型列表以及结果。
4.5.2. 控制器:controllers/books.py
| # controllers/books.py:通过 GET 发送的搜索表单
from flask import Blueprint, render_template, request
from models.books import Book, SearchModel
books = Blueprint("books", __name__)
BOOKS = (
Book("Le Rouge et le Noir", "Stendhal", "novel"),
Book("Les Fleurs du mal", "Baudelaire", "poetry"),
Book("Madame Bovary", "Flaubert", "novel"),
Book("Alcools", "Apollinaire", "poetry"),
Book("Le Cid", "Corneille", "drama"),
)
GENRES = ["novel", "poetry", "drama"]
# GET / 和 GET /search?keyword=...&genre=...:表单及其结果。
# 两个装饰器:同一个动作对应两条路由
@books.get("/")
@books.get("/search")
def search():
keyword = request.args.get("keyword", "")
genre = request.args.get("genre", "")
word = keyword.strip().lower()
results = [book for book in BOOKS
if (not word or word in book.title.lower() or word in book.author.lower())
and (not genre or book.genre == genre)]
return render_template("books/search.html",
model=SearchModel(keyword, genre, GENRES, results))
|
- 第 8–16 行:为本示例硬编码的数据。[BOOKS] 是一个元组(用圆括号括起来),即不可变序列。按照惯例,大写名称表示常量;
- 第 21–22 行:同一个动作上的两个路由装饰器:它对两个 URL 都做出响应。首次访问([/])时没有参数:显示所有图书;
- 第 24–25 行:表单字段作为 URL 的参数读取(示例 07)。[get] 的第二个参数是默认值;
- 第 27–29 行:使用带条件([if])的列表推导式进行过滤:如果关键字为空,或者出现在书名或作者中(两边都转为小写),并且类型为空或与该书的类型匹配,则该书被选中;
- 第 31 行:视图模板。
4.5.3. 视图:templates/books/search.html
| {% extends "layout.html" %}
{% block content %}
<h1 class="h3">Book search</h1>
{# method="get":字段通过 URL 发送(?keyword=...&genre=...) #}
<form method="get" action="/search" class="row g-2 align-items-end mb-3">
<div class="col-auto">
<label class="form-label" for="keyword">Title or author</label>
{# value:字段重新显示所输入的内容(由 {{ }} 转义) #}
<input class="form-control" id="keyword" name="keyword" value="{{ model.keyword }}">
</div>
<div class="col-auto">
<label class="form-label" for="genre">Genre</label>
<select class="form-select" id="genre" name="genre">
<option value="">(all)</option>
{% for genre in model.genres %}
{# selected:布尔属性,条件为真时写出,否则省略 #}
<option value="{{ genre }}"{{ " selected" if genre == model.genre }}>{{ genre }}</option>
{% endfor %}
</select>
</div>
<div class="col-auto">
<button class="btn btn-primary" type="submit">Search</button>
</div>
</form>
<p>{{ model.results | length }} book(s) found.</p>
<ul>
{% for book in model.results %}
<li><i>{{ book.title }}</i>, {{ book.author }} ({{ book.genre }})</li>
{% endfor %}
</ul>
{% endblock %}
|
- 第 6 行:[<form>] 标签。[action] 属性是表单提交到的 URL;[method="get"] 使字段出现在 URL 中。[Bootstrap] 的类把这些字段排布在同一行;
- 第 8 行:一个标签。它的 [for] 属性指定它所描述的字段的标识符([id]):点击标签会把光标置于该字段中,屏幕阅读器也会把标签与字段一起朗读;
- 第 10 行:一个输入字段。它的 [name] 属性是发送到服务器的参数名称:这就是表单与动作之间的联系([request.args.get("keyword")])。[value] 属性是显示的值:即重新显示的上一次输入(并由 [{{ }}] 转义,这在属性中至关重要:包含引号 ["] 的输入否则会提前关闭该属性);
- 第 14–20 行:一个下拉列表。每个 [<option>] 都有一个发送到服务器的值([value])和显示的文本。第一个选项的值为空,表示“所有类型”;
- 第 18 行:上一次请求中所选的选项会被赋予属性 [selected]。这是一个布尔属性:只要出现就足够了,它没有值。不带 [else] 的条件表达式决定是否写出它;
- 第 23 行:提交按钮([type="submit"]);
- 第 26 行:结果数量。
4.5.4. 执行

我们输入 [le] 并选择类型 [novel]:

结果页面的 URL 包含表单字段:[/search?keyword=le&genre=novel]。表单的响应:
| curl "http://localhost:5000/search?keyword=le&genre=novel"
|
| ...
<form method="get" action="/search" class="row g-2 align-items-end mb-3">
<div class="col-auto">
<label class="form-label" for="keyword">Title or author</label>
<input class="form-control" id="keyword" name="keyword" value="le">
</div>
<div class="col-auto">
<label class="form-label" for="genre">Genre</label>
<select class="form-select" id="genre" name="genre">
<option value="">(all)</option>
<option value="novel" selected>novel</option>
<option value="poetry">poetry</option>
<option value="drama">drama</option>
</select>
</div>
...
</form>
<p>1 book(s) found.</p>
<ul>
<li><i>Le Rouge et le Noir</i>, Stendhal (novel)</li>
</ul>
...
|
“Madame Bovary”没有被选中:“le”既不出现在书名中,也不出现在作者姓名中。
4.6. 示例 18:表单字段
手动输入每个字段的 HTML、重新显示其值、勾选正确的复选框并选中正确的选项,这些工作既重复又容易出错。[WTForms] 库替我们完成这些工作。表单在其中由一个类来描述,类的每个属性都是一个字段;每个字段都知道如何:
- 如何绑定到请求:从提交的数据中读取其值并转换为它的类型;
- 验证自身,依据其验证器列表(示例 19);
- 以 HTML 形式显示自身,连同其当前值。
[Flask-WTF] 扩展把 [WTForms] 集成到 [Flask] 中:它的表单会自己读取当前请求,并且受到保护,可以抵御 CSRF 攻击(我们稍后会讲到)。本示例展示了 HTML 表单中的所有字段类型。
4.6.1. 列表服务:services/lists.py
| # services/lists.py:表单提供的列表。在真实
# 应用中,它们会来自数据库:由于所有用户的列表都相同,
# 我们只会在启动时读取一次。
from flask import current_app
class ListsService:
# 每个列表:若干对(发送的值,显示的文本)
def titles(self) -> list[tuple[str, str]]:
return [(t, t) for t in ("Mr", "Mme", "Melle")]
def countries(self) -> list[tuple[str, str]]:
return [("fr", "France"), ("be", "Belgium"), ("ch", "Switzerland"), ("ca", "Canada")]
def hobbies(self) -> list[tuple[str, str]]:
return [(h, h) for h in ("reading", "music", "sport", "cinema")]
def languages(self) -> list[tuple[str, str]]:
return [(l, l) for l in ("French", "English", "Spanish", "German")]
def lists_service() -> ListsService:
return current_app.extensions["lists"]
|
表单的下拉列表(称谓、国家、爱好、语言)由一个服务提供,遵循示例 06 中的模式:在真实的应用程序中,它们将来自数据库。每个选项是一个 [(value, text)] 对:即发送到服务器的值和显示的文本。[[(t, t) for t in (...)]] 创建两个元素相同的对。函数 [lists_service] 使对象保持唯一,它由 [app.extensions] 中的 [app.py] 存储:
| # app.py:示例 18 的应用
from pathlib import Path
from flask import Blueprint, Flask
from controllers.form import form
from services.lists import ListsService
# Bootstrap,由各示例共享(见示例 15)
BOOTSTRAP = Path(__file__).resolve().parent.parent / "common" / "bootstrap"
def create_app():
app = Flask(__name__)
app.jinja_env.trim_blocks = True
app.jinja_env.lstrip_blocks = True
# 应用的密钥:它用于签名表单的 anti-CSRF 令牌
# (见 models/input.py)。生产环境中应使用保密的长随机字符串
app.config["SECRET_KEY"] = "a-secret-key-for-example-18"
# 列表服务:单一的共享对象(见示例 06)
app.extensions["lists"] = ListsService()
app.register_blueprint(Blueprint("bootstrap", __name__, static_folder=BOOTSTRAP,
static_url_path="/bootstrap"))
app.register_blueprint(form)
return app
if __name__ == "__main__":
create_app().run(port=5000, debug=True)
|
- 第 19 行:[app.config] 是应用程序的配置,一个字典。键 [SECRET_KEY] 是应用程序的密钥:[Flask] 及其扩展用它来对托付给浏览器的数据进行签名,也就是添加一个只有密钥持有者才能计算出的数字指纹。浏览器对数据的任何修改因此都会被检测到。[Flask-WTF] 的防 CSRF 令牌需要它;我们还会在会话 Cookie(示例 20)中再次看到它。在生产环境中,它是一个很长的随机字符串,绝不能出现在源代码中(身份验证一章将从环境变量中读取它);
- 第 21 行:所有请求共享的唯一服务。
| # models/input.py:由 WTForms 类描述的表单。每个字段
# 都知道如何从请求中读取自己(绑定),以及如何以 HTML 显示自己(渲染)
from flask_wtf import FlaskForm
from wtforms import (DateField, HiddenField, PasswordField, RadioField,
SelectField, SelectMultipleField, StringField, TextAreaField)
from wtforms.validators import Optional
from wtforms.widgets import CheckboxInput, ListWidget
from services.lists import lists_service
# 复选框:多选列表(SelectMultipleField),
# 绘制为一组复选框(控件),而不是下拉列表
class Checkboxes(SelectMultipleField):
widget = ListWidget(prefix_label=False)
option_widget = CheckboxInput()
# FlaskForm:适配 Flask 的 WTForms 表单;它自己读取
# 当前 POST 请求的字段,并包含一个隐藏的 [csrf_token] 字段
class InputForm(FlaskForm):
token = HiddenField()
title = RadioField("Title")
name = StringField("Name")
password = PasswordField("Password")
# <input type="date"> 字段以 yyyy-mm-dd 格式交换其值;
# Optional:该字段可以保持为空
birth_date = DateField("Date of birth", validators=[Optional()])
hobbies = Checkboxes("Hobbies")
country = SelectField("Country")
languages = SelectMultipleField("Spoken languages")
comment = TextAreaField("Comment")
# 选项列表,每次创建表单时由服务提供
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
lists = lists_service()
self.title.choices = lists.titles()
self.country.choices = lists.countries()
self.hobbies.choices = lists.hobbies()
self.languages.choices = lists.languages()
|
- 第 14–16 行:[WTForms] 没有“复选框组”字段。然而,对服务器而言,一组同名的复选框就是一个多选列表:它会发送零个、一个或多个值。因此,我们创建一个派生自 [SelectMultipleField] 的类,只改变它的呈现方式:字段的控件 是生成其 HTML 的对象;[ListWidget] 渲染一个选项列表,而每个选项由 [CheckboxInput] 渲染,即一个复选框;
- 第 21 行:表单继承自 [FlaskForm],即 [Flask-WTF] 的基类;
- 第 22–32 行:各个字段。第一个参数是标签。每个字段类对应一个 HTML 元素:
WTForms 字段 | 生成的 HTML 元素 |
[StringField] | [<input type="text">] |
[PasswordField] | [<input type="password">],从不预先填充 |
[HiddenField] | [<input type="hidden">],一个不可见的字段 |
[DateField] | [<input type="date">],其值被转换为 [date] |
[IntegerField]、[EmailField] | [<input type="number">]、[<input type="email">] (示例 19) |
[RadioField] | 一组单选按钮:只有一个值 |
[SelectField] | 一个下拉列表 [<select>]:只有一个值 |
[SelectMultipleField] | 一个列表 [<select multiple>]:可有多个值 |
[TextAreaField] | 一个文本框 [<textarea>],多行 |
[BooleanField] | 单个复选框,转换为布尔值 |
- 第 28 行:验证器 [Optional()] 允许该字段保持为空(否则,把空字符串转换为日期会失败)。[<input type="date">] 字段以 [yyyy-mm-dd] 格式与服务器交换其值,而不管浏览器以何种格式显示它;
- 第 35–41 行:下拉字段需要其选项列表([choices])。每次创建表单时都要在构造函数,即 [__init__] 方法中提供该列表。它首先调用父类的构造函数([super().__init__(...)]),把所有参数传给它,然后再填充各个字段。在类级别声明的字段 [title]在对象内部会变成专属于该表单的绑定字段([self.title])。
| # controllers/form.py:使用所有字段类型的表单
from flask import Blueprint, render_template, request
from models.input import InputForm
form = Blueprint("form", __name__, url_prefix="/form")
# GET:带有初始值的表单(关键字参数:每个字段一个)
@form.get("")
def display():
input_form = InputForm(title="Mme", country="fr", languages=["French"], token="A7X2")
return render_template("form/form.html", form=input_form)
# POST:InputForm() 读取发送的字段;表单再次显示它们
@form.post("")
def process():
input_form = InputForm()
# validate:检查 anti-CSRF 令牌以及各字段的约束
valid = input_form.validate()
# 浏览器实际发送的内容,逐个参数列出
received = "\n".join(f"{name} = [{', '.join(values)}]"
for name, values in request.form.lists())
return render_template("form/form.html", form=input_form, received=received,
valid=valid)
|
- 第 12 行:在请求(GET)期间创建的表单不会读取任何内容:其字段取传给构造函数的值(命名参数,每个字段一个),或者保持为空。这些是表单的初始值;
- 第 13 行:表单本身被传给视图,由视图来渲染它;
- 第 19 行:在 POST 请求期间,[FlaskForm] 会自己读取提交的字段([request.form]):每个字段取得收到的值,并转换为其类型;
- 第 21 行:[validate()] 对每个字段运行验证器,如果全部满足则返回 [True] 。下拉字段会自动验证收到的值是否在其选项之中:恶意用户可以发送任何内容,而不仅仅是页面提供的内容。[Flask-WTF] 在此之外还增加了防 CSRF 令牌检查;
- 第 23–24 行:作为示例,列出浏览器实际发送的内容:[request.form.lists()] 针对每个参数返回其名称和值列表。[", ".join(...)] 把它们合并为一个字符串。
| {% extends "layout.html" %}
{% block content %}
<h1 class="h3">A complete form</h1>
<form method="post" action="/form" style="max-width: 40rem">
{# 隐藏字段:Flask-WTF 的防 CSRF 令牌,以及我们自己的 [token] 字段 #}
{{ form.csrf_token }}
{{ form.token }}
<div class="mb-2">
<span class="form-label me-3">{{ form.title.label.text }}</span>
{# 单选按钮:遍历字段的选项;[name] 相同,只发送一个值 #}
{% for option in form.title %}
<div class="form-check form-check-inline">
{{ option(class="form-check-input") }}
{{ option.label(class="form-check-label") }}
</div>
{% endfor %}
</div>
<div class="row g-2 mb-2">
<div class="col">
{# 字段通过调用(CALLING)它来显示;其参数会变成 HTML 属性 #}
{{ form.name.label(class="form-label") }}
{{ form.name(class="form-control") }}
</div>
<div class="col">
{# 密码绝不会在页面中送回:PasswordField 会省略它 #}
{{ form.password.label(class="form-label") }}
{{ form.password(class="form-control") }}
</div>
<div class="col">
{{ form.birth_date.label(class="form-label") }}
{{ form.birth_date(class="form-control") }}
</div>
</div>
<div class="mb-2">
<span class="form-label me-3">{{ form.hobbies.label.text }}</span>
{# 复选框:[name] 相同,可以发送多个值 #}
{% for option in form.hobbies %}
<div class="form-check form-check-inline">
{{ option(class="form-check-input") }}
{{ option.label(class="form-check-label") }}
</div>
{% endfor %}
</div>
<div class="row g-2 mb-2">
<div class="col">
{{ form.country.label(class="form-label") }}
{{ form.country(class="form-select") }}
</div>
<div class="col">
{{ form.languages.label(class="form-label") }}
{# 多选列表:可以发送多个值 #}
{{ form.languages(class="form-select", size=4) }}
</div>
</div>
<div class="mb-2">
{{ form.comment.label(class="form-label") }}
{# 文本区域:值位于标签之间 #}
{{ form.comment(class="form-control", rows=2) }}
</div>
<button class="btn btn-primary" type="submit">Send</button>
</form>
{% if received is defined %}
<h2 class="h5 mt-3">What the server received</h2>
<pre class="bg-light p-2 border">{{ received }}</pre>
<p>Valid form: {{ "yes" if valid else "no" }}</p>
{# form.errors:一个字典,字段 -> 其错误消息列表 #}
<ul>
{% for field, messages in form.errors.items() %}
<li>{{ field }}: {{ messages | join(", ") }}</li>
{% endfor %}
</ul>
{% endif %}
{% endblock %}
|
- 第 5 行:一个 POST 表单;
- 第 7 行:包含防 CSRF 令牌的隐藏字段。CSRF 攻击(*Cross-Site Request Forgery*,跨站请求伪造)是指恶意网站诱使受害者的浏览器向我们的应用程序发送表单。浏览器会在请求中带上我们应用程序的 Cookie,因而也带上已登录用户的会话,所以该请求看起来是合法的。防御方法:我们应用程序中的每个表单都包含一个随机令牌,该令牌与用户的会话关联,并用密钥签名,而恶意网站无从得知这个密钥。[Flask-WTF] 会拒绝任何令牌缺失或无效的 POST 表单;
- 第 8 行:字段通过调用它来渲染,或者直接通过 [{{ }}] 把它插入页面(这等同于不带参数地调用它)。它生成的 HTML 不会被转义:[WTForms] 将其标记为安全(不过,它放入其中的值是经过转义的);
- 第 13–18 行:一组单选按钮。通过循环遍历时,字段会渲染其选项,每个按钮一个:每个选项都被绘制出来([option(...)]),并有自己的标签([option.label(...)])。所有单选按钮共享同一个属性 [name]:每次只能选中一个,也只会提交一个值;
- 第 24–25 行:标签和输入字段。调用的命名参数会变成 HTML 属性:[class="form-control"]。由于 [class] 在 [Python] 中是保留字,[WTForms] 也接受 [class_];
- 第 30 行:[PasswordField] 从不重新显示收到的值:密码不应在 HTML 页面中来回传送;
- 第 41–46 行:复选框,样式与单选按钮相同。它们也有相同的 [name];不过,可以选中多个复选框,此时浏览器会发送多个值(例如 10);
- 第 57 行:多选列表,显示为四行([size]);
- 第 64 行:文本字段,占两行;
- 第 70–80 行:条件 [is defined] 在变量 [received] 已被传给视图(通过 POST 动作)时为真。[form.errors] 是一个字典,它把每个无效字段与其错误消息列表关联起来;[items()] 返回这些键值对。过滤器 [join] 把列表中的元素合并起来。
4.6.5. 执行

可以看到传给构造函数的初始值:单选按钮“Mme”、国家“France”和语言“French”。由 [WTForms] 生成的 HTML(节选):
| <input id="csrf_token" name="csrf_token" type="hidden" value="ImJmYmRjNWU0NGMyZDMwNDM1MGQ0ODQ5YTExZjAzYThhYTc0YWI0ZDYi.arfKQQ.9PqkMic5droodAE5iZdcz87dHJI">
<input id="token" name="token" type="hidden" value="A7X2">
...
<input checked class="form-check-input" id="title-1" name="title" type="radio" value="Mme">
<label class="form-check-label" for="title-1">Mme</label>
...
<input class="form-control" id="birth_date" name="birth_date" type="date" value="">
...
<input class="form-check-input" id="hobbies-0" name="hobbies" type="checkbox" value="reading">
<label class="form-check-label" for="hobbies-0">reading</label>
...
<select class="form-select" id="country" name="country"><option selected value="fr">France</option><option value="be">Belgium</option>...</select>
...
<select class="form-select" id="languages" multiple name="languages" size="4"><option selected value="French">French</option>...</select>
...
<textarea class="form-control" id="comment" name="comment" rows="2">
</textarea>
|
[WTForms] 写出了属性 [id] (字段名称,对于分组则后接选项序号)、[name]、[type]、[value],以及用于常见选择的 [checked] 和 [selected] 。防 CSRF 令牌是一个经过签名的字符串。让我们填写表单并提交:

页面显示了服务器收到的内容:每个字段对应一个参数,复选框和下拉列表有多个值;密码已被发送,但不会再在其字段中显示。隐藏字段 [token] 被原样返回:用户看不见的信息就是这样来回传送的(案例研究用它来传送记录的版本号)。不过,隐藏字段并不是受保护的字段:用户可以使用浏览器的开发者工具修改它,服务器必须像验证其他任何字段一样验证它。
现在让我们用 [curl] 发送一个没有令牌、且国家不在列表中的表单:
| curl -d "name=Martin&country=xx" http://localhost:5000/form
|
| ...
<h2 class="h5 mt-3">What the server received</h2>
<pre class="bg-light p-2 border">name = [Martin]
country = [xx]</pre>
<p>Valid form: no</p>
<ul>
<li>title: Not a valid choice.</li>
<li>country: Not a valid choice.</li>
<li>csrf_token: The CSRF token is missing.</li>
</ul>
...
|
三个错误:缺少令牌;国家 [xx] 不在选项之中;没有提交称谓([RadioField] 要求必须有一个选择)。这些消息是英文的,英文是 [WTForms] 的默认语言:下一个示例将展示如何选择它们的语言。
4.7. 示例 19:表单验证
一个注册表单,其中每个字段都有自己的约束。如果出现错误,表单会连同用户的输入一起重新显示,并在每个出错字段的下方显示一条消息。
4.7.1. 表单:models/registration.py
| # models/registration.py:表单的字段及其约束
from flask_wtf import FlaskForm
from wtforms import EmailField, IntegerField, PasswordField, StringField
from wtforms.validators import DataRequired, Email, EqualTo, InputRequired, Length, NumberRange
# 过滤器:在验证之前转换接收到的值;
# 这里是去除输入两端的空格
def clean(value):
return value.strip() if isinstance(value, str) else value
class RegistrationForm(FlaskForm):
# WTForms 自己编写的消息所用的语言(例如无法转换:
# 整数字段中输入 "abc")
class Meta:
locales = ["en"]
# 每个字段:一个标签、若干过滤器,以及一个验证器列表,每个验证器
# 都带有自己的错误消息。DataRequired 拒绝空输入(或由空格组成的输入);
# 它还会生成 HTML5 的 [required] 属性
name = StringField("Name", filters=[clean], validators=[
DataRequired("The name is required."),
Length(max=20, message="The name must not exceed 20 characters.")])
# EmailField:一个 <input type="email"> 字段
email = EmailField("Email address", filters=[clean], validators=[
DataRequired("The email address is required."),
Email("Invalid email address.")])
# 来自表单的一切都是字符串:IntegerField 负责转换
# ("42" -> 42);InputRequired:输入不得为空
age = IntegerField("Age", validators=[
InputRequired("The age is required."),
NumberRange(min=18, max=120, message="The age must be between 18 and 120 years.")])
password = PasswordField("Password", validators=[
DataRequired("The password is required."),
Length(min=6, message="The password must have at least 6 characters.")])
# 涉及两个字段的规则:EqualTo 将本字段与另一个字段比较
confirmation = PasswordField("Confirmation", validators=[
DataRequired("The confirmation is required."),
EqualTo("password", message="The confirmation does not match the password.")])
|
- 第 9–10 行:[WTForms] 过滤器是一个在验证之前转换所收到的值的函数。它会去除字符串两端的空格(例如输入 [" "] 会变成空值,并被 [DataRequired] 拒绝)。[isinstance] 测试用于防范缺失的值([None]);
- 第 17–18 行:内部类 [Meta] 控制表单的行为。[locales = ["en"]]:由 [WTForms] 自己生成的消息(无法转换、选择无效等)将是英文的;[WTForms] 自带多种语言的翻译(["fr"] 会给出法语消息)。 [app.py] 为此禁用了 [Flask-WTF] 的翻译机制([WTF_I18N_ENABLED = False]);否则,它会等待 [Flask-Babel] 扩展;
- 第 23–25 行:参数 [validators] 是字段的验证器列表,按顺序执行。每个验证器都有自己的错误消息。[DataRequired] 拒绝空值;[Length] 限制字符串的长度;
- 第 28–30 行:[EmailField] 生成一个 [<input type="email">];验证器 [Email] 检查地址的语法(使用库 [email-validator],示例 08 中 [Pydantic] 已经用过它);
- 第 34–36 行:[IntegerField] 转换整个输入。[InputRequired] 要求必须有输入;与 [DataRequired] 不同,它检查的是是否有内容被输入,而不是转换后的值是否为“真”:[DataRequired] 会拒绝 0 岁的年龄,因为 [0] 在 [Python] 中为假。[NumberRange] 限制取值范围;
- 第 43–45 行:一条作用于两个字段的规则:[EqualTo("password")] 把一个字段的值与另一个字段的值进行比较。
验证器也用于显示:[WTForms] 由它们推导出 HTML5 属性([required]、[maxlength]、[minlength]、[min]、[max]),使浏览器在提交之前就能验证输入(我们稍后会讲到)。“自定义”验证器是一个以表单和字段为参数的函数,如果值无效,它会抛出 [ValidationError] (来自 [wtforms.validators] 模块);它也可以写成名为 [validate_<field>] 的表单方法。[WTForms] 还提供其他现成的验证器:[Regexp] (正则表达式)、[AnyOf] (允许值的列表)、[Optional]……案例研究会用到这些验证器。
4.7.2. 控制器:controllers/registration.py
| # controllers/registration.py:由服务器验证的表单
from flask import Blueprint, render_template, request
from models.registration import RegistrationForm
registration = Blueprint("registration", __name__, url_prefix="/register")
# ?html5=true:我们让浏览器在发送之前验证表单
def html5_requested() -> bool:
return request.args.get("html5") == "true"
@registration.get("")
def display():
return render_template("registration/registration.html", form=RegistrationForm(),
html5=html5_requested())
@registration.post("")
def register():
form = RegistrationForm()
# validate_on_submit:请求是 POST 并且表单有效
if not form.validate_on_submit():
# 我们再次显示表单:已输入的值(密码除外),
# 以及每个错误字段下方的消息(见 fragments/field.html)
return render_template("registration/registration.html", form=form,
html5=html5_requested(),
error="The form contains errors.")
return render_template("registration/welcome.html", form=form)
|
- 第 10–11 行:参数 [?html5=true] 启用浏览器端验证(见下文);
- 第 24 行:[validate_on_submit()] 返回 [True] ,如果请求是 POST 并且表单有效;
- 第 27–29 行:无效的表单被重新显示:它仍是同一个 [form] 对象,其中包含用户的输入和每个字段的错误。变量 [error] 是一条通用消息,由模板显示在页面底部;
- 第 30 行:有效的表单——欢迎页面。(下一个示例将说明,POST 成功之后最好进行重定向。)
4.7.3. 可复用的字段:templates/fragments/field.html
每个字段的显示方式都相同:一个标签、输入字段,以及在出错时用红色框出的区域和其下方的消息。宏可以避免把这些代码写五遍:
| {# 一个输入字段,带有其标签和第一条错误消息。
field.errors:该字段的错误消息列表;HTML5 属性
(required、maxlength、minlength、min、max)由 WTForms 自己写出,
依据的是该字段的验证器 #}
{% macro field_row(field) %}
<div class="mb-2">
{{ field.label(class="form-label") }}
{{ field(class="form-control" ~ (" is-invalid" if field.errors else "")) }}
{% if field.errors %}
<div class="invalid-feedback">{{ field.errors[0] }}</div>
{% endif %}
</div>
{% endmacro %}
|
- 第 5 行:宏接收表单中的一个字段;
- 第 8 行:类 [is-invalid],来自 [Bootstrap],用红色框出字段。如果字段的错误列表 [field.errors] 不为空,就会添加它;
- 第 9–11 行:字段的第一条错误消息,放在 [invalid-feedback] 元素中,[Bootstrap] 会把它以红色显示在 [is-invalid] 字段的下方。
4.7.4. 视图
| {% extends "layout.html" %}
{% from "fragments/field.html" import field_row %}
{% block content %}
<h1 class="h3">Registration</h1>
{% if html5 %}
<p>Browser validation <b>enabled</b> - <a href="/register">disable it</a></p>
{% else %}
<p>Browser validation <b>disabled</b> - <a href="/register?html5=true">enable it</a></p>
{% endif %}
{# novalidate:浏览器忽略 required、min... 等属性,并
原样发送表单;只有服务器进行验证 #}
<form method="post" action="{{ '/register?html5=true' if html5 else '/register' }}"
{{- '' if html5 else ' novalidate' }}>
{{ form.csrf_token }}
{{ field_row(form.name) }}
{{ field_row(form.email) }}
{{ field_row(form.age) }}
{{ field_row(form.password) }}
{{ field_row(form.confirmation) }}
<button class="btn btn-primary" type="submit">Register</button>
</form>
{% endblock %}
|
- 第 13–14 行:[novalidate] 属性禁用浏览器验证:表单原样提交,只有服务器进行验证。这正是我们首先想要观察的。[{{-] 会移除标签之前的空白,使该属性紧挨着 [<form>] 标签;
- 第 16–20 行:对每个字段调用一次宏。
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Registration</title>
<link rel="stylesheet" href="{{ url_for('bootstrap.static', filename='css/bootstrap.min.css') }}">
<link rel="stylesheet" href="{{ url_for('static', filename='css/styles.css') }}">
</head>
<body>
<div class="container py-3" style="max-width: 36rem">
<main>
{% block content %}{% endblock %}
</main>
{# 页面底部的全局错误,显示在浅粉色背景上;[error] 由操作提供 #}
{% if error %}
<div class="error-area" role="alert">{{ error }}</div>
{% endif %}
</div>
</body>
</html>
|
- 第 15–17 行:页面底部的通用消息,位于一个区域中,其样式由 [static/css/styles.css] 定义(示例 15)。属性 [role="alert"] 为屏幕阅读器标示它。
| {% extends "layout.html" %}
{% block content %}
{# form.name.data:字段的值,经过过滤器和转换之后 #}
<h1 class="h3">Welcome {{ form.name.data }}</h1>
<p>Your registration is saved: address <b>{{ form.email.data }}</b>,
age <b>{{ form.age.data }}</b> years.</p>
{% endblock %}
|
[form.name.data] 是字段经过过滤和转换之后的值:去掉空格的姓名,以及作为整数的年龄。
4.7.5. 执行
让我们提交一个充满错误的表单:由空格组成的姓名、不带完整域名的地址、12 岁的年龄、过短的密码,以及不一致的确认密码:

输入内容得到了保留(密码除外),每个错误都标示在对应字段的下方。借助 [curl],这一次提供防 CSRF 令牌,我们还可以提交浏览器不会发送的内容——非数字的年龄:由 [WTForms] 生成的转换消息是英文的,即 [locales] 所选择的语言:
| <input class="form-control is-invalid" id="age" max="120" min="18" name="age" required type="number" value="abc">
<div class="invalid-feedback">Not a valid integer value.</div>
|
我们还可以看到由验证器推导出的 HTML5 属性:[required]、[min]、[max]。
4.7.6. 浏览器验证
让我们点击“enable it”链接来移除 [novalidate] 属性(参数 [?html5=true])。于是浏览器在提交表单之前,会自行检查属性 [required]、[type="email"]、[min]、[maxlength]……,并显示它自己的消息:

这种验证对用户很方便:它是即时的,无需与服务器来回通信。但它不能取代服务器端验证:用户可以禁用它,而像 [curl] 这样的程序则完全忽略它。规则是绝对的:服务器始终要进行验证;浏览器端验证只是一种额外的便利。
终于得到了一次正确的输入。两侧带有空格输入的姓名已被过滤器清理:

4.8. 示例 20:Post/Redirect/Get 模式
当 POST 动作以一个页面作为响应时,该页面是 POST 的结果。如果用户重新加载页面(按下 [F5]),浏览器会再次发送 POST 请求,并在此之前显示一条几乎没人会读的警告:命令被发送了两次,消息也被发布了两次。Post/Redirect/Get 模式(PRG)避免了这个问题:成功的 POST 动作不返回页面;它以一个重定向(示例 04)作为响应,指向一个 GET 页面,浏览器会立即请求该页面。重新加载这个页面只会重新执行 GET 动作。
还有一个问题:GET 页面想要显示一条消息(“任务已添加”),但知道这条消息的是 POST 动作,而它无法向尚未发生的请求传递变量。解决方案是:闪现消息,由 POST 动作发布,保留到下一个请求,显示之后即被丢弃。
4.8.1. 服务:services/tasks.py
| # services/tasks.py:任务列表,存放在内存中,由所有人共享
from threading import Lock
from flask import current_app
class TasksService:
def __init__(self):
self._tasks = ["Read chapter 3"]
# 多个请求可能同时运行(服务器在多个线程上
# 处理它们):锁(Lock)保证同一时刻只有一个
# 线程读取或修改该列表
self._lock = Lock()
def list(self) -> list[str]:
with self._lock:
return list(self._tasks) # 一份副本:调用方无法修改我们的数据
def add(self, label: str):
with self._lock:
self._tasks.append(label)
def tasks_service() -> TasksService:
return current_app.extensions["tasks"]
|
- 第 14 行:任务列表由所有请求共享。然而,开发服务器在不同的线程上处理每个请求:两个请求可能同时运行并同时修改该列表。锁 ([Lock],来自标准模块 [threading])确保同一时刻只有一个线程执行它所保护的代码。前缀 [_] 按惯例表示类的内部属性;
- 第 17 行:语句 [with] 获取锁,执行代码块,然后释放锁,即使代码块抛出异常也是如此。发现锁已被获取的线程会等待,直到锁被释放;
- 第 18 行:该方法返回列表的副本 :调用者可以安全地遍历它,即使另一个线程正在向原列表中添加任务。
4.8.2. 控制器:controllers/tasks.py
| # controllers/tasks.py:Post / Redirect / Get 模式
from flask import Blueprint, flash, redirect, render_template, request, url_for
from services.tasks import tasks_service
tasks = Blueprint("tasks", __name__, url_prefix="/tasks")
# GET /tasks:列表和添加表单
@tasks.get("")
def display():
return render_template("tasks/tasks.html", tasks=tasks_service().list())
# POST /tasks:Post / Redirect / Get 模式
@tasks.post("")
def add():
label = request.form.get("label", "")
text = label.strip()
if not text or len(text) > 40:
# 输入无效:我们不重定向,直接再次显示页面
return render_template("tasks/tasks.html", tasks=tasks_service().list(),
label=label,
error="The label must have 1 to 40 characters.")
tasks_service().add(text)
# "flash" 消息:它会在重定向之后保留,供下一个请求使用
flash(f"The task [{text}] has been added.")
# 不返回页面:重定向到 GET 页面
return redirect(url_for("tasks.display"))
# POST /tasks/without-prg:反例(以页面响应 POST)
@tasks.post("/without-prg")
def add_without_prg():
label = request.form.get("label", "").strip()
tasks_service().add(label or "(untitled)")
return render_template("tasks/tasks.html", tasks=tasks_service().list(),
without_prg=True)
|
- 第 18–24 行:为使示例保持简单,输入是手动验证的,没有使用 [WTForms]。无效的输入会被重新显示而不重定向:由于没有任何内容被修改,也就没有什么需要防范重复提交;
- 第 27 行:[flash] 为下一个请求设置一条消息;
- 第 29 行:重定向到 GET 页面;
- 第 34–38 行:反例:作为 POST 响应的页面。
4.8.3. 视图
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Tasks</title>
<link rel="stylesheet" href="{{ url_for('bootstrap.static', filename='css/bootstrap.min.css') }}">
<link rel="stylesheet" href="{{ url_for('static', filename='css/styles.css') }}">
</head>
<body>
<div class="container py-3" style="max-width: 36rem">
{# 页面顶部的 flash 消息:在重定向之前设置;
get_flashed_messages 返回它们,然后将其清除 #}
{% for message in get_flashed_messages() %}
<div class="alert alert-success" role="status">{{ message }}</div>
{% endfor %}
<main>
{% block content %}{% endblock %}
</main>
{% if error %}
<div class="error-area" role="alert">{{ error }}</div>
{% endif %}
</div>
</body>
</html>
|
- 第 13–15 行:函数 [get_flashed_messages()] 在所有视图中都可用,它返回待显示的闪现消息列表,然后将它们丢弃:它们只会显示一次。[alert alert-success] 类来自 [Bootstrap] ,它把消息显示在绿色边框中。
| {% extends "layout.html" %}
{% block content %}
<h1 class="h3">My tasks</h1>
<ol>
{% for task in tasks %}
<li>{{ task }}</li>
{% endfor %}
</ol>
<form method="post" action="/tasks" class="d-flex gap-2">
<input class="form-control" name="label" value="{{ label }}" placeholder="New task">
<button class="btn btn-primary text-nowrap" type="submit">Add</button>
{# formaction:此按钮将同一个表单发送到另一个地址 #}
<button class="btn btn-outline-secondary text-nowrap" type="submit" formaction="/tasks/without-prg">Add without PRG</button>
</form>
{% if without_prg %}
<p class="text-danger mt-2">Page displayed in response to a POST: press F5 and the task will be added a second time.</p>
{% endif %}
{% endblock %}
|
- 第 14 行:按钮的 [formaction] 属性会把表单发送到不同于其 [action] 属性的地址:因此,同一个表单可以触发两个不同的动作。
4.8.4. 闪现消息存储在哪里?
在 POST 请求和随后的 GET 请求之间,消息必须存储在某个地方。[Flask] 把它存储在用户的会话 中(见作用域一章)。默认情况下,[Flask] 的会话并不存储在服务器上:它存储在发送给浏览器的 Cookie 中,浏览器会在每次请求时将其重新发回。为防止用户篡改,Cookie 用密钥进行了签名 ——这就是 [app.py] 要设置密钥的原因。让我们用 [curl] 来检查一下。[-c] 选项把收到的 Cookie 记录到文件中,而 [-b] 选项则把文件中的 Cookie 发回:
| curl -i -c cookies.txt -d "label=Do%20the%20exercises" http://localhost:5000/tasks
|
| HTTP/1.1 302 FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 199
Location: /tasks
Set-Cookie: session=eyJfZmxhc2hlcyI6W3siIHQiOlsibWVzc2FnZSIsIlRoZSB0YXNrIFtEbyB0aGUgZXhlcmNpc2VzXSBoYXMgYmVlbiBhZGRlZC4iXX1dfQ.arfKbA.72zBgSN6wiA_v1Ci_KS3Si8Brbc; HttpOnly; Path=/
...
|
对 POST 的响应是一个重定向(状态码 302,头部 [Location]),并附带一个 Cookie [session]。它的值由三部分组成,以句点分隔:经过 Base64 编码的数据(未压缩:[Flask] 仅在压缩后更短时才压缩);签名日期;以及签名。解码之后,数据是可读的:
| {"_flashes":[{" t":["message","The task [Do the exercises] has been added."]}]}
|
因此,名为 [Flask] 的应用程序的会话对用户而言是可读的 (它没有加密),但防篡改 (它经过签名):其中不存放任何机密。属性 [HttpOnly] 可防止页面上的 [JavaScript] 读取该 Cookie。让我们回传 Cookie 来跟随重定向:
| curl -i -b cookies.txt -c cookies.txt http://localhost:5000/tasks
|
| HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 885
Set-Cookie: session=; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Max-Age=0; HttpOnly; Path=/
...
<div class="alert alert-success" role="status">The task [Do the exercises] has been added.</div>
<main>
<h1 class="h3">My tasks</h1>
<ol>
<li>Read chapter 3</li>
<li>Do the exercises</li>
</ol>
...
|
消息被显示出来,而会话——此时已为空——被删除:服务器返回一个过期日期已过的空 Cookie。再发起一次 GET 请求就不会再显示该消息了。
4.8.5. 执行
添加任务:浏览器跟随了重定向;URL 是 GET 页面的 URL,可以安全地重新加载。

无效的输入,连同其错误消息一起重新显示:

反例:页面是对 POST 的响应,其 URL 为 [/tasks/without-prg]。如果点击 [F5],浏览器会询问是否要重新提交表单;如果同意,任务就会被第二次添加。

4.9. 示例 21:链接、按钮与确认
HTTP 协议的一条原则:GET 请求不会改变任何东西。浏览器、搜索引擎和预加载页面的工具会随意跟随链接,而不会征求用户的许可。因此,“删除”链接([<a href="/contacts/2/delete">])将是危险的:抓取网站的机器人会删除所有内容。在 Web 应用程序中:
- 查看通过链接 ([<a href>])完成,它发送 GET 请求;
- 编辑(保存、复制、删除)通过放在表单(POST)中的按钮 完成,并由防 CSRF 令牌保护。
本示例管理一个联系人列表,并在每次删除之前显示一个确认窗口。
| # services/contacts.py:联系人,存放在内存中,由所有人共享
from dataclasses import dataclass, replace
from threading import Lock
from flask import current_app
# 一个联系人:标识符、姓名、电话号码
@dataclass(frozen=True)
class Contact:
id: int
name: str
phone: str
class ContactsService:
def __init__(self):
self._contacts = [
Contact(1, "Marie Durand", "01 23 45 67 89"),
Contact(2, "Paul Martin", "06 12 34 56 78"),
Contact(3, "Philippe Jandot", "02 98 76 54 32"),
]
self._last_id = 3
self._lock = Lock()
def list(self) -> list[Contact]:
with self._lock:
return list(self._contacts)
# 该联系人,如果不存在则为 None
def read(self, id: int) -> Contact | None:
with self._lock:
return next((c for c in self._contacts if c.id == id), None)
def edit(self, id: int, name: str, phone: str) -> Contact | None:
with self._lock:
for i, contact in enumerate(self._contacts):
if contact.id == id:
# 联系人是不可变的(frozen):replace 构建一个
# 新的联系人,用它替换列表中的旧联系人
self._contacts[i] = replace(contact, name=name, phone=phone)
return self._contacts[i]
return None
def add(self, name: str, phone: str) -> Contact:
with self._lock:
self._last_id += 1
contact = Contact(self._last_id, name, phone)
self._contacts.append(contact)
return contact
def delete(self, id: int) -> Contact | None:
with self._lock:
contact = next((c for c in self._contacts if c.id == id), None)
if contact is not None:
self._contacts.remove(contact)
return contact
def contacts_service() -> ContactsService:
return current_app.extensions["contacts"]
|
一个内存中的服务,由一把与示例 20 中相同的锁保护。关于 [Python] 的几点说明:
- 第 34 行:括号中的表达式是一个由 ID 与所查找的 ID 相匹配的联系人构成的生成器 (见示例 05);[next] 返回第一个元素,如果不存在,则返回默认值 [None] ;
- 第 38 行:[enumerate] 遍历列表,为每一项返回索引和元素;
- 第 42 行:联系人是不可变的([frozen=True]);模块 [replace] 中的函数 [dataclasses] 会创建它的一个副本,并修改其中某些属性;
- 对于不存在的联系人,这些方法返回 [None] :由控制器决定如何响应。
| # controllers/contacts.py:链接(GET)和按钮(POST)
from flask import Blueprint, abort, flash, redirect, render_template, request, url_for
from services.contacts import contacts_service
contacts = Blueprint("contacts", __name__, url_prefix="/contacts")
# 该联系人,如果不存在则返回 404 响应
def contact_or_404(contact):
if contact is None:
abort(404, "unknown contact")
return contact
# 链接(<a href>):GET 请求,不修改任何内容
@contacts.get("")
def list_contacts():
return render_template("contacts/list.html", contacts=contacts_service().list())
@contacts.get("/<int:id>")
def details(id):
contact = contact_or_404(contacts_service().read(id))
return render_template("contacts/details.html", contact=contact)
# POST 表单中的按钮:修改数据的请求
@contacts.post("/<int:id>")
def save(id):
contact = contact_or_404(contacts_service().edit(
id, request.form.get("name", ""), request.form.get("phone", "")))
flash(f"The contact [{contact.name}] has been edited.")
return redirect(url_for("contacts.list_contacts"))
# 同一个表单,另一个按钮(formaction 属性):另一个动作
@contacts.post("/<int:id>/duplicate")
def duplicate(id):
copy = contacts_service().add(request.form.get("name", "") + " (copy)",
request.form.get("phone", ""))
flash(f"The contact [{copy.name}] has been created.")
return redirect(url_for("contacts.list_contacts"))
@contacts.post("/<int:id>/delete")
def delete(id):
contact = contact_or_404(contacts_service().delete(id))
flash(f"The contact [{contact.name}] has been deleted.")
return redirect(url_for("contacts.list_contacts"))
|
- 第 10–13 行:一个工具函数:不存在的联系人会使动作以 404 响应终止;
- 第 17–23 行:两个 GET 动作,它们不修改任何内容:列表和联系人的记录;
- 第 29–34 行:保存记录:一个遵循 PRG 模式的 POST 动作。同一个 URL [/contacts/2] 由两个不同的动作按方法分别处理:GET 负责显示,POST 负责保存;
- 第 38–43 行:复制——另一个 POST 动作,由同一表单上的第二个按钮触发;
- 第 46–50 行:删除。
4.9.3. 防 CSRF 保护:app.py
| # app.py:示例 21 的应用
from pathlib import Path
from flask import Blueprint, Flask
from flask_wtf.csrf import CSRFProtect
from controllers.contacts import contacts
from services.contacts import ContactsService
# Bootstrap,由各示例共享(见示例 15)
BOOTSTRAP = Path(__file__).resolve().parent.parent / "common" / "bootstrap"
def create_app():
app = Flask(__name__)
app.jinja_env.trim_blocks = True
app.jinja_env.lstrip_blocks = True
app.config["SECRET_KEY"] = "a-secret-key-for-example-21"
app.extensions["contacts"] = ContactsService()
app.register_blueprint(Blueprint("bootstrap", __name__, static_folder=BOOTSTRAP,
static_url_path="/bootstrap"))
app.register_blueprint(contacts)
# Flask-WTF 的 anti-CSRF 保护,适用于应用的所有 POST 请求:
# 每个表单都必须回传 csrf_token() 令牌
CSRFProtect(app)
return app
if __name__ == "__main__":
create_app().run(port=5000, debug=True)
|
- 第 26 行:在示例 18 和 19 中,是 [WTForms] 表单在 [validate()] 中验证自己的令牌。而这里,表单是手写的,没有使用 [WTForms]。[CSRFProtect] 把保护扩展到整个应用程序:在每个请求(POST,以及 PUT、PATCH、DELETE)之前,它都会验证令牌,如果令牌缺失或无效,则在调用动作之前就返回 400 状态码。动作无法省略这一检查。案例研究将使用这种配置。
4.9.4. 视图
| {% extends "layout.html" %}
{% block content %}
<h1 class="h3">Contacts</h1>
<table class="table align-middle">
<tbody>
{% for contact in contacts %}
<tr>
<td>{{ contact.name }}</td>
<td>{{ contact.phone }}</td>
<td class="text-end">
{# view:一个简单的链接;url_for 把 id 放入路径中:/contacts/2 #}
<a class="btn btn-sm btn-outline-primary" href="{{ url_for('contacts.details', id=contact.id) }}">View</a>
{# delete:一个 POST 表单,其提交需要确认 #}
<form method="post" class="d-inline" action="{{ url_for('contacts.delete', id=contact.id) }}"
data-confirmation="Delete the contact {{ contact.name }}?">
{# 防 CSRF 令牌,由 CSRFProtect 要求(参见 app.py) #}
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<button class="btn btn-sm btn-outline-danger" type="submit">Delete</button>
</form>
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% endblock %}
|
- 第 13 行:一个链接,由 [Bootstrap] 的类([btn]……)呈现为按钮:外观与 HTTP 方法无关。[url_for('contacts.details', id=contact.id)] 把 ID 放在路径中:[/contacts/2];
- 第 15–20 行:每个“Delete”按钮对应一个 POST 表单 ,除令牌外没有其他字段。[d-inline] 类使它与链接显示在同一行。[data-confirmation] 属性包含确认消息:[data-...] 属性不被赋予任何含义,专供页面上的 [JavaScript] 使用;
- 第 18 行:函数 [csrf_token()] 由 [Flask-WTF] 提供给视图,它返回会话的防 CSRF 令牌;该令牌被放在名为 [csrf_token] 的隐藏字段中。
| {% extends "layout.html" %}
{% block content %}
<h1 class="h3">Contact no. {{ contact.id }}</h1>
<form method="post" action="{{ url_for('contacts.save', id=contact.id) }}">
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
<div class="mb-2">
<label class="form-label" for="name">Name</label>
<input class="form-control" id="name" name="name" value="{{ contact.name }}">
</div>
<div class="mb-3">
<label class="form-label" for="phone">Phone</label>
<input class="form-control" id="phone" name="phone" value="{{ contact.phone }}">
</div>
{# 同一表单的两个提交按钮 #}
<button class="btn btn-primary" type="submit">Save</button>
<button class="btn btn-outline-primary" type="submit"
formaction="{{ url_for('contacts.duplicate', id=contact.id) }}">Duplicate</button>
<a class="btn btn-link" href="{{ url_for('contacts.list_contacts') }}">Back to the list</a>
</form>
{% endblock %}
|
- 第 16–18 行:同一个表单有两个提交按钮:“Save”把表单提交到其 [action] 属性指定的地址,“Duplicate”则把它提交到其 [formaction] 属性指定的地址(示例 20);
- 第 19 行:返回列表:一个链接。
4.9.5. 确认窗口
浏览器可以显示确认框([JavaScript] [confirm] 函数),但它不太美观,而且外观取决于浏览器。这里我们使用 模态窗口 ,来自 [Bootstrap],由几行 [JavaScript] 代码显示。该窗口是包含在布局模板中的片段,因此它存在于所有页面中,只是处于隐藏状态:
| {# 整个页面只有一个窗口,起初是隐藏的(d-none) #}
<div id="confirmation-modal" class="d-none">
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true">
<div class="modal-dialog modal-dialog-centered">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title">Confirmation</h5>
</div>
<div class="modal-body">
<p class="mb-0" id="confirmation-modal-message"></p>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-secondary" data-action="no">No, go back</button>
<button type="button" class="btn btn-danger" data-action="yes">Yes, confirm</button>
</div>
</div>
</div>
</div>
</div>
|
- 第 2 行:来自 [d-none] 类的 [Bootstrap] 会隐藏该元素;
- 第 3–4 行:灰色背景以及随后的窗口,由 [Bootstrap] 的类渲染;
- 第 11 行:消息的位置;
- 第 14–15 行:两个类型为 [button] (而不是 [submit]:它们不提交任何表单)的按钮,通过它们的 [data-action] 属性加以区分。
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Contacts</title>
<link rel="stylesheet" href="{{ url_for('bootstrap.static', filename='css/bootstrap.min.css') }}">
<link rel="stylesheet" href="{{ url_for('static', filename='css/styles.css') }}">
</head>
<body>
<div class="container py-3" style="max-width: 40rem">
{% for message in get_flashed_messages() %}
<div class="alert alert-success" role="status">{{ message }}</div>
{% endfor %}
<main>
{% block content %}{% endblock %}
</main>
</div>
{# 确认窗口,存在于所有页面中 #}
{% include "fragments/confirmation.html" %}
{# 脚本放在页面末尾:它查找的元素此时已经存在 #}
<script src="{{ url_for('static', filename='js/app.js') }}"></script>
</body>
</html>
|
- 第 19 行:窗口,包含在所有页面中;
- 第 21 行:脚本,放在页面末尾:脚本运行时,它要查找的元素已经存在。
[static/js/app.js] 脚本:
| // 对带有 data-confirmation="..." 属性的表单进行确认
// 没有 JavaScript 时,这些表单会直接发送,不经确认。
(() => {
const modal = document.getElementById('confirmation-modal');
const message = document.getElementById('confirmation-modal-message');
let pending = null; // 用户确认后要发送的表单
// 1. 我们拦截需要确认的表单的提交
document.querySelectorAll('form[data-confirmation]').forEach((form) => {
form.addEventListener('submit', (event) => {
event.preventDefault(); // 提交被挂起
pending = form;
message.textContent = form.dataset.confirmation;
modal.classList.remove('d-none'); // 出现窗口
});
});
// 2. 窗口的两个按钮
modal.addEventListener('click', (event) => {
const action = event.target.dataset.action;
if (action === 'yes') {
pending.submit(); // 提交,不再次触发 'submit' 事件
} else if (action === 'no') {
modal.classList.add('d-none');
pending = null;
}
});
})();
|
- 第 3 行:代码被包裹在一个立即执行的匿名函数中;它的变量不会与页面上其他脚本的变量相互干扰;
- 第 4–6 行:窗口、消息位置,以及等待确认的表单;
- 第 9–14 行:对于每个带有 [data-confirmation] 属性的表单,拦截 [submit] 事件——即表单提交时触发的事件。[preventDefault()] 暂停提交;表单被搁置,其消息([dataset.confirmation],即 [data-confirmation] 属性的值)显示在窗口中,窗口随即出现;
- 第 19–25 行:窗口中点击事件的单一处理器:[event.target] 是被点击的元素;它的 [data-action] 属性指明是哪个按钮。“Yes”使用 [submit()] 方法提交待处理的表单,该方法与点击按钮不同,不会触发 [submit] 事件(否则窗口会再次出现);“No”则隐藏窗口。
没有 [JavaScript] 时,表单只是不经确认直接提交:页面仍然可用。这就是渐进增强:[JavaScript] 增添了便利,但应用程序并不依赖它。
4.9.6. 执行
联系人列表:

点击“Delete”会显示确认窗口:

确认之后,POST、重定向和弹出消息:

联系人的资料,带有它的两个发送按钮:

没有防 CSRF 令牌的 POST 请求会被 [CSRFProtect] 拒绝,而不存在的联系人会返回 404 错误:
| curl -i -X POST http://localhost:5000/contacts/2/delete
curl -i http://localhost:5000/contacts/9
|
| HTTP/1.1 400 BAD REQUEST
Content-Type: text/html; charset=utf-8
Content-Length: 117
<!doctype html>
<html lang=en>
<title>400 Bad Request</title>
<h1>Bad Request</h1>
<p>The CSRF token is missing.</p>
HTTP/1.1 404 NOT FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 102
<!doctype html>
<html lang=en>
<title>404 Not Found</title>
<h1>Not Found</h1>
<p>unknown contact</p>
|
错误页面仍然是 [Werkzeug] 自带的英文页面。请求生命周期一章将展示如何用自定义页面替换它们。