HTMLFormElement

在此页

特性
方法
事件
用法注意事项
范例
规范
浏览器兼容性
另请参阅
相关话题

HTMLFormElement 接口表示 <form> element in the DOM. It allows access to—and, in some cases, modification of—aspects of the form, as well as access to its component elements.

  <div id="interfaceDiagram" style="display: inline-block; position: relative; width: 100%; padding-bottom: 20%; vertical-align: middle; overflow: hidden;"><svg style="display: inline-block; position: absolute; top: 0; left: 0;" viewbox="-50 0 600 120" preserveAspectRatio="xMinYMin meet"><a xlink:href="../API/EventTarget.html" target="_top"><rect x="1" y="1" width="110" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text  x="56" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">EventTarget</text></a><polyline points="111,25  121,20  121,30  111,25" stroke="#D4DDE4" fill="none"/><line x1="121" y1="25" x2="151" y2="25" stroke="#D4DDE4"/><a xlink:href="../API/Node" target="_top"><rect x="151" y="1" width="75" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text  x="188.5" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">Node</text></a><polyline points="226,25  236,20  236,30  226,25" stroke="#D4DDE4" fill="none"/><line x1="236" y1="25" x2="266" y2="25" stroke="#D4DDE4"/><a xlink:href="../API/Element" target="_top"><rect x="266" y="1" width="75" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text  x="303.5" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">Element</text></a><polyline points="341,25  351,20  351,30  341,25" stroke="#D4DDE4" fill="none"/><line x1="351" y1="25" x2="381" y2="25" stroke="#D4DDE4"/><a xlink:href="../API/HTMLElement" target="_top"><rect x="381" y="1" width="110" height="50" fill="#fff" stroke="#D4DDE4" stroke-width="2px" /><text  x="436" y="30" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">HTMLElement</text></a><polyline points="491,25  501,20  501,30  491,25" stroke="#D4DDE4" fill="none"/><line x1="501" y1="25" x2="509" y2="25" stroke="#D4DDE4"/><line x1="509" y1="25" x2="509" y2="90" stroke="#D4DDE4"/><line x1="509" y1="90" x2="492" y2="90" stroke="#D4DDE4"/><a xlink:href="../API/HTMLFormElement" target="_top"><rect x="341" y="65" width="150" height="50" fill="#F4F7F8" stroke="#D4DDE4" stroke-width="2px" /><text  x="416" y="94" font-size="12px" font-family="Consolas,Monaco,Andale Mono,monospace" fill="#4D4E53" text-anchor="middle" alignment-baseline="middle">HTMLFormElement</text></a></svg></div>

  a:hover text { fill: #0095DD; pointer-events: all;}

特性

This interface also inherits properties from its parent, HTMLElement .

HTMLFormElement.elements 只读: HTMLFormControlsCollection holding all form controls belonging to this form element.
HTMLFormElement.length 只读: A long reflecting the number of controls in the form.
HTMLFormElement.name: DOMString reflecting the value of the form's 名称 HTML attribute, containing the name of the form.
HTMLFormElement.method: DOMString reflecting the value of the form's 方法 HTML attribute, indicating the HTTP method used to submit the form. Only specified values can be set.
HTMLFormElement.target: DOMString reflecting the value of the form's target HTML attribute, indicating where to display the results received from submitting the form.
HTMLFormElement.action: DOMString reflecting the value of the form's action HTML attribute, containing the URI of a program that processes the information submitted by the form.
HTMLFormElement.encoding or HTMLFormElement.enctype: DOMString reflecting the value of the form's enctype HTML attribute, indicating the type of content that is used to transmit the form to the server. Only specified values can be set. The two properties are synonyms.
HTMLFormElement.acceptCharset: DOMString reflecting the value of the form's accept-charset HTML attribute, representing the character encoding that the server accepts.
HTMLFormElement.autocomplete: DOMString reflecting the value of the form's autocomplete HTML attribute, indicating whether the controls in this form can have their values automatically populated by the browser.
HTMLFormElement.noValidate: 布尔 reflecting the value of the form's novalidate HTML attribute, indicating whether the form should not be validated.

Named inputs are added to their owner form instance as properties, and can overwrite native properties if they share the same name (e.g. a form with an input named action will have its action property return that input instead of the form's action HTML attribute).

方法

This interface also inherits methods from its parent, HTMLElement .

checkValidity(): 返回 true if the element's child controls are subject to constraint validation and satisfy those contraints; returns false if some controls do not satisfy their constraints. Fires an event named 无效 at any control that does not satisfy its constraints; such controls are considered invalid if the event is not canceled. It is up to the programmer to decide how to respond to false .
reportValidity(): 返回 true if the element's child controls satisfy their validation constraints 。当 false is returned, cancelable 无效 events are fired for each invalid child and validation problems are reported to the user.
requestSubmit()
reset()
submit()

弃用方法

HTMLFormElement.requestAutocomplete(): Triggers a native browser interface to assist the user in completing the fields which have an autofill field name value that is not off or on . The form will receive an event once the user has finished with the interface, the event will either be autocomplete when the fields have been filled or autocompleteerror when there was a problem.

事件

监听这些事件使用 addEventListener() , or by assigning an event listener to the on eventname 特性为此接口。

formdata: formdata event fires after the entry list representing the form's data is constructed.
也可用凭借 onformdata 特性。
reset: reset event fires when a form is reset.
也可用凭借 onreset 特性。
submit: submit event fires when a form is submitted.
也可用凭借 onsubmit 特性。

用法注意事项

Obtaining a form element object

To obtain an HTMLFormElement object, you can use a CSS selector with querySelector() , or you can get a list of all of the forms in the document using its forms 特性。

Document.forms returns an array of HTMLFormElement objects listing each of the forms on the page. You can then use any of the following syntaxes to get an individual form:

document.forms[ index ]: Returns the form at the specified index into the array of forms.
document.forms[ id ]: Returns the form whose ID is id .
document.forms[ 名称 ]: Returns the form whose 名称 attribute's value is 名称 .

Accessing the form's elements

You can access the list of the form's data-containing elements by examining the form's 元素 property. This returns an HTMLFormControlsCollection listing all of the form's user data entry elements, both those which are descendants of the <form> and those which are made members of the form using their form 属性。

You can also get the form's element by using its 名称 attribute as a key of the form , but using 元素 is a better approach—it contains only the form's elements, and it cannot be mixed with other attributes of the form .

Issues with Naming Elements

Some names will interfere with JavaScript access to the form’s properties and elements.

例如：

<input name="id"> will take precedence over <form id="…"> 。这意味着 form.id will not refer to the form’s id, but to the element whose name is " id ". This will be the case with any other form properties, such as <input name="action"> or <input name="post"> .
<input name="elements"> will render the form’s 元素 collection inaccessible. The reference form.elements will now refer to the individual element.

To avoid such problems with element names:

Always 使用 元素 collection to avoid ambiguity between an element name and a form property.
Never use " 元素 " as an element name.

If you are not using JavaScript, this will not cause a problem.

Elements that are considered form controls

The elements included by HTMLFormElement.elements and HTMLFormElement.length are the following:

<button>
<fieldset>
<input> (with the exception that any whose type is "image" are omitted for historical reasons)
<object>
<output>
<select>
<textarea>

No other elements are included in the list returned by 元素 , which makes it an excellent way to get at the elements most important when processing forms.

范例

Creating a new form element, modifying its attributes, then submitting it:

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

Extract information from a <form> element and set some of its attributes:

<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" onclick="getFormInfo();">Info</button>
  <button type="button" onclick="setFormInfo(this.form);">Set</button>
  <button type="reset">Reset</button>
 </p>
 <textarea id="form-info" rows="15" cols="20"></textarea>
</form>
<script>
  function getFormInfo(){
    // Get a reference to the form via its name
    var f = document.forms["formA"];
    // The form properties we're interested in
    var 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
    var info = properties.map(function(property) { return 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
  }
  function setFormInfo(f){ // Argument should be a form element reference.
    f.action = "a-different-url.cgi";
    f.name   = "a-different-name";
  }
</script>

Submit a <form> into a new window:

<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>Example new-window form submission</title>
</head>
<body>
<form action="test.php">
  <p><label>First name: <input type="text" name="firstname"></label></p>
  <p><label>Last name: <input type="text" name="lastname"></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>
</body>
</html>

Submitting forms and uploading files using XMLHttpRequest

If you want to know how to serialize and submit a form using the XMLHttpRequest API, please read this paragraph .

规范

规范	状态	注释
HTML 实时标准 The definition of 'HTMLFormElement' in that specification.	实时标准	The following method has been added: `requestAutocomplete()` .
HTML5 The definition of 'HTMLFormElement' in that specification.	推荐	The elements properties returns an `HTMLFormControlsCollection` instead of a raw `HTMLCollection` . This is mainly a technical change. The following method has been added: `checkValidity()` . The following properties have been added: `autocomplete` , `noValidate` ，和 `encoding` .

浏览器兼容性

The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request. 更新 GitHub 上的兼容性数据

	桌面						移动
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`HTMLFormElement`	Chrome 1	Edge 12	Firefox 1	IE 9	Opera 8	Safari 3	WebView Android 1	Chrome Android 18	Firefox Android 4	Opera Android 10.1	Safari iOS 1	Samsung Internet Android 1.0
`acceptCharset`	Chrome Yes	Edge 12	Firefox Yes	IE ?	Opera Yes	Safari Yes	WebView Android Yes	Chrome Android Yes	Firefox Android Yes	Opera Android Yes	Safari iOS Yes	Samsung Internet Android Yes
`action`	Chrome Yes	Edge 12	Firefox Yes	IE ?	Opera Yes	Safari Yes	WebView Android Yes	Chrome Android Yes	Firefox Android Yes	Opera Android Yes	Safari iOS Yes	Samsung Internet Android Yes
`autocomplete`	Chrome Yes	Edge 12	Firefox Yes	IE ?	Opera Yes	Safari Yes	WebView Android Yes	Chrome Android Yes	Firefox Android Yes	Opera Android Yes	Safari iOS Yes	Samsung Internet Android Yes
`checkValidity`	Chrome Yes	Edge 12	Firefox Yes	IE ?	Opera Yes	Safari Yes	WebView Android Yes	Chrome Android Yes	Firefox Android Yes	Opera Android Yes	Safari iOS Yes	Samsung Internet Android Yes
`元素`	Chrome 1	Edge 12	Firefox 1	IE 9	Opera 8	Safari 3	WebView Android 1	Chrome Android 18	Firefox Android 4	Opera Android 10.1	Safari iOS 1	Samsung Internet Android 1.0
`encoding`	Chrome Yes	Edge 12	Firefox Yes	IE ?	Opera Yes	Safari Yes	WebView Android Yes	Chrome Android Yes	Firefox Android Yes	Opera Android Yes	Safari iOS Yes	Samsung Internet Android Yes
`enctype`	Chrome Yes	Edge 12	Firefox Yes	IE ?	Opera Yes	Safari Yes	WebView Android Yes	Chrome Android Yes	Firefox Android Yes	Opera Android Yes	Safari iOS Yes	Samsung Internet Android Yes
`formdata` event	Chrome 77	Edge 79	Firefox 72	IE No	Opera 64	Safari No	WebView Android 77	Chrome Android 77	Firefox Android No	Opera Android 55	Safari iOS No	Samsung Internet Android 12.0
`length`	Chrome Yes	Edge 12	Firefox Yes	IE ?	Opera Yes	Safari Yes	WebView Android Yes	Chrome Android Yes	Firefox Android Yes	Opera Android Yes	Safari iOS Yes	Samsung Internet Android Yes
`method`	Chrome Yes	Edge 12	Firefox Yes	IE ?	Opera Yes	Safari Yes	WebView Android Yes	Chrome Android Yes	Firefox Android Yes	Opera Android Yes	Safari iOS Yes	Samsung Internet Android Yes
`名称`	Chrome Yes	Edge 12	Firefox Yes	IE ?	Opera Yes	Safari Yes	WebView Android Yes	Chrome Android Yes	Firefox Android Yes	Opera Android Yes	Safari iOS Yes	Samsung Internet Android Yes
`noValidate`	Chrome Yes	Edge 12	Firefox Yes	IE ?	Opera Yes	Safari Yes	WebView Android Yes	Chrome Android Yes	Firefox Android Yes	Opera Android Yes	Safari iOS Yes	Samsung Internet Android Yes
`reportValidity`	Chrome 40	Edge 17	Firefox 49	IE No	Opera Yes	Safari Yes	WebView Android 40	Chrome Android 40	Firefox Android Yes	Opera Android Yes	Safari iOS Yes	Samsung Internet Android 4.0
`requestAutocomplete` 弃用非标	Chrome No	Edge No	Firefox No	IE ?	Opera No	Safari ?	WebView Android No	Chrome Android No	Firefox Android No	Opera Android No	Safari iOS ?	Samsung Internet Android No
`requestSubmit()`	Chrome 76	Edge 79	Firefox 75	IE No	Opera 63	Safari No	WebView Android 76	Chrome Android 76	Firefox Android No	Opera Android 54	Safari iOS No	Samsung Internet Android 12.0
`reset`	Chrome 1	Edge 12	Firefox 1	IE 9	Opera 8	Safari 3	WebView Android 1	Chrome Android 18	Firefox Android 4	Opera Android 10.1	Safari iOS 1	Samsung Internet Android 1.0
`reset` event	Chrome Yes	Edge 12	Firefox Yes	IE Yes	Opera Yes	Safari Yes	WebView Android Yes	Chrome Android Yes	Firefox Android Yes	Opera Android Yes	Safari iOS Yes	Samsung Internet Android Yes
`submit`	Chrome Yes	Edge 12	Firefox Yes	IE Yes	Opera Yes	Safari Yes	WebView Android Yes	Chrome Android Yes	Firefox Android Yes	Opera Android Yes	Safari iOS Yes	Samsung Internet Android Yes
`submit` event	Chrome 1	Edge 12	Firefox 1	IE 9	Opera 8	Safari 3	WebView Android 1	Chrome Android 18	Firefox Android 4	Opera Android 10.1	Safari iOS 1	Samsung Internet Android 1.0
`target`	Chrome Yes	Edge 12	Firefox Yes	IE ?	Opera Yes	Safari Yes	WebView Android Yes	Chrome Android Yes	Firefox Android Yes	Opera Android Yes	Safari iOS Yes	Samsung Internet Android Yes

图例

完整支持
不支持
兼容性未知 ?
非标。预期跨浏览器支持较差。
弃用。不要用于新网站。

另请参阅

The HTML element implementing this interface: <form> .

元数据

最后修改： Jul 28, 2020

在此页

特性

方法