HTMLFieldSetElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLFieldSetElement extends HTMLElement

Beschreibung

Das Interface HTMLFieldSetElement steht für ein <fieldset>-Element im DOM. Neben allem, was es von HTMLElement erbt, stellt es spezielle Eigenschaften und Methoden bereit, mit denen sich eine Gruppe zusammengehöriger Formularsteuerelemente – meist mit einer <legend> beschriftet – gemeinsam steuern und prüfen lässt.

Wichtige Eigenschaften:

disabled (boolean): Deaktiviert alle enthaltenen Steuerelemente auf einmal (außer denen innerhalb der ersten <legend>). Deaktivierte Felder werden beim Absenden nicht übertragen.
elements (HTMLCollection, schreibgeschützt): Live-Sammlung aller Formularsteuerelemente innerhalb des Fieldsets.
form (HTMLFormElement | null, schreibgeschützt): Das zugehörige Formular – entweder das umschließende oder das über das form-Attribut referenzierte.
name (string): Spiegelt das name-Attribut wider.
type (string, schreibgeschützt): Liefert immer "fieldset".
validity, validationMessage, willValidate (schreibgeschützt): Teil der Constraint-Validation-API; ein Fieldset selbst ist nie Ziel einer Validierung, daher ist willValidate immer false.

Methoden: checkValidity(), reportValidity() und setCustomValidity(message). Da ein Fieldset nicht selbst validiert wird, liefern checkValidity() und reportValidity() für das Fieldset immer true – um die enthaltenen Felder zu prüfen, iteriert man über elements.

Praktisch nützlich ist das Interface vor allem für mehrstufige Formulare (Wizards), bedingt aktivierte Abschnitte (z. B. „Lieferadresse abweichend“) und für das gezielte Auslesen oder Prüfen einzelner Formularbereiche.

Rückgabewert

Typ

HTMLFieldSetElement

Beschreibung

Instanzen erhält man über document.createElement("fieldset") oder durch Abfragen vorhandener <fieldset>-Elemente, z. B. mit querySelector().

Beispiele

Fieldset dynamisch erzeugen und einfügen

const fieldset = document.createElement('fieldset');
fieldset.name = 'kontakt';

const legend = document.createElement('legend');
legend.textContent = 'Kontaktdaten';

const input = document.createElement('input');
input.type = 'email';
input.name = 'email';
input.required = true;

fieldset.append(legend, input);
document.querySelector('form').append(fieldset);

console.log(fieldset instanceof HTMLFieldSetElement);
console.log(fieldset.type, fieldset.elements.length);

true fieldset 1

Abschnitt per Checkbox aktivieren/deaktivieren

// HTML:
// <label><input type="checkbox" id="abweichend"> Abweichende Lieferadresse</label>
// <fieldset id="lieferadresse" disabled>
//   <legend>Lieferadresse</legend>
//   <input name="strasse" required>
//   <input name="ort" required>
// </fieldset>

const checkbox = document.querySelector('#abweichend');
const lieferadresse = document.querySelector('#lieferadresse');

checkbox.addEventListener('change', () => {
  // Deaktivierte Felder werden weder validiert noch abgeschickt
  lieferadresse.disabled = !checkbox.checked;
});

Einzelnen Schritt eines Wizards validieren

const validiereSchritt = (fieldset) => {
  const felder = [...fieldset.elements].filter((el) => el.willValidate);
  // reportValidity() zeigt dem Nutzer die Browser-Fehlermeldung an
  return felder.every((el) => el.reportValidity());
};

document.querySelector('#weiter').addEventListener('click', () => {
  const schritt = document.querySelector('fieldset.aktiv');
  if (validiereSchritt(schritt)) {
    console.log(`Schritt "${schritt.name}" ist gültig`);
  }
});

Schritt "persoenlich" ist gültig

Daten nur eines Fieldsets auslesen

const fieldsetDaten = (fieldset) =>
  Object.fromEntries(
    [...fieldset.elements]
      .filter((el) => el.name && !el.disabled)
      .map((el) => [el.name, el.value])
  );

const kontakt = document.querySelector('fieldset[name="kontakt"]');
console.log(fieldsetDaten(kontakt));

{ email: "max@example.com" }

// Wichtig · Fallstricke

Validierung: fieldset.checkValidity() liefert immer true, auch wenn enthaltene Felder ungültig sind. Zur Prüfung über elements iterieren. Die CSS-Pseudoklassen :valid/:invalid greifen in modernen Browsern dagegen auch auf Fieldsets (anhand der Kindelemente).
disabled und <legend>: Steuerelemente in der ersten <legend> bleiben aktiv – praktisch für eine Checkbox, die den Abschnitt ein- und ausschaltet.
Deaktivierte Felder sind in FormData nicht enthalten. Soll ein Wert nur schreibgeschützt, aber übertragen werden, stattdessen readOnly auf den einzelnen Feldern setzen.
elements ist eine Live-Collection und enthält auch verschachtelte Fieldsets sowie <button>, <output> und <object>; <input type=\"image\"> ist ausgeschlossen.
Styling: <fieldset> hatte historisch Einschränkungen bei display: flex/grid (ältere Chrome- und Safari-Versionen). Das Interface selbst wird von allen Browsern seit Langem unterstützt.

Siehe auch

HTMLFrameSetElement HTMLDListElement HTMLOListElement HTMLSelectElement HTMLTitleElement