Jade 文檔 · Express.js 中文文檔

# Jade 文檔 Jade 是一個高性能的模板引擎，它深受[Haml](http://haml-lang.com)影響，它是用javascript實現的,并且可以供[node](http://nodejs.org)使用. 翻譯:[草依山](http://jser.me) ? [翻譯反饋](http://weibo.com/1826461472/z9jriDdmB#pl_profile_nav) ?[Fork me](https://github.com/jserme/jade/) ## 特性 * 客戶端支持 * 代碼高可讀 * 靈活的縮進 * 塊展開 * 混合 * 靜態包含 * 屬性改寫 * 安全，默認代碼是轉義的 * 運行時和編譯時上下文錯誤報告 * 命令行下編譯jade模板 * html 5 模式 (使用 _!!! 5_ 文檔類型) * 在內存中緩存(可選) * 合并動態和靜態標簽類 * 可以通過 _filters_ 修改樹 * 模板繼承 * 原生支持 [Express JS](http://expressjs.com) * 通過 `each` 枚舉對象、數組甚至是不能枚舉的對象 * 塊注釋 * 沒有前綴的標簽 * AST filters * 過濾器 * :sass 必須已經安裝[sass.js](http://github.com/visionmedia/sass.js) * :less 必須已經安裝[less.js](http://github.com/cloudhead/less.js) * :markdown 必須已經安裝[markdown-js](http://github.com/evilstreak/markdown-js) 或者[node-discount](http://github.com/visionmedia/node-discount) * :cdata * :coffeescript 必須已經安裝[coffee-script](http://jashkenas.github.com/coffee-script/) * [Vim Syntax](https://github.com/digitaltoad/vim-jade) * [TextMate Bundle](http://github.com/miksago/jade-tmbundle) * [Screencasts](http://tjholowaychuk.com/post/1004255394/jade-screencast-template-engine-for-nodejs) * [html2jade](https://github.com/donpark/html2jade) 轉換器 ## 其它實現 * [php](http://github.com/everzet/jade.php) * [scala](http://scalate.fusesource.org/versions/snapshot/documentation/scaml-reference.html) * [ruby](http://github.com/stonean/slim) ## 安裝通過 npm: ``` npm install jade ``` ## 瀏覽器支持把jade編譯為一個可供瀏覽器使用的單文件，只需要簡單的執行: ``` $ make jade.js ``` 如果你已經安裝了uglifyjs (`npm install uglify-js`)，你可以執行下面的命令它會生成所有的文件。其實每一個正式版本里都幫你做了這事。 ``` $ make jade.min.js ``` 默認情況下，為了方便調試Jade會把模板組織成帶有形如 `__.lineno = 3` 的行號的形式。在瀏覽器里使用的時候，你可以通過傳遞一個選項`{ compileDebug: false }`來去掉這個。下面的模板 ``` p Hello #{name} ``` 會被翻譯成下面的函數： ``` function anonymous(locals, attrs, escape, rethrow) { var buf = []; with (locals || {}) { var interp; buf.push('\n<p>Hello ' + escape((interp = name) == null ? '' : interp) + '\n</p>'); } return buf.join(""); } ``` 通過使用Jade的 `./runtime.js`你可以在瀏覽器使用這些預編譯的模板而不需要使用Jade, 你只需要使用runtime.js里的工具函數, 它們會放在`jade.attrs`, `jade.escape` 這些里。把選項 `{ client: true }` 傳遞給 `jade.compile()`, Jade 會把這些幫助函數的引用放在`jade.attrs`, `jade.escape`. ``` function anonymous(locals, attrs, escape, rethrow) { var attrs = jade.attrs, escape = jade.escape, rethrow = jade.rethrow; var buf = []; with (locals || {}) { var interp; buf.push('\n<p>Hello ' + escape((interp = name) == null ? '' : interp) + '\n</p>'); } return buf.join(""); } ``` ## 公開API ``` var jade = require('jade'); // Compile a function var fn = jade.compile('string of jade', options); fn(locals); ``` ### 選項 * `self` 使用`self` 命名空間來持有本地變量. _默認為false_ * `locals` 本地變量對象 * `filename` 異常發生時使用，includes時必需 * `debug` 輸出token和翻譯后的函數體 * `compiler` 替換掉jade默認的編譯器 * `compileDebug` `false`的時候調試的結構不會被輸出 ## 語法 ### 行結束標志 **CRLF** 和 **CR** 會在編譯之前被轉換為 **LF** ### 標簽標簽就是一個簡單的單詞: ``` html ``` 它會被轉換為 `<html></html>` 標簽也是可以有id的: ``` div#container ``` 它會被轉換為 `<div id="container"></div>` 怎么加類呢？ ``` div.user-details ``` 轉換為 `<div class="user-details"></div>` 多個類? 和id? 也是可以搞定的: ``` div#foo.bar.baz ``` 轉換為 `<div id="foo" class="bar baz"></div>` 不停的div div div 很討厭啊 , 可以這樣: ``` #foo .bar ``` 這個算是我們的語法糖，它已經被很好的支持了，上面的會輸出： ``` `<div id="foo"></div><div class="bar"></div>` ``` ### 標簽文本只需要簡單的把內容放在標簽之后： ``` p wahoo! ``` 它會被渲染為 `<p>wahoo!</p>`. 很帥吧，但是大段的文本怎么辦呢： ``` p | foo bar baz | rawr rawr | super cool | go jade go ``` 渲染為 `<p>foo bar baz rawr.....</p>` 怎么和數據結合起來？所有類型的文本展示都可以和數據結合起來，如果我們把`{ name: 'tj', email: 'tj@vision-media.ca' }` 傳給編譯函數，下面是模板上的寫法: ``` #user #{name} <#{email}> ``` 它會被渲染為 `<div id="user">tj <tj@vision-media.ca></div>` 當就是要輸出`#{}` 的時候怎么辦? 轉義一下! ``` p \#{something} ``` 它會輸出`<p>#{something}</p>` 同樣可以使用非轉義的變量`!{html}`, 下面的模板將直接輸出一個script標簽 ``` - var html = "<script></script>" | !{html} ``` 內聯標簽同樣可以使用文本塊來包含文本： ``` label | Username: input(name='user[name]') ``` 或者直接使用標簽文本: ``` label Username: input(name='user[name]') ``` _只_包含文本的標簽，比如`script`, `style`, 和 `textarea` 不需要前綴`|` 字符, 比如: ``` html head title Example script if (foo) { bar(); } else { baz(); } ``` 這里還有一種選擇，可以使用'.' 來開始一段文本塊，比如： ``` p. foo asdf asdf asdfasdfaf asdf asd. ``` 會被渲染為: ``` <p>foo asdf asdf asdfasdfaf asdf asd . </p> ``` 這和帶一個空格的 '.' 是不一樣的, 帶空格的會被Jade的解析器忽略，當作一個普通的文字: ``` p . ``` 渲染為: ``` <p>.</p> ``` 需要注意的是廣西塊需要兩次轉義。比如想要輸出下面的文本： ``` </p>foo\bar</p> ``` 使用: ``` p. foo\\bar ``` ### 注釋單行注釋和JavaScript里是一樣的，通過"//"來開始，并且必須單獨一行： ``` // just some paragraphs p foo p bar ``` 渲染為： ```  <p>foo</p> <p>bar</p> ``` Jade 同樣支持不輸出的注釋，加一個短橫線就行了： ``` //- will not output within markup p foo p bar ``` 渲染為： ``` <p>foo</p> <p>bar</p> ``` ### 塊注釋塊注釋也是支持的： ``` body // #content h1 Example ``` 渲染為： ``` <body>  </body> ``` Jade 同樣很好的支持了條件注釋： ``` body //if IE a(href='http://www.mozilla.com/en-US/firefox/') Get Firefox ``` 渲染為： ### 內聯 Jade 支持以自然的方式定義標簽嵌套: ``` ul li.first a(href='#') foo li a(href='#') bar li.last a(href='#') baz ``` ### 塊展開塊展開可以幫助你在一行內創建嵌套的標簽，下面的例子和上面的是一樣的： ``` ul li.first: a(href='#') foo li: a(href='#') bar li.last: a(href='#') baz ``` ### 屬性 Jade 現在支持使用'(' 和 ')' 作為屬性分隔符 ``` a(href='/login', title='View login page') Login ``` 當一個值是 `undefined` 或者 `null` 屬性_不_會被加上, 所以呢，它不會編譯出 'something="null"'. ``` div(something=null) ``` Boolean 屬性也是支持的: ``` input(type="checkbox", checked) ``` 使用代碼的Boolean 屬性只有當屬性為`true`時才會輸出： ``` input(type="checkbox", checked=someValue) ``` 多行同樣也是可用的： ``` input(type='checkbox', name='agreement', checked) ``` 多行的時候可以不加逗號： ``` input(type='checkbox' name='agreement' checked) ``` 加點空格，格式好看一點？同樣支持 ``` input( type='checkbox' name='agreement' checked) ``` 冒號也是支持的: ``` rss(xmlns:atom="atom") ``` 假如我有一個`user` 對象 `{ id: 12, name: 'tobi' }` 我們希望創建一個指向"/user/12"的鏈接 `href`, 我們可以使用普通的javascript字符串連接，如下: ``` a(href='/user/' + user.id)= user.name ``` 或者我們使用jade的修改方式,這個我想很多使用Ruby或者 CoffeeScript的人會看起來像普通的js..: a(href='/user/#{user.id}')= user.name `class`屬性是一個特殊的屬性，你可以直接傳遞一個數組，比如`bodyClasses = ['user', 'authenticated']` : ``` body(class=bodyClasses) ``` ### HTML 內聯的html是可以的，我們可以使用管道定義一段文本 : ``` html body | <h1>Title</h1> | <p>foo bar baz</p> ``` 或者我們可以使用`.` 來告訴Jade我們需要一段文本： ``` html body. <h1>Title</h1> <p>foo bar baz</p> ``` 上面的兩個例子都會渲染成相同的結果： ``` <html><body><h1>Title</h1> <p>foo bar baz</p> </body></html> ``` 這條規則適應于在jade里的任何文本： ``` html body h1 User <em>#{name}</em> ``` ### Doctypes 添加文檔類型只需要簡單的使用 `!!!`, 或者 `doctype` 跟上下面的可選項: ``` !!! ``` 會渲染出 _transitional_ 文檔類型, 或者: ``` !!! 5 ``` or ``` !!! html ``` or ``` doctype html ``` doctypes 是大小寫不敏感的, 所以下面兩個是一樣的: ``` doctype Basic doctype basic ``` 當然也是可以直接傳遞一段文檔類型的文本： ``` doctype html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN ``` 渲染后: ``` <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN> ``` 會輸出 _html 5_ 文檔類型. 下面的默認的文檔類型，可以很簡單的擴展： ``` var doctypes = exports.doctypes = { '5': '<!DOCTYPE html>', 'xml': '<?xml version="1.0" encoding="utf-8" ?>', 'default': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">', 'transitional': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">', 'strict': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">', 'frameset': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">', '1.1': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">', 'basic': '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd">', 'mobile': '<!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.2//EN" "http://www.openmobilealliance.org/tech/DTD/xhtml-mobile12.dtd">' }; ``` 通過下面的代碼可以很簡單的改變默認的文檔類型： ``` jade.doctypes.default = 'whatever you want'; ``` ## 過濾器過濾器前綴 `:`, 比如 `:markdown` 會把下面塊里的文本交給專門的函數進行處理。查看頂部 _特性_ 里有哪些可用的過濾器。 ``` body :markdown Woah! jade _and_ markdown, very **cool** we can even link to [stuff](http://google.com) ``` 渲染為: ``` <body><p>Woah! jade <em>and</em> markdown, very <strong>cool</strong> we can even link to <a href="http://google.com">stuff</a></p></body> ``` ## 代碼 Jade目前支持三種類型的可執行代碼。第一種是前綴`-`，這是不會被輸出的： ``` - var foo = 'bar'; ``` 這可以用在條件語句或者循環中： ``` - for (var key in obj) p= obj[key] ``` 由于Jade的緩存技術，下面的代碼也是可以的： ``` - if (foo) ul li yay li foo li worked - else p oh no! didnt work ``` 哈哈，甚至是很長的循環也是可以的： ``` - if (items.length) ul - items.forEach(function(item){ li= item - }) ``` 所以你想要的！下一步我們要_轉義_輸出的代碼，比如我們返回一個值，只要前綴一個`=`： ``` - var foo = 'bar' = foo h1= foo ``` 它會渲染為`bar<h1>bar</h1>`. 為了安全起見，使用`=`輸出的代碼默認是轉義的,如果想直接輸出不轉義的值可以使用`!=`： ``` p!= aVarContainingMoreHTML ``` Jade 同樣是設計師友好的，它可以使javascript更直接更富表現力。比如下面的賦值語句是相等的，同時表達式還是通常的javascript： ``` - var foo = 'foo ' + 'bar' foo = 'foo ' + 'bar' ``` Jade會把 `if`, `else if`, `else`, `until`, `while`, `unless`同別的優先對待, 但是你得記住它們還是普通的javascript： ``` if foo == 'bar' ul li yay li foo li worked else p oh no! didnt work ``` ## 循環盡管已經支持JavaScript原生代碼，Jade還是支持了一些特殊的標簽，它們可以讓模板更加易于理解，其中之一就是`each`, 這種形式： ``` each VAL[, KEY] in OBJ ``` 一個遍歷數組的例子： ``` - var items = ["one", "two", "three"] each item in items li= item ``` 渲染為: ``` <li>one</li> <li>two</li> <li>three</li> ``` 遍歷一個數組同時帶上索引： ``` items = ["one", "two", "three"] each item, i in items li #{item}: #{i} ``` 渲染為: ``` <li>one: 0</li> <li>two: 1</li> <li>three: 2</li> ``` 遍歷一個數組的鍵值： ``` obj = { foo: 'bar' } each val, key in obj li #{key}: #{val} ``` 將會渲染為：`<li>foo: bar</li>` Jade在內部會把這些語句轉換成原生的JavaScript語句，就像使用 `users.forEach(function(user){`, 詞法作用域和嵌套會像在普通的JavaScript中一樣： ``` each user in users each role in user.roles li= role ``` 如果你喜歡，也可以使用`for` ： ``` for user in users for role in user.roles li= role ``` ## 條件語句 Jade 條件語句和使用了(`-`) 前綴的JavaScript語句是一致的,然后它允許你不使用圓括號，這樣會看上去對設計師更友好一點，同時要在心里記住這個表達式渲染出的是_常規_Javascript： ``` for user in users if user.role == 'admin' p #{user.name} is an admin else p= user.name ``` 和下面的使用了常規JavaScript的代碼是相等的： ``` for user in users - if (user.role == 'admin') p #{user.name} is an admin - else p= user.name ``` Jade 同時支持`unless`, 這和`if (!(expr))`是等價的： ``` for user in users unless user.isAnonymous p | Click to view a(href='/users/' + user.id)= user.name ``` ## 模板繼承 Jade 支持通過 `block` 和 `extends` 關鍵字來實現模板繼承。一個塊就是一個Jade的"block" ，它將在子模板中實現，同時是支持遞歸的。 Jade 塊如果沒有內容，Jade會添加默認內容，下面的代碼默認會輸出`block scripts`, `block content`, 和 `block foot`. ``` html head h1 My Site - #{title} block scripts script(src='/jquery.js') body block content block foot #footer p some footer content ``` 現在我們來繼承這個布局，簡單創建一個新文件，像下面那樣直接使用`extends`，給定路徑（可以選擇帶.jade擴展名或者不帶）. 你可以定義一個或者更多的塊來覆蓋父級塊內容, 注意到這里的`foot`塊_沒有_定義，所以它還會輸出父級的"some footer content"。 ``` extends extend-layout block scripts script(src='/jquery.js') script(src='/pets.js') block content h1= title each pet in pets include pet ``` 同樣可以在一個子塊里添加塊，就像下面實現的塊`content`里又定義了兩個可以被實現的塊`sidebar`和`primary`，或者子模板直接實現`content`。 ``` extends regular-layout block content .sidebar block sidebar p nothing .primary block primary p nothing ``` ## 包含 Includes 允許你靜態包含一段Jade, 或者別的存放在單個文件中的東西比如css, html。非常常見的例子是包含頭部和頁腳。假設我們有一個下面目錄結構的文件夾： ``` ./layout.jade ./includes/ ./head.jade ./tail.jade ``` 下面是 _layout.jade_ 的內容: ``` html include includes/head body h1 My Site p Welcome to my super amazing site. include includes/foot ``` 這兩個包含 _includes/head_ 和 _includes/foot_ 都會讀取相對于給 _layout.jade_ 參數`filename` 的路徑的文件, 這是一個絕對路徑，不用擔心Express幫你搞定這些了。Include 會解析這些文件，并且插入到已經生成的語法樹中，然后渲染為你期待的內容： ``` <html> <head> <title>My Site</title> <script src="/javascripts/jquery.js"> </script><script src="/javascripts/app.js"></script> </head> <body> <h1>My Site</h1> <p>Welcome to my super lame site.</p> <div id="footer"> <p>Copyright>(c) foobar</p> </div> </body> </html> ``` 前面已經提到，`include` 可以包含比如html或者css這樣的內容。給定一個擴展名后，Jade不會把這個文件當作一個Jade源代碼，并且會把它當作一個普通文本包含進來： ``` html body include content.html ``` Include 也可以接受塊內容，給定的塊將會附加到包含文件 _最后_ 的塊里。舉個例子，`head.jade` 包含下面的內容： ``` head script(src='/jquery.js') ``` 我們可以像下面給`include head`添加內容, 這里是添加兩個腳本. ``` html include head script(src='/foo.js') script(src='/bar.js') body h1 test ``` ## Mixins Mixins在編譯的模板里會被Jade轉換為普通的JavaScript函數。 Mixins 可以還參數，但不是必需的： ``` mixin list ul li foo li bar li baz ``` 使用不帶參數的mixin看上去非常簡單，在一個塊外： ``` h2 Groceries mixin list ``` Mixins 也可以帶一個或者多個參數，參數就是普通的javascripts表達式，比如下面的例子： ``` mixin pets(pets) ul.pets - each pet in pets li= pet mixin profile(user) .user h2= user.name mixin pets(user.pets) ``` 會輸出像下面的html： ``` <div class="user"> <h2>tj</h2> <ul class="pets"> <li>tobi</li> <li>loki</li> <li>jane</li> <li>manny</li> </ul> </div> ``` ## 產生輸出假設我們有下面的Jade源碼： ``` - var title = 'yay' h1.title #{title} p Just an example ``` 當 `compileDebug` 選項不是`false`, Jade 會編譯時會把函數里加上 `__.lineno = n;`, 這個參數會在編譯出錯時傳遞給`rethrow()`, 而這個函數會在Jade初始輸出時給出一個有用的錯誤信息。 ``` function anonymous(locals) { var __ = { lineno: 1, input: "- var title = 'yay'\nh1.title #{title}\np Just an example", filename: "testing/test.js" }; var rethrow = jade.rethrow; try { var attrs = jade.attrs, escape = jade.escape; var buf = []; with (locals || {}) { var interp; __.lineno = 1; var title = 'yay' __.lineno = 2; buf.push('<h1'); buf.push(attrs({ "class": ('title') })); buf.push('>'); buf.push('' + escape((interp = title) == null ? '' : interp) + ''); buf.push('</h1>'); __.lineno = 3; buf.push('<p>'); buf.push('Just an example'); buf.push('</p>'); } return buf.join(""); } catch (err) { rethrow(err, __.input, __.filename, __.lineno); } } ``` 當`compileDebug` 參數是`false`, 這個參數會被去掉，這樣對于輕量級的瀏覽器端模板是非常有用的。結合Jade的參數和當前源碼庫里的 `./runtime.js` 文件，你可以通過toString()來編譯模板而不需要在瀏覽器端運行整個Jade庫，這樣可以提高性能，也可以減少載入的JavaScript數量。 ``` function anonymous(locals) { var attrs = jade.attrs, escape = jade.escape; var buf = []; with (locals || {}) { var interp; var title = 'yay' buf.push('<h1'); buf.push(attrs({ "class": ('title') })); buf.push('>'); buf.push('' + escape((interp = title) == null ? '' : interp) + ''); buf.push('</h1>'); buf.push('<p>'); buf.push('Just an example'); buf.push('</p>'); } return buf.join(""); } ``` ## Makefile的一個例子通過執行`make`，下面的Makefile例子可以把 _pages/*.jade_ 編譯為 _pages/*.html_ 。 ``` JADE = $(shell find pages/*.jade) HTML = $(JADE:.jade=.html) all: $(HTML) %.html: %.jade jade < $< --path $< > $@ clean: rm -f $(HTML) .PHONY: clean ``` 這個可以和`watch(1)` 命令起來產生像下面的行為： ``` $ watch make ``` ## 命令行的jade(1) ``` 使用: jade [options] [dir|file ...] 選項: -h, --help 輸出幫助信息 -v, --version 輸出版本號 -o, --obj <str> javascript選項 -O, --out <dir> 輸出編譯后的html到<dir> -p, --path <path> 在處理stdio時，查找包含文件時的查找路徑 Examples: # 編譯整個目錄 $ jade templates # 生成 {foo,bar}.html $ jade {foo,bar}.jade # 在標準IO下使用jade $ jade < my.jade > my.html # 在標準IO下使用jade, 同時指定用于查找包含的文件 $ jade < my.jade -p my.jade > my.html # 在標準IO下使用jade $ echo "h1 Jade!" | jade # foo, bar 目錄渲染到 /tmp $ jade foo bar --out /tmp ``` ## License (The MIT License) Copyright (c) 2009-2010 TJ Holowaychuk <tj@vision-media.ca> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Edit By [MaHua](http://mahua.jser.me)