TmodJS

項目已經停止維護，請使用更好的代替方案：art-template-loader

TmodJS（原名 atc）是一個簡單易用的前端模板預編譯工具。它通過預編譯技術讓前端模板突破瀏覽器限制，實現後端模板一樣的同步“文件”加載能力。它采用目錄來組織維護前端模板，從而讓前端模板實現工程化管理，最終保證前端模板在復雜單頁 web 應用下的可維護性。同時預編譯輸出的代碼經過多層優化，能夠在最大程度節省客戶端資源消耗。

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

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

二、模板支持引入子模板

{{include ‘../public/header‘}}

TmodJS 一經啟動，就無需人工幹預，每次模板創建與更新都會自動編譯，引入一個 js 即可使用template(path)接口調用本地模板文件，直到正式上線都無需對代碼進行任何修改，整個過程簡單自然。

所有特性

0. 編譯模板為不依賴引擎的 js 文件
1. 前端模板按文件與目錄組織
2. 模板之間支持引入外部模板
3. 使用同步模板加載接口
4. 可選多種規範的模塊輸出：AMD、CMD、CommonJS
5. 支持作為 GruntJS 的插件構建項目
6. 模板目錄可被前後端共享
7. 支持檢測修改即時編譯
8. 支持模板運行時調試
9. 配置文件支持多人共享

若想深入了解，請閱讀：《進擊！前端模板工程化》

文檔目錄

• 安裝
• 編寫模板
• 編譯模板
• 使用模板
• 演示
• 配置
• grunt
• gulp
• 常見問題
• 更新日誌
• 加入我們
• 授權協議

安裝

使用 NodeJS 附帶的npm命令，執行：

npm install -g tmodjs

Mac OSX 可能需要管理員權限運行： sudo npm install -g tmodjs

編寫模板

TmodJS 的前端模板不再耦合在業務頁面中，而是和後端模板一樣有專門的目錄管理。目錄名稱只支持英文、數字、下劃線的組合，一個模板對應一個.html文件。

支持基本的模板語法，如輸出變量、條件判斷、循環、包含子模板。模板語法參考

完全支持 artTemplate 的語法

編譯模板

只需要運行tmod這個命令即可，默認配置參數可以滿足絕大多數項目。

tmod [模板目錄] [配置參數]

模板目錄必須是模板的根目錄，若無參數則為默認使用當前工作目錄，tmodjs 會監控模板目錄修改，每次模板修改都會增量編譯。

配置參數

• --debug 輸出調試版本
• --charset value 定義模板編碼，默認utf-8
• --output value 定義輸出目錄，默認./build
• --type value 定義輸出模塊格式，默認default，可選cmd、amd、commonjs
• --no-watch 關閉模板目錄監控
• --version 顯示版本號
• --help 顯示幫助信息

配置參數將會保存在模板目錄配置文件中，下次運行無需輸入配置參數（--no-watch 與 --debug 除外）。

示例

tmod ./tpl --output ./build

使用模板

根據編譯的type的配置不同，會有兩種不同使用方式：

使用默認的格式

TmodJS 默認將整個目錄的模板壓縮打包到一個名為 template.js 的腳本中，可直接在頁面中使用它：

<script src="tpl/build/template.js"></script>
<script>
	var html = template(‘news/list‘, _list);
	document.getElementById(‘list‘).innerHTML = html;
</script>

template.js 還支持 RequireJS、SeaJS、NodeJS 加載。示例

指定格式（amd / cmd / commonjs)

此時每個模板就是一個單獨的模塊，無需引用 template.js：

var render = require(‘./tpl/build/news/list‘);
var html = render(_list);

註意：模板路徑不能包含模板後綴名

演示

TmodJS 源碼包中test/tpl是一個演示項目的前端模板目錄，基於默認配置。切換到源碼目錄後，編譯：

tmod test/tpl

編譯完畢後你可以在瀏覽器中打開 test/index.html 查看如何使用編譯後的模板。

配置

TmodJS 的項目配置文件保存在模板目錄的 package.json 文件中：

{
    "name": "template",
    "version": "1.0.0",
    "dependencies": {
        "tmodjs": "1.0.0"
    },
    "tmodjs-config": {
        "output": "./build",
        "charset": "utf-8",
        "syntax": "simple",
        "helpers": null,
        "escape": true,
        "compress": true,
        "type": "default",
        "runtime": "template.js",
        "combo": true,
        "minify": true,
        "cache": false
    }
}

grunt

讓 TmodJS 作為 Grunt 的一個插件使用：

npm install grunt-tmod --save-dev

由@Jsonzhang開發，項目主頁：

https://github.com/Jsonzhang/grunt-tmod

gulp

讓 TmodJS 作為 Gulp 的一個插件使用：

npm install gulp-tmod --save-dev

由@lichunqiang開發，項目主頁：

https://github.com/lichunqiang/gulp-tmod

常見問題

問：TmodJS 需要部署到服務器中嗎？

不需要，這是本地工具，基於 NodeJS 編寫是為了實現跨平臺。

問：如何將每個模板都編譯成單獨的 amd/cmd 模塊輸出？

指定 type 參數即可，如--type cmd則可以讓每個模板都支持 RequireJS/SeaJS 調用。

問：如何將模板編譯成 NodeJS 的模塊？

指定 type 參數即可，如--type commonjs。

問：線上運行的模板報錯了如何調試？

開啟 debug 模式編譯，如--debug，這樣會輸出調試版本，可以讓你快速找到模板運行錯誤的語句以及數據。

問：如何不壓縮輸出 js？

編輯配置文件，設置"minify": false。

問：如何修改默認的輸出目錄？

指定 output 參數即可，如--output ../../build。

問：如何讓模板訪問全局變量？

請參考：輔助方法。

問：可以使用使用類似 tmpl 那種的 js 原生語法作為模板語法嗎？

可以。編輯配置文件，設置"syntax": "native"即可，目前 TmodJS 默認使用的是 simple 語法。

問：如何兼容舊版本 atc 的項目？

編輯配置文件，分別設置"type": "cmd"、"syntax": "native"、"output": "./"

問：如何遷移原來寫在頁面中的 artTemplate 模板，改為 TmodJS 這種按按文件存放的方式？

請參考：頁面中的模板遷移指南。

問：我需要手動合並模板，如何讓 tmodjs 不合並輸出？

編輯配置文件，設置combo:false。

更新日誌

v1.0.4

• 設置"output":false則不進行輸出，方便Gulp插件利用
• 新增"verbose": true選項，選擇是否顯示日誌

v1.0.1

• 解決新版本設置"minify":true輸出後，輸出的腳本中文沒有被編碼的問題
• 給引入後綴名的模板給予報錯提示

v1.0.0

• 使用 artTemplate3.0 作為模板引擎，NodJS 可直接共享前端的模板目錄的模板，無需預編譯
• 提供 GruntJS 插件
• 取消engine配置
• 增加runtime配置
• 接口重構，支持多實例

v0.1.1

• 給壓縮打包合並後的每條模板增加版本標記，例如/*v:13*/，以便對比線上版本

v0.1.0

• 增加自動遞增的模板版本號，控制臺可顯示模板被修改的次數
• 優化默認設置下的文件輸出，僅保留template.js，臨時文件使用隱藏的.cache目錄存放
• 自動清理.debug.js文件
• 對非規範的include語句模板在編譯過程給予提示
• 修復compileError事件觸發異常的 bug
• 減少對磁盤的讀寫，優化性能

v0.0.4

• 增加escape配置，如果後臺給出的數據已經進行了 XSS 過濾，就可以關閉模板的默認過濾以提升模板渲染效率
• 簡化combo功能，default只提供全部合並與不合並兩個選項，值為布爾類型（兼容舊的版本的配置，會自動轉換成布爾類型）
• 取消雞肋的異步載入插件，同時async配置失效
• 為了便於理解，命令行輸入的--output參數不再相對於模板目錄，而是工作目錄（配置文件的output參數仍保持不變）
• 優化控制臺日誌顯示

v0.0.3

• 修復combo配置不能為空數組的 BUG
• 支持頁面內嵌動態編譯與預編譯兩種方案共存（請設置engine:true，並在頁面中中引入 TmodJS 輸出的 template.js。如果想讓 template.js 不內置合並的模板，可以設置combo:[]）
• 運行時性能優化
• 增加alias配置字段，在 AMD 與 CMD 模式下可以指定運行時依賴 ID

v0.0.2

修復極其特殊情況下 TmodJS 無法為 AMD/CMD 模塊正確聲明依賴的問題#14

v0.0.1

這是一個革命性的版本，內部大量優化！同時項目更名為 TmodJS，內部版本號收歸到 0.0.1

使用 TemplageJS 格式的模塊作為默認輸出的類型：它包含模板目錄中所有模板，除了支持頁面 Script 直接引入之外還支持 RequireJS、SeaJS、NodeJS 加載，並且接口統一，跨架構與前後端運行！

詳細更新列表：

• 吸收了來自業務的一些建議，編譯方案的大調整，內部進行無數次優化，編譯後的代碼更小
• 編譯後的腳本使用統一的接口：template(path, data) 其中 path 相對於 template.js 所在目錄
• 自動打包目錄與子目錄的模板
• 可選支持異步載入模板功能
• 可選嵌入完整模板引擎（使用字符串存儲模板）
• 可選支持 RequireJS/SeaJS/NodeJS 模塊
• 保存模板配置文件（方便多人協作中使用版本管理工具共享配置）
• 可選編譯調試版本
• 編譯後的函數體優化
• 錯誤處理優化
• compile(file)接口可遞歸編譯依賴
• 增加saveUserConfig接口保存用戶設置
• 默認語法變更：默認使用簡潔語法，取消--define-syntax，並使用新的界定符 {{與}}。模板語法參考
• 取消--clone-helpers參數

atc v1.0.3

• 默認使用簡潔語法，取消--define-syntax，增加--no-define-syntax參數恢復原生語法
• 增加-t, --type設置輸出的模塊類型，默認 CMD ，可選：CMD | AMD | CommonJS。讓模板可以前後端共用
• 優化無邏輯語句的模板編譯後的函數體積
• 因 Windows 批處理無法模擬 NodeJS 的高級特性，atc 不再包含 Windows 批處理腳本，若需要可用批處理調用 NodeJS
• 模板語法的界定符有變更，請參考：模板語法

atc v1.0.2

NodeJS 版本：

• 增加-o path或--output path定義輸出目錄
• 修復-d或--define-syntax可能失效的問題
• 修改-w或--watch參數啟動後的規則：只監控模板修改，而不再編譯所有模板
• 增強調試特性：模板語法錯誤將在控制臺輸出調試源碼，並停止進程

atc v1.0.1

NodeJS 版本：

• 支持監控目錄，即時編譯
• 使用命令行傳遞參數
• 使用 npm 管理包
• 支持設置簡潔語法

atc v1.0.0

• 支持前端模板按文件與目錄組織，自動處理 include 依賴
• NodeJS 與 Windows 批處理版本同時發布

加入我們

TmodJS 是一個開源項目，如果你喜歡，非常期待你通過微博或者博客等來宣傳 TmodJS。

使用 TmodJS 的項目

• QQ空間
• 騰訊視頻
• 愛奇藝
• 愛拍原創
• Spa（迅雷）
• MicroTrend（騰訊）
• Tracker（騰訊）
• UR（騰訊）
• ……

如果你使用了 TmodJS 敬請留下項目名，我們將在 TmodJS 主頁展示你的項目。

作者：ylbtech 出處：http://ylbtech.cnblogs.com/ 本文版權歸作者和博客園共有，歡迎轉載，但未經作者同意必須保留此段聲明，且在文章頁面明顯位置給出原文連接，否則保留追究法律責任的權利。

TModJS：README