amp-autocomplete

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

用法

amp-autocomplete 擴充功能應用於根據使用者輸入建議完整項目，以協助使用者更快速地完成工作。

這可用於強化搜尋體驗，適用於使用者可能不知道完整潛在輸入範圍的情況，或是在表單中協助確保可能有多種方式來表達相同意圖的輸入 (例如，使用州縮寫而非全名) 產生更可預測的結果。

範例

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

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

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

屬性

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

透過將結果清單中的第一個項目標記為活動狀態來建議該項目。

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

在第一個範例中，JSON 酬載由「items」索引鍵排入佇列，因此不需要元件屬性，因為預設值與其對應。在第二個範例中，JSON 酬載由「fruit」索引鍵排入佇列，因此 items 屬性會被賦予值 "fruit"，以便準確擷取預期的資料來源。在這兩個範例中，最終使用者互動都是相同的。

inline

amp-autocomplete 應根據完整使用者輸入或僅根據使用者輸入的觸發子字串自動建議。預設情況下，當屬性不存在時，建議將基於完整使用者輸入。屬性不能有空值，但必須採用單一字元符記，即啟動自動完成行為的 @。例如，如果 inline="@"，則使用者輸入 hello 不會擷取建議，但使用者輸入 hello @abc 可能會觸發根據子字串 abc 篩選的選項。目前，觸發的子字串以空白字元分隔，但未來可能會變更。

prefetch

包含 prefetch 屬性以預先擷取遠端資料，以提升使用者的回應速度。需要指定 src。

活動

select

當使用者透過點擊、輕觸、鍵盤導覽或接受 typeahead 選取選項時，amp-autocomplete 會觸發 select 事件。如果使用者使用鍵盤導覽至某個項目並按下 Tab 鍵離開輸入欄位，也會觸發 select 事件。event 包含所選元素的 value 屬性值，即其文字表示法 (例如，data-value 的值)。

如果建議範本包含 data-json={{objToJson}}，則 event 也可能包含 valueAsObject 欄位中的整個物件。這會導致呈現的元素具有 data-json 資料屬性，其中包含對應物件的 JSON 字串表示法，然後可在 event 的 valueAsObject 欄位中使用。

範例

驗證

請參閱 AMP 驗證器規格中的 amp-autocomplete 規則。