網站

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>

輸入類型=日期

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>

輸入類型=月份

對於應包含月份的輸入欄位，請使用 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>

輸入類型=週

對於應包含週的輸入欄位，請使用 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>

輸入類型=日期時間-本地

對於應包含日期和時間的輸入欄位，請使用 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>

輸入類型=時間

對於應包含時間的輸入欄位，請使用 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>

輸入類型=核取方塊

使用 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>

輸入類型=電子郵件

對於應包含電子郵件地址的輸入欄位，請使用 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>

輸入類型=隱藏

使用 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>

輸入類型=數字

對於應包含數值的輸入欄位，請使用 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>

輸入類型=單選按鈕

使用 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>

輸入類型=範圍

對於應包含範圍內值的輸入欄位，請使用 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>

輸入類型=電話

對於應包含電話號碼的輸入欄位，請使用 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>

輸入類型=網址

對於應包含網址的輸入欄位，請使用 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>

輸入類型=密碼

對於安全 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 撰寫