DocumentFragment.firstElementChild — Eigenschaft · JavaScript-Referenz

Signatur

get DocumentFragment.prototype.firstElementChild

Beschreibung

firstElementChild gibt das erste direkte Kind eines DocumentFragment zurück, das ein Element ist. Anders als firstChild werden Textknoten (auch reine Leerzeichen und Zeilenumbrüche) und Kommentarknoten übersprungen. Gibt es kein Kind-Element, ist der Wert null.

Die Eigenschaft stammt aus dem ParentNode-Mixin und ist deshalb auch auf Element und Document verfügbar. Bei Fragmenten ist sie besonders nützlich, wenn man den Inhalt eines <template>-Elements klont (template.content ist ein DocumentFragment) und das Wurzelelement der Vorlage vor dem Einfügen ins Dokument anpassen möchte.

Wichtig: Sobald ein Fragment per append(), appendChild() o. Ä. in das Dokument eingefügt wird, werden seine Kinder verschoben. Das Fragment ist danach leer und firstElementChild liefert null. Eine Referenz auf das Element sollte man also vor dem Einfügen sichern.

Rückgabewert

Typ

Element | null

Beschreibung

Das erste direkte Kind-Element des Fragments oder null, wenn das Fragment keine Kind-Elemente enthält.

Beispiele

Unterschied zu firstChild

const fragment = document.createRange().createContextualFragment(`
  <!-- Kommentar -->
  <li>Erster Eintrag</li>
  <li>Zweiter Eintrag</li>
`);

console.log(fragment.firstChild.nodeName);        // Textknoten (Zeilenumbruch)
console.log(fragment.firstElementChild.nodeName); // erstes echtes Element
console.log(fragment.firstElementChild.textContent);

#text LI Erster Eintrag

Template klonen und Wurzelelement vor dem Einfügen anpassen

// HTML: <template id="card-tpl">\n  <article class="card"><h2></h2><p></p></article>\n</template>
const tpl = document.querySelector('#card-tpl');

const renderCard = ({ id, title, text }) => {
  const fragment = tpl.content.cloneNode(true);
  const card = fragment.firstElementChild; // <article> sichern
  card.dataset.id = id;
  card.querySelector('h2').textContent = title;
  card.querySelector('p').textContent = text;
  document.body.append(fragment);
  return card; // Referenz bleibt nach dem Einfügen gültig
};

const el = renderCard({ id: 42, title: 'Hallo', text: 'Welt' });
console.log(el.isConnected, el.dataset.id);

true 42

Fragment ist nach dem Einfügen leer

const fragment = new DocumentFragment();
console.log(fragment.firstElementChild); // noch leer

const p = document.createElement('p');
p.textContent = 'Absatz';
fragment.append('Nur Text', p);
console.log(fragment.firstElementChild === p);

document.body.append(fragment);
console.log(fragment.firstElementChild); // Kinder wurden verschoben

null true null

// Wichtig · Fallstricke

Nur lesbar: Eine Zuweisung wird im nicht-strikten Modus stillschweigend ignoriert und löst im strikten Modus einen TypeError aus (Getter ohne Setter).
Nach dem Einfügen null: Durch append()/appendChild() wird das Fragment geleert. Referenzen deshalb vorher speichern.
Nur direkte Kinder: Verschachtelte Elemente werden nicht berücksichtigt; für tiefere Suche querySelector() verwenden.
Template-Fallstrick: Führende Leerzeichen im <template> machen firstChild zu einem Textknoten – deshalb hier immer firstElementChild nutzen.
Kompatibilität: In allen modernen Browsern verfügbar; der Internet Explorer unterstützte die Eigenschaft auf DocumentFragment nicht (nur auf Element).

Siehe auch

DocumentFragment.lastElementChild DocumentFragment.children DocumentFragment.childElementCount Node.firstChild Element.firstElementChild HTMLTemplateElement.content DocumentFragment