amp-form

描述

允许您创建表单以在 AMP 文档中提交输入字段。

必需的脚本

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

示例

高级服务器请求会议调查电子邮件在 feed 中动态更新项目文章书签电子邮件订阅设置

用法

amp-form 扩展允许您创建表单 (<form>) 以在 AMP 文档中提交输入字段。amp-form 扩展还为浏览器中一些缺失的行为提供 polyfills。

如果您在表单中提交数据，您的服务器端点必须实现 CORS 安全性的要求。

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

在 playground 中打开此代码片段

输入和字段

允许

其他与表单相关的元素，包括：<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 来呈现成功响应

响应属性	描述
`submit-success`	如果响应成功（即状态为 `2XX`），则可用于显示成功消息。
`submit-error`	如果响应不成功（即状态不是 `2XX`），则可用于显示提交错误。
`提交中`	可用于在表单提交时显示消息。请参阅下面的完整表单示例，了解如何使用 `submitting` 属性。

使用模板渲染响应

将响应属性应用于 <form> 元素的任何后代。
通过在子元素中包含通过 <template></template> 或 <script type="text/plain"></script> 标签的模板，或通过引用具有 template="id_of_other_template" 属性的模板来呈现子元素中的响应。
为 submit-success 和 submit-error 响应提供有效的 JSON 对象。成功和错误响应都应具有 Content-Type: application/json 标头。

当将 <amp-form> 与另一个模板 AMP 组件（如 <amp-list>）结合使用时，请注意模板可能不会在有效的 AMP 文档中嵌套。在这种情况下，一种有效的解决方法是通过 template 属性通过 id 提供模板。了解有关 <amp-mustache> 中的嵌套模板的更多信息。

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

<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 属性来捕获响应数据。
将状态属性添加到所需元素以绑定表单响应。

以下示例演示了带有 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 扩展 polyfills 此行为以阻止任何无效提交，并在无效输入上显示验证消息气泡。

用户交互伪类

: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 用于旧版浏览器。

您的 XHR 端点必须实现 CORS 安全性的要求。

对于 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>

在 playground 中打开此代码片段

请在此处查看完整示例。

样式

类和 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 规则。

需要更多帮助？

您已经阅读此文档十几次了，但它并没有真正涵盖您的所有问题？也许其他人也有同样的感受：在 Stack Overflow 上与他们联系。

转到 Stack Overflow

发现错误或缺少功能？

AMP 项目强烈鼓励您的参与和贡献！我们希望您成为我们开源社区的长期参与者，但我们也欢迎您为自己特别感兴趣的问题做出一次性贡献。

转到 GitHub

amp-form

描述

必需的脚本

示例

用法

输入和字段

允许

不允许

成功和错误响应呈现

使用模板渲染响应

使用数据绑定渲染成功响应

自动展开

Polyfills

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

用户交互伪类

<textarea> 验证

安全注意事项

防止 XSRF

属性

action-xhr

其他表单属性

无效的 AMP 电子邮件属性

操作

submit

clear

活动

submit

submit-success

submit-error

输入事件

样式

类和 CSS 钩子

验证

`<textarea>` 验证

`action-xhr`

`submit`

`clear`

`submit`

`submit-success`

`submit-error`