HTMLFormElement

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

* Some parts of this feature may have varying levels of support.

HTMLFormElement 接口表示 DOM 中的 <form> 元素。它允许访问和（在某些情况下）修改表单的各个方面，以及访问其组成元素。

实例属性

此接口还从其父接口 HTMLElement 继承属性。

HTMLFormElement.elements 只读: 包含所有属于此表单元素的表单控件的 HTMLFormControlsCollection。
HTMLFormElement.length 只读: 反映表单中控件的数量的 long 值。
HTMLFormElement.name: 反映表单的 name HTML 属性值的字符串，包含表单的名称。
HTMLFormElement.method: 反映表单的 method HTML 属性值的字符串，表示用于提交表单的 HTTP 方法。只能设置特定的值。
HTMLFormElement.target: 反映表单的 target HTML 属性值的字符串，表示用于显示提交表单的结果的位置。
HTMLFormElement.action: 反映表单的 action HTML 属性值的字符串，包含处理表单提交的信息的程序的 URI。
HTMLFormElement.encoding 或 HTMLFormElement.enctype: 反映表单的 enctype HTML 属性值的字符串，表示用于将表单传输到服务器的内容类型。只能设置特定的值。这两个属性是同义词。
HTMLFormElement.acceptCharset: 反映表单的 accept-charset HTML 属性值的字符串。
HTMLFormElement.autocomplete: 反映表单的 autocomplete HTML 属性值的字符串，表示此表单中的控件是否可以由浏览器自动填充其值。
HTMLFormElement.noValidate: 反映表单的 novalidate HTML 属性值的布尔值，表示是否不应对表单进行验证。

具名输入会被作为属性添加到其所属表单的实例中，且如果它们共享相同的名称（例如，具有名为 action 的输入的表单将使其 action 属性返回该输入，而不是表单的 action HTML 属性）。

实例方法

此接口还从其父接口 HTMLElement 继承方法。

checkValidity(): 如果元素的子控件受到约束验证并满足这些约束，则返回 true；如果某些控件不满足其约束，则返回 false。在不满足其约束的任何控件上触发名为 invalid 的事件；如果未取消事件，则这些控件被视为无效。由程序员决定如何响应 false。
reportValidity(): 如果元素的子控件满足其验证约束，则返回 true。当返回 false 时，将为每个无效的子控件触发可取消的 invalid 事件，并将验证问题报告给用户。
requestSubmit(): 请求使用指定的提交按钮及其相应的配置来提交表单。
reset(): 将表单重置为其初始状态。
submit(): 将表单提交至服务器。

事件

使用 addEventListener() 或将事件监听器赋值给此接口的 oneventname 属性来监听这些事件。

formdata: 在构建表示表单数据的条目列表之后触发 formdata 事件。
reset: 在表单重置时触发 reset 事件。
submit: 在表单提交时触发 submit 事件。

使用说明

获得表单元素对象

要获取 HTMLFormElement 对象，你可以使用 CSS 选择器和 querySelector()，或者使用文档的 forms 属性获取文档中所有表单的列表。

Document.forms 返回 HTMLFormElement 对象数组，其中列出了页面上的每个表单。然后，你可以使用以下任何语法来获取单个表单：

document.forms[index]: 返回数组中指定索引（index）的表单。
document.forms[id]: 返回 ID 为 id 的表单。
document.forms[name]: 返回 name 属性值为 name 的表单。

访问表单的元素

你可以通过检查表单的 elements 属性来访问表单中用于包含数据的元素列表。这将返回一个 HTMLFormControlsCollection，其中列出了表单的所有用户数据输入元素，包括 <form> 的后代元素，以及使用其 form 属性而成为表单成员的元素。

你也可以通过将表单元素 name 属性作为 form 的键来获取该表单的元素，但使用 elements 是一个更好的方法——它只包含表单的元素，并且不能与 form 的其他属性混合使用。

元素命名问题

有些名称会干扰 JavaScript 访问表单的属性和元素。

例如：

<input name="id"> 会优先于 <form id="…">。这意味着 form.id 不会引用表单的 id，而是引用名称为 "id" 的元素。这也适用于其他表单属性，例如 <input name="action"> 或 <input name="post">。
<input name="elements"> 会使表单的 elements 集合无法访问。引用 form.elements 现在将引用单个元素。

要避免这些元素名称的问题，你应该：

始终使用 elements 集合来避免元素名称和表单属性之间的歧义。
切勿将 "elements" 作为元素名称。

如果你不使用 JavaScript，这不会造成问题。

被视为表单控件的元素

HTMLFormElement.elements 和 HTMLFormElement.length 包含以下元素：

<button>
<fieldset>
<input>（但由于历史原因，type 为 "image" 的元素会被忽略）
<object>
<output>
<select>
<textarea>

elements 返回的列表不包含其他元素，这使得它成为处理表单时获取最重要元素的绝佳方法。

示例

创建一个新的表单元素，修改其属性，然后提交：

const f = document.createElement("form"); // 创建表单
document.body.appendChild(f); // 将其添加到文档主体
f.action = "/cgi-bin/some.cgi"; // 添加 action 和 method 属性
f.method = "POST";
f.submit(); // 调用表单的 submit() 方法

从 <form> 元素中提取信息并设置一些属性：

html

<form name="formA" action="/cgi-bin/test" method="post">
  <p>点击“信息”以获得表单详细信息，或点击“设置”以改变这些信息。</p>
  <p>
    <button type="button" onclick="getFormInfo();">信息</button>
    <button type="button" onclick="setFormInfo(this.form);">设置</button>
    <button type="reset">重置</button>
  </p>

  <textarea id="form-info" rows="15" cols="20"></textarea>
</form>

<script>
  function getFormInfo() {
    // 通过表单名称获取对其的引用
    const f = document.forms["formA"];
    // 我们感兴趣的表单属性
    const properties = [
      "elements",
      "length",
      "name",
      "charset",
      "action",
      "acceptCharset",
      "action",
      "enctype",
      "method",
      "target",
    ];
    // 迭代这些属性，将它们转换为一个字符串，以便我们可以显示给用户
    const info = properties
      .map((property) => `${property}：${f[property]}`)
      .join("\n");

    // 设置表单的 <textarea> 以显示表单的属性
    document.forms["formA"].elements["form-info"].value = info; // 也可以使用 document.forms["formA"]['form-info'].value
  }

  function setFormInfo(f) {
    // 参数应该是表单元素的引用。
    f.action = "a-different-url.cgi";
    f.name = "a-different-name";
  }
</script>

在新窗口中提交表单（<form>）：

html

<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="utf-8" />
    <title>在新窗口提交表单的示例</title>
  </head>
  <body>
    <form action="test.php" target="_blank">
      <p>
        <label>名字：<input type="text" name="first-name" /></label>
      </p>
      <p>
        <label>姓氏：<input type="text" name="last-name" /></label>
      </p>
      <p>
        <label><input type="password" name="pwd" /></label>
      </p>

      <fieldset>
        <legend>宠物偏好</legend>

        <p>
          <label><input type="radio" name="pet" value="cat" />猫</label>
        </p>
        <p>
          <label><input type="radio" name="pet" value="dog" />狗</label>
        </p>
      </fieldset>

      <fieldset>
        <legend>拥有的车辆</legend>

        <p>
          <label
            ><input type="checkbox" name="vehicle" value="Bike" />自行车</label
          >
        </p>
        <p>
          <label
            ><input type="checkbox" name="vehicle" value="Car" />汽车</label
          >
        </p>
      </fieldset>

      <p><button>提交</button></p>
    </form>
  </body>
</html>

规范

Specification
HTML # htmlformelement

浏览器兼容性

参见

实现此接口的 HTML 元素：<form>。