amp-autocomplete

<script async custom-element="amp-autocomplete" src="https://cdn.ampproject.org/v0/amp-autocomplete-0.1.js"></script>

用法

amp-autocomplete 扩展应根据用户输入建议已完成项目，以帮助用户更快地完成任务。

这可用于增强搜索体验，在用户可能不知道所有潜在输入的情况下，或者在表单中帮助确保输入，在表单中可能存在多种表达相同意图的方式（例如，使用州缩写而不是全名），从而产生更可预测的结果。

示例

将 src 属性与 amp-autocomplete 一起使用时，端点的响应包含要在指定模板中呈现的数据。

您可以通过以下两种方式之一指定模板

• 引用现有模板元素的 ID 的 template 属性。
• 直接嵌套在 amp-autocomplete 元素内的模板元素。

有关模板的更多详细信息，请参阅 AMP HTML 模板。

<template type="amp-mustache">

  <!-- NOT RECOMMENDED -->
  <div class="item">{{item}}</div>
  <div class="price">{{price}}</div>
</template>

<template type="amp-mustache">

  <!-- RECOMMENDED -->
  <div data-value="{{items}}">
    <div class="item">{{item}}</div>
    <div class="price">{{price}}</div>
  </div>
</template>

属性

src

返回 JSON 的远程端点的 URL，该 JSON 将在此 amp-autocomplete 中进行筛选和呈现。这必须是 CORS HTTP 服务，并且 URL 的协议必须是 HTTPS。端点必须实现 AMP 中的 CORS 请求 规范中指定的 requirement。如果获取 src URL 处的数据失败，则 amp-autocomplete 会触发回退。如果存在 [src] 属性，则可以省略 src 属性。

query

用于生成静态远程端点的查询参数，该端点返回将在此 amp-autocomplete 中进行筛选和呈现的 JSON。这需要存在 src 属性。例如，如果 src="http://www.example.com" 和 query="q"，那么当用户输入 abc 时，组件将从 http://www.example.com?q=abc 中检索数据。

min-characters

提供结果的用户输入的最小字符长度，默认为 1

max-items

基于用户输入一次建议的最大指定项目数，如果未指定，则显示全部

suggest-first

通过将结果列表中的第一个条目标记为活动状态来建议它。

submit-on-enter

Enter 键主要用于在自动完成中选择建议，因此它也不应提交表单，除非开发人员明确将其设置为这样做（对于搜索字段/单字段表单等）。

用户流程如下：如果 submit-on-enter 为 true，则按 Enter 键将选择任何当前活动的项目并进行默认行为，包括在适用时提交表单。如果 submit-on-enter 为 false，则按 Enter 键当显示建议时将仅选择任何当前活动的项目并阻止任何其他默认行为。如果未显示建议，则自动完成允许默认行为。默认为 false。

highlight-user-entry

如果存在，则在建议项内暴露 autocomplete-partial 类，该子字符串导致其与用户输入匹配。这可用于样式化相应的匹配，以突出显示给用户。默认为 false。

items

指定 JSON 响应中数据数组的键。嵌套键可以用点表示的值来表示，例如 field1.field2. 默认值为 "items"。以下是使用和不使用示例

在第一个示例中，JSON 有效负载由 "items" 键排队，因此不需要组件属性，因为默认值对应。在第二个示例中，JSON 有效负载由 "fruit" 键排队，因此 items 属性的值为 "fruit"，以便准确检索预期的数据源。在这两个示例中，最终用户交互是相同的。

inline

amp-autocomplete 是否应根据完整用户输入或仅根据用户输入的触发子字符串自动建议。默认情况下，当属性不存在时，建议将基于完整的用户输入。该属性不能有空值，但必须采用单个字符标记，即 @，它会激活自动完成行为。例如，如果 inline="@"，则用户输入 hello 不会检索建议，但用户输入 hello @abc 可能会触发根据子字符串 abc 筛选的选项。当前，触发的子字符串以空格字符分隔，但这在将来可能会发生变化。

prefetch

包括 prefetch 属性以预取远程数据，以提高用户的响应速度。需要指定 src。

活动

select

当用户通过单击、点击、键盘导航或接受提前输入选择一个选项时，amp-autocomplete 会触发 select 事件。如果用户使用键盘导航到项目并从输入字段 Tab 离开，它也会触发 select 事件。event 包含所选元素的 value 属性值，即其文本表示形式（例如，data-value 的值）。

如果建议模板包含 data-json={{objToJson}}，则 event 也可能包含 valueAsObject 字段中的整个对象。这会导致呈现的元素具有带有相应对象的 JSON 字符串表示形式的 data-json 数据属性，然后该属性在 event 的 valueAsObject 字段中可用。

示例

验证

请参阅 AMP 验证器规范中的 amp-autocomplete 规则。