Signatur
Beschreibung
querySelector() durchsucht alle Nachfahren eines DocumentFragment in Dokumentreihenfolge (Tiefensuche, Pre-Order) und liefert das erste Element, das zur übergebenen Selektorliste passt. Die Methode stammt aus dem Mixin ParentNode und verhält sich genauso wie Document.querySelector() oder Element.querySelector().
Besonders praktisch ist sie bei Templates (template.content ist ein DocumentFragment) und bei Shadow DOM (ShadowRoot erbt von DocumentFragment). So kann man geklonte Template-Inhalte vor dem Einfügen ins Dokument befüllen – das ist schneller, weil das Live-DOM erst einmal geändert wird.
Zu beachten: Ein Fragment ist kein Element und kann deshalb selbst nicht getroffen werden – durchsucht werden nur seine Nachfahren. Nachdem das Fragment per append() ins Dokument eingefügt wurde, ist es leer. Weitere Abfragen darauf liefern dann null.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $selectors Pflicht | string | Ein gültiger CSS-Selektor oder eine kommagetrennte Selektorliste, z. B. '.item', '#titel' oder 'li:first-child, p.hinweis'. |
Rückgabewert
Element in Dokumentreihenfolge oder null, wenn kein Nachfahre passt.Beispiele
Element in einem selbst gebauten Fragment finden
const fragment = document.createDocumentFragment();
['Äpfel', 'Birnen', 'Kirschen'].forEach((obst, i) => {
const li = document.createElement('li');
li.textContent = obst;
if (i === 1) li.classList.add('aktiv');
fragment.append(li);
});
const aktiv = fragment.querySelector('li.aktiv');
console.log(aktiv.textContent);
console.log(fragment.querySelector('.fehlt'));Template-Inhalt vor dem Einfügen befüllen
// HTML: <template id="karte"><article><h2 class="titel"></h2><p class="text"></p></article></template>
const template = document.querySelector('#karte');
const renderKarte = ({ titel, text }) => {
const klon = template.content.cloneNode(true); // DocumentFragment
klon.querySelector('.titel').textContent = titel;
klon.querySelector('.text').textContent = text;
return klon;
};
document.body.append(renderKarte({ titel: 'Hallo', text: 'Aus dem Template.' }));
console.log(document.querySelector('article .titel').textContent);Abfrage im Shadow DOM (ShadowRoot ist ein DocumentFragment)
class ZaehlerButton extends HTMLElement {
#count = 0;
constructor() {
super();
const root = this.attachShadow({ mode: 'open' });
root.innerHTML = '<button type="button">Klicks: <span class="wert">0</span></button>';
root.querySelector('button').addEventListener('click', () => {
root.querySelector('.wert').textContent = ++this.#count;
});
}
}
customElements.define('zaehler-button', ZaehlerButton);
const el = document.createElement('zaehler-button');
document.body.append(el);
console.log(el.shadowRoot instanceof DocumentFragment);Fallstrick: Fragment nach dem Einfügen leer
const frag = document.createDocumentFragment();
const p = document.createElement('p');
p.className = 'info';
frag.append(p);
console.log(frag.querySelector('.info') === p);
document.body.append(frag); // Kinder werden verschoben
console.log(frag.querySelector('.info'));
console.log(document.body.querySelector('.info') === p);// Wichtig · Fallstricke
- Ungültige Selektoren wie
'div['lösen eineSyntaxError-DOMExceptionaus. Dynamische Werte (z. B. IDs, die mit einer Ziffer beginnen) sollte man mitCSS.escape()absichern. - Leeres Fragment nach dem Einfügen:
append()/appendChild()verschiebt die Kinder ins Dokument. Referenzen daher vorher holen. - Das Fragment selbst wird nie gefunden, nur seine Nachfahren. Selektoren wie
:scope > libeziehen sich auf die Wurzel des Fragments und funktionieren in modernen Browsern. - Im Shadow DOM findet
shadowRoot.querySelector()nur Elemente im Schattenbaum, nicht die per<slot>projizierten Light-DOM-Kinder. Umgekehrt dringtdocument.querySelector()nicht in Shadow Roots ein. - Wenn man nur eine ID sucht, ist
DocumentFragment.getElementById()etwas schneller. - Kompatibilität: wird von allen modernen Browsern unterstützt (IE ab Version 9).