HTMLFormElement

Интерфейс HTMLFormElement представляет собой элемент <form> в DOM. Он позволяет получить доступ к — и в некоторых случаях изменить — аспекты формы, а также получить доступ к её составным элементам.

Этот интерфейс также наследует свойства от своего родителя, HTMLElement.

HTMLFormElement.elements Только для чтения

Объект HTMLFormControlsCollection, содержащий все элементы управления формы, принадлежащие этому элементу формы.

HTMLFormElement.length Только для чтения

Значение, отражающее количество элементов управления в форме.

HTMLFormElement.name

Строка, отражающая значение атрибута HTML формы name, содержащего имя формы.

HTMLFormElement.method

Строка, отражающая значение атрибута HTML формы method, указывающего HTTP-метод, используемый для отправки формы. Можно установить только указанные значения.

HTMLFormElement.target

Строка, отражающая значение атрибута HTML формы target, указывающего, где отобразить результаты, полученные при отправке формы.

HTMLFormElement.action

Строка, отражающая значение атрибута HTML формы action, содержащего URI программы, которая обрабатывает информацию, отправленную формой.

HTMLFormElement.encoding или HTMLFormElement.enctype

Строка, отражающая значение атрибута HTML формы enctype, указывающего тип содержимого, используемого для передачи формы на сервер. Можно установить только указанные значения. Эти два свойства являются синонимами.

HTMLFormElement.acceptCharset

Строка, отражающая значение атрибута HTML формы accept-charset.

HTMLFormElement.autocomplete

Строка, отражающая значение атрибута HTML формы autocomplete, указывающего, могут ли значения элементов управления в этой форме автоматически заполняться браузером.

HTMLFormElement.noValidate

Булево значение, отражающее значение атрибута HTML формы novalidate, указывающего, должна ли форма не проходить валидацию.

Имена ввода добавляются к экземпляру формы в качестве свойств, и могут перезаписывать родные свойства, если у них одинаковое имя (например, форма с элементом ввода с именем action будет иметь свойство action, возвращающее этот элемент ввода вместо атрибута HTML формы action).

Этот интерфейс также наследует методы от своего родителя, HTMLElement.

checkValidity()

Возвращает true если дочерние элементы управления элемента подвержены валидации ограничений и удовлетворяют этим ограничениям; возвращает false если некоторые элементы управления не удовлетворяют их ограничениям. Вызывает событие с именем invalid для любого элемента управления, который не удовлетворяет своим ограничениям; такие элементы управления считаются невалидными, если событие не отменено. Программисту необходимо решить, как реагировать на false.

reportValidity()

Возвращает true если дочерние элементы управления элемента удовлетворяют своим ограничениям валидации. Когда возвращается false, отменяемые события invalid генерируются для каждого невалидного дочернего элемента, и проблемы валидации сообщаются пользователю.

requestSubmit()

Запрашивает отправку формы с использованием указанной кнопки отправки и её конфигурации.

reset()

Сбрасывает форму в исходное состояние.

submit()

Отправляет форму на сервер.

Слушайте эти события, используя addEventListener(), или назначив обработчик событий свойству oneventname этого интерфейса.

formdata

Событие formdata срабатывает после построения списка записей, представляющих данные формы.

reset

Событие reset срабатывает при сбросе формы.

submit

Событие submit срабатывает при отправке формы.

Чтобы получить объект HTMLFormElement , можно использовать селектор CSS с querySelector(), или получить список всех форм в документе с помощью его свойства forms.

Document.forms возвращает массив объектов HTMLFormElement , перечисляя каждую форму на странице. Затем можно использовать любой из следующих синтаксисов для получения отдельной формы:

document.forms[index]

Возвращает форму по указанному index в массиве форм.

document.forms[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.elements и HTMLFormElement.length:

• <button>
• <fieldset>
• <input> (за исключением тех, у которых type равен "image" по историческим причинам)
• <object>
• <output>
• <select>
• <textarea>

Никакие другие элементы не включаются в список, возвращаемый elements, что делает его отличным способом получить наиболее важные элементы при обработке форм.

Создание нового элемента формы, изменение его атрибутов и отправка:

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> и установка некоторых его атрибутов:

<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
    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
  }

  function setFormInfo(f) {
    // Argument should be a form element reference.
    f.action = "a-different-url.cgi";
    f.name = "a-different-name";
  }
</script>

Отправка <form> в новое окно:

<!doctype html>
<html lang="en-US">
  <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="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>
  </body>
</html>

• Элемент HTML, реализующий этот интерфейс: <form>.