amp-autocomplete

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

用法

amp-autocomplete 扩展应该用于根据用户输入建议完整的条目，以帮助用户更快地完成任务。

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

示例

<amp-autocomplete
  id="myAutocomplete"
  src="/static/samples/json/amp-autocomplete-cities.json"
>
  <input />
  <template type="amp-mustache">
    <div data-value="{{.}}">{{.}}</div>
  </template>
</amp-autocomplete>

当使用带有 amp-autocomplete 的 src 属性时，来自端点的响应包含要在指定模板中呈现的数据。

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

• 一个 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

返回将在 amp-autocomplete 中过滤和呈现的 JSON 的远程端点的 URL。这必须是 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"。以下是使用和不使用的示例

请注意，以下数据由远程 src 返回

{
  "items" : ["apples", "bananas", "pears"],
  "fruit" : ["kiwis", "oranges", "watermelons"]
}

<amp-autocomplete src="/static/samples/json/amp-autocomplete-fruit-items.json">
  <input type="text">
</amp-autocomplete>

<amp-autocomplete src="/static/samples/json/amp-autocomplete-fruit-items.json" items="fruit">
  <input type="text">
</amp-autocomplete>

在第一个示例中，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 字段中包含整个对象。 这会导致呈现的元素具有一个 data-json 数据属性，该属性具有相应对象的 JSON 字符串表示形式，然后该数据属性在 event 的 valueAsObject 字段中可用。

示例

<amp-autocomplete
  id="myAutocomplete"
  on="select:AMP.setState({chosenFruit: event.value})"
  src="/static/samples/json/amp-autocomplete-fruit.json"
>
  <input />
  <template type="amp-mustache">
    <div data-value="{{name}}">{{name}}</div>
  </template>
</amp-autocomplete>
<p [text]="'Your fruit: ' + chosenFruit">
  No fruit selected
</p>

验证

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