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>

输入和字段

允许

不允许

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

有关有效输入和字段的详细信息，请参阅 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 作为在具有 submit-success 和 submit-error 属性的元素上设置的 template 属性的值，在文档前面定义的引用模板中渲染响应。

<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 表单为 <textarea> 元素提供 autoexpand 属性。这允许文本区域扩展和收缩以适应用户的输入行，直到字段的最大大小。如果用户手动调整字段大小，则将删除自动展开行为。

<textarea autoexpand></textarea>

Polyfills

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

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

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

用户交互伪类

:user-invalid 和 :user-valid 伪类是 未来的 CSS 选择器 4 规范的一部分，引入它们是为了更好地钩住基于几个条件设置无效/有效字段的样式。

:invalid 和 :user-invalid 之间的主要区别之一是它们何时应用于元素。在用户与该字段进行重要交互之后（例如，用户在字段中键入或从字段中移开焦点）应用 :user-invalid 类。

amp-form 扩展提供了 类来 polyfill 这些伪类。amp-form 扩展还将这些伪类传播到祖先 form。但是，fieldset 元素始终仅设置为具有类“user-valid”，以与浏览器行为保持一致。

<textarea> 验证

正则表达式匹配是大多数输入元素原生支持的常见验证功能，但 <textarea> 除外。我们 polyfill 此功能并支持 <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 元素公开以下操作。

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

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

请参阅 此处的完整示例，了解如何使用它们。

验证

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