amp-autocomplete

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

屬性

src

遠端端點的網址，該端點會傳回 JSON，JSON 將在此 amp-autocomplete 中篩選和呈現。這必須是 CORS HTTP 服務，且網址的協定必須是 HTTPS。端點必須實作 AMP 中的 CORS 要求 規格中指定的必要條件。如果擷取 src 網址的資料失敗，amp-autocomplete 會觸發備用機制。如果存在 [src] 屬性，則可以省略 src 屬性。

query

用於產生靜態遠端端點的查詢參數，該端點會傳回 JSON，JSON 將在此 amp-autocomplete 中篩選和呈現。這需要存在 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 鍵主要用於在自動完成功能中選取建議，因此除非開發人員明確設定執行此操作（適用於搜尋欄位/單一欄位表單等），否則 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

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

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

範例

驗證

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