跳至主要内容

內建變數

Asgard Expression 與 Template 系統提供內建變數，讓您能夠在工作流程中動態存取對話資料、檔案資訊和頻道狀態。

內建變數清單​

對話相關變數​

prevMessage​

  • 型別：string
  • 說明：前一則使用者訊息內容
  • 用法：
// Expression
prevMessage || '無訊息';
{{! Template }}
{{#if prevMessage}}
  您說：{{prevMessage}}
{{/if}}

prevBlobs​

  • 型別：array<Blob>
  • 說明：前一則訊息的檔案清單
  • 用法：
// Expression
prevBlobs && prevBlobs.length > 0 ? `收到 ${prevBlobs.length} 個檔案` : '沒有檔案';
{{! Template }}
{{#if prevBlobs}}
  檔案清單：
  {{#each prevBlobs}}
    • {{fileName}} ({{size}} bytes)
  {{/each}}
{{/if}}

prevPayload​

  • 型別：object
  • 說明：前一則訊息的載荷資料
  • 用法：
// Expression
prevPayload && prevPayload.userAction;
{{! Template }}
{{#if prevPayload}}
  載荷資料：{{{toJson prevPayload}}}
{{/if}}

prevError​

  • 型別：string
  • 說明：最近一次處理器錯誤訊息
  • 用法：
// Expression
prevError ? `發生錯誤：${prevError}` : '處理正常';
{{! Template }}
{{#if prevError}}
  錯誤訊息：{{prevError}}
{{else}}
  處理成功
{{/if}}

頻道相關變數​

customChannelId​

  • 型別：string
  • 說明：自定義頻道 ID
  • 用法：
// Expression
`頻道：${customChannelId}`;
{{! Template }}
當前頻道：{{customChannelId}}

customMessageId​

  • 型別：string
  • 說明：前一則訊息的客製化 ID（如果 client 無提供則為空字串）
  • 用法：
// Expression
customMessageId || '無自定義 ID';
{{! Template }}
{{#if customMessageId}}
  訊息 ID：{{customMessageId}}
{{/if}}

Blob 物件結構​

interface Blob {
  blobId: number; // Blob 檔案的識別 ID
  fileType: FileType; // 檔案類型
  fileName?: string; // 原始檔名（可選）
  size: number; // 檔案大小（bytes）
  mime: string; // MIME 類型
}

type FileType = 'BINARY' | 'IMAGE' | 'VIDEO' | 'AUDIO' | 'DOCUMENT';

變數存取方式​

安全存取模式​

Expression 模式

// 檢查變數存在性
prevMessage && prevMessage.length > 0 ? prevMessage : '無訊息';

// 使用邏輯運算符
prevMessage || '預設訊息';

// 安全存取陣列
prevBlobs && prevBlobs[0] && prevBlobs[0].fileName;

// 檢查物件屬性
prevPayload && 'property' in prevPayload ? prevPayload.property : '預設值';

Template 模式

{{#if prevMessage}}
  有訊息：{{prevMessage}}
{{else}}
  無訊息
{{/if}}

{{#each prevBlobs}}
  檔案
  {{@index}}:
  {{fileName}}
{{/each}}

實用範例​

對話狀態檢查​

// Expression：完整狀態檢查
(() => {
  let status = [];

  if (prevMessage) {
    status.push(`訊息：${prevMessage.substring(0, 50)}...`);
  }

  if (prevBlobs && prevBlobs.length > 0) {
    status.push(`檔案：${prevBlobs.length} 個`);
  }

  if (prevError) {
    status.push(`錯誤：${prevError}`);
  }

  return status.length > 0 ? status.join(' | ') : '無狀態';
})();
{{! Template：狀態報告 }}
• 對話狀態

{{#if prevMessage}}
  • 最後訊息：{{prevMessage}}
{{else}}
  • 尚未收到訊息
{{/if}}

{{#if prevBlobs}}
  • 檔案資訊：
  {{#each prevBlobs}}
    • {{fileName}} ({{fileType}}, {{size}} bytes)
  {{/each}}
{{else}}
  • 沒有附件
{{/if}}

{{#if prevError}}
  • 錯誤：{{prevError}}
{{else}}
  • 運作正常
{{/if}}

• 頻道：{{customChannelId}}

檔案處理範例​

// Expression：檔案分類統計
(() => {
  if (!prevBlobs || prevBlobs.length === 0) {
    return '沒有檔案';
  }

  const stats = {};
  prevBlobs.forEach(blob => {
    stats[blob.fileType] = (stats[blob.fileType] || 0) + 1;
  });

  return Object.entries(stats)
    .map(([type, count]) => `${type}: ${count}`)
    .join(', ');
})();
{{! Template：檔案詳細資訊 }}
{{#if prevBlobs}}
  • 檔案詳情：
  {{#each prevBlobs}}
    {{@index}}.
    {{fileName}}
    • 類型：{{fileType}}
    • 大小：{{size}} bytes
    • MIME：{{mime}}
    • ID：{{blobId}}
  {{/each}}
{{/if}}

常見問題​

Q: 如何檢查變數是否存在？

// Expression
typeof prevMessage !== 'undefined' && prevMessage !== null;
prevMessage != null; // 同時檢查 undefined 和 null
{{! Template }}
{{#if prevMessage}}
  變數存在
{{/if}}

Q: 如何處理空陣列？

// Expression
prevBlobs && Array.isArray(prevBlobs) && prevBlobs.length > 0;
{{! Template }}
{{#if prevBlobs}}
  {{#if prevBlobs.length}}
    有檔案
  {{/if}}
{{/if}}

Q: 如何安全存取檔案屬性？

// Expression
prevBlobs && prevBlobs[0] && prevBlobs[0].fileName;
{{! Template }}
{{#if prevBlobs}}
  {{#each prevBlobs}}
    {{#if fileName}}
      檔名：{{fileName}}
    {{/if}}
  {{/each}}
{{/if}}

Q: 如何處理載荷資料？

// Expression：安全存取載荷屬性
prevPayload && typeof prevPayload === 'object' && 'action' in prevPayload ? prevPayload.action : '無動作';
{{! Template：顯示載荷內容 }}
{{#if prevPayload}}
  載荷內容：{{{toJson prevPayload}}}
{{/if}}

透過正確使用這些內建變數，您可以建立更智能和個人化的對話體驗。