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-autocomplete 的数据源需要 amp-bind。

<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 通过修改其 src 值来动态更改 amp-autocomplete 的内容。

<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 属性允许显示但不能搜索或选择，因此它可以用于在结果列表中构建 “标题”，该标题可以将可选择的项目组织成类别。在下面的示例中，“热门杂货”充当禁用项的示例，因为它实际上不是您要视为产品的项目。

内联自动完成

<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 上编辑示例