DocumentFragment.getElementById() — Methode · JavaScript-Referenz

Signatur

DocumentFragment.prototype.getElementById(id)

Beschreibung

Mit getElementById() findet man innerhalb eines DocumentFragment das Element, dessen id-Attribut genau dem übergebenen String entspricht. Sie funktioniert wie document.getElementById(), durchsucht aber nur die Nachfahren des Fragments und nicht das ganze Dokument.

Gebraucht wird das vor allem, wenn man DOM-Strukturen vor dem Einfügen ins Dokument aufbaut oder anpasst, zum Beispiel beim Klonen eines <template>-Inhalts oder beim Befüllen eines mit document.createDocumentFragment() erzeugten Fragments. Einzelne Elemente lassen sich so gezielt ansprechen und befüllen, ohne dass der Browser zwischendurch neu rendern muss.

Die Methode kommt aus dem Mixin NonElementParentNode. Deshalb steht sie auf DocumentFragment und Document zur Verfügung, aber nicht auf normalen Element-Objekten. Für Elemente nimmt man stattdessen element.querySelector('#id'). Weil ShadowRoot von DocumentFragment erbt, geht getElementById() auch in einem Shadow DOM.

Wichtig: Sobald das Fragment ins Dokument eingefügt wurde, wandern seine Kindknoten dorthin und das Fragment ist leer. Ein späterer Aufruf von fragment.getElementById() gibt dann null zurück.

Parameter

Name	Typ	Default	Beschreibung
$id Pflicht	string		Die ID des gesuchten Elements. Groß- und Kleinschreibung werden unterschieden, und anders als bei CSS-Selektoren steht davor kein `#`.

Rückgabewert

Typ

Element | null

Beschreibung

Das erste Element in Baumreihenfolge innerhalb des Fragments, dessen id passt, oder null, wenn keins gefunden wird.

Beispiele

Element in einem selbst erstellten Fragment finden

const fragment = document.createDocumentFragment();

const liste = document.createElement('ul');
liste.id = 'einkaufsliste';
fragment.append(liste);

// Element im Fragment suchen, bevor es ins Dokument kommt
const gefunden = fragment.getElementById('einkaufsliste');
console.log(gefunden === liste);

['Milch', 'Brot', 'Käse'].forEach((artikel) => {
  const li = document.createElement('li');
  li.textContent = artikel;
  gefunden.append(li);
});

document.body.append(fragment);
console.log(fragment.getElementById('einkaufsliste'));

true null

Template-Inhalt klonen und befüllen

// HTML:
// <template id="karte-vorlage">
//   <article><h2 id="titel"></h2><p id="text"></p></article>
// </template>

const vorlage = document.getElementById('karte-vorlage');

const erstelleKarte = (titel, text) => {
  // content ist ein DocumentFragment
  const klon = vorlage.content.cloneNode(true);
  klon.getElementById('titel').textContent = titel;
  klon.getElementById('text').textContent = text;
  // IDs entfernen, damit sie im Dokument nicht mehrfach vorkommen
  klon.getElementById('titel').removeAttribute('id');
  klon.getElementById('text').removeAttribute('id');
  return klon;
};

document.body.append(erstelleKarte('Hallo', 'Erste Karte'));
document.body.append(erstelleKarte('Welt', 'Zweite Karte'));

Suche im Shadow DOM einer Web Component

class StatusAnzeige extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    shadow.innerHTML = '<span id="status">bereit</span>';
  }

  set status(wert) {
    // ShadowRoot erbt von DocumentFragment
    this.shadowRoot.getElementById('status').textContent = wert;
  }
}

customElements.define('status-anzeige', StatusAnzeige);

const anzeige = document.createElement('status-anzeige');
document.body.append(anzeige);
anzeige.status = 'lädt …';
console.log(anzeige.shadowRoot.getElementById('status').textContent);

lädt …

// Wichtig · Fallstricke

Nicht auf Elementen verfügbar: element.getElementById() gibt es nicht und führt zu einem TypeError. Nimm dort element.querySelector('#id'). Enthält die ID Sonderzeichen, maskiere sie vorher mit CSS.escape().
Fragment nach dem Einfügen leer: Nach append() oder appendChild() liegen die Knoten im Dokument. Hebe Verweise auf benötigte Elemente also vorher auf.
Doppelte IDs: Beim Klonen von Templates tauchen dieselben IDs leicht mehrfach im Dokument auf. Das ist ungültiges HTML und führt dazu, dass document.getElementById() nur das erste Element findet. Entferne die IDs nach dem Befüllen oder benutze Klassen oder data-*-Attribute.
Kein #-Präfix: getElementById('#titel') sucht nach einer ID, die wörtlich #titel lautet, und gibt deshalb meistens null zurück.
Kompatibilität: Wird von allen modernen Browsern unterstützt, nicht aber vom Internet Explorer. Dort bleibt nur fragment.querySelector().

Siehe auch

DocumentFragment.replaceChildren() DocumentFragment.prepend() DocumentFragment.append() DocumentFragment.querySelector() DocumentFragment.moveBefore()