HTMLFormElement

HTMLFormElement interface represents a <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.

特性

This interface also inherits properties from its parent, HTMLElement .

HTMLFormElement.elements 只读
A HTMLFormControlsCollection holding all form controls belonging to this form element.
HTMLFormElement.length 只读
A long reflecting the number of controls in the form.
HTMLFormElement.name
A DOMString reflecting the value of the form's name HTML attribute, containing the name of the form.
HTMLFormElement.method
A DOMString reflecting the value of the form's method HTML attribute, indicating the HTTP method used to submit the form. Only specified values can be set.
HTMLFormElement.target
A DOMString reflecting the value of the form's target HTML attribute, indicating where to display the results received from submitting the form.
HTMLFormElement.action
A 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
A 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
A DOMString reflecting the value of the form's accept-charset HTML attribute, representing the character encoding that the server accepts.
HTMLFormElement.autocomplete
A 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
A Boolean 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 invalid 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 invalid events are fired for each invalid child and validation problems are reported to the user.
requestSubmit()
Requests that the form be submitted using the specified submit button and its corresponding configuration.
reset()
Resets the form to its initial state.
submit()
Submits the form to the server.

弃用方法

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.

Events

监听这些事件使用 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.
Also available via the onformdata 特性。
reset
reset event fires when a form is reset.
Also available via the onreset 特性。
submit
submit event fires when a form is submitted.
Also available via the onsubmit 特性。

Usage notes

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[ name ]
Returns the form whose name attribute's value is name .

Accessing the form's elements

You can access the list of the form's data-containing elements by examining the form's elements 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 name attribute as a key of the form , but using elements 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="…"> . This means that 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 elements collection inaccessible. The reference form.elements will now refer to the individual element.

To avoid such problems with element names:

  • Always 使用 elements collection to avoid ambiguity between an element name and a form property.
  • Never use " elements " 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:

No other elements are included in the list returned by elements , 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" target="_blank">
  <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 .

规范

规范 状态 Comment
HTML Living Standard
The definition of 'HTMLFormElement' in that specification.
实时标准 The following method has been added: requestAutocomplete() .
HTML5
The definition of 'HTMLFormElement' in that specification.
Recommendation 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 .

浏览器兼容性

更新 GitHub 上的兼容性数据
Desktop Mobile
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
elements 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
name 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> .
  1. HTMLFormElement
  2. 特性
    1. acceptCharset
    2. action
    3. elements
    4. encoding
    5. enctype
    6. length
    7. method
    8. name
    9. target
  3. 方法
    1. reportValidity()
    2. requestSubmit()
    3. reset()
    4. submit()
  4. Events
    1. formdata
    2. reset
    3. submit
  5. 继承:
    1. HTMLElement
    2. Element
    3. Node
    4. EventTarget
  6. Related pages for HTML DOM
    1. BeforeUnloadEvent
    2. DOMStringMap
    3. ErrorEvent
    4. GlobalEventHandlers
    5. HTMLAnchorElement
    6. HTMLAreaElement
    7. HTMLAudioElement
    8. HTMLBRElement
    9. HTMLBaseElement
    10. HTMLBaseFontElement
    11. HTMLBodyElement
    12. HTMLButtonElement
    13. HTMLCanvasElement
    14. HTMLContentElement
    15. HTMLDListElement
    16. HTMLDataElement
    17. HTMLDataListElement
    18. HTMLDialogElement
    19. HTMLDivElement
    20. HTMLDocument
    21. HTMLElement
    22. HTMLEmbedElement
    23. HTMLFieldSetElement
    24. HTMLFormControlsCollection
    25. HTMLFrameSetElement
    26. HTMLHRElement
    27. HTMLHeadElement
    28. HTMLHeadingElement
    29. HTMLHtmlElement
    30. HTMLIFrameElement
    31. HTMLImageElement
    32. HTMLInputElement
    33. HTMLIsIndexElement
    34. HTMLKeygenElement
    35. HTMLLIElement
    36. HTMLLabelElement
    37. HTMLLegendElement
    38. HTMLLinkElement
    39. HTMLMapElement
    40. HTMLMediaElement
    41. HTMLMetaElement
    42. HTMLMeterElement
    43. HTMLModElement
    44. HTMLOListElement
    45. HTMLObjectElement
    46. HTMLOptGroupElement
    47. HTMLOptionElement
    48. HTMLOptionsCollection
    49. HTMLOutputElement
    50. HTMLParagraphElement
    51. HTMLParamElement
    52. HTMLPictureElement
    53. HTMLPreElement
    54. HTMLProgressElement
    55. HTMLQuoteElement
    56. HTMLScriptElement
    57. HTMLSelectElement
    58. HTMLShadowElement
    59. HTMLSourceElement
    60. HTMLSpanElement
    61. HTMLStyleElement
    62. HTMLTableCaptionElement
    63. HTMLTableCellElement
    64. HTMLTableColElement
    65. HTMLTableDataCellElement
    66. HTMLTableElement
    67. HTMLTableHeaderCellElement
    68. HTMLTableRowElement
    69. HTMLTableSectionElement
    70. HTMLTemplateElement
    71. HTMLTextAreaElement
    72. HTMLTimeElement
    73. HTMLTitleElement
    74. HTMLTrackElement
    75. HTMLUListElement
    76. HTMLUnknownElement
    77. HTMLVideoElement
    78. HashChangeEvent
    79. History
    80. ImageData
    81. Location
    82. MessageChannel
    83. MessageEvent
    84. MessagePort
    85. Navigator
    86. NavigatorGeolocation
    87. NavigatorID
    88. NavigatorLanguage
    89. NavigatorOnLine
    90. NavigatorPlugins
    91. PageTransitionEvent
    92. Plugin
    93. PluginArray
    94. PopStateEvent
    95. PortCollection
    96. PromiseRejectionEvent
    97. RadioNodeList
    98. Transferable
    99. ValidityState
    100. Window
    101. WindowBase64
    102. WindowEventHandlers
    103. WindowTimers