網站

amp-form

簡介

amp-form 擴充功能允許在 AMP 文件中使用表單和輸入欄位。amp-form 允許 HTTP 和 XHR (XMLHttpRequest) 表單提交。HTTP 表單提交會載入新頁面，而 XHR 表單提交則不需要頁面重新載入。

amp-form 擴充功能也允許您使用 submit-success 和 submit-error 特殊屬性來呈現成功和錯誤回應。如需使用詳情，請參閱 amp-form 文件中有關成功/錯誤回應呈現的說明。

設定

匯入 amp-form 擴充功能。

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

用戶端呈現表單回應需要 amp-mustache。

<script async custom-template="amp-mustache" src="https://cdn.ampproject.org/v0/amp-mustache-0.2.js"></script>

使用頁面重新載入提交表單

使用 action 屬性指定應處理表單輸入的伺服器端點。這僅適用於 GET 請求。網址必須是 HTTPS。以下範例使用 type="search" 來模擬搜尋。搜尋按鈕將觸發頁面重新載入。

請閱讀安全性考量，以瞭解何時使用 GET 或 POST 的最佳做法。

您可以在 /examples/api/amp-form.js 找到此示範中使用的伺服器端點程式碼。

<form class="sample-form" method="GET" action="/documentation/examples/api/submit-form" target="_top">
  <input type="search" placeholder="Search..." name="search">
  <input type="submit" value="OK">
</form>

使用用戶端渲染提交表單

使用 action-xhr 屬性透過 XMLHttpRequest (XHR) 提交表單。您可以使用 amp-mustache 範本來用戶端呈現 POST 回應。可以使用伺服器端點以 JSON 格式傳送的資料，顯示自訂成功或錯誤訊息。例如，如果伺服器傳送 {"foo": "bar"}，您可以在範本中使用 {{foo}} 來呈現 bar。

amp-form 組件會根據回應顯示 submit-success 或 submit-error 元素，並在這些元素內呈現範本資料。submit-success 和 submit-error 元素必須是 form 的直接子元素。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-input-text-xhr" target="_top">
  <input type="text" name="name" placeholder="Name..." required>
  <input type="email" name="email" placeholder="Email..." required>
  <input type="submit" value="Subscribe">
  <div submit-success>
    <template type="amp-mustache">
      Success! Thanks {{name}} for trying the <code>amp-form</code> demo! Try to insert the word "error" as a name input in the form to see how <code>amp-form</code> handles errors.
    </template>
  </div>
  <div submit-error>
    <template type="amp-mustache">
      Error! Thanks {{name}} for trying the <code>amp-form</code> demo with an error response.
    </template>
  </div>
</form>

表單自訂驗證

amp-form 擴充功能允許您透過使用 custom-validation-reporting 建置自己的自訂驗證 UI，請按此處閱讀有關不同策略的資訊。

使用 show-all-on-submit 策略，以確保在使用者提交表單時顯示所有驗證訊息。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-input-text-xhr" target="_top" custom-validation-reporting="show-all-on-submit">
  <input type="text" id="show-all-on-submit-name" name="name" placeholder="Name..." required pattern="\p{L}+\s\p{L}+">
  <span visible-when-invalid="valueMissing" validation-for="show-all-on-submit-name"></span>
  <span visible-when-invalid="patternMismatch" validation-for="show-all-on-submit-name">
    Please enter your first and last name separated by a space (e.g. Jane Miller)
  </span>
  <input type="email" id="show-all-on-submit-email" name="email" placeholder="Email..." required>
  <span visible-when-invalid="valueMissing" validation-for="show-all-on-submit-email"></span>
  <span visible-when-invalid="typeMismatch" validation-for="show-all-on-submit-email"></span>
  <input type="submit" value="Subscribe">
  <div submit-success>
    <template type="amp-mustache">
      Success! Thanks {{name}} for trying the <code>amp-form</code> demo! Try to insert the word "error" as a name input in the form to see how <code>amp-form</code> handles errors.
    </template>
  </div>
  <div submit-error>
    <template type="amp-mustache">
      Error! Thanks {{name}} for trying the <code>amp-form</code> demo.
    </template>
  </div>
</form>

使用 show-first-on-submit 策略，在使用者提交表單時顯示第一個驗證訊息。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-input-text-xhr" target="_top" custom-validation-reporting="show-first-on-submit">
  <input type="text" id="show-first-on-submit-name" name="name" placeholder="Name..." required pattern="\p{L}+\s\p{L}+">
  <span visible-when-invalid="valueMissing" validation-for="show-first-on-submit-name"></span>
  <span visible-when-invalid="patternMismatch" validation-for="show-first-on-submit-name">
    Please enter your first and last name separated by a space (e.g. Jane Miller)
  </span>
  <input type="email" id="show-first-on-submit-email" name="email" placeholder="Email..." required>
  <span visible-when-invalid="valueMissing" validation-for="show-first-on-submit-email"></span>
  <span visible-when-invalid="typeMismatch" validation-for="show-first-on-submit-email"></span>
  <input type="submit" value="Subscribe">
  <div submit-success>
    <template type="amp-mustache">
      Success! Thanks {{name}} for trying the <code>amp-form</code> demo! Try to insert the word "error" as a name input in the form to see how <code>amp-form</code> handles errors.
    </template>
  </div>
  <div submit-error>
    <template type="amp-mustache">
      Error! Thanks {{name}} for trying the <code>amp-form</code> demo with an error response.
    </template>
  </div>
</form>

使用 as-you-go 策略，在使用者與表單互動時顯示驗證訊息。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-input-text-xhr" target="_top" custom-validation-reporting="as-you-go">
  <input type="text" id="as-you-go-name" name="name" placeholder="Name..." required pattern="\p{L}+\s\p{L}+">
  <span visible-when-invalid="valueMissing" validation-for="as-you-go-name"></span>
  <span visible-when-invalid="patternMismatch" validation-for="as-you-go-name">
    Please enter your first and last name separated by a space (e.g. Jane Miller)
  </span>
  <input type="email" id="as-you-go-email" name="email" placeholder="Email..." required>
  <span visible-when-invalid="valueMissing" validation-for="as-you-go-email"></span>
  <span visible-when-invalid="typeMismatch" validation-for="as-you-go-email"></span>
  <input type="submit" value="Subscribe">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

表單驗證

表單驗證功能可對表單欄位進行非同步驗證。當使用者填寫已啟用驗證的表單時，amp-form 會將欄位傳送至 verify-xhr 網址，以使用伺服器端的邏輯檢查其值。如果發現錯誤 (例如使用者名稱已被使用)，則會將其顯示為表單中的驗證錯誤。請按此處閱讀完整文件。

使用 verify-xhr 屬性啟用表單驗證功能。

表單驗證可以結合使用自訂錯誤報告，方法是使用 visible-when-invalid="customError"。當 amp-form 從 XHR 回應收到錯誤時，它會在違規元素上設定 customError 有效性。由於 AMP 使用 HTML5 表單約束驗證 API，因此表單驗證錯誤可以輕鬆地與標準表單驗證訊息互動。

在 submit-error 範本中，您可以選擇如何使用 verifyErrors 清單呈現驗證錯誤訊息。這些訊息僅在使用者在非同步驗證回應完成之前提交表單時才會顯示。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/verify-form-input-text-xhr" verify-xhr="/documentation/examples/api/verify-form-input-text-xhr" target="_top" custom-validation-reporting="as-you-go">
  <input type="text" id="verification-username" name="username" placeholder="Username..." required pattern="\w+">
  <span visible-when-invalid="customError" validation-for="verification-username">That username is already taken</span>
  <span visible-when-invalid="patternMismatch" validation-for="verification-username">Invalid character in username</span>
  <input type="submit" value="Check">
  <div submit-success>
    <template type="amp-mustache">
      Success! Thanks {{name}} for trying the <code>amp-form</code> demo! Try to insert the word "error" as a name input in the form to see how <code>amp-form</code> handles errors.
    </template>
  </div>
  <div submit-error>
    <template type="amp-mustache">
      {{#verifyErrors}}
      <p>{{message}}</p>
      {{/verifyErrors}}
      {{^verifyErrors}}
      <p>Something went wrong. Try again later?</p>
      {{/verifyErrors}}
      <p>Submission failed</p>
    </template>
  </div>
</form>

重設 / 清除表單輸入

您可以使用 <input type="reset"> 或 clear 動作來清除輸入欄位。

<form class="sample-form" id="formResetSample" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="text" placeholder="Some text...">
  <input type="submit" value="OK">
  <input type="reset" value="Reset">
  <button type="button" on="tap:formResetSample.clear">Clear input</button>
</form>

成功提交後隱藏輸入欄位

使用 amp-form-submit-success 類別，在成功提交後隱藏輸入欄位。以下 CSS 規則會在成功提交表單後隱藏所有表單輸入欄位

form.amp-form-submit-success > input {
  display: none
}

<form class="sample-form hide-inputs" method="post" action-xhr="/documentation/examples/api/submit-form-input-text-xhr" target="_top">
  <input type="text" name="name" placeholder="Name..." required>
  <input type="submit" value="Subscribe">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

輸入類型=date

amp-form 支援所有 HTML5 表單類型，但檔案和圖片除外。建議您針對應包含日期的輸入欄位使用 amp-date-picker 組件。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input name="select-date" type="date" value="2020-12-30">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

輸入類型=month

針對應包含月份的輸入欄位使用 type="month"。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input name="select-month" type="month" value="2020-12">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
   Error!
  </div>
</form>

輸入類型=week

針對應包含週的輸入欄位使用 type="week"。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="week" name="week_year">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

輸入類型=datetime-local

針對應包含日期和時間的輸入欄位使用 type="datetime-local"。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input name="select-datetime" type="datetime-local" value="2020-12-30T12:34:56">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

輸入類型=time

針對應包含時間的輸入欄位使用 type="time"。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="time" name="time_now">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

輸入類型=checkbox

使用 type="checkbox" 讓使用者從有限數量的選項中選取零個或多個選項。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="checkbox" id="animal1" name="animal1" value="Cats">
  <label for="animal1">I like cats</label>
  <input type="checkbox" id="animal2" name="animal2" value="Dogs">
  <label for="animal2"> I like dogs </label>
  <button type="submit" value="OK">OK</button>
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

輸入類型=email

針對應包含電子郵件地址的輸入欄位使用 type="email"。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="email" name="email" placeholder="Email...">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

輸入類型=hidden

使用 type="hidden" 定義使用者不可見的欄位。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="hidden" name="city" value="London">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

輸入類型=number

針對應包含數值的輸入欄位使用 type="number"。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="number" name="quantity" min="1" max="5">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

輸入類型=radio

使用 type="radio" 讓使用者從有限數量的選項中僅選取一個選項。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="radio" id="cat" name="favourite animal" value="cat" checked>
  <label for="cat">Cat</label>
  <input type="radio" id="dog" name="favourite animal" value="dog">
  <label for="dog">Dog</label>
  <input type="radio" id="other" name="favourite animal" value="other">
  <label for="other">Other</label>
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

輸入類型=range

針對應包含範圍內值的輸入欄位使用 type="range"。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="range" name="points" min="0" max="10">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

輸入類型=tel

針對應包含電話號碼的輸入欄位使用 type="tel"。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="tel" name="my_tel" placeholder="Telephone...">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

輸入類型=url

針對應包含 URL 位址的輸入欄位使用 type="url"。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="url" placeholder="URL..." name="website">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

輸入類型=password

針對安全 POST 表單內的隱藏文字輸入使用 type="password"。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="password" placeholder="Password..." name="pw">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

輸入選擇

針對下拉式選單使用 select 元素。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <select name="cars" id="cars">
    <option value="volvo">Volvo</option>
    <option value="saab">Saab</option>
    <option value="fiat">Fiat</option>
    <option value="audi">Audi</option>
  </select>
  <label for="cars">Select a car</label>
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

需要進一步說明嗎？

如果此頁面上的說明未能涵蓋您的所有問題，請隨時與其他 AMP 使用者聯繫，討論您的確切使用案例。

前往 Stack Overflow

未說明的特色？

AMP 專案強烈鼓勵您的參與和貢獻！我們希望您能成為我們開放原始碼社群的長期參與者，但我們也歡迎您針對您特別熱衷的問題做出一次性的貢獻。

在 GitHub 上編輯範例

作者 @kul3r4