Document.childElementCount — Eigenschaft · JavaScript-Referenz

Signatur

get Document.childElementCount

Beschreibung

Die schreibgeschützte Eigenschaft Document.childElementCount liefert die Anzahl der direkten Kindknoten des Dokuments, die Elemente sind. Textknoten, Kommentare, Verarbeitungsanweisungen und der Doctype-Knoten (<!DOCTYPE html>) werden dabei nicht mitgezählt.

Weil ein wohlgeformtes Dokument genau ein Wurzelelement hat (bei HTML <html>, bei XML/SVG das jeweilige Wurzelelement), ist der Wert in der Praxis fast immer 1. Den Wert 0 sieht man bei leeren Dokumenten, etwa wenn sie mit document.implementation.createDocument(null, null) erzeugt oder das Wurzelelement entfernt wurde.

Die Eigenschaft stammt aus dem ParentNode-Mixin und steht deshalb auch an Element und DocumentFragment zur Verfügung. Dort ist sie deutlich nützlicher. Sie entspricht document.children.length, ist aber kürzer zu schreiben und macht den Zweck klarer.

Rückgabewert

Typ

number

Beschreibung

Eine nicht-negative ganze Zahl: die Anzahl der Kind-Elemente des Dokuments, im Regelfall 1 (das Wurzelelement).

Beispiele

Kind-Elemente im HTML-Dokument zählen

// In einer normalen HTML-Seite
console.log(document.childElementCount);
console.log(document.childNodes.length); // inkl. Doctype-Knoten
console.log(document.firstElementChild.tagName);

1 2 HTML

Leeres XML-Dokument aufbauen und prüfen

const xmlDoc = document.implementation.createDocument(null, null);
console.log(xmlDoc.childElementCount); // noch kein Wurzelelement

const root = xmlDoc.createElement('bestellungen');
xmlDoc.appendChild(root);
console.log(xmlDoc.childElementCount);

0 1

Geparstes Dokument auf ein Wurzelelement prüfen

const parseXml = (text) => {
  const doc = new DOMParser().parseFromString(text, 'application/xml');
  if (doc.querySelector('parsererror') || doc.childElementCount !== 1) {
    throw new Error('Ungültiges XML');
  }
  return doc.documentElement;
};

const root = parseXml('<config><debug>true</debug></config>');
console.log(root.nodeName, root.childElementCount);

config 1

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie document.childElementCount = 2 wird im nicht-strikten Modus stillschweigend ignoriert. Im Strict Mode wirft sie einen TypeError, weil es nur einen Getter gibt.
Nicht mit document.childNodes.length verwechseln: Diese Zählung enthält auch Doctype-, Kommentar- und Textknoten.
Ein Dokument kann nur ein Kind-Element haben. Wer ein zweites mit appendChild einfügen will, bekommt eine HierarchyRequestError-DOMException. Mehr als 1 ist also nicht möglich.
Der Wert wird bei jedem Zugriff aktuell berechnet und ist damit immer auf dem neuesten Stand.
Browser-Kompatibilität: Alle modernen Browser unterstützen die Eigenschaft am Document. Sehr alte Internet-Explorer-Versionen boten sie nur an Element an.

Siehe auch

Document.children Document.customElementRegistry Document.activeElement Document.firstElementChild Document.lastElementChild