本文是一份歷史文獻:2010 年,一則提案試圖把模板支援放進 jQuery 核心。雖然最終 jQuery 選擇以官方插件(jquery-tmpl)的形式落地,並在幾年後被 JsRender 取代,但這份提案對「模板該長什麼樣子」的思辨,至今讀來仍很有參考價值。
核心訴求是為 jQuery 新增一個 render() 方法,讓你能用一段 HTML 作為模板,渲染單一 JavaScript 物件或物件陣列。標準化帶來的好處是雙向的:
體積極小(未壓縮僅約 2KB),卻已涵蓋渲染模板的核心能力。模板寫在 type 為 text/html 的 script 標籤裡,瀏覽器會忽略其內容,當作字串對待:
<script type="text/html" id="productTemplate"> Product Name: <%= name %> <br /> Product Price: <%= formatPrice(price) %> </script> <div id="results"></div>
渲染單一物件:
var product = { name: "Laptop", price: 788.67 };
$("#results").html( tmpl("productTemplate", product) );
渲染陣列時,tmpl() 展現了 currying 的能力——不傳資料給它,它就回傳一個代表已解析模板的函式:
var template = tmpl("productTemplate");
var results = '';
for (var i = 0; i < products.length; i++) {
results += template(products[i]);
}
$("#results").html(results);
功能完整的 jQuery 插件,支援外部模板與外部資料載入、定時刷新、HTML 編碼防注入、模板包含(include)以及除錯模式。模板放在 textarea 中:
<textarea id="template" style="display:none">
{#foreach $T.products as product}
<div>
Product Name: {$T.product.name}
<br />
Product Price: {formatPrice($T.product.price)}
</div>
{#/for}
</textarea>
使用方式是 attach 加上 process:
$("#results").setTemplateElement("template");
$("#results").processTemplate(data);
它也可以從外部 URL 載入模板與資料,例如 setTemplateURL("MyTemplate.htm") 搭配 processTemplateURL("MyData.htm")。預設會對特殊字元做 HTML 編碼以防插入攻擊——若產品名為 <b>Laptop</b>,輸出會被轉義成 <b>Laptop</b>。
PURE 的哲學是「模板裡不要有任何特殊標記」。它提供 autoRender(),會自動把 JSON 屬性名映射到 CSS class 上:
<div class="product"> Product Name: <span class="name"></span> <br /> Product Price: <span class="price"></span> </div>
$('div.product').autoRender(product); // name → .name, price → .price
若不想依賴這個命名協議,可改用 render() 明確指定對應關係:
var directives = { 'span#name' : 'name', 'span#price': 'price' };
$('div.product').render(product, directives);
微軟的方案把模板直接寫成普通 DOM 元素(加上 sys-template class),不必包在 script 或 textarea 裡。它支援 $id() 偽變數為每個模板實例產生唯一 id、動態切換模板,以及動態占位符(把不同資料項渲染到不同位置)。動態模板的寫法是透過 itemRendering 事件:
function itemRendering(dataView, args) {
var product = args.get_dataItem();
if (product.dateCreated.getFullYear() == 2010) {
args.set_itemTemplate("#newTemplate");
} else {
args.set_itemTemplate("#normalTemplate");
}
}
把模板套用到單一資料項或一組資料項上,產生 DOM 元素:
$("#template")
.render(arrayOrObject, options)
.appendTo("selector");
參數中,data 若是陣列就逐項實例化,若是物件則只實例化一次;options 是可選設定,可放 rendering / rendered 回呼,也可放任何你想傳進模板的額外值。
提案主張讓 append() 這類方法也能直接吃模板選擇器,寫法更貼近既有習慣:
$("ul").append("#template", products);
預先編譯並命名模板,方便在同一份文件裡重複使用:
jQuery.templates.foo = jQuery.tmpl("<li>{%=name%}</li>");
jQuery("#container").append("foo", products);
tmplFn 則用來擴充模板可用的函式。模板內建 text() 與 html(),你也可以加入自訂函式,例如做 zebra striping 用的 even():
$.tmplFn.even = function() {
var context = jQuery._.context;
return (context.index % 2 === 0);
};
提案最終採用 {%= ... %} 插入表達式、{% ... %} 包裹程式碼區塊。選這個分隔符的理由是盡量降低與既有伺服器端樣板(如 ASP、JSP)或客戶端擴充語法衝突的機率。
<li>{%= last %}, {%= first %}</li>
表達式就是 JavaScript,可以呼叫任何函式:
<li>{%= last + " " + first %}</li>
程式碼區塊則處理條件與迴圈:
<li>
{%= name %}
{% if (specials.length) { %}
<ul>
{% for (var i = 0, l = specials.length; i < l; i++) { %}
<li>{%= specials[i].details %}</li>
{% } %}
</ul>
{% } %}
</li>
提案明確指出:資料項預設不會被 HTML 編碼。若你在模板中輸出使用者提交的內容,等於為 XSS 敞開大門。第一個產品名稱若被塞進 <a onclick='alert("do evil")'>,點一下程式碼就執行了。
解法是改用內建的 text() 函式,它把資料項轉成文字節點:
<li>{% text(name) %} - {%= price %}</li>
提案在討論區坦承這個預設值是有爭議的,早期版本曾考慮用 {! ... } 這種特殊分隔符來標示「不編碼的 HTML」。以今日的標準看,預設編碼才是對的——這也是後來幾乎所有模板引擎的共識。
模板中可用 $context 存取四項資訊:data(傳入的陣列或物件)、dataItem(當前項,被放進 with 區塊所以可直接用欄位名)、index(當前索引)、options(呼叫時傳入的選項)。
這讓「把計算邏輯留在模板外」成為可能。例如在 rendering 回呼中先算出稅金:
function rendering(context) {
context.tax = context.dataItem.price * 0.23;
}
模板只需 {%= $context.tax %},不必塞進複雜的內嵌表達式。同理,options 可用來控制顯示行為:
<li>
{%= name %} -
{%= $context.options.showSalePrice ? salePrice : price %}
</li>
提案特別提醒一個細節:dataItem 被放進 with 區塊,所以可以直接寫 name;但若某個資料項缺少該欄位,表達式就會失效。資料為 [{name:"dave"},{firstname:"bob"}] 時,第二項的 name 會出錯。
function rendering(context) {
if (context.dataItem.deleted) {
return false;
}
}
用 rendered 回呼在剛產生的 DOM 中再渲染另一個模板,就能處理一對多結構,例如聯絡人與電話號碼:
function rendered(context, dom) {
$("div.phones", dom)
.append("#phoneTemplate", context.dataItem.phones);
}
這是 rendered 最實用的場合——DOM 已存在但尚未插入文件,正好用來掛上 jQuery UI Datepicker 這類需要實體元素的插件,並把資料項的值設為預設值:
function rendered(context, dom) {
$("input", dom).datepicker({ defaultDate: context.dataItem.birthdate });
}
若你完全不想在模板中出現 {%= ... %},也可以在 rendered 裡手動賦值,模板只留純 HTML 骨架。
有人主張用 <style type="text/html">,因為「樣式」更能體現模板的呈現性質。但缺點很實際:style 不能出現在 body 中,若你無法改動 head(例如在 CMS 環境下工作),就無法建立模板。提案最終選擇 script,並指出技術上兩者相容,端看你偏好。
支持者認為這與 ASP.NET Ajax 的做法一致。但反對意見很有說服力:真正的 DOM 元素會產生副作用。例如:
<div id="template" style="display:none">
<img src="{%= imageUrl %}" />
</div>
瀏覽器會立刻嘗試載入那個不存在的 URL。同類問題還包括:模板中的 input 若位於 form 內可能被送出、id 屬性含無效字元等。用 script 容器就能完全避開這些坑——這也是後來多數模板引擎的選擇。
從今天的視角看,這份提案最有價值的部分不是那些語法細節,而是它把問題定義清楚了:模板需要「可複用的元件邊界」、「邏輯與呈現分離」、「安全的預設行為」以及「渲染前後的擴充點」。這四件事在後來的 React、Vue 乃至各種 JSX 方案中,都還是以不同形式存在。至于 {% %} 這種分隔符,最終也被證實不如直接用 JavaScript 表達式來得靈活。
原文作者 Stephen Walther,中文譯者 Denis deng。