amp-autocomplete

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

用法

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

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

示例

<amp-autocomplete filter="substring" id="myAutocomplete">
  <input />
  <script type="application/json">
    {"items": ["a", "b", "c"]}
  </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>

属性

filter（必需）

应用于源数据以产生用户输入过滤结果的过滤机制。在所有情况下，过滤后的结果将以检索到的数据的数组顺序显示。如果正在进行过滤（filter != none），则在客户端进行。支持以下值

• substring：如果用户输入是项目的子字符串，则建议该项目
• prefix：如果用户输入是项目的前缀，则建议该项目
• token-prefix：如果用户输入是多词项中任何单词的前缀，则建议该项目；示例“je”是“blue jeans”中的标记前缀
• fuzzy：输入字段中的拼写错误可能导致部分匹配的项目出现在过滤后的结果中 - 需要进一步研究
• none：无客户端过滤；基于绑定的 [src] 属性呈现检索到的数据；如果提供，则截断为 max-items 属性
• custom：一个涉及项目和用户输入的条件语句，应用于每个项目，使得评估为 true 意味着建议该项目；如果 filter==custom，则使用此过滤器需要包含 amp-bind，还需要一个额外的属性 filter-expr 来指定执行自定义过滤的布尔表达式

filter-expr

如果 filter==custom，则为必需

filter-value

如果数据是 JsonObject 的数组，则 filter-value 是将用于客户端过滤的属性名称。如果过滤器为 none，则此属性是不必要的。默认为“value”。

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

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

只有在 filter==prefix 时才有可能（否则不执行任何操作）。

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"。以下是使用和不使用情况的示例

      <amp-autocomplete filter="prefix">
          <input type="text">
          <script type=application/json>
            { "items" : ["apples", "bananas", "pears"] }
           </script>

      </amp-autocomplete>

<amp-autocomplete filter="prefix" items="fruit">
  <input type="text">
  <script type=application/json>
    { "fruit" : ["kiwis", "oranges", "watermelons"]  }
    </script>
</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
  filter="substring"
  id="myAutocomplete"
  on="select:AMP.setState({chosenFruit: event.valueAsObject})"
>
  <input />
  <script type="application/json">
    {
      "items": [
        {"fruit": "apple", "color": "red"},
        {"fruit": "banana", "color": "yellow"}
      ]
    }
  </script>
  <template type="amp-mustache">
    <div data-value="{{fruit}}" data-json="{{objToJson}}">
{{color}} {{fruit}}    </div>
  </template>
</amp-autocomplete>
<p [text]="'Your fruit: ' + chosenFruit.color + ', ' + chosenFruit.fruit">
  No fruit selected
</p>

验证

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