HTMLFormElement - 表示 DOM 中的 <form> 元素

HTMLFormElement 接口表示 DOM 中的 <form> 元素；它允许访问并在某些情况下修改表单的各个属性，以及访问其组件元素。

属性

该接口还从其父类 HTMLElement 继承了属性。

HTMLFormElement.elements 只读

一个 HTMLFormControlsCollection，包含属于该表单元素的所有表单控件。

HTMLFormElement.length只读

一个 long，反映了表单中控件的数量。

HTMLFormElement.name

一个 DOMString，反映了表单的 name HTML 属性的值，包含表单的名称。

HTMLFormElement.method

一个 DOMString，反映了表单的 method HTML 属性的值，表示用于提交表单的 HTTP 方法。只能设置指定的值。

HTMLFormElement.target

一个 DOMString，反映了表单的 target HTML 属性的值，指示在何处显示从提交表单收到的结果。

HTMLFormElement.action

一个 DOMString 反映了表单的 action HTML 属性的值，包含处理表单提交的信息的程序的 URI。

HTMLFormElement.encoding 或 HTMLFormElement.enctype

一个 DOMString，反映了表单的 enctype HTML 属性的值，表示用于将表单传输到服务器的内容类型。只能设置指定的值。这两个属性是同义词。

HTMLFormElement.acceptCharset

一个 DOMString，反映了表单的 accept-charset HTML 属性的值，表示服务器接受的字符编码。

HTMLFormElement.autocomplete

一个 DOMString，反映了表单的 autocomplete HTML 属性的值，指示该表单中的控件是否可以通过浏览器自动填充其值。

HTMLFormElement.noValidate

一个 Boolean，反映了表单的 novalidate HTML 属性的值，指示是否不应验证表单。

带有 name 的输入控件将作为属性添加到其所有者表单实例（即可通过 form.name 访问相应的控件）。并且如果它们有着相同的名称时，则会覆盖表单的属性（例如，name 为 action 的输入控件，将使其表单的 action 属性返回为该输入控件对象，而不是表单的 action HTML 属性）。

方法

该接口还从其父类 HTMLElement 继承了方法。

HTMLFormElement.submit()

将表单提交到服务器。

HTMLFormElement.reset()

将表单重置为其初始状态。

HTMLFormElement.checkValidity()

如果元素的子控件受约束验证的约束并且满足这些约束，则返回 true; 如果某些控件不满足其约束，则返回 false。在任何不满足其约束的控件上触发名为 invalid 的事件；如果事件未被取消，则该类控件被视为无效。由程序员决定如何回应 false 。

HTMLFormElement.reportValidity()

如果元素的子控件满足其验证约束，则返回 true。返回 false 时，会为每个无效的子项触发可取消的 invalid 事件，并向用户报告验证问题。

HTMLFormElement.requestAutocomplete()

当具有自动填充字段名称值的字段值不是 off 或 on 时，触发本机浏览器界面以帮助用户自动完成。一旦用户完成界面的操作，表单将收到一个事件，当填写字段时，事件是 autocomplete，或当有问题时，事件是 autocompleteerror。 该方法已从 Chrome 和 Firefox 中删除 - 有关原因的背景信息，请参阅 Mozilla bug 1270740。

使用注意

获取表单元素对象

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

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

document.forms[*index*]

返回表单数组中指定 index 处的表单。

document.forms[*id*]

返回 ID 为 id 的表单。

document.forms[*name*]

返回 name 属性的值为 name 的表单。

访问表单的元素

您可以通过检查表单的 elements 属性来访问表单的包含数据的元素的列表。这将返回一个 HTMLFormControlsCollection，列出所有表单的用户数据条目元素，这些元素都是 <form> 的后代，以及那些使用 form 属性成为表单成员的元素。

被视为表单控件的元素

HTMLFormElement.elements 和 HTMLFormElement.length 包含的元素是：

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

实例

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

var f = document.createElement("form");// 创建一个表单
document.body.appendChild(f);          // 将其添加到文档正文中
f.action = "/cgi-bin/some.cgi";        // 增加操作和方法属性
f.method = "POST";
f.submit();                            // 调用表单的提交方法

从表单元素中提取信息并设置其一些属性：

<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="50"></textarea>
</form>

<script>
  function getFormInfo(){
    // 通过名称获取对表单的引用
    var f = document.forms["formA"];
    // 我们感兴趣的表单属性
    var properties = [ 'elements', 'length', 'name', 'charset', 'action', 'acceptCharset', 'action', 'enctype', 'method', 'target' ];
    // 遍历属性，将它们转换为我们可以向用户显示的字符串
    var info = properties.map(function(property) {
      console.log(f)
      return property + ": " + f[property]; 
    }).join("\n");

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

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

尝试一下 »

将表单提交到新窗口：

<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>提交表单到新窗口实例</title>
</head>
<body>

<form action="test.php" target="_blank">
  <p><label>姓：<input type="text" name="firstname"></label></p>
  <p><label>名：<input type="text" name="lastname"></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>

使用 XMLHttpRequest 提交表单和上传文件

如果您想知道如何使用 XMLHttpRequest API 序列化和提交表单，请阅读本段。

规范

规范 状态 备注
HTML Living Standard
HTMLFormElement 的定义		 现行的标准 添加了以下方法：requestAutocomplete()。
HTML5
HTMLFormElement 的定义		 推荐 elements 属性返回 HTMLFormControlsCollection 而不是原生的 HTMLCollection。这主要是技术上的变化。添加了以下方法： checkValidity() 。添加了以下属性： autocomplete ，noValidate 和 encoding。
Document Object Model (DOM) Level 2 HTML Specification
HTMLFormElement 的定义		 已过时 没有变化
Document Object Model (DOM) Level 1 Specification
HTMLFormElement 的定义		 已过时 初始定义

桌面浏览器兼容性

特性 Chrome Edge Firefox Internet Explorer Opera Safari
基础支持 支持 支持 1 支持 支持 支持
reportValidity 40 17 49 不支持 支持 支持

移动浏览器兼容性

特性 Android Chrome for Android Edge mobile Firefox for Android IE mobile Opera Android iOS Safari
基础支持 支持 支持 支持 支持 未知 支持 支持
reportValidity 40 40 17 未知 未知 未知 未知

相关链接

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