amp-autocomplete

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

用法

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

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

範例

<amp-autocomplete
  id="myAutocomplete"
  src="/static/samples/json/amp-autocomplete-cities.json"
>
  <input />
  <template type="amp-mustache">
    <div data-value="{{.}}">{{.}}</div>
  </template>
</amp-autocomplete>

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

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

• template 屬性，參照現有範本元素的 ID。
• 直接巢狀內嵌於 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

遠端端點的網址，傳回將在此 amp-autocomplete 中篩選和呈現的 JSON。這必須是 CORS HTTP 服務，且網址的協定必須是 HTTPS。端點必須實作 AMP 中的 CORS 要求 規格中指定的規定。如果擷取 src 網址中的資料失敗，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"。以下為使用和不使用的範例

請注意，以下資料由遠端 src 傳回

{
  "items" : ["apples", "bananas", "pears"],
  "fruit" : ["kiwis", "oranges", "watermelons"]
}

<amp-autocomplete src="/static/samples/json/amp-autocomplete-fruit-items.json">
  <input type="text">
</amp-autocomplete>

<amp-autocomplete src="/static/samples/json/amp-autocomplete-fruit-items.json" items="fruit">
  <input type="text">
</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
  id="myAutocomplete"
  on="select:AMP.setState({chosenFruit: event.value})"
  src="/static/samples/json/amp-autocomplete-fruit.json"
>
  <input />
  <template type="amp-mustache">
    <div data-value="{{name}}">{{name}}</div>
  </template>
</amp-autocomplete>
<p [text]="'Your fruit: ' + chosenFruit">
  No fruit selected
</p>

驗證

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