View in English Always switch to English

HTMLFormElement

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨2015年7月⁩.

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>。

Help improve MDN

Learn how to contribute

This page was last modified on ⁨2025年11月10日⁩ by MDN contributors.

View this page on GitHub • Report a problem with this content