Skip to main content

Handlebars 5分鐘快速入門

Handlebars 是 Asgard Template 模式中使用的模板引擎，讓您能以簡潔的語法產生動態文字內容。

基本概念​

Handlebars 使用大括號語法插入動態內容，有兩種不同的使用方式：

雙大括號 vs 三大括號的差異​

雙大括號 {{}} - HTML 轉義

Hello {{name}}！您的訂單編號是 {{orderNumber}}

三大括號 {{{}}} - 非轉義輸出

Hello {{{name}}}！您的訂單編號是 {{{orderNumber}}}
語法用途HTML 轉義範例
{{}}一般文字輸出✅ 會轉義{{content}} → <script>
{{{}}}原始內容輸出❌ 不轉義{{{content}}} → <script>

在 Asgard 中的使用建議​

大部分情況下，在 Asgard 內應該使用三大括號 {{{}}}語法，因為：

  • 避免意外轉換：防止特殊字元被錯誤轉換（如 < 變成 &lt;）
  • 保持資料完整性：確保變數內容按原樣輸出，不被修改
Hello {{{name}}}！您的訂單編號是 {{{orderNumber}}}

輸出結果：

Hello Alice！您的訂單編號是 ORD20240115001

📖 詳細語法學習
完整的 Handlebars 語法請參考 官方文檔

核心語法​

變數插入​

{{{user.name}}} 您好！ 您的會員等級是 {{{user.level}}}

條件判斷​

{{#if hasNewOrders}}
  您有
  {{{newOrderCount}}}
  筆新訂單
{{else}}
  目前沒有新訂單
{{/if}}

迴圈處理​

• 商品清單：
{{#each products}}
  {{{@index}}}.
  {{{name}}}
  - NT$
  {{{price}}}
{{/each}}

Asgard 內建函數​

Asgard 提供 8 個專用輔助函數：

{{{history 0 -1}}}
<!-- 對話歷史 -->

{{{historySize}}}
<!-- 對話記錄數量 -->

{{{toJson user}}}
<!-- JSON 轉換 -->

{{{urlEncode searchKeyword}}}
<!-- URL 編碼 -->

{{{xpathExtract xmlData '/root/item'}}}
<!-- XML 查詢 -->

{{{vecToStr vector '[' ']' ','}}}
<!-- 向量轉字串 -->

{{{isoNow 'Asia/Taipei'}}}
<!-- 當前時間 -->

{{{isoToday 'Asia/Taipei'}}}
<!-- 今日日期 -->

實用範例​

基本訊息模板​

{{{user.name}}}
您好！ 
系統狀態： 
• 對話記錄：{{{historySize}}} 則
• 當前時間：{{{isoNow 'Asia/Taipei'}}}

{{#if hasUpdates}}
  最近對話：
  {{{history -3 -1}}}
{{/if}}

按鈕模板​

{
  "type": "BUTTON",
  "title": "{{{user.name}}} 的資料",
  "text": "會員資料：\n{{{toJson user}}}",
  "buttons": [
    {
      "label": "查看歷史",
      "action": {
        "type": "MESSAGE",
        "text": "顯示對話歷史"
      }
    }
  ]
}

API 查詢範例​

• 搜尋：{{{urlEncode query}}}
• 查詢時間：{{{isoNow 'Asia/Taipei'}}}

{{#if xmlResponse}}
• 結果：
  {{{xpathExtract xmlResponse '//item/title'}}}
{{/if}}

Template 與 Expression 選擇​

情境建議使用原因
文字模板Template語法簡潔
複雜運算ExpressionJavaScript 功能完整
條件判斷Template內建支援
數學計算Expression更靈活

快速檢查清單​

✅ 變數插入：{{{variable}}}
✅ 條件判斷：{{#if condition}}
✅ 迴圈處理：{{#each array}}
✅ Asgard 函數：8 個內建函數
✅ 物件屬性：{{{user.name}}} 巢狀存取

進階學習​

結合標準 Handlebars 語法與 Asgard 內建函數，您可以建立強大的動態訊息模板。