Document.querySelectorAll()

Die Methode querySelectorAll() von Document gibt eine statische (nicht live) NodeList (en-US) zurück, die eine Liste der Elemente des Dokuments darstellt, die mit der angegebenen Selektorgruppe übereinstimmen.

Hinweis: Diese Methode wird basierend auf dem Mixin der Methode querySelectorAll() von ParentNode implementiert.

Syntax

elementList = parentNode.querySelectorAll(selectors);

Parameter

selectors
Ein DOMString der einen oder mehrere Selektoren zum Abgleich enthält. Dieser String muss ein valider CSS-Selektor-String sein, andernfalls wird eine SyntaxError Exception ausgelöst. Weitere Informationen zu Selektoren und deren Verwaltung finden Sie unter DOM Elemente mittels Selektoren ermitteln. Es können mehrere durch Kommata getrennte Selektoren angegeben werden.

Hinweis: Zeichen, die nicht zur Standard-CSS-Syntax gehören, müssen mit einem Backslash-Zeichen maskiert werden. Da JavaScript auch Backslash-Escape-Anweisungen verwendet, müssen Sie beim Schreiben von String-Literalen mit diesen Zeichen besonders vorsichtig sein. Weitere Informationen finden Sie unter Sonderzeichen maskieren.

Rückgabewert

Eine statische (nicht-live) NodeList (en-US) mit je einem Element-Objekt für jedes Element das mind. einem der angegebenen Selektoren entspricht oder eine leere NodeList (en-US) im Falle keiner Übereinstimmungen.

Hinweis: Wenn selectors ein CSS Pseudo-Element enthält ist die zurückgegebene Liste immer leer.

Exceptions

SyntaxError
Die Syntax des selectors-String ist ungültig.

Beispiele

Eine Liste von Übereinstimmungen erhalten

Um eine NodeList (en-US) aller <p>-Elemente des Dokuments zu erhalten:

var matches = document.querySelectorAll("p");

Das folgende Beispiel gibt eine Liste aller <div>-Elemente innerhalb des Dokuments zurück, deren Klasse entweder "note" oder "alert" ist:

var matches = document.querySelectorAll("div.note, div.alert");

Hier erhalten wir eine Liste von <p>-Elementen, deren unmittelbares übergeordnetes Element ein <div> mit der Klasse "highlighted" ist und die sich in einem Container befinden, dessen ID "test" ist.

var container = document.querySelector("#test");
var matches = container.querySelectorAll("div.highlighted > p");

Das folgende Beispiel nutzt einen Attribut-Selektor, um eine Liste von <iframe>-Elementen im Dokument zurückzugeben, die ein "data-src" Attribut besitzen:

var matches = document.querySelectorAll("iframe[data-src]");

Hier wird ein Attribut-Selektor verwendet, um eine Aufzählung der Listenelemente zurückzugeben, die in einer Liste mit der ID "userlist" enthalten sind und deren Attribut "data-active" den Wert "1" hat:

var container = document.querySelector("#userlist");
var matches = container.querySelectorAll("li[data-active='1']");

Auf Übereinstimmungen zugreifen

Sobald die NodeList (en-US) der übereinstimmenden Elemente zurückgegeben wird, können Sie sie wie jedes Array untersuchen. Wenn das Array leer ist (d. h. die Eigenschaft length 0 ist), wurden keine Übereinstimmungen gefunden.

Ansonsten können Sie einfach die Standard-Array-Notation verwenden, um auf den Inhalt der Liste zuzugreifen. Sie können jede allgemeine Schleifenanweisung verwenden, wie etwa:

var highlightedItems = userList.querySelectorAll(".highlighted");

highlightedItems.forEach(function(userItem) {
  deleteUser(userItem);
});

Benutzerhinweise

querySelectorAll() verhält sich anders als die meisten JavaScript-DOM-Bibliotheken, was zu unerwarteten Ergebnissen führen kann.

HTML

Betrachten Sie dieses HTML mit seinen drei geschachtelten <div> Blöcken.

<div class="outer">
  <div class="select">
    <div class="inner">
    </div>
  </div>
</div>

JavaScript

var select = document.querySelector('.select');
var inner = select.querySelectorAll('.outer .inner');
inner.length; // 1, not 0!

Wenn Sie in diesem Beispiel ".outer .inner" im Kontext des <div> mit der Klasse "select" auswählen, wird das Element mit der Klasse ".inner" immer noch gefunden, obwohl .outer kein Nachkomme des Basis-Elements ist, auf dem die Suche durchgeführt wird (".select"). Standardmäßig überprüft querySelectorAll() nur, ob sich das letzte Element im Selektor im Suchbereich befindet.

Die :scope (en-US) Pseudo-Klasse stellt das erwartete Verhalten wieder her, bei dem Selektoren nur mit Nachkommen des Basis-Elements übereinstimmen:

var select = document.querySelector('.select');
var inner = select.querySelectorAll(':scope .outer .inner');
inner.length; // 0

Spezifikationen

Specification Status Comment
DOM
Die Definition von 'ParentNode.querySelectorAll()' in dieser Spezifikation.
Lebender Standard Lebender Standard
Selectors API Level 2
Die Definition von 'ParentNode.querySelectorAll()' in dieser Spezifikation.
Veraltet Keine Änderung
DOM4
Die Definition von 'ParentNode.querySelectorAll()' in dieser Spezifikation.
Veraltet Initiale Definition
Selectors API Level 1
Die Definition von 'document.querySelector()' in dieser Spezifikation.
Veraltet Originale Definition

Browserkompatibilität

BCD tables only load in the browser

Siehe auch