amp-autocomplete
- 简介设置基本用法动态 src 建议富内容显示默认项内联显示建议指定查询参数

网站

amp-autocomplete

简介

启用自动完成功能的输入字段会在用户在输入字段中键入时建议与用户输入对应的已完成结果。此功能可以帮助用户更快地完成他们的任务。

数据可以从 JSON 端点获取，也可以从 amp-state 本地获取。

设置

导入 amp-autocomplete 组件。

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

导入 amp-form 组件。

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

可选：需要 amp-bind 来动态更改 amp-autocomplete 的数据源。

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

可选：amp-mustache 用于富内容模板和表单响应的客户端渲染。

<script async custom-template="amp-mustache" src="https://cdn.ampproject.org/v0/amp-mustache-0.2.js"></script>

基本用法

amp-autocomplete 必须始终嵌套在表单中，并且必须指定一个带有 input 或 textarea 标签和一个数据源的输入字段。当用户在此输入字段中键入时，相关的建议将自动出现在输入字段下方。

数据源必须是一个包含数组属性 items 的 JSON 对象，并且可以使用子 script type="application/json" 标签内联指定，或者使用 src 属性指定的服务器端点。

<form class="sample-form" method="post" action-xhr="https://amp.org.cn/documentation/examples/api/echo" target="_top">
  <amp-autocomplete filter="substring">
    <input>
    <script type="application/json">
      {
        "items": ["apple", "orange", "banana"]
      }
    </script>
  </amp-autocomplete>
</form>

或者，数据源也可以通过 src 属性以远程数据的形式提供。

<form class="sample-form" method="post" action-xhr="https://amp.org.cn/documentation/examples/api/echo" target="_top">
  <amp-autocomplete filter="substring" src="/static/samples/json/amp-autocomplete-cities.json">
    <input>
  </amp-autocomplete>
</form>

动态 `src`

可以通过使用 amp-bind 修改 amp-autocomplete 的 src 值来动态更改其内容。

<div class="suggest-data">
  <button on="tap:AMP.setState({ srcUrl: '/static/samples/json/amp-autocomplete-countries.json' })">Suggest countries</button>
  <button on="tap:AMP.setState({ srcUrl: '/static/samples/json/amp-autocomplete-cities.json' })">Suggest US cities</button>
</div>
<form class="sample-form" method="post" action-xhr="https://amp.org.cn/documentation/examples/api/echo" target="_top">
  <div class="input-field">
    <amp-autocomplete filter="substring" min-characters="0" src="/static/samples/json/amp-autocomplete-cities.json" [src]="srcUrl">
        <input name="name" required>
    </amp-autocomplete>
    <input name="submit-button" type="submit" value="Submit"><br>
  </div>
  <div submit-success>
    <template type="amp-mustache">
      Success! Mailing a postcard to {{name}}.
    </template>
  </div>
</form>

建议富内容

更复杂的数据可以使用 "items" 中的 JsonObject 数组传递到自动完成中。

{ "items" : [
    {
        "city" : "Albany",
        "state" : "New York",
        "areaCode" : 518,
        "population" : 98251
    }, {
        "city" : "Annapolis",
        "state" : "Maryland",
        "areaCode" : 410,
        "population" : 39321
    }, {
        "city" : "Trenton",
        "state" : "New Jersey",
        "areaCode" : 609,
        "population" : 84964
    }
] }

这些数据在 amp-autocomplete 中的相应显示可以通过模板指定。

<template type="amp-mustache" id="amp-template-custom">
  <div class="city-item" data-value="{{city}}, {{state}}">
      <div>{{city}}, {{state}}</div>
      <div class="custom-population">Population: {{population}}</div>
  </div>
</template>

默认情况下，amp-autocomplete 将通过匹配每个 JsonObject 的 "value" 属性来建议项目，但对于更指定的数据，可以提供属性 filter-value 来表示要搜索的相应属性。在上面的示例中，我们将需要搜索属性 name，因为这可能是用户最有可能搜索的内容。

<form class="sample-form" method="post" action-xhr="https://amp.org.cn/documentation/examples/api/echo" target="_top">
  <label>
      <span>Search for</span>
      <amp-autocomplete filter="token-prefix" filter-value="city" min-characters="0">
        <input type="search" name="city">
          <script type="application/json">
              { "items" : [
                  {
                      "city" : "Albany",
                      "state" : "New York",
                      "areaCode" : 518,
                      "population" : 98251
                  }, {
                      "city" : "Annapolis",
                      "state" : "Maryland",
                      "areaCode" : 410,
                      "population" : 39321
                  }, {
                      "city" : "Trenton",
                      "state" : "New Jersey",
                      "areaCode" : 609,
                      "population" : 84964
                  }
              ] }
          </script>
          <template type="amp-mustache" id="amp-template-custom">
              <div class="city-item" data-value="{{city}}, {{state}}">
                  <div>{{city}}, {{state}}</div>
                  <div class="custom-population">Population: {{population}}</div>
              </div>
          </template>
      </amp-autocomplete>
  </label>
  <input type="submit" value="Search">
  <div submit-success>
    <template type="amp-mustache">
      Successfully submitted {{city}}!
    </template>
  </div>
  <div submit-error>
    Error!
  </div>
</form>

显示默认项

可以使用富内容模板和 amp-autocomplete 上的 min-characters 属性在用户 focus 时显示 amp-autocomplete 的默认建议。

此外，由于模板渲染项上的 data-disabled 属性允许显示但不能针对其进行搜索或选择，因此它对于在结果列表中构造“标题”非常有用，该标题可以将可选项目组织到类别中。在下面的示例中，“Popular groceries”充当禁用项的示例，因为它不是您真正想要将其视为产品的项目。

内联自动完成

<div>
  <amp-state id="generalInventory">
      <script type="application/json">
        { "items" : [{
          "name": "apple",
          "emoji": "🍎",
          "price": "$1"
        }, {
          "name": "grapes",
          "emoji": "🍇",
          "price": "$2"
        }, {
          "name": "whole milk",
          "emoji": "🥛",
          "price": "$4"
        }, {
          "name": "banana",
          "emoji": "🍌",
          "price": "$0.50"
        }] }
      </script>
  </amp-state>
  <form class="sample-form" method="post" action-xhr="https://amp.org.cn/documentation/examples/api/echo" target="_top">
    <amp-autocomplete filter="substring" min-characters="0" filter-value="name" [src]="manualFilterData">
      <input type="search" name="product" on="input-debounced:AMP.setState({ manualFilterData: event.value.length == 0 ?
          initialInventory : generalInventory })">
      <amp-state id="initialInventory">
          <script type="application/json">
            { "items" : [
             { "isInitial": "true",
                "name": "apple"
              }, { "isInitial": "true",
                "name": "grapes"
              }, { "isInitial": "true",
                "name": "whole milk"
              }, { "isInitial": "true",
                "name": "banana"
              } ]
            }
          </script>
      </amp-state>
      <template type="amp-mustache">
          {{#isInitial}}
            <div class="product" data-value="{{name}}">
              <amp-img class="trending" width="24" height="24" src="/static/samples/img/trending.png"></amp-img>
              <span class="name-and-description">{{name}}</span>
            </div>
          {{/isInitial}}
          {{^isInitial}}
            <div data-value="{{name}}" class="product">
              <div class="name-and-description">
                  <div class="product-name">{{emoji}} <b>{{name}}</b> <i>{{price}}</i></div>
              </div>
            </div>
          {{/isInitial}}
        </template>
      </amp-autocomplete>
    <input type="submit" value="Search">
    <div submit-success>
      <template type="amp-mustache">
        Success! Added <strong>{{product}}</strong> to your cart.
      </template>
    </div>
    <div submit-error>
      Error!
    </div>
  </form>
</div>

<h2>Inline autocomplete</h2>

内联显示建议

可以通过使用 inline 属性在 amp-autocomplete 中为单个输入中的多个自动建议在指定字符标记上触发建议。

用于触发自动建议的标记必须是为 inline 属性提供的值。例如，如果 inline="+"，则当用户输入 + 标记时，将显示任何相关的建议。否则，该字段的行为将与未增强的输入字段相同。inline 属性不支持空字符串或 "" 作为 amp-autocomplete 上的合法标记值。

<form class="sample-form" method="post" action-xhr="https://amp.org.cn/documentation/examples/api/echo" target="_top">
  <amp-autocomplete filter="prefix" inline="+" min-characters="0" filter-value="name">
      <textarea autoexpand rows="2" placeholder="Type your message here" name="message"></textarea>
    <template type="amp-mustache">
      <div class="close-friends" data-value="{{ email }}">
        <amp-img class="profile-pic" height="20" width="20" layout="responsive" alt="Profile picture of AMP logo" src="/static/samples/img/favicon.png"></amp-img>
        <div class="info">
          <div>{{ name }}</div>
          <div class="custom">{{ email }}</div>
        </div>
      </div>
    </template>
    <script type="application/json">
      {
        "items": [
          {"email": "harrypotter@hogwarts.edu", "name": "Harry Potter"},
          {
            "email": "albusdumbledore@hogwarts.edu",
            "name": "Albus Dumbledore"
          },
          {
            "email": "voldemort@deatheater.org",
            "name": "Tom Marvolo Riddle"
          },
          {"email": "severussnape@hogwarts.edu", "name": "Severus Snape"},
          {"email": "siriusblack@hogwarts.edu", "name": "Sirius Black"},
          {
            "email": "hermionegranger@hogwarts.edu",
            "name": "Hermione Granger"
          },
          {"email": "ronweasley@hogwarts.edu", "name": "Ron Weasley"},
          {"email": "dracomalfoy@hogwarts.edu", "name": "Draco Malfoy"},
          {
            "email": "nevillelongbottom@hogwarts.edu",
            "name": "Neville Longbottom"
          },
          {"email": "rubeushagrid@hogwarts.edu", "name": "Rubeus Hagrid"},
          {"email": "dobby@hogwarts.edu", "name": "Dobby"},
          {
            "email": "bellatrixlestrange@deatheater.org",
            "name": "Bellatrix Lestrange"
          },
          {
            "email": "minervamcgonagall@hogwarts.edu",
            "name": "Minerva McGonagall"
          }
        ]
      }
    </script>
  </amp-autocomplete>
  <input type="submit" value="Search">
  <div submit-success>
    <template type="amp-mustache">
      Success! <strong>{{message}}</strong>
    </template>
  </div>
  <div submit-error>
    Error!
  </div>
</form>

指定查询参数

当 query 属性与 src 属性配对时，可以将用户输入传递到静态生成的端点。

例如，如果 src="https://example.com 和 query="q"，则键入 abc 的用户将从 https://example.com?q=abc 获取 JSON 结果。

<form class="sample-form" method="post" action-xhr="https://amp.org.cn/documentation/examples/api/echo" target="_top">
  <amp-autocomplete filter="none" min-characters="1" src="https://amp.org.cn/samples_templates/products_autosuggest" query="q">
    <input type="search" name="queryInput">
    </amp-autocomplete>
  <input type="submit" value="Search">
  <div submit-success>
    <template type="amp-mustache">
      Success! Received <strong>{{queryInput}}</strong>.
    </template>
  </div>
</form>

需要进一步解释？

如果此页面上的解释没有涵盖您的所有问题，请随时与其他 AMP 用户联系，讨论您的确切用例。

转到 Stack Overflow

一个未解释的功能？

AMP 项目强烈鼓励您的参与和贡献！我们希望您能成为我们开源社区的持续参与者，但我们也欢迎您为您特别感兴趣的问题进行一次性贡献。

在 GitHub 上编辑示例