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 一起使用时，来自端点的响应包含要在指定模板中呈现的数据。

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

• 一个 template 属性，该属性引用现有模板元素的 ID。
• 一个直接嵌套在 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 请求 规范中指定的必要条件。 如果在 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 规则。