指南

用自动补全构建“您是不是要找”建议框

“您是不是要找”建议框的最佳效果是:低调地出现,提供一个简短的列表,如果所有建议都不合适就不再碍事。自动补全端点正是为这种模式而设计的。

请求

GET /v1/autocomplete?q=Baker Stret&limit=4
{
  "status": "ok",
  "query": "Baker Stret",
  "suggestions": [
    {"text": "Baker Street, London, UK", "place_id": "abc123"},
    {"text": "Baker Street, York, UK", "place_id": "abc789"}
  ]
}

请注意,查询中像 “Stret” 这样的错别字并不会妨碍返回合理的建议,因为该端点本来就是为处理不完美的输入而设计的,而这正是建议框存在的意义所在。

第二个示例:完全没有建议

并非每个查询都能产生有用的匹配,无论有没有错别字。

GET /v1/autocomplete?q=Zzqxlm Nonexistent Rd&limit=4
{
  "status": "ok",
  "query": "Zzqxlm Nonexistent Rd",
  "suggestions": []
}

这里返回空的 suggestions 数组是正确的响应,并不表示请求出了问题。请将建议框设计为在这种情况下悄悄消失,而不是对只是没有合适匹配的输入显示一个空的下拉列表或明显的错误状态。

显示列表

把每条建议的 text 字段显示为可见标签,并为被点击的那一条保留 place_id,因为之后要解析完整地址时,应传递的是这个标识符,而不是重新解析显示文本。

保持可选

这种模式最重要的一点,尤其是在没有客户端 JavaScript 驱动交互的网站上,是无论是否点击了建议,字段在表单提交时都仍然直接接受输入的地址。如果建议框在选中某个选项之前阻止提交,就会把有帮助的提示变成硬性要求,任何确实不在建议列表中的地址都将无法提交。

值得测试的边界情况

用与建议框主要测试所用文字不同的文字书写的地址,或经过音译的地名,是大多数地址数据库中真实存在的一部分,应当与其他任何未匹配的查询一样,采用“退回到纯文本”的处理方式。不要以为不寻常的输入没有建议就说明输入本身无效,因为正确的做法往往只是让客户按原样提交所输入的内容。

限制请求数量

将 limit 设为一个较小的数值,对于建议框来说通常三到五个就够了,因为列表太长就失去了快速浏览的意义。对调用做防抖处理,只在输入出现短暂停顿后才发出请求,从而让每个会话的总请求数保持在较低水平。

每个会话的成本

一个典型的地址字段,在访客输入和自我更正的过程中,可能会触发几次自动补全调用,每次一个请求。即使表单流量可观,这也只占每个密钥附带的(或无密钥时单个地址可用的)每天 2,500 次免费请求中很小的一部分。

一个构建良好的建议框能悄悄地发现错别字,并对任何它无法识别的内容主动让路。完整的字段定义请参阅地址自动补全文档