CKTIS / JavaScript
Element.querySelector() und Element.querySelectorAll()
Durchsuche die Nachfahren eines Elements mit CSS-Selektoren. Wähle den ersten Treffer oder eine statische Liste aller Treffer.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
element.querySelector(selectors) // Element | null
element.querySelectorAll(selectors) // static NodeList of Element objectsquerySelector() und querySelectorAll() sind Instanzmethoden von Element. Beide erwarten eine Zeichenkette mit einem CSS-Selektor oder einer kommagetrennten Liste von CSS-Selektoren. querySelector() liefert das erste passende Element in Dokumentreihenfolge oder null. querySelectorAll() liefert eine statische NodeList mit allen passenden Elementen in derselben Reihenfolge: Elternelemente vor Nachfahren, frühere Geschwister vor späteren. Die Reihenfolge der Selektoren legt keine Priorität fest, und jedes Element erscheint höchstens einmal. Ohne Treffer ist die Liste leer (length === 0).
Das Ergebnis enthält nur Nachfahren des Elements, auf dem du die Methode aufrufst, nie das Element selbst. Für einen Treffer können aber auch Vorfahren außerhalb dieses Teilbaums relevant sein. :scope steht für das Element, auf dem du die Methode aufrufst. Daher wählt :scope > .item nur dessen direkte Kinder mit der Klasse item aus. Abfragen überschreiten keine Shadow-DOM-Grenzen. Verwende für die Suche darin einen zugänglichen ShadowRoot.
Eine statische Liste behält die Einträge und deren Reihenfolge vom Zeitpunkt des Aufrufs bei. Eine Klassenänderung sowie das Hinzufügen, Entfernen oder Verschieben eines Elements aktualisieren die Liste nicht. Die Einträge verweisen weiterhin auf die ursprünglichen Element-Objekte, nicht auf Kopien. Frage für ein aktuelles Ergebnis erneut ab. Mit Array.from(list) kannst du Array-Methoden nutzen.
Bei einer ungültigen Selektorzeichenkette lösen beide Methoden eine DOMException namens SyntaxError aus. Das ist etwas anderes als ein Ergebnis ohne Treffer. CSS-Pseudoelemente wie ::before werden nicht als DOM-Elemente zurückgegeben. Bilde einen Selektor für eine dynamische ID mit "#" + CSS.escape(id): Maskiert wird der CSS-Bezeichner, nicht der gesamte Selektor oder HTML. Die Methoden gehören zum DOM der Webplattform, nicht zu ECMAScript 2024. Prüfe, ob die Zielumgebung das DOM und die verwendeten Selektoren unterstützt.
Beispiele
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Element selector queries</title>
</head>
<body>
<script>
const frame = document.createElement("div");
frame.className = "frame";
const root = frame.appendChild(document.createElement("section"));
const direct = root.appendChild(document.createElement("p"));
const wrapper = root.appendChild(document.createElement("div"));
const nested = wrapper.appendChild(document.createElement("p"));
direct.className = nested.className = "item";
direct.textContent = "A";
nested.textContent = "B";
const snapshot = root.querySelectorAll(".frame .item");
console.log(root.querySelector(":scope > .item").textContent);
console.log(snapshot.length);
console.log(root.querySelectorAll(":scope > .item").length);
nested.remove();
console.log(`${snapshot.length} ${root.querySelectorAll(".frame .item").length}`);
</script>
</body>
</html>Ergebnis
A 2 1 2 1
Speichere das Beispiel als HTML-Datei, öffne es im Browser und prüfe die Ausgabe in der Browserkonsole. `:scope > .item` findet nur `A`, während `.frame .item` beide Absätze über einen Vorfahren außerhalb von `root` findet. Nachdem `B` entfernt wurde, hat die gespeicherte Liste noch zwei Einträge, die neue Abfrage aber nur einen.
Zugehörige Lektionen
- JavaScript · Lektion 30 · Fortgeschritten · Version: 4