动态搜索（也称为 Search API）允许 select_one、select_multiple 或 text 字段在枚举员输入时实时从远程网络服务加载其选项。当选项列表太大无法捆绑在 CSV 文件中、频繁更新或来自实时数据库时，这是正确的方法。

search-api() appearance

动态搜索通过 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": "内罗毕中央诊所"},
    {"id": "HF002", "name": "内罗毕西部医院"}
  ]
}

下拉列表显示内罗毕中央诊所和内罗毕西部医院；存储的值为 HF001 或 HF002。

高级显示格式

使用 ##key## 模板

在标签中显示多个字段：

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

显示为：内罗毕中央诊所 (内罗毕)。

使用 @{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 客户端版本中的支持可能有限。
此页面有帮助吗？