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>