amp-form

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

用法

amp-form 擴充功能允許您建立表單 (<form>) 以在 AMP 文件中提交輸入欄位。 amp-form 擴充功能也為瀏覽器中某些缺失的行為提供 polyfills (填補程式)。

在建立 <form> 之前，您必須包含 <amp-form> 擴充功能的必要指令碼，否則您的文件將無效。 如果您使用 input 標籤的目的不是提交其值（例如，不在 <form> 內的輸入），則不需要載入 amp-form 擴充功能。

<form method="post"
    action-xhr="https://example.com/subscribe"    target="_top">
    <fieldset>
      <label>
        <span>Name:</span>
        <input type="text"
          name="name"
          required>
      </label>
      <br>
      <label>
        <span>Email:</span>
        <input type="email"
          name="email"
          required>
      </label>
      <br>
      <input type="submit"
        value="Subscribe">
    </fieldset>
    <div submit-success>
      <template type="amp-mustache">
        Subscription successful!
      </template>
    </div>
    <div submit-error>
      <template type="amp-mustache">
        Subscription failed!
      </template>
    </div>
  </form>

輸入和欄位

允許

• 其他表單相關元素，包括： <textarea>、 <select>、 <option>、 <fieldset>、 <label>、 <input type=text>、 <input type=submit> 等。
• amp-selector

不允許

• <input type=button>、 <input type=image>
• <input type=password> 和 <input type=file>
• 輸入上的大多數表單相關屬性，包括： form、 formaction、 formtarget、 formmethod 等。

（未來可能會重新考慮放寬其中一些規則 - 如果您需要這些規則並提供使用案例，請告訴我們）。

有關有效輸入和欄位的詳細資訊，請參閱 AMP 驗證器規範中的 amp-form 規則。

成功和錯誤回應呈現

您可以使用 amp-mustache 在表單中呈現成功或錯誤回應，或透過 amp-bind 和下列回應屬性進行資料繫結以呈現成功回應

使用範本呈現回應

• 將回應屬性套用到 <form> 元素的任何後代。
• 透過在子元素中包含 <template></template> 或 <script type="text/plain"></script> 標籤，或透過 template="id_of_other_template" 屬性參考範本，在子元素中呈現回應。
• 為 submit-success 和 submit-error 的回應提供有效的 JSON 物件。 成功和錯誤回應都應具有 Content-Type: application/json 標頭。

在以下範例中，回應在表單內的內嵌範本中呈現。

<form ...>
  <fieldset>
    <input type="text" name="firstName" />
    ...
  </fieldset>
  <div submitting>
    Form submitting... Thank you for waiting.
  </div>
  <div submit-success>
    <template type="amp-mustache">
      Success! Thanks {{name}} for subscribing! Please make sure to check your
      email {{email}} to confirm! After that we'll start sending you weekly
      articles on {{#interests}}<b>{{name}}</b> {{/interests}}.
    </template>
  </div>
  <div submit-error>
    <template type="amp-mustache">
      Oops! {{name}}, {{message}}.
    </template>
  </div>
</form>

發佈者的 action-xhr 端點傳回以下 JSON 回應

成功時

{
  "name": "Jane Miller",
  "interests": [
    {"name": "Basketball"},
    {"name": "Swimming"},
    {"name": "Reading"}
  ],
  "email": "email@example.com"
}

錯誤時

{
  "name": "Jane Miller",
  "message": "The email (email@example.com) you used is already subscribed."
}

您可以使用範本的 ID 作為 template 屬性的值，並在具有 submit-success 和 submit-error 屬性的元素上設定，以在先前在文件中定義的參考範本中呈現回應。

<template type="amp-mustache" id="submit_success_template">
  Success! Thanks {{name}} for subscribing! Please make sure to check your email
{{email}} to confirm! After that we'll start sending you weekly articles on
{{#interests}}<b>{{name}}</b> {{/interests}}.
</template>
<template type="amp-mustache" id="submit_error_template">
  Oops! {{name}}, {{message}}.
</template>

<form ...>
  <fieldset>
    ...
  </fieldset>
  <div submit-success template="submit_success_template"></div>
  <div submit-error template="submit_error_template"></div>
</form>

請參閱此處的完整範例。

使用資料繫結呈現成功回應

• 使用 on 屬性 將表單的 *submit-success* 屬性繫結到 AMP.setState()。
• 使用 event 屬性來擷取回應資料。
• 將 state 屬性新增到所需的元素以繫結表單回應。

以下範例示範了使用 amp-bind 的表單 submit-success 回應

<p [text]="'Thanks, ' + subscribe +'! You have successfully subscribed.'">
  Subscribe to our newsletter
</p>
<form
  method="post"
  action-xhr="/components/amp-form/submit-form-input-text-xhr"
  target="_top"
  on="submit-success: AMP.setState({'subscribe': event.response.name})"
>
  <div>
    <input type="text" name="name" placeholder="Name..." required />
    <input type="email" name="email" placeholder="Email..." required />
  </div>
  <input type="submit" value="Subscribe" />
</form>

當表單成功提交時，它將傳回類似以下的 JSON 回應

{
  "name": "Jane Miller",
  "email": "email@example.com"
}

然後 amp-bind 會更新 <p> 元素的文字以符合 subscibe 狀態

...
<p [text]="'Thanks, ' + subscribe +'! You have successfully subscribed.'">
  Thanks Jane Miller! You have successfully subscribed.
</p>
...

自動展開

AMP Form 為 <textarea> 元素提供了 autoexpand 屬性。 這允許 textarea 擴展和收縮以容納使用者的輸入行，直到欄位的最大大小。 如果使用者手動調整欄位大小，則自動擴展行為將被移除。

<textarea autoexpand></textarea>

Polyfills (填補程式)

amp-form 擴充功能為某些瀏覽器中缺失或在下一個 CSS 版本中實作的行為和功能提供 polyfills (填補程式)。

無效提交封鎖和驗證訊息泡泡

使用 webkit 型引擎的瀏覽器目前（截至 2016 年 8 月）不支援無效的表單提交。 這些包括所有平台上的 Safari 和所有 iOS 瀏覽器。 amp-form 擴充功能填補了此行為以阻止任何無效的提交，並在無效的輸入上顯示驗證訊息泡泡。

使用者互動虛擬類別

:user-invalid 和 :user-valid 虛擬類別是 未來 CSS Selectors 4 規範 的一部分，並且引入了這些類別，以便根據一些條件更好地掛鉤樣式無效/有效欄位。

:invalid 和 :user-invalid 之間的主要區別之一是它們何時應用於元素。 :user-invalid 類別是在使用者與欄位進行重要互動後應用的（例如，使用者在欄位中輸入內容，或從欄位中模糊）。

amp-form 擴充功能提供 類別 來填補這些虛擬類別。 amp-form 擴充功能也會將這些傳播到祖先 form。 但是，fieldset 元素始終設定為具有類別 'user-valid'，以與瀏覽器行為一致。

<textarea> 驗證

正規表示式匹配是大多數輸入元素原生支援的常見驗證功能，但 <textarea> 除外。 我們填補了此功能並支援 <textarea> 元素上的 pattern 屬性。

安全考量

防範 XSRF

除了遵循 AMP CORS 規範 中的詳細資訊外，請特別注意 "處理狀態變更請求" 部分，以防範 XSRF 攻擊，攻擊者可以在使用者不知情的情況下使用目前的使用者會話執行未經授權的指令。

一般來說，在接受使用者的輸入時，請記住以下幾點

• 僅將 POST 用於狀態變更請求。
• 僅將非 XHR GET 用於導航目的（例如搜尋）。
  • 非 XHR GET 請求將不會收到準確的 origin/headers，並且後端將無法使用上述機制來防範 XSRF。
  • 一般來說，僅將 XHR/非 XHR GET 請求用於導航或資訊檢索。
• AMP 文件中不允許非 XHR POST 請求。 這是由於在這些請求上跨瀏覽器設定 Origin 標頭的不一致性，以及支援它會在防範 XSRF 時引入的複雜性。 這可能會在以後重新考慮和引入 — 如果您認為需要，請提交問題。

屬性

action-xhr

指定一個伺服器端點來處理表單輸入並透過 XMLHttpRequest (XHR) 提交表單。 XHR 請求（有時稱為 AJAX 請求）是指瀏覽器在不完全載入頁面或開啟新頁面的情況下發出請求。 瀏覽器將使用 Fetch API（如果可用）並回退到 XMLHttpRequest API（對於較舊的瀏覽器）在背景中發送請求。

對於 method=POST，此屬性是必需的，對於 method=GET，此屬性是可選的。

action-xhr 的值可以與 action 相同或不同的端點，並且具有與上述相同的 action 要求。

其他表單屬性

所有其他 表單屬性 都是可選的。

無效的 AMP 電子郵件屬性

AMP for Email 規範不允許在 AMP 電子郵件格式上使用以下屬性。

• action
• name
• target
• verify-xhr

動作

amp-form 元素公開以下動作。

submit

允許您在特定動作上觸發表單提交，例如，點擊連結或 在輸入變更時提交表單。

clear

清空表單中每個輸入的值。 這可以讓使用者快速地再次填寫表單。

活動

將 amp-form 事件與 on 屬性 一起使用

以下範例偵聽 submit-success 和 submit-error 事件，並根據事件顯示不同的燈箱

<form
  ...
  on="submit-success:success-lightbox;submit-error:error-lightbox"
  ...
></form>

submit

表單已提交，並且提交尚未完成。

submit-success

表單提交已完成，並且回應成功。

submit-error

表單提交已完成，並且回應錯誤。

輸入事件

AMP 在子 <input> 元素上公開 change 和 input-debounced 事件。 這允許您使用 on 屬性 在輸入值變更時對任何元素執行動作。

例如，一個常見的用例是在輸入變更時提交表單（選擇單選按鈕以回答投票，從 select 輸入中選擇語言以翻譯頁面等）。

<form id="myform"
    method="post"
    action-xhr="https://example.com/myform"    target="_blank">
    <fieldset>
      <label>
        <input name="answer1"
          value="Value 1"
          type="radio"
          on="change:myform.submit">Value 1
      </label>
      <label>
        <input name="answer1"
          value="Value 2"
          type="radio"
          on="change:myform.submit">Value 2
      </label>
    </fieldset>
  </form>

請參閱此處的完整範例。

樣式設定

類別和 CSS 掛鉤

amp-form 擴充功能為發佈者提供了類別和 CSS 掛鉤，以設定其表單和輸入的樣式。

以下類別可用於指示表單提交的狀態

• .amp-form-initial
• .amp-form-verify
• .amp-form-verify-error
• .amp-form-submitting
• .amp-form-submit-success
• .amp-form-submit-error

以下類別是 使用者互動虛擬類別的 polyfill (填補程式)

• .user-valid
• .user-invalid

發佈者可以使用這些類別來設定其輸入和欄位集的樣式，以回應使用者動作（例如，在使用者從其模糊後用紅色邊框突出顯示無效的輸入）。

請參閱此處的完整範例，瞭解如何使用這些。

驗證

請參閱 AMP 驗證器規範中的 amp-form 規則。