跳至主要内容

REFERENCE

開發者參考

認證、API、SDK、Flow Agent 處理節點與參數取值的完整參考。

Handlebars 5分鐘快速入門

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

  1. 基本概念​

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

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

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

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

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

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

    在 Asgard 中的使用建議​

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

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

    輸出結果：

    Hello Alice！您的訂單編號是 ORD20240115001

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

  2. 核心語法​

    變數插入​

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

    條件判斷​

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

    迴圈處理​

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

  3. 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'}}}
    <!-- 今日日期 -->

  4. 實用範例​

    基本訊息模板​

    {{{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}}

  5. Template 與 Expression 選擇​

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

  6. 快速檢查清單​

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

  7. 進階學習​

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

準備好開始了嗎？

想知道 Asgard 怎麼用在你的團隊？跟我們聊聊。

聯絡我們