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。

在创建 <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>

输入和字段

允许

不允许

（未来可能会重新考虑放宽其中一些规则 - 如果您需要这些规则并提供了用例，请告知我们）。

有关有效输入和字段的详细信息，请参阅 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 标头。

在以下示例中，响应呈现在表单内的内联模板中。

发布者的 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 autoexpand></textarea>

Polyfill

amp-form 扩展为某些浏览器中缺少或在下一版本的 CSS 中实现的行为和功能提供了 polyfill。

阻止无效提交和验证消息气泡

截至 2016 年 8 月，使用基于 Webkit 的引擎的浏览器目前不支持无效的表单提交。其中包括所有平台上的 Safari 和所有 iOS 浏览器。amp-form 扩展将此行为 polyfill 为阻止任何无效提交，并在无效输入上显示验证消息气泡。

用户交互伪类

: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 请求不会接收准确的来源/标头，并且后端将无法使用上述机制防止 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-form 元素公开以下操作。

提交

允许您在特定操作（例如，点击链接或 在输入更改时提交表单）上触发表单提交。

清除

清空表单中每个输入的值。这可以让用户快速第二次填写表单。

活动

将 on 属性 与 amp-form 事件结合使用

以下示例同时侦听 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>

请参阅此处的完整示例。

样式

类和 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

以下类是 用户交互伪类的填充

• .user-valid
• .user-invalid

发布商可以使用这些类来设置其输入和字段集的样式，以便对用户操作做出响应（例如，在用户离开无效输入后用红色边框突出显示）。

请参阅此处有关如何使用它们的完整示例。

验证

请参阅 AMP 验证器规范中的amp-form 规则。