diff --git a/files/zh-cn/web/api/htmlformelement/index.md b/files/zh-cn/web/api/htmlformelement/index.md index 4ac36567e2b579..7855b63f6dc018 100644 --- a/files/zh-cn/web/api/htmlformelement/index.md +++ b/files/zh-cn/web/api/htmlformelement/index.md @@ -1,232 +1,241 @@ --- title: HTMLFormElement slug: Web/API/HTMLFormElement +l10n: + sourceCommit: c99afd3cafe73c93831bd73ad1dac285c3c713b1 --- {{APIRef("HTML DOM")}} -HTMLFormElement 接口可以创建或者修改{{HTMLElement("form")}}对象;它继承了{{domxref("HTMLElement")}}接口的方法和属性。 +**`HTMLFormElement`** 接口表示 DOM 中的 {{HTMLElement("form")}} 元素。它允许访问和(在某些情况下)修改表单的各个方面,以及访问其组成元素。 -## 属性 +{{InheritanceDiagram}} -_继承自父类的属性,{{domxref("HTMLElement")}}._ +## 实例属性 -- {{domxref("HTMLFormElement.acceptCharset")}} - - : Is a {{domxref("DOMString")}} that reflects the [`accept-charset`](/zh-CN/docs/Web/HTML/Element/form#accept-charset) HTML attribute, containing a list of character encodings that the server accepts. +_此接口还从其父接口 {{domxref("HTMLElement")}} 继承属性。_ + +- {{domxref("HTMLFormElement.elements")}} {{ReadOnlyInline}} + - : 包含所有属于此表单元素的表单控件的 {{domxref("HTMLFormControlsCollection")}}。 +- {{domxref("HTMLFormElement.length")}} {{ReadOnlyInline}} + - : 反映表单中控件的数量的 `long` 值。 +- {{domxref("HTMLFormElement.name")}} + - : 反映表单的 [`name`](/zh-CN/docs/Web/HTML/Element/form#name) HTML 属性值的字符串,包含表单的名称。 +- {{domxref("HTMLFormElement.method")}} + - : 反映表单的 [`method`](/zh-CN/docs/Web/HTML/Element/form#method) HTML 属性值的字符串,表示用于提交表单的 HTTP 方法。只能设置特定的值。 +- {{domxref("HTMLFormElement.target")}} + - : 反映表单的 [`target`](/zh-CN/docs/Web/HTML/Element/form#target) HTML 属性值的字符串,表示用于显示提交表单的结果的位置。 - {{domxref("HTMLFormElement.action")}} - - : Is a {{domxref("DOMString")}} that reflects the [`action`](/zh-CN/docs/Web/HTML/Element/form#action) HTML attribute, containing the URI of a program that processes the information submitted by the form. + - : 反映表单的 [`action`](/zh-CN/docs/Web/HTML/Element/form#action) HTML 属性值的字符串,包含处理表单提交的信息的程序的 URI。 +- {{domxref("HTMLFormElement.encoding")}} 或 {{domxref("HTMLFormElement.enctype")}} + - : 反映表单的 [`enctype`](/zh-CN/docs/Web/HTML/Element/form#enctype) HTML 属性值的字符串,表示用于将表单传输到服务器的内容类型。只能设置特定的值。这两个属性是同义词。 +- {{domxref("HTMLFormElement.acceptCharset")}} + - : 反映表单的 [`accept-charset`](/zh-CN/docs/Web/HTML/Element/form#accept-charset) HTML 属性值的字符串,表示服务器接受的字符编码。 - {{domxref("HTMLFormElement.autocomplete")}} - - : Is a {{domxref("DOMString")}} that reflects the [`autocomplete`](/zh-CN/docs/Web/HTML/Element/form#autocomplete) HTML attribute, containing a string that indicates whether the controls in this form can have their values automatically populated by the browser. -- {{domxref("HTMLFormElement.elements")}} {{readonlyinline}} - - : Returns a live {{domxref("HTMLFormControlsCollection")}} containing all the form controls belonging to this form element. -- {{domxref("HTMLFormElement.encoding")}} - - : Is a synonym for `enctype`. -- {{domxref("HTMLFormElement.enctype")}} - - : Is a {{domxref("DOMString")}} reflects the [`enctype`](/zh-CN/docs/Web/HTML/Element/form#enctype) HTML attribute, indicating the type of content that is used to transmit the form to the server. Only specified values can be set. -- {{domxref("HTMLFormElement.length")}} {{readonlyinline}} - - : Returns a `long` that represents the number of controls in the form. -- {{domxref("HTMLFormElement.method")}} - - : Is a {{domxref("DOMString")}} that reflects the [`method`](/zh-CN/docs/Web/HTML/Element/form#method) HTML attribute, indicating the HTTP method used to submit the form. Only specified values can be set. -- {{domxref("HTMLFormElement.name")}} - - : Is a {{domxref("DOMString")}} that reflects the [`name`](/zh-CN/docs/Web/HTML/Element/form#name) HTML attribute, containing the name of the form. + - : 反映表单的 [`autocomplete`](/zh-CN/docs/Web/HTML/Element/form#autocomplete) HTML 属性值的字符串,表示此表单中的控件是否可以由浏览器自动填充其值。 - {{domxref("HTMLFormElement.noValidate")}} - - : Is a {{jsxref("Boolean")}} that reflects the [`novalidate`](/zh-CN/docs/Web/HTML/Element/form#novalidate) HTML attribute, indicating that the form should not be validated. -- {{domxref("HTMLFormElement.target")}} - - : Is a {{domxref("DOMString")}} that reflects the [`target`](/zh-CN/docs/Web/HTML/Element/form#target) HTML attribute, indicating where to display the results received from submitting the form. + - : 反映表单的 [`novalidate`](/zh-CN/docs/Web/HTML/Element/form#novalidate) HTML 属性值的布尔值,表示是否不应对表单进行验证。 -## 方法 +具名输入会被作为属性添加到其所属表单的实例中,且如果它们共享相同的名称(例如,具有名为 `action` 的输入的表单将使其 `action` 属性返回该输入,而不是表单的 [`action`](/zh-CN/docs/Web/HTML/Element/form#action) HTML 属性)。 -_这个元素继承了 {{domxref("HTMLElement")}} 的属性。_ +## 实例方法 -- {{domxref("HTMLFormElement.checkValidity()")}} - - : Returns a {{jsxref("Boolean")}} that is `true` if the element's child controls are subject to constraint validation and satify those contraints, or `false` if some controls do not satisfy their constraints. Fires an event named [`invalid`](/zh-CN/docs/Web/API/HTMLInputElement/invalid_event) 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`. -- {{domxref("HTMLFormElement.item()")}} - - : Gets the item in the `elements` collection at the specified index, or null if there is no item at that index. You can also specify the index in array-style brackets or parentheses after the form object name, without calling this method explicitly. -- {{domxref("HTMLFormElement.namedItem()")}} - - : 从元素集合中获取 `name` 或者 `id` 与指定名称匹配的项,没有匹配项则返回 null。你也可以像调用数组那样用圆括号或方括号来指定名称,而不必显式地调用这个方法。 -- {{domxref("HTMLFormElement.submit()")}} - - : Submits the form to the server. -- {{domxref("HTMLFormElement.reset()")}} - - : Resets the forms to its initial state. -- {{domxref("HTMLFormElement.reportValidity()")}} - - : Returns `true` if the element's child controls satisfy their validation constraints. When `false` is returned, cancelable [`invalid`](/zh-CN/docs/Web/Events/invalid) events are fired for each invalid child and validation problems are reported to the user. +_此接口还从其父接口 {{domxref("HTMLElement")}} 继承方法。_ -## Examples +- {{domxref("HTMLFormElement.checkValidity", "checkValidity()")}} + - : 如果元素的子控件受到[约束验证](/zh-CN/docs/Web/HTML/Constraint_validation)并满足这些约束,则返回 `true`;如果某些控件不满足其约束,则返回 `false`。在不满足其约束的任何控件上触发名为 {{domxref("HTMLInputElement/invalid_event", "invalid")}} 的事件;如果未取消事件,则这些控件被视为无效。由程序员决定如何响应 `false`。 +- {{domxref("HTMLFormElement.reportValidity", "reportValidity()")}} + - : 如果元素的子控件满足其[验证约束](/zh-CN/docs/Web/HTML/Constraint_validation),则返回 `true`。当返回 `false` 时,将为每个无效的子控件触发可取消的 {{domxref("HTMLInputElement/invalid_event", "invalid")}} 事件,并将验证问题报告给用户。 +- {{domxref("HTMLFormElement.requestSubmit", "requestSubmit()")}} + - : 请求使用指定的提交按钮及其相应的配置来提交表单。 +- {{domxref("HTMLFormElement.reset", "reset()")}} + - : 将表单重置为其初始状态。 +- {{domxref("HTMLFormElement.submit", "submit()")}} + - : 将表单提交至服务器。 -The following example shows how to create a new form element, modify its attributes and submit it. +## 事件 -```js -// Create a form -var f = document.createElement("form"); +使用 `addEventListener()` 或将事件监听器赋值给此接口的 `oneventname` 属性来监听这些事件。 -// Add it to the document body -document.body.appendChild(f); +- {{domxref("HTMLFormElement/formdata_event", "formdata")}} + - : 在构建表示表单数据的条目列表之后触发 `formdata` 事件。 +- {{domxref("HTMLFormElement/reset_event", "reset")}} + - : 在表单重置时触发 `reset` 事件。 +- {{domxref("HTMLFormElement/submit_event", "submit")}} + - : 在表单提交时触发 `submit` 事件。 -// Add action and method attributes -f.action = "/cgi-bin/some.cgi"; -f.method = "POST"; +## 使用说明 + +### 获得表单元素对象 + +要获取 `HTMLFormElement` 对象,你可以使用 [CSS 选择器](/zh-CN/docs/Web/CSS/CSS_selectors)和 {{domxref("Document.querySelector", "querySelector()")}},或者使用文档的 {{domxref("Document.forms", "forms")}} 属性获取文档中所有表单的列表。 + +{{domxref("Document.forms")}} 返回 `HTMLFormElement` 对象数组,其中列出了页面上的每个表单。然后,你可以使用以下任何语法来获取单个表单: + +- `document.forms[index]` + - : 返回数组中指定索引(`index`)的表单。 +- `document.forms[id]` + - : 返回 ID 为 `id` 的表单。 +- `document.forms[name]` + - : 返回 `name` 属性值为 `name` 的表单。 + +### 访问表单的元素 + +你可以通过检查表单的 {{domxref("HTMLFormElement.elements", "elements")}} 属性来访问表单中用于包含数据的元素列表。这将返回一个 {{domxref("HTMLFormControlsCollection")}},其中列出了表单的所有用户数据输入元素,包括 `
``` -The following example shows how to submit a form in a [popup window](/zh-CN/docs/DOM/window.open). +在新窗口中提交表单(` ``` -### Submitting forms and uploading files using `XMLHttpRequest` - -If you want to know how to serialize and submit a form using the [`XMLHttpRequest`](/zh-CN/docs/DOM/XMLHttpRequest) API, please read [this paragraph](/zh-CN/docs/DOM/XMLHttpRequest_API/Using_XMLHttpRequest#Submitting_forms_and_uploading_files). - -## Specifications +## 规范 {{Specifications}} -## Browser compatibility +## 浏览器兼容性 {{Compat}} -## See also +## 参见 -- The HTML element implementing this interface: {{ HTMLElement("form") }}. +- 实现此接口的 HTML 元素:{{HTMLElement("form")}}。