不包含模板的翻译 Tornado 4.3 文档翻译: 用户指南-模板和UI

翻译者说

Tornado 4.3 于2015年11月6日发布，该版本正式支持Python3.5的async/await关键字，使用旧版本编译Tornado时也可以使用这两个关键字CPython。这无疑是一种进步。其次，这是*后一个支持 Python2.6 和 Python3.2 的版本，后续版本中会移除与它们的兼容性。网上没有Tornado4.3的中文文档，为了让更多的朋友接触和学习，我开始了这个翻译项目。希望有兴趣的朋友可以一起参与翻译。项目地址在Github上是tornado-zh，翻译后的文档可以直接在Read the Docs上查看。欢迎使用问题或 PR。

模板和用户界面

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 模板只是将 Python 控制序列和表达式嵌入 HTML（或任何其他文本格式）文件中，并带有一些标记：

    
       
          
       
       
         

           {% for item in items %}
             
{{ escape(item) }}
           {% end %}
         
       
     

如果将此目标另存为“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 %)。表达式包含在 (( 和 }} 中，例如，{{ items[0] }}。

控制语句或多或少类似于 Python 语句。我们支持 if、for、while 和 try不包含模板的翻译，它们必须标有 {% end %}。我们也支持使用extends和block标签的模板继承免责声明，这些内容的详细信息可以在tornado.template中看到。

表达式可以是任何 Python 表达式，包括函数调用。模板代码将在包含以下对象和函数的命名空间中执行（注意此列表适用于使用 RequestHandler.render

和 RequestHandler.render_string 渲染模板。如果直接在 RequestHandler 之外使用 tornado.template 模块，则以下许多不存在）。

当您构建一个真正的应用程序时，您可能希望使用 Tornado 模板的所有功能，尤其是目标继承。在 tornado.template 部分阅读有关这些功能的所有信息（一些功能，包括 UIModules，在 tornado.web 模块中已实现）

在引擎下，Tornado 模板直接转换为 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 或在模板中使用语言环境来访问。语言环境的名称（例如，en_US）可以通过locale.name 获得，你可以通过Locale.translate 方法翻译字符串。该模板还有一个名为 _() 的全局函数，用于字符串翻译。翻译函数有两种形式：

_("Translate this string")

它是根据当前的区域设置直接翻译的，并且：

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

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

*常见的翻译模式四使用 Python 来命名占位符变量（上例中的 %(num)d），因为占位符在翻译过程中可能会发生变化。

这是一个正确的国际化模板：

    
       
          
       
       
         

           
{{ _("Username") }} 
           
{{ _("Password") }} 
           

           {% module xsrf_form_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() 来获取您的应用程序支持的语言环境（设置）列表。通过从支持的语言环境中选择*接近的匹配来获得用户的语言环境。比如用户的locale是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) %}

模块可以包含自定义 CSS 和 JavaScript 函数，方法是覆盖 embedding_css、embedded_javascript、javascript_files 或 css_files 方法：

    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 始终包含在页面的标签中，而 JavaScript 始终包含在页面底部的标签之前。

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

    {{ set_resources(embedded_css=".entry { margin-bottom: 1em; }") }}
    

这个修改后的模块模块可以参考：

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

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