FreeMarker 設計指南 (三)：模板結構、指令與表達式詳解

1. 模板整體結構

模板由四部分組成：

• 文字：直接輸出
• 插值：${...} 或 #{...}，計算後輸出
• FTL 標籤：<#directive>，不輸出，控制邏輯
• 註解：<#-- ... -->，不輸出

範例

<#-- 問候用戶 -->
<h1>Welcome ${user}!</h1>
<p>We have these animals:</p>
<ul>
<#list animals as being>
  <li>${being.name} for ${being.price} Euros</li>
</#list>
</ul>

2. 指令語法

• 開始標籤：<#directive params>
• 結束標籤：</#directive>
• 空內容：<#directive params/>
• 使用者定義指令用 @：<@macro>
• 標籤需正確巢狀，不可交叉。

3. 表達式詳解

字面值

變數存取

• 頂層：${var}
• 雜湊：book.author.name 或 book["author"].name
• 序列：animals[0].name (索引從 0 起)
• 切片：seq[1..3]
• 特殊變數：.now, .locale 等

運算子優先序 (高→低)

1. 後綴 [] . (params)
2. 一元 + - !
3. 內建 ?
4. 乘除 * / %
5. 加減 + -
6. 關係 < > <= >= (亦可用 lt gt lte gte)
7. 相等 == !=
8. 邏輯與 &&
9. 邏輯或 ||
10. 數字範圍 ..

常用內建函數

4. 插值進階

• 通用插值 ${expr}：依預設格式輸出字串/數字/日期/布林。
• 數字插值 #{expr; format}：mX (最少小數位)、MX (最多小數位)。
• 日期格式化：${date?string("yyyy-MM-dd HH:mm:ss zzzz")}
• 布林格式化：${flag?string("yes","no")}

插值僅能用於文字區塊，不可用於 <#if ${cond}> 等標籤屬性中。