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>

當搭配 amp-autocomplete 使用 src 屬性時，來自端點的回應包含要在指定範本中呈現的資料。

您可以用兩種方式之一指定範本

• 參考現有範本元素 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>

屬性

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

遠端端點的 URL，該端點傳回將在此 amp-autocomplete 中過濾和呈現的 JSON。這必須是 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

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 規則。