翻譯者說

Tornado 4.3 于2015年11月6日發(fā)布，該版本正式支持Python3.5的async/await關(guān)鍵字，使用舊版本編譯Tornado時也可以使用這兩個關(guān)鍵字CPython。這無疑是一種進(jìn)步。其次，這是*后一個支持 Python2.6 和 Python3.2 的版本，后續(xù)版本中會移除與它們的兼容性。網(wǎng)上沒有Tornado4.3的中文文檔，為了讓更多的朋友接觸和學(xué)習(xí)，我開始了這個翻譯項目。希望有興趣的朋友可以一起參與翻譯。項目地址在Github上是tornado-zh，翻譯后的文檔可以直接在Read the Docs上查看。歡迎使用問題或 PR。

模板和用戶界面

Tornado 包含一種簡單、快速且靈活的模板語言。本節(jié)介紹語言和相關(guān)問題，例如國際化。

Tornado 也可以使用其他 Python 模板語言，盡管沒有計劃將這些系統(tǒng)集成到 RequestHandler.render 中。相反，它只是將模板轉(zhuǎn)換為字符串并將其傳遞給 RequestHandler.write

配置模板

默認(rèn)情況下，Tornado 會在與當(dāng)前 .py 文件相同的目錄中找到關(guān)聯(lián)的模板文件。如果你想把你的模板文件放在不同的目錄下，你可以使用template_path（或者如果你有不同的處理函數(shù)，則覆蓋RequestHandler.get_template_path 有不同的模板路徑）。

要從非文件系統(tǒng)位置加載模板，請實例化子類 tornado.template.BaseLoader 并在應(yīng)用程序設(shè)置中配置 template_loader。

默認(rèn)情況下，編譯后的模板會被緩存；為了關(guān)閉此緩存并使更改（對目標(biāo)）在重新加載后始終可見，請在應(yīng)用程序設(shè)置中使用compiled_template_cache=False 或debug=True。

模板語法

Tornado 模板只是將 Python 控制序列和表達(dá)式嵌入 HTML（或任何其他文本格式）文件中，并帶有一些標(biāo)記：

    
       
          
       
       
         

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

如果將此目標(biāo)另存為“template.html”并將其放在與 Python 文件相同的目錄中，則可以使用以下代碼呈現(xiàn)它：

    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 模板支持控制語句和表達(dá)式。控制語句包含在 (% 和 %) 中，例如 (% if len(items)> 2 %)。表達(dá)式包含在 (( 和 }} 中，例如，{{ items[0] }}。

控制語句或多或少類似于 Python 語句。我們支持 if、for、while 和 try不包含模板的翻譯，它們必須標(biāo)有 {% end %}。我們也支持使用extends和block標(biāo)簽的模板繼承免責(zé)聲明，這些內(nèi)容的詳細(xì)信息可以在tornado.template中看到。

表達(dá)式可以是任何 Python 表達(dá)式，包括函數(shù)調(diào)用。模板代碼將在包含以下對象和函數(shù)的命名空間中執(zhí)行（注意此列表適用于使用 RequestHandler.render

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

當(dāng)您構(gòu)建一個真正的應(yīng)用程序時，您可能希望使用 Tornado 模板的所有功能，尤其是目標(biāo)繼承。在 tornado.template 部分閱讀有關(guān)這些功能的所有信息（一些功能，包括 UIModules，在 tornado.web 模塊中已實現(xiàn)）

在引擎下，Tornado 模板直接轉(zhuǎn)換為 Python。模板中包含的表達(dá)式將被逐字復(fù)制到表示模板的 Python 函數(shù)中。我們不會試圖阻止模板語言中的任何內(nèi)容；我們很清楚創(chuàng)建一個高度靈活的模板系統(tǒng)，而??不是一個嚴(yán)格限制的模板系統(tǒng)。因此，如果隨意在模板表達(dá)式中填充（代碼），執(zhí)行時也會出現(xiàn)各種隨機錯誤。

默認(rèn)情況下，所有模板輸出都會被 tornado.escape.xhtml_escape 函數(shù)轉(zhuǎn)義。通過將 autoescape=None 傳遞給 Application 或 tornado.template.Loader 構(gòu)造函數(shù)，可以全局更改此行為。對于模板文件，可以使用 {% autoescape None %} 命令，對于單個表達(dá)式，可以使用 {% raw ...%} 代替 {{ ... }}。此外，每個地方都可以使用可選的轉(zhuǎn)義函數(shù)名稱代替 None 。

請注意，雖然 Tornado 的自動轉(zhuǎn)義有助于防止 XSS 漏洞，但它并不適用于所有情況。出現(xiàn)在特定位置的表達(dá)式，例如 Javascript 或 CSS，可能需要額外的轉(zhuǎn)義。此外，您必須小心在可能包含不受信任內(nèi)容的 HTML 中始終使用雙引號和 xhtml_escape，或者您必須在屬性中使用單獨的轉(zhuǎn)義函數(shù)（參見例如）

全球化

當(dāng)前用戶的語言環(huán)境（無論他們是否登錄）始終可以通過在請求處理程序中使用 self.locale 或在模板中使用語言環(huán)境來訪問。語言環(huán)境的名稱（例如，en_US）可以通過locale.name 獲得，你可以通過Locale.translate 方法翻譯字符串。該模板還有一個名為 _() 的全局函數(shù)，用于字符串翻譯。翻譯函數(shù)有兩種形式：

_("Translate this string")

它是根據(jù)當(dāng)前的區(qū)域設(shè)置直接翻譯的，并且：

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

可以根據(jù)第三個參數(shù)的值翻譯字符串單數(shù)和復(fù)數(shù)。在上面的例子中，如果 len(people) 為 1，則返回第一句的翻譯，否則返回第二句的翻譯。

*常見的翻譯模式四使用 Python 來命名占位符變量（上例中的 %(num)d），因為占位符在翻譯過程中可能會發(fā)生變化。

這是一個正確的國際化模板：

    
       
          
       
       
         

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

           {% module xsrf_form_html() %}
         
       
     

默認(rèn)情況下不包含模板的翻譯，我們使用用戶瀏覽器發(fā)送的 Accept-Language 標(biāo)頭來發(fā)現(xiàn)用戶的語言環(huán)境。如果我們沒有找到合適的 Accept-Language 值，我們將使用 en_US。如果您讓用戶設(shè)置他們的首選語言環(huán)境，您可以通過覆蓋 RequestHandler.get_user_locale 來覆蓋默認(rèn)選定的語言環(huán)境：

    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，那么我們（繼續(xù)）依靠 Accept-Language 標(biāo)頭（做出判斷）。

tornado.locale 模塊支持兩種形式的加載翻譯：一種是使用 gettext 和相關(guān)工具的 .mo 格式，另一種是簡單的 .csv 格式。應(yīng)用程序通常調(diào)用 tornado.locale.load_translations 或 tornado.locale.load_gettext_translations 其中之一；檢查這些方法以獲取有關(guān)支持格式的更多詳細(xì)信息。

您可以使用 tornado.locale.get_supported_locales() 來獲取您的應(yīng)用程序支持的語言環(huán)境（設(shè)置）列表。通過從支持的語言環(huán)境中選擇*接近的匹配來獲得用戶的語言環(huán)境。比如用戶的locale是es_GT，同時支持es區(qū)域，請求中的self.locale會設(shè)置為es。如果未找到*接近的匹配項，我們將使用 en_US。

用戶界面模塊

Tornado 支持 UI 模塊，以便在您的應(yīng)用程序中輕松支持標(biāo)準(zhǔn)和重用 UI 組件。UI 模塊就像在頁面上渲染組件的特殊函數(shù)調(diào)用，它們可以包裝自己的 CSS 和 JavaScript。

例如，如果您實現(xiàn)了一個博客，并且您希望一個博客條目出現(xiàn)在主頁和每個博客頁面上，您可以實現(xiàn)一個 Entry 模塊來在這些頁面上呈現(xiàn)它們。首先，為您的 UI 模塊創(chuàng)建一個 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)

在您的應(yīng)用程序設(shè)置中，使用 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 %} 語法調(diào)用模塊。例如，您可以從 home.html 調(diào)用 Entry 模塊：

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

和 entry.html：

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

模塊可以包含自定義 CSS 和 JavaScript 函數(shù)，方法是覆蓋 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 始終包含在頁面的標(biāo)簽中，而 JavaScript 始終包含在頁面底部的標(biāo)簽之前。

當(dāng)不需要額外的 Python 代碼時，模板文件本身可以用作模塊。例如，可以將前面的示例重寫為以下 module-entry.html：

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

這個修改后的模塊模塊可以參考：

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

set_resources 函數(shù)只能通過 {% module Template(...) %} 在模板中使用。與 {% include ... %} 指令不同，模板模塊對于它們的包含模板有一個明確的命名空間——它們只能看到全局模板命名空間和它們自己的關(guān)鍵字參數(shù)。