artTemplate-3.0

https://github.com/aui/artTemplate

artTemplate-3.0

新一代 javascript 模板引擎

目錄

• 特性
• 快速上手
• 模板語法
• 下載
• 方法
• NodeJS
• 使用預編譯
• 更新日志
• 授權協議

特性

1. 性能卓越，執行速度通常是 Mustache 與 tmpl 的 20 多倍（性能測試）
2. 支持運行時調試，可精確定位異常模板所在語句（演示）
3. 對 NodeJS Express 友好支持
4. 安全，默認對輸出進行轉義、在沙箱中運行編譯后的代碼（Node版本可以安全執行用戶上傳的模板）
5. 支持include語句
6. 可在瀏覽器端實現按路徑加載模板（詳情）
7. 支持預編譯，可將模板轉換成為非常精簡的 js 文件
8. 模板語句簡潔，無需前綴引用數據，有簡潔版本與原生語法版本可選
9. 支持所有流行的瀏覽器

快速上手

編寫模板

使用一個type="text/html"的script標簽存放模板：

<script id="test" type="text/html">
<h1>{{title}}</h1>
<ul>
    {{each list as value i}}
        <li>索引 {{i + 1}} ：{{value}}</li>
    {{/each}}
</ul>
</script>

渲染模板

var data = {
    title: '標簽',
    list: ['文藝', '博客', '攝影', '電影', '民謠', '旅行', '吉他']
};
var html = template('test', data);
document.getElementById('content').innerHTML = html;

演示

模板語法

有兩個版本的模板語法可以選擇。

簡潔語法

推薦使用，語法簡單實用，利於讀寫。

{{if admin}}
    {{include 'admin_content'}}

    {{each list}}
        <div>{{$index}}. {{$value.user}}</div>
    {{/each}}
{{/if}}

查看語法與演示

原生語法

<%if (admin){%>
    <%include('admin_content')%>

    <%for (var i=0;i<list.length;i++) {%>
        <div><%=i%>. <%=list[i].user%></div>
    <%}%>
<%}%>

查看語法與演示

下載

• template.js (簡潔語法版, 2.7kb)
• template-native.js (原生語法版, 2.3kb)

方法

template(id, data)

根據 id 渲染模板。內部會根據document.getElementById(id)查找模板。

如果沒有 data 參數，那么將返回一渲染函數。

template.compile(source, options)

將返回一個渲染函數。演示

template.render(source, options)

將返回渲染結果。

template.helper(name, callback)

添加輔助方法。

例如時間格式器：演示

template.config(name, value)

更改引擎的默認配置。

字段	類型	默認值	說明
openTag	String	'{{'	邏輯語法開始標簽
closeTag	String	"}}"	邏輯語法結束標簽
escape	Boolean	true	是否編碼輸出 HTML 字符
cache	Boolean	true	是否開啟緩存（依賴 options 的 filename 字段）
compress	Boolean	false	是否壓縮 HTML 多余空白字符

使用預編譯

可突破瀏覽器限制，讓前端模板擁有后端模板一樣的同步“文件”加載能力：

一、按文件與目錄組織模板

template('tpl/home/main', data)

二、模板支持引入子模板

{{include '../public/header'}}

基於預編譯：

• 可將模板轉換成為非常精簡的 js 文件（不依賴引擎）
• 使用同步模板加載接口
• 支持多種 js 模塊輸出：AMD、CMD、CommonJS
• 支持作為 GruntJS 插件構建
• 前端模板可共享給 NodeJS 執行
• 自動壓縮打包模板

預編譯工具：TmodJS

NodeJS

安裝

npm install art-template

使用

var template = require('art-template');
var data = {list: ["aui", "test"]};

var html = template(__dirname + '/index/main', data);

配置

NodeJS 版本新增了如下默認配置：

字段	類型	默認值	說明
base	String	''	指定模板目錄
extname	String	'.html'	指定模板后綴名
encoding	String	'utf-8'	指定模板編碼

配置base指定模板目錄可以縮短模板的路徑，並且能夠避免include語句越級訪問任意路徑引發安全隱患，例如：

template.config('base', __dirname);
var html = template('index/main', data)

NodeJS + Express

var template = require('art-template');
template.config('base', '');
template.config('extname', '.html');
app.engine('.html', template.__express);
app.set('view engine', 'html');
//app.set('views', __dirname + '/views');

運行 demo:

node demo/node-template-express.js

若使用 js 原生語法作為模板語法，請改用 require('art-template/node/template-native.js')

升級參考

為了適配 NodeJS express，artTemplate v3.0.0 接口有調整。

接口變更

1. 默認使用簡潔語法
2. template.render()方法的第一個參數不再是 id，而是模板字符串
3. 使用新的配置接口template.config()並且字段名有修改
4. template.compile()方法不支持 id 參數
5. helper 方法不再強制原文輸出，是否編碼取決於模板語句
6. template.helpers 中的$string、$escape、$each已遷移到template.utils中
7. template()方法不支持傳入模板直接編譯

升級方法

1. 如果想繼續使用 js 原生語法作為模板語言，請使用 template-native.js
2. 查找項目template.render替換為template
3. 使用template.config(name, value)來替換以前的配置
4. template()方法直接傳入的模板改用template.compile()（v2初期版本）

更新日志

v3.0.3

1. 解決template.helper()方法傳入的數據被轉成字符串的問題 #96
2. 解決{{value || value2}}被識別為管道語句的問題 #105 https://github.com/aui/tmodjs/issues/48

v3.0.2

1. 解決管道語法必須使用空格分隔的問題

v3.0.1

1. 適配 express3.x 與 4.x，修復路徑 BUG

v3.0.0

1. 提供 NodeJS 專屬版本，支持使用路徑加載模板，並且模板的include語句也支持相對路徑
2. 適配 express 框架
3. 內置print語句支持傳入多個參數
4. 支持全局緩存配置
5. 簡潔語法版支持管道風格的 helper 調用，例如：{{time | dateFormat:'yyyy年 MM月 dd日 hh:mm:ss'}}

當前版本接口有調整，請閱讀 升級參考

artTemplate 預編譯工具 TmodJS 已更新

v2.0.4

1. 修復低版本安卓瀏覽器編譯后可能產生語法錯誤的問題（因為此版本瀏覽器 js 引擎存在 BUG）

v2.0.3

1. 優化輔助方法性能
2. NodeJS 用戶可以通過 npm 獲取 artTemplate：$ npm install art-template -g
3. 不轉義輸出語句推薦使用<%=#value%>（兼容 v2.0.3 版本之前使用的<%==value%>），而簡版語法則可以使用{{#value}}
4. 提供簡版語法的合並版本 dist/template-simple.js

v2.0.2

1. 優化自定義語法擴展，減少體積
2. [重要]為了最大化兼容第三方庫，自定義語法擴展默認界定符修改為{{與}}。
3. 修復合並工具的BUG #25
4. 公開了內部緩存，可以通過template.cache訪問到編譯后的函數
5. 公開了輔助方法緩存，可以通過template.helpers訪問到
6. 優化了調試信息

v2.0.1

1. 修復模板變量靜態分析的BUG

v2.0 release

1. 編譯工具更名為 atc，成為 artTemplate 的子項目單獨維護：https://github.com/cdc-im/atc

v2.0 beta5

1. 修復編譯工具可能存在重復依賴的問題。感謝 @warmhug
2. 修復預編譯include內部實現可能產生上下文不一致的問題。感謝 @warmhug
3. 編譯工具支持使用拖拽文件進行單獨編譯

v2.0 beta4

1. 修復編譯工具在壓縮模板可能導致 HTML 意外截斷的問題。感謝 @warmhug
2. 完善編譯工具對include支持支持，可以支持不同目錄之間模板嵌套
3. 修復編譯工具沒能正確處理自定義語法插件的輔助方法

v2.0 beta1

1. 對非 String、Number 類型的數據不輸出，而 Function 類型求值后輸出。
2. 默認對 html 進行轉義輸出，原文輸出可使用<%==value%>（備注：v2.0.3 推薦使用<%=#value%>），也可以關閉默認的轉義功能template.defaults.escape = false。
3. 增加批處理工具支持把模板編譯成不依賴模板引擎的 js 文件，可通過 RequireJS、SeaJS 等模塊加載器進行異步加載。

授權協議

Released under the MIT, BSD, and GPL Licenses

 

所有演示例子 | 引擎原理