Tornado 模板和用户界面

2022-03-08 10:40 更新

Tornado 包含一种简单、快速且灵活的模板语言。本节介绍该语言以及国际化等相关问题。

Tornado 也可以与任何其他 Python 模板语言一起使用，尽管没有将这些系统集成到 RequestHandler.render. 只需将模板呈现为字符串并将其传递给RequestHandler.write

配置模板

默认情况下，Tornado 在与引用它们的 .py 文件相同的目录中查找模板文件。要将您的模板文件放在不同的目录中，请使用 template_path 应用程序设置（或者如果您对不同的处理程序有不同的模板路径，则覆盖 RequestHandler.get_template_path）。

要从非文件系统位置加载模板，子类 tornado.template.BaseLoader传递一个实例作为template_loader应用程序设置。

编译后的模板默认缓存；要关闭此缓存并重新加载模板以对底层文件的更改始终可见，请使用应用程序设置compiled_template_cache=False 或debug=True。

模板语法

Tornado 模板只是 HTML（或任何其他基于文本的格式），在标记中嵌入了 Python 控制序列和表达式：

<html>
   <head>
      <title>{{ title }}</title>
   </head>
   <body>
     <ul>
       {% for item in items %}
         <li>{{ escape(item) }}</li>
       {% end %}
     </ul>
   </body>
 </html>

如果您将此模板保存为“template.html”并将其放在与 Python 文件相同的目录中，您可以使用以下方式渲染此模板：

class MainHandler(tornado.web.RequestHandler):
    def get(self):
        items = ["Item 1", "Item 2", "Item 3"]
        self.render("template.html", title="My title", items=items)

Tornado 模板支持控制语句和表达式。控制语句被 {% 和 %} 包围，例如 {% if len(items) > 2 %}。表达式被 {{ 和 }} 包围，例如 {{ item[0] }}。

控制语句大多数精确地映射到 Python 语句。它支持 if、for、while 和 try，它们都以 {% end %} 结束。它还支持使用 extends 和 block 语句的模板继承，在 tornado.template 的文档中有详细描述。

表达式可以是任何 Python 表达式，包括函数调用。模板代码在包含以下对象和函数的命名空间中执行。（请注意，此列表适用于使用 RequestHandler.render 和 render_string 呈现的模板。如果您直接在 RequestHandler 之外使用 tornado.template 模块，则其中许多条目不存在）。

escape: 别名 tornado.escape.xhtml_escape
xhtml_escape: 别名 tornado.escape.xhtml_escape
url_escape: 别名 tornado.escape.url_escape
json_encode: 别名 tornado.escape.json_encode
squeeze: 别名 tornado.escape.squeeze
linkify: 别名 tornado.escape.linkify
datetime: datetime
handler: RequestHandler
request: 别名 handler.request
current_user: 别名 handler.current_user
locale: 别名 handler.locale
_: 别名 handler.locale.translate
static_url: 别名 handler.static_url
xsrf_form_html: 别名 handler.xsrf_form_html
reverse_url: 别名 Application.reverse_url

当你构建一个真正的应用程序时，你会想要使用 Tornado 模板的所有特性，尤其是模板继承。阅读本节中有关这些功能的所有信息tornado.template （一些功能，包括UIModules在 tornado.web模块中实现）

在底层，Tornado 模板被直接翻译成 Python。您包含在模板中的表达式被逐字复制到代表您的模板的 Python 函数中。它不会试图阻止模板语言中的任何内容；它明确创建它是为了提供其他更严格的模板系统所阻止的灵活性。因此，如果您在模板表达式中编写随机内容，则在执行模板时会出现随机 Python 错误。

默认情况下，使用 tornado.escape.xhtml_escape 函数对所有模板输出进行转义。可以通过将 autoescape=None 传递给 Application 或 tornado.template.Loader 构造函数来全局更改此行为，对于具有 {% autoescape None %} 指令的模板文件，或者通过替换 {{ ... }} 来更改单个表达式使用 {% raw ...%}。此外，在这里的每一个地方，都可以使用替代转义函数的名称来代替 None。

请注意，虽然 Tornado 的自动转义有助于避免 XSS 漏洞，但并非在所有情况下都足够。出现在某些位置的表达式，例如 JavaScript 或 CSS，可能需要额外的转义。此外，必须注意始终在可能包含不受信任的内容的 HTML 属性中使用双引号和 xhtml_escape，或者必须为属性使用单独的转义函数（参见例如此博客文章）。

国际化

当前用户的语言环境（无论他们是否登录）始终在请求处理程序中作为self.locale和在模板中作为locale可用。语言环境的名称（例如 en_US）以 locale.name的形式提供，您可以使用 Locale.translate 方法翻译字符串。模板还具有可用于字符串翻译的全局函数调用 _()。 translate函数有两种形式：

_("Translate this string")

它直接根据当前语言环境翻译字符串，并且：

_("A person liked this", "%(num)d people liked this",
  len(people)) % {"num": len(people)}

它根据第三个参数的值翻译一个可以是单数或复数的字符串。在上面的示例中，如果 len(people) 为 1，则返回第一个字符串的翻译，否则返回第二个字符串的翻译。

最常见的翻译模式是对变量使用 Python 命名的占位符（上例中的 %(num)d），因为占位符可以在翻译时移动。

以下是一个正确国际化的模板:

<html>
   <head>
      <title>FriendFeed - {{ _("Sign in") }}</title>
   </head>
   <body>
     <form action="{{ request.path }}" method="post">
       <div>{{ _("Username") }} <input type="text" name="username"/></div>
       <div>{{ _("Password") }} <input type="password" name="password"/></div>
       <div><input type="submit" value="{{ _("Sign in") }}"/></div>
       {% module xsrf_form_html() %}
     </form>
   </body>
 </html>

默认情况下，我们使用用户浏览器发送的 Accept-Language 表头检测用户的语言环境。如果找不到合适的 Accept-Language 值，我们选择 en_US。如果您让用户将其区域设置为首选项，则可以通过覆盖 RequestHandler.get_user_locale 来覆盖此默认区域选择：

class BaseHandler(tornado.web.RequestHandler):
    def get_current_user(self):
        user_id = self.get_secure_cookie("user")
        if not user_id: return None
        return self.backend.get_user_by_id(user_id)

    def get_user_locale(self):
        if "locale" not in self.current_user.prefs:
            # Use the Accept-Language header
            return None
        return self.current_user.prefs["locale"]

如果 get_user_locale 返回 None，我们将使用 Accept-Language 表头。

tornado.locale 模块支持以两种格式加载翻译：gettext 和相关工具使用的 .mo 格式，以及简单的 .csv 格式。应用程序通常会在启动时调用一次 tornado.locale.load_translations 或 tornado.locale.load_gettext_translations

您可以使用 tornado.locale.get_supported_locales() 获取应用程序中支持的语言环境列表。根据支持的语言环境，用户的语言环境被选择为最接近的匹配。例如，如果用户的语言环境是 es_GT，并且支持 es 语言环境，那么对于该请求，self.locale 将是 es。如果找不到匹配项，我们将使用 en_US。

用户界面模块

Tornado 支持 UI 模块，以便在您的应用程序中轻松支持标准的、可重用的 UI 小部件。 UI 模块就像渲染页面组件的特殊函数调用，它们可以使用自己的 CSS 和 JavaScript 打包。

例如，如果你正在实现一个博客，并且你想让博客条目出现在博客主页和每个博客条目页面上，你可以制作一个Entry模块来在两个页面上呈现它们。首先，为您的 UI 模块创建一个 Python 模块，例如 uimodules.py：

class Entry(tornado.web.UIModule):
    def render(self, entry, show_comments=False):
        return self.render_string(
            "module-entry.html", entry=entry, show_comments=show_comments)

使用应用程序中的 ui_modules 设置告诉 Tornado 使用 uimodules.py：

from . import uimodules

class HomeHandler(tornado.web.RequestHandler):
    def get(self):
        entries = self.db.query("SELECT * FROM entries ORDER BY date DESC")
        self.render("home.html", entries=entries)

class EntryHandler(tornado.web.RequestHandler):
    def get(self, entry_id):
        entry = self.db.get("SELECT * FROM entries WHERE id = %s", entry_id)
        if not entry: raise tornado.web.HTTPError(404)
        self.render("entry.html", entry=entry)

settings = {
    "ui_modules": uimodules,
}
application = tornado.web.Application([
    (r"/", HomeHandler),
    (r"/entry/([0-9]+)", EntryHandler),
], **settings)

在模板中，您可以使用 {% module %} 语句调用模块。例如，您可以从 home.html 中调用 Entry 模块：

{% for entry in entries %}
  {% module Entry(entry) %}
{% end %}

entry.html:

{% module Entry(entry, show_comments=True) %}

模块可以通过覆盖 embedded_css、embedded_javascript、javascript_files 或 css_files 方法来包含自定义 CSS 和 JavaScript 函数：

class Entry(tornado.web.UIModule):
    def embedded_css(self):
        return ".entry { margin-bottom: 1em; }"

    def render(self, entry, show_comments=False):
        return self.render_string(
            "module-entry.html", show_comments=show_comments)

无论模块在页面上使用多少次，模块 CSS 和 JavaScript 都会被包含一次。 CSS 总是包含在页面的 <head> 中，而 JavaScript 总是包含在页面末尾的 </body> 标记之前。

当不需要额外的 Python 代码时，可以将模板文件本身用作模块。例如，可以重写前面的示例以将以下内容放入 module-entry.html 中：

{{ set_resources(embedded_css=".entry { margin-bottom: 1em; }") }}
<!-- more template html... -->

这个修改后的模板模块将被调用：

{% module Template("module-entry.html", show_comments=True) %}

set_resources 函数仅在通过 {% module Template(...) %} 调用的模板中可用。与 {% include ... %} 指令不同，模板模块具有与其包含模板不同的命名空间——它们只能看到全局模板命名空间和它们自己的关键字参数。

以上内容是否对您有帮助：

Tornado 模板和用户界面

配置模板

模板语法

国际化

用户界面模块

推荐文章

推荐教程

推荐课程