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 扩展组件还提供 polyfill，用于处理浏览器中的某些缺失行为。

您必须先为 <amp-form> 扩展组件添加所需脚本，然后再创建 <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>

属性

target

用于指明提交表单后表单回应的显示位置。该值必须为 _blank 或 _top。

action

用于指定处理表单输入的服务器端点。该值必须是 https 网址（绝对网址或相对网址），且不得是指向 CDN 的链接。

• 对于 method=GET：使用此属性或 action-xhr。
• 对于 method=POST：使用 action-xhr 属性。

action-xhr

用于指定通过 XMLHttpRequest (XHR) 处理表单输入和提交表单的服务器端点。XHR 请求（有时称为 AJAX 请求）是指浏览器无需完全加载页面或打开新页面即可发出的请求。浏览器会使用 Fetch API（如果有）在后台发送请求，而旧版浏览器则会回退为使用 XMLHttpRequest API。

对于 method=POST，此属性是必需项，而对于 method=GET，此属性是可选项。

action-xhr 与 action 的值可以是相同的端点，也可以是不同的端点，且需要遵守上述 action 要求。

如需了解如何在成功提交表单后重定向用户，请参阅下面的提交后重定向部分。

其他表单属性

所有其他表单属性都是可选的。

custom-validation-reporting

这是一个可选属性，可用于启用和选择自定义验证报告策略。有效值包括：show-first-on-submit、show-all-on-submit 或 as-you-go。

如需了解更多详情，请参阅自定义验证部分。

输入和字段

支持的内容：

• 其他与表单相关的元素，包括：<textarea>、<select>、<option>、<fieldset>、<label>、<input type=text>、<input type=submit> 等等。
• <form method=POST action-xhr> 中的 <input type=password> 和 <input type=file>。
• amp-selector

不支持的内容：

• <input type=button>、<input type=image>
• 输入时大部分与表单相关的属性，包括：form、formaction、formtarget、formmethod 等等。

（将来我们可能会重新考虑放松上述部分规则 - 如果您需要这些规则，请告知我们并提供相关用例）。

如需详细了解有效输入和字段，请参阅 AMP 验证工具规范中的 amp-form 规则。

操作

amp-form 提供了以下操作：

事件

amp-form 提供了以下事件：

您可以通过 on 属性使用这些事件。

例如，以下代码会监听 submit-success 和 submit-error 事件，并显示不同的灯箱，具体取决于对应的事件：

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

如需查看完整示例，请点击此处。

输入事件

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>

如需查看完整示例，请点击此处。

分析触发器

amp-form 扩展组件会触发以下事件，您可以在 amp-analytics 配置中跟踪这些事件：

您可以对分析进行配置，以发送这些事件，如下例所示：

<amp-analytics>
  <script type="application/json">
    {
      "requests": {
        "event": "https://www.example.com/analytics/event?eid=${eventId}",
        "searchEvent": "https://www.example.com/analytics/search?formId=${formId}&query=${formFields[query]}"
      },
      "triggers": {
        "formSubmit": {
          "on": "amp-form-submit",
          "request": "searchEvent"
        },
        "formSubmitSuccess": {
          "on": "amp-form-submit-success",
          "request": "event",
          "vars": {
            "eventId": "form-submit-success"
          }
        },
        "formSubmitError": {
          "on": "amp-form-submit-error",
          "request": "event",
          "vars": {
            "eventId": "form-submit-error"
          }
        }
      }
    }
  </script>
</amp-analytics