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 请求 规范中指定的要求。如果在 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

回车键主要用于在自动完成中选择建议，因此除非开发人员明确设置它执行此操作（对于搜索字段/单字段表单等），否则它不应提交表单。

用户流程如下：如果 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 事件。如果用户键盘导航到某个项目并从输入字段切换到选项卡，它也会触发 select 事件。event 包含所选元素的 value 属性值，即其文本表示形式（例如，data-value 的值）。

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

示例

验证

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