HTMLFormElement

Baseline 已广泛支持

此特性已相当成熟,可在许多设备和浏览器版本上使用。自 ⁨2015 年 7 月⁩以来,各浏览器均已提供此特性。

HTMLFormElement 接口表示 DOM 中的 <form> 元素。它允许访问(有时也允许修改)表单的各个方面,以及访问其组成元素。

EventTarget Node Element HTMLElement HTMLFormElement

实例属性

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

HTMLFormElement.acceptCharset

一个字符串,反映表单的 accept-charset HTML 属性的值。

HTMLFormElement.action

一个字符串,反映表单的 action HTML 属性的值,其中包含处理表单提交信息程序的 URI。

HTMLFormElement.autocomplete

一个字符串,反映表单的 autocomplete HTML 属性的值,指示此表单中的控件是否可以由浏览器自动填充其值。

HTMLFormElement.encodingHTMLFormElement.enctype

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

HTMLFormElement.elements 只读

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

HTMLFormElement.length 只读

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

HTMLFormElement.name

一个字符串,反映表单的 name HTML 属性的值,包含表单的名称。

HTMLFormElement.noValidate

一个布尔值,反映表单的 novalidate HTML 属性的值,指示表单是否不应进行验证。

HTMLFormElement.method

一个字符串,反映表单的 method HTML 属性的值,指示用于提交表单的 HTTP 方法。只能设置指定的值。

HTMLFormElement.rel

一个字符串,反映表单的 rel HTML 属性的值,该属性表示表单创建的链接类型,以空格分隔的枚举值列表。

HTMLFormElement.relList 只读

一个 DOMTokenList,它反映 rel HTML 属性,作为令牌列表。

HTMLFormElement.target

一个字符串,反映表单的 target 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 对象,您可以使用 querySelector()CSS 选择器,或者可以使用 Documentforms 属性来获取文档中所有表单的列表。

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.elementsHTMLFormElement.length 所包含的元素如下:

elements 返回的列表中不包含其他任何元素,这使其成为处理表单时获取最重要元素的一个绝佳方法。

示例

创建新的表单元素、修改其属性,然后提交

js
const f = document.createElement("form"); // Create a form
document.body.appendChild(f); // Add it to the document body
f.action = "/cgi-bin/some.cgi"; // Add action and method attributes
f.method = "POST";
f.submit(); // Call the form's submit() method

<form> 元素中提取信息并设置其部分属性

html
<form name="formA" action="/cgi-bin/test" method="post">
  <p>Press "Info" for form details, or "Set" to change those details.</p>
  <p>
    <button type="button" id="info">Info</button>
    <button type="button" id="set-info">Set</button>
    <button type="reset">Reset</button>
  </p>

  <textarea id="form-info" rows="15" cols="20"></textarea>
</form>
js
document.getElementById("info").addEventListener("click", () => {
  // Get a reference to the form via its name
  const f = document.forms["formA"];
  // The form properties we're interested in
  const properties = [
    "elements",
    "length",
    "name",
    "charset",
    "action",
    "acceptCharset",
    "action",
    "enctype",
    "method",
    "target",
  ];
  // Iterate over the properties, turning them into a string that we can display to the user
  const info = properties
    .map((property) => `${property}: ${f[property]}`)
    .join("\n");

  // Set the form's <textarea> to display the form's properties
  document.forms["formA"].elements["form-info"].value = info; // document.forms["formA"]['form-info'].value would also work
});

document.getElementById("set-info").addEventListener("click", (e) => {
  // Get a reference to the form via the event target
  // e.target is the button, and .form is the form it belongs to
  const f = e.target.form;
  // Argument should be a form element reference.
  f.action = "a-different-url.cgi";
  f.name = "a-different-name";
});

<form> 提交到新窗口

html
<form action="test.php" target="_blank">
  <p>
    <label>First name: <input type="text" name="first-name" /></label>
  </p>
  <p>
    <label>Last name: <input type="text" name="last-name" /></label>
  </p>
  <p>
    <label><input type="password" name="pwd" /></label>
  </p>

  <fieldset>
    <legend>Pet preference</legend>

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

  <fieldset>
    <legend>Owned vehicles</legend>

    <p>
      <label
        ><input type="checkbox" name="vehicle" value="Bike" />I have a
        bike</label
      >
    </p>
    <p>
      <label
        ><input type="checkbox" name="vehicle" value="Car" />I have a car</label
      >
    </p>
  </fieldset>

  <p><button>Submit</button></p>
</form>

规范

规范
HTML
# htmlformelement

浏览器兼容性

另见

  • 实现此接口的 HTML 元素:<form>