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.dev.org.tw/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.dev.org.tw/documentation/examples/api/echo" target="_top">
  <amp-autocomplete filter="substring" src="/static/samples/json/amp-autocomplete-cities.json">
    <input>
  </amp-autocomplete>
</form>

動態 `src`

amp-autocomplete 的內容可以透過使用 amp-bind 修改其 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.dev.org.tw/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.dev.org.tw/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 的預設建議可以在使用者 focus 時顯示，方法是使用豐富內容範本化和 amp-autocomplete 上的 min-characters 屬性。

此外，由於範本轉譯項目的 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.dev.org.tw/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>

內嵌顯示建議

在 amp-autocomplete 中，可以使用 inline 屬性，針對單一輸入中的多個自動建議，在指定的字元符記上觸發建議。

用於觸發自動建議的符記必須是為 inline 屬性提供的值。例如，如果 inline="+"，則當使用者輸入 + 符記時，系統會顯示任何相關建議。否則，欄位的行為會與未增強的輸入欄位相同。inline 屬性不支援空字串或 "" 作為 amp-autocomplete 上的合法符記值。

<form class="sample-form" method="post" action-xhr="https://amp.dev.org.tw/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.dev.org.tw/documentation/examples/api/echo" target="_top">
  <amp-autocomplete filter="none" min-characters="1" src="https://amp.dev.org.tw/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 上編輯範例