网站

amp-form

简介

amp-form 扩展允许在 AMP 文档中使用表单和输入字段。 amp-form 允许 HTTP 和 XHR (XMLHttpRequest) 表单提交。 HTTP 表单提交会加载一个新页面，而 XHR 表单提交则不需要页面重新加载。

amp-form 扩展还允许您使用 submit-success 和 submit-error 特殊属性呈现成功和错误响应。有关使用详情，请参阅关于成功/错误响应呈现的 amp-form 文档。

设置

导入 amp-form 扩展。

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

amp-mustache 用于客户端渲染表单响应。

<script async custom-template="amp-mustache" src="https://cdn.ampproject.org/v0/amp-mustache-0.2.js"></script>

使用页面重新加载的表单提交

使用 action 属性来指定一个应处理表单输入的服务器端点。这仅适用于 GET 请求。URL 必须是 HTTPS。以下示例使用 type="search" 来模拟搜索。搜索按钮将触发页面重新加载。

请阅读安全注意事项，了解何时使用 GET 或 POST 的最佳实践。

您可以在 /examples/api/amp-form.js 中找到此演示中使用的服务器端点的代码。

<form class="sample-form" method="GET" action="/documentation/examples/api/submit-form" target="_top">
  <input type="search" placeholder="Search..." name="search">
  <input type="submit" value="OK">
</form>

使用客户端渲染的表单提交

使用 action-xhr 属性通过 XMLHttpRequest (XHR) 提交表单。您可以使用 amp-mustache 模板来客户端渲染 POST 响应。可以使用服务器端点作为 JSON 发送的数据来显示自定义的成功或错误消息。例如，如果服务器发送 {"foo": "bar"}，您可以在模板中使用 {{foo}} 来呈现 bar。

amp-form 组件会根据响应显示 submit-success 或 submit-error 元素，并在这两个元素内呈现模板数据。submit-success 和 submit-error 元素必须是 form 的直接子元素。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-input-text-xhr" target="_top">
  <input type="text" name="name" placeholder="Name..." required>
  <input type="email" name="email" placeholder="Email..." required>
  <input type="submit" value="Subscribe">
  <div submit-success>
    <template type="amp-mustache">
      Success! Thanks {{name}} for trying the <code>amp-form</code> demo! Try to insert the word "error" as a name input in the form to see how <code>amp-form</code> handles errors.
    </template>
  </div>
  <div submit-error>
    <template type="amp-mustache">
      Error! Thanks {{name}} for trying the <code>amp-form</code> demo with an error response.
    </template>
  </div>
</form>

表单自定义验证

amp-form 扩展允许您通过使用 custom-validation-reporting 来构建自己的自定义验证 UI，请在此处阅读关于不同策略的信息。

使用 show-all-on-submit 策略来确保在用户提交表单时显示所有验证消息。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-input-text-xhr" target="_top" custom-validation-reporting="show-all-on-submit">
  <input type="text" id="show-all-on-submit-name" name="name" placeholder="Name..." required pattern="\p{L}+\s\p{L}+">
  <span visible-when-invalid="valueMissing" validation-for="show-all-on-submit-name"></span>
  <span visible-when-invalid="patternMismatch" validation-for="show-all-on-submit-name">
    Please enter your first and last name separated by a space (e.g. Jane Miller)
  </span>
  <input type="email" id="show-all-on-submit-email" name="email" placeholder="Email..." required>
  <span visible-when-invalid="valueMissing" validation-for="show-all-on-submit-email"></span>
  <span visible-when-invalid="typeMismatch" validation-for="show-all-on-submit-email"></span>
  <input type="submit" value="Subscribe">
  <div submit-success>
    <template type="amp-mustache">
      Success! Thanks {{name}} for trying the <code>amp-form</code> demo! Try to insert the word "error" as a name input in the form to see how <code>amp-form</code> handles errors.
    </template>
  </div>
  <div submit-error>
    <template type="amp-mustache">
      Error! Thanks {{name}} for trying the <code>amp-form</code> demo.
    </template>
  </div>
</form>

使用 show-first-on-submit 策略在用户提交表单时显示第一个验证消息。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-input-text-xhr" target="_top" custom-validation-reporting="show-first-on-submit">
  <input type="text" id="show-first-on-submit-name" name="name" placeholder="Name..." required pattern="\p{L}+\s\p{L}+">
  <span visible-when-invalid="valueMissing" validation-for="show-first-on-submit-name"></span>
  <span visible-when-invalid="patternMismatch" validation-for="show-first-on-submit-name">
    Please enter your first and last name separated by a space (e.g. Jane Miller)
  </span>
  <input type="email" id="show-first-on-submit-email" name="email" placeholder="Email..." required>
  <span visible-when-invalid="valueMissing" validation-for="show-first-on-submit-email"></span>
  <span visible-when-invalid="typeMismatch" validation-for="show-first-on-submit-email"></span>
  <input type="submit" value="Subscribe">
  <div submit-success>
    <template type="amp-mustache">
      Success! Thanks {{name}} for trying the <code>amp-form</code> demo! Try to insert the word "error" as a name input in the form to see how <code>amp-form</code> handles errors.
    </template>
  </div>
  <div submit-error>
    <template type="amp-mustache">
      Error! Thanks {{name}} for trying the <code>amp-form</code> demo with an error response.
    </template>
  </div>
</form>

使用 as-you-go 策略在用户与表单交互时显示验证消息。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-input-text-xhr" target="_top" custom-validation-reporting="as-you-go">
  <input type="text" id="as-you-go-name" name="name" placeholder="Name..." required pattern="\p{L}+\s\p{L}+">
  <span visible-when-invalid="valueMissing" validation-for="as-you-go-name"></span>
  <span visible-when-invalid="patternMismatch" validation-for="as-you-go-name">
    Please enter your first and last name separated by a space (e.g. Jane Miller)
  </span>
  <input type="email" id="as-you-go-email" name="email" placeholder="Email..." required>
  <span visible-when-invalid="valueMissing" validation-for="as-you-go-email"></span>
  <span visible-when-invalid="typeMismatch" validation-for="as-you-go-email"></span>
  <input type="submit" value="Subscribe">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

表单验证

表单验证支持对表单字段进行异步验证。当用户填写启用了验证的表单时，amp-form 会将字段发送到 verify-xhr URL，以便使用服务器上的逻辑检查其值。如果发现错误（例如用户名已被占用），它将作为表单中的验证错误显示。请在此处阅读完整的文档。

使用 verify-xhr 属性启用表单验证功能。

表单验证可以与使用 visible-when-invalid="customError" 的自定义错误报告相结合。当 amp-form 从 XHR 响应中收到错误时，它会在违规元素上设置 customError 有效性。由于 AMP 使用 HTML5 表单约束验证 API，因此表单验证错误很容易与标准表单验证消息进行交互。

在 submit-error 模板中，您可以使用 verifyErrors 列表来选择如何呈现验证错误消息。仅当用户在异步验证响应完成之前提交表单时，这些消息才会显示。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/verify-form-input-text-xhr" verify-xhr="/documentation/examples/api/verify-form-input-text-xhr" target="_top" custom-validation-reporting="as-you-go">
  <input type="text" id="verification-username" name="username" placeholder="Username..." required pattern="\w+">
  <span visible-when-invalid="customError" validation-for="verification-username">That username is already taken</span>
  <span visible-when-invalid="patternMismatch" validation-for="verification-username">Invalid character in username</span>
  <input type="submit" value="Check">
  <div submit-success>
    <template type="amp-mustache">
      Success! Thanks {{name}} for trying the <code>amp-form</code> demo! Try to insert the word "error" as a name input in the form to see how <code>amp-form</code> handles errors.
    </template>
  </div>
  <div submit-error>
    <template type="amp-mustache">
      {{#verifyErrors}}
      <p>{{message}}</p>
      {{/verifyErrors}}
      {{^verifyErrors}}
      <p>Something went wrong. Try again later?</p>
      {{/verifyErrors}}
      <p>Submission failed</p>
    </template>
  </div>
</form>

重置/清除表单输入

您可以使用 <input type="reset"> 或 clear 操作来清除输入字段。

<form class="sample-form" id="formResetSample" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="text" placeholder="Some text...">
  <input type="submit" value="OK">
  <input type="reset" value="Reset">
  <button type="button" on="tap:formResetSample.clear">Clear input</button>
</form>

成功提交后隐藏输入字段

使用 amp-form-submit-success 类在成功提交后隐藏输入字段。以下 CSS 规则在成功提交表单后隐藏所有表单输入字段

form.amp-form-submit-success > input {
  display: none
}

<form class="sample-form hide-inputs" method="post" action-xhr="/documentation/examples/api/submit-form-input-text-xhr" target="_top">
  <input type="text" name="name" placeholder="Name..." required>
  <input type="submit" value="Subscribe">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

输入类型=日期

amp-form 支持所有 HTML5 表单类型，但文件和图像除外。建议对应该包含日期的输入字段使用 amp-date-picker 组件。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input name="select-date" type="date" value="2020-12-30">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

输入类型=月份

对应该包含月份的输入字段使用 type="month"。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input name="select-month" type="month" value="2020-12">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
   Error!
  </div>
</form>

输入类型=周

对应该包含周的输入字段使用 type="week"。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="week" name="week_year">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

输入类型=日期时间-本地

对应该包含日期和时间的输入字段使用 type="datetime-local"。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input name="select-datetime" type="datetime-local" value="2020-12-30T12:34:56">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

输入类型=时间

对应该包含时间的输入字段使用 type="time"。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="time" name="time_now">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

输入类型=复选框

使用 type="checkbox" 让用户从有限数量的选项中选择零个或多个选项。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="checkbox" id="animal1" name="animal1" value="Cats">
  <label for="animal1">I like cats</label>
  <input type="checkbox" id="animal2" name="animal2" value="Dogs">
  <label for="animal2"> I like dogs </label>
  <button type="submit" value="OK">OK</button>
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

输入类型=电子邮件

对应该包含电子邮件地址的输入字段使用 type="email"。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="email" name="email" placeholder="Email...">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

输入类型=隐藏

使用 type="hidden" 来定义用户不可见的字段。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="hidden" name="city" value="London">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

输入类型=数字

对应该包含数字值的输入字段使用 type="number"。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="number" name="quantity" min="1" max="5">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

输入类型=单选按钮

使用 type="radio" 让用户从有限数量的选项中仅选择一个选项。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="radio" id="cat" name="favourite animal" value="cat" checked>
  <label for="cat">Cat</label>
  <input type="radio" id="dog" name="favourite animal" value="dog">
  <label for="dog">Dog</label>
  <input type="radio" id="other" name="favourite animal" value="other">
  <label for="other">Other</label>
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

输入类型=范围

对应该包含范围内的值的输入字段使用 type="range"。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="range" name="points" min="0" max="10">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

输入类型=电话

对应该包含电话号码的输入字段使用 type="tel"。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="tel" name="my_tel" placeholder="Telephone...">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

输入类型=网址

对应该包含 URL 地址的输入字段使用 type="url"。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="url" placeholder="URL..." name="website">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

输入类型=密码

对于安全的 POST 表单内的隐藏文本输入，请使用 type="password"。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <input type="password" placeholder="Password..." name="pw">
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

输入选择

对下拉列表使用 select 元素。

<form class="sample-form" method="post" action-xhr="/documentation/examples/api/submit-form-xhr" target="_top">
  <select name="cars" id="cars">
    <option value="volvo">Volvo</option>
    <option value="saab">Saab</option>
    <option value="fiat">Fiat</option>
    <option value="audi">Audi</option>
  </select>
  <label for="cars">Select a car</label>
  <input type="submit" value="OK">
  <div submit-success>
    Success!
  </div>
  <div submit-error>
    Error!
  </div>
</form>

需要进一步解释？

如果本页上的解释没有涵盖您的所有问题，请随时与其他 AMP 用户联系，讨论您的确切用例。

转到 Stack Overflow

未解释的功能？

AMP 项目强烈鼓励您的参与和贡献！我们希望您成为我们开源社区的长期参与者，但我们也欢迎您针对您特别关注的问题进行一次性贡献。

在 GitHub 上编辑示例

撰写者： @kul3r4