動態搜尋（也稱為搜尋 API）允許 select_one、select_multiple 或 text 字段在調查員輸入時即時從遠端網路服務載入其選項。當您的選項列表太大而無法打包在 CSV 文件中、頻繁更新或來自即時資料庫時，這是正確的方法。

search-api() 外觀

動態搜尋透過 appearance 欄使用 search-api() 函數配置：

  search-api(method, url, post_body, value_column, display, data_path, save_path)

參數

參數說明
method始終使用 'POST'
url要查詢的 API 端點
post_body發送到 API 的 JSON 主體。使用 %__input__% 作為調查員當前搜尋文字的占位符
value_column回應物件中用作儲存值的鍵
display用作下拉選單中顯示的標籤的鍵（或模板）。支援 ##key## 占位符和 @{func} 表達式
data_path回應中結果物件陣列的 JSONPath（例如 $.data、$.hits.hits.*._source）
save_path保存原始回應以供其他字段使用的名稱

基本範例

調查員輸入部分機構名稱的醫療機構查詢：

typenamelabelappearance
select_onefacility選擇醫療機構search-api('POST', 'https://api.example.com/facilities/search', '{"query": "%__input__%"}', 'id', 'name', '$.results', 'facility_data')

當調查員輸入「nair」時，API 接收 {"query": "nair"} 並返回：

  {
  "results": [
    {"id": "HF001", "name": "Nairobi Central Clinic"},
    {"id": "HF002", "name": "Nairobi West Hospital"}
  ]
}

下拉選單顯示 Nairobi Central Clinic 和 Nairobi West Hospital；儲存值為 HF001 或 HF002。

進階顯示格式

使用 ##key## 模板

在標籤中顯示多個字段：

  search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id', '##name## (##district##)', '$.data', 'res')

顯示為：Nairobi Central Clinic (Nairobi)。

使用 @{func} 表達式

在顯示標籤中應用條件邏輯：

  search-api('POST', 'https://api.example.com/search', '{"q": "%__input__%"}', 'id',
  '@{if_else(eq("##status##", "active"), "✓ ##name##", "✗ ##name##")}',
  '$.data', 'res')

活躍結果顯示 ✓ 機構名稱；非活躍顯示 ✗ 機構名稱。

設定預設值：search-default-api()

在 search-api() 後使用 search-default-api() 以從單獨 API 呼叫載入的預設選項預填字段（例如編輯現有記錄時）：

  appearance: search-api(...) search-default-api('POST', 'https://api.example.com/get', '{"id": "##saved_id##"}', 'id', 'name', '$.item')

select_multiple 的自訂分隔符：search-default-separator()

對於 select_multiple 字段，指定多個已選值在儲存字串中的連接方式：

  appearance: search-api(...) search-default-separator(' || ')

預設分隔符是空格。

支援的問題類型

問題類型使用案例
select_one從搜尋結果中單選
select_multiple從搜尋結果中多選
text自動完成——調查員自由輸入但可選擇建議

使用儲存的回應資料

save_path 將完整的 API 回應物件儲存在給定名稱下。其他字段可使用 pulldata() 引用它：

typenamelabelcalculation
select_onefacility選擇機構search-api(..., 'facility_data')
calculatefacility_districtpulldata('facility_data', 'district')
calculatefacility_typepulldata('facility_data', 'type')

最佳實踐

  1. 確保 API 端點在 1–2 秒內響應——慢速 API 使搜尋感覺無響應。
  2. 在 post_body 中使用 %__input__%，使 API 只返回匹配結果，而不是整個資料集。
  3. 在伺服器端對搜尋字段建立索引（例如 Elasticsearch、資料庫全文索引）以實現快速響應。
  4. 每次查詢限制 20–50 個結果——返回數千個結果會失去搜尋的意義。
  5. 在 API 中包含最小輸入長度要求，以避免在單字符輸入時觸發廣泛查詢。

限制

  • 動態搜尋需要網路連線——離線時不工作。
  • %__input__% 占位符按原樣注入；在伺服器端清理輸入以防止注入攻擊。
  • 複雜的 @{func} 顯示表達式在所有 rtSurvey 客戶端版本中的支援可能有限。
此頁面有幫助嗎？